Replacing Code as Source of Truth with Ideal State Artifacts
Daniel Miessler proposes a spec-driven methodology replacing code with Ideal State Artifacts as the definitive source of truth in AI development. Moving iterations into written prose and criteria evals keeps AI execution aligned with human intent.
Why it matters
AI tools execute instructions effectively, but project failures often stem from communication and articulation gaps. Anchoring development in living specification artifacts prevents wasteful iteration cycles around suboptimal implementations.
TL;DR
- 01Code is an abstraction of intent; clear written prose provides higher conceptual accuracy when prompting AI.
- 02An Ideal State Artifact (ISA) structures projects into Ideal State, Constraints, Decisions, and Ideal State Criteria.
- 03Ideal State Criteria (ISCs) serve simultaneously as development prompts and automated evaluation harnesses.
Key facts
- Methodology
- Ideal State Artifact (ISA)
- Evaluation Spectrum
- Assert -> System 1 questions -> Rubric/LLM-as-a-Judge
The Code-as-Truth Problem in AI Development
Treating the codebase as the authoritative artifact creates friction when building with AI. Code is an abstraction and a representation of intent, not the intent itself. When an AI generates a flawed implementation, iterating directly on the generated code traps developers into running in circles around an imperfect output instead of clarifying the original requirement.
Architecture of an Ideal State Artifact (ISA)
An ISA establishes a single source of truth structured across four components:
1. Ideal State: A prose narrative of the system's behavior and user experience, drafted interactively using interview skills such as Discuss or /grill-me. 2. Constraints: Explicit negative specifications defining boundaries and what not to build. 3. Decisions: A dated log recording pivots and requirement changes discovered during generation. 4. Ideal State Criteria (ISCs): Atomic, measurable specifications that serve simultaneously as the build instructions and the evaluation harness.
# Ideal State Artifact (ISA): Meal Planner
## Ideal State
A CLI utility generating weekly grocery lists matching caloric targets.
## Constraints
- No external database dependencies; use local JSON files.
- Never suggest ingredients containing peanuts.
## Decisions
- 2026-03-29: Replaced SQLite with flat JSON to minimize environment friction.
## Ideal State Criteria (ISCs)
- [ ] ISC-1: Output contains exactly 7 dinner recipes.
- Eval: assert len(output.dinners) == 7
- [ ] ISC-2: All recipes strictly exclude peanuts.
- Eval: LLM-as-a-Judge allergy audit over ingredient listDual Iteration Loops
Instead of editing source code when an implementation drifts, developers maintain two distinct loops: refining intent within the ISA document, and triggering fresh code generation validated directly against the criteria evals.
Try it in 2 minutes
## Ideal State Criteria (ISCs)
- [ ] ISC-1: Output contains exactly 7 dinner recipes.
- Eval: assert len(output.dinners) == 7
- [ ] ISC-2: All recipes strictly exclude peanuts.
- Eval: LLM-as-a-Judge allergy audit over ingredient listmarkdown
✓ When to use
- When developing complex applications with AI where direct code refactoring causes repetitive regressions.
✕ When NOT to use
- When making quick one-off scripts where formal evaluation harnesses add unnecessary overhead.
What to do today
- Draft an Ideal State Artifact document with criteria and constraints before prompting AI for code.
- Update the Decisions section of the specification whenever implementation feedback refines user intent.