Spec-Driven Development: Make AI Agents Build the Right Thing

Coding agents are very good at building what you describe. That is the problem. If the description is vague, they fill the gaps with plausible guesses, and you find out what they guessed when you review a large diff. A few minutes spent writing down what "right" means moves those decisions to the start, where they are cheap to change.

What is spec-driven development?

Spec-driven development is writing the specification first and treating it as the input the AI builds from and is checked against. Birgitta Böckeler's analysis on martinfowler.com defines it simply: "writing a 'spec' before writing code with AI ('documentation first')." She describes three levels:

• Spec-first: a spec is written for the task at hand and used during AI-assisted development.
• Spec-anchored: the spec is kept after the task and used for later changes and maintenance.
• Spec-as-source: the spec becomes the main file a human edits, and code is generated from it.

Most teams, and all of my client work, sit at the first level with a little of the second: the spec is written for a feature, kept in the repository, and updated when the feature changes. The third level is still an aspiration rather than a practice I would recommend for client systems.

Why does a spec make AI agents more accurate?

Because it gives the agent information it cannot get from the code, and it gives everyone a definition of done. Anthropic's Claude Code best practices describe a concrete version of this: when you have not worked out what you want, ask the agent to interview you until it could write the spec, save it as SPEC.md, then start a fresh session to build from it "so the build begins with a clean context and a written definition of done." The same file is what the reviewer checks against later.

That last part matters as much as the first. Specs do not guarantee compliance. Böckeler reports that in her experiments she "frequently saw the agent ultimately not follow all the instructions." A spec is only useful if something checks the result against it, which is why the loop below ends in a gate rather than a merge.

The spec, plan, build and verify loop

This is the loop I use on client features, scaled to the size of the work.

• Spec. I write, or have the agent interview me into, a short spec. The client reviews it if the feature affects their users, and an AI feature brief from the client is often its starting point. This is the cheapest point to catch a misunderstanding.
• Plan. The agent reads the spec and the codebase, using the context engineering habits for unfamiliar codebases, and proposes a plan: which files change, in what order, and what tests prove it works. I read the plan before any code exists. Claude Code's large codebase guide notes that a plan written to a file is re-injected after the conversation is compacted, so it survives long sessions where chat history may not.
• Build. The agent works through the plan in small steps, running the checks as it goes. I covered why that matters in give the agent a way to check its work.
• Verify. A reviewer that did not write the code checks the diff against the spec: is every requirement implemented, do the listed edge cases have tests? The best practices page suggests telling that reviewer to report only gaps that affect correctness and to skip style, because a reviewer asked to find problems will always find something.

If verification fails, the work goes back to build. If it fails because the spec was wrong, the spec is fixed first and the change follows. Keeping the spec in the repository means the next person, or the next agent, inherits the decisions rather than rediscovering them.

A short spec template

A spec for an AI agent does not need to look like a requirements document from twenty years ago. Mine fit on a page and use these headings:

The scope lines do more work than they look. Anthropic's best practices note that Claude tends to read a request conservatively and build the smallest thing that satisfies it, because it cannot see how much you were hoping for. Saying explicitly what is in and out of scope tells the agent how much to build, and prevents the off-spec near-misses I described in the almost-right problem.

Project-wide rules, such as the error helper to use or how to run the tests, belong in the memory file rather than in every spec. I explained what goes there in how to write a CLAUDE.md.

How do you write a good spec quickly?

Let the agent do the drafting and keep the decisions for yourself. The interview approach from Anthropic's best practices works well: describe the feature in a sentence or two, and ask the agent to question you until it could write the spec. It will raise the parts you had not pinned down, such as what happens at limits, who is allowed to do what, and what is explicitly out of scope.

A few rules keep the result useful:

• Write acceptance criteria as things a test can check. "Fast" is not checkable; "the export finishes within the request timeout for the largest current account" is closer.
• List edge cases by name. Empty, duplicate, very large, unauthorised, offline. Named cases become test cases.
• Stay at the level of behaviour. Leave file-by-file decisions for the plan, so the spec stays readable by a client.
• Keep it in the repository. A spec next to the code can be updated in the same pull request as the change it describes.

How big should a spec be?

As small as the task allows. The most useful warning in Böckeler's analysis is about size: on a small change, the structured workflow "was like using a sledgehammer to crack a nut", and the generated documents were "very verbose and tedious to review." She adds: "I'd rather review code than all these markdown files."

I agree, so I scale the spec to the work:

• A bug fix: no spec document. A specific prompt and a failing test that reproduces the bug are the spec.
• A feature: one page using the template above, reviewed before the plan.
• A large or risky change: a spec, a written plan and a task list, reviewed in stages. This is where dedicated tools earn their place.

For that last category, there are tools built around the workflow. Kiro generates three files for every spec, requirements.md, design.md and tasks.md, and moves through requirements, design and task phases. GitHub's Spec Kit describes a process of specify, plan, tasks, implement and converge, where each phase produces a Markdown artifact that feeds the next, and it sets up workspaces for many common coding assistants. Both are useful structures; neither replaces the judgement about how much spec a task deserves.

Work with me

I build AI agents and SaaS products with a spec-first loop, so clients see and approve what will be built before any code is written. See AI agent development and SaaS MVP development, or browse my work and book a scoping call.