Spec-driven development with Claude Code: write intent before code

You ask Claude Code for a feature. It reads some files, makes reasonable assumptions and builds something that works. It just isn’t what you meant. The data lives in the wrong place, the edge case you cared about is missing, and the fix is half a rewrite. Then you explain what you meant, and the agent explains it back to you in code, and you are an hour in.

Spec-driven development is the name for not doing that. You write down what you want and how to prove it works before the agent writes anything. It sounds like waterfall. In practice it is closer to a good ticket, written for a reader that takes every word literally.

What spec-driven development means for AI agents

The idea is old. What’s new is who reads the spec. A human developer fills gaps from context, asks in Slack and notices when something feels off. An agent fills gaps with the most statistically plausible guess and keeps going with confidence. So the cost of a missing sentence in the spec went up, and the cost of writing the spec went down, because the agent can draft most of it for you.

The tools converged on a similar shape. GitHub’s open-source Spec Kit splits the work into a project constitution (principles that hold for every feature), then for each feature a specification of what and why, a technical plan, a task list and implementation, with a final step that checks the result. It works with many agents through integrations, and Claude Code is one of them. Amazon’s Kiro produces three files per feature: requirements.md with user stories and acceptance criteria, design.md with architecture and data flow, and tasks.md with trackable implementation tasks.

You don’t need either tool to work this way. You need the stages and the discipline to not skip them.

Spec-driven development with an agent

• Person
• Agent
• Automated check

Steps as text

Step	What happens
1. Spec	Person — what and why, by a person
2. Plan	Agent — agent drafts the technical approach
3. Criteria	Automated check — each one a command that can fail
4. Build	Agent — one task at a time
5. Verify	Automated check — criteria run, reviewer reads diff
Loop	findings go back: back from step 5 to step 4
Loop	plan shows a gap in the spec: back from step 2 to step 1

What a good spec for an AI agent contains

Most specs fail by being either a wish or a design document. A wish (“users should be able to export their data”) leaves every decision to the agent. A design document dictates the implementation and leaves no room for the agent to be useful. The useful spec sits between them.

Here is what I put in one:

• The problem, in one paragraph. Who has it and what they do today. This is what the agent uses to break ties.
• Scope and non-scope. What is in this change and, just as important, what isn’t. Agents love to helpfully refactor the neighbouring module.
• Behaviour, as examples. Given this input or state, this happens. Three concrete examples beat a paragraph of rules.
• Constraints. Where data may live, which libraries are allowed, performance budgets, what must not change.
• Acceptance criteria with commands. Every criterion has a way to fail. “Export works” is not a criterion. “npm test -- export.spec.ts passes, and exporting the fixture account produces a file that matches fixtures/export.json” is.
• Open questions. Things you haven’t decided. Saying so stops the agent from deciding silently.

The last two are where most of the value is. I wrote more on the criteria part in acceptance criteria an agent can’t talk its way around.

Spec line	Problem	Better version
“Make search faster”	No finish line	“p95 of /search?q= under 200 ms on the seed dataset, measured by bench/search.sh”
“Handle errors properly”	Agent decides what proper is	“On a network timeout, show the retry banner. Never show a raw error string”
“Add tests”	Agent writes tests that pass by construction	“A test that fails on the current main and passes after the change”
“Use best practices”	Means nothing	Name the pattern, or link to the file that already does it right
“Refactor as needed”	Unbounded diff	“Only files under src/export/ may change”

Why the plan needs a challenger before code

A spec is half the job. The other half is the plan, and plans are where agents make their most expensive mistakes, because a wrong plan looks fine until it has been half implemented.

The cheapest way I know to catch a bad plan is to get two independent ones. Two models read the same spec, each writes an approach without seeing the other, and then one lists only the material disagreements. Usually there are two or three: where state lives, how a failure is handled, which existing module to extend. Those are exactly the decisions a person should glance at, and they take a minute to settle on paper and an hour to undo in code.

I measured this on one task and published the numbers: rebuilding a mobile game from a video, given to three setups. The writer model was the same in all of them.

Tokens processed on the same task

Three setups, same writer model

Data as a table

	Value
Claude Code alone	389 M
Claude plus one review at the end	155.6 M
Two independent plans before code	34.3 M

The setup with independent plans before code also finished fastest, 1.5 hours against 3.7 for Claude alone, and with no broken mechanics against about 13 bugs counted by hand. It is one task, and the full caveats are in the write-up of the review loop. The pattern still matches what the spec-driven tools are built around: decisions made in writing are cheap, decisions discovered in code are not.

How to do spec-driven development in Claude Code

You can start with plain files and a few habits. This is the order I’d follow.

1. Keep project rules in CLAUDE.md. This is your constitution: stack, conventions, commands to build and test, things the agent must never do. Keep it short and specific, because it is loaded into every session.
2. One spec file per feature. For example specs/export/spec.md. Ask Claude to draft it from your description, then edit it yourself. Your edits are the point. Mark open questions explicitly.
3. Ask for a plan, not code. Plan mode in Claude Code is made for this. Have the plan written to specs/export/plan.md. Read it, or have a second model read it and list disagreements only.
4. Turn criteria into commands. A specs/export/checks.sh that exits 0 only when every criterion holds. If a criterion can’t be checked by a command, rewrite it until it can or accept that a person must check it.
5. Write a task list the agent can’t rewrite. Anthropic’s team, describing their harness for long-running agents, kept a feature list in JSON with every item marked as failing and allowed the agent to change only the passes field. They chose JSON because the model was less likely to edit it inappropriately than Markdown. Copy that idea.
6. Build one task at a time, and gate the stop. A Stop hook that runs checks.sh and returns "decision": "block" with the output when it fails keeps Claude working until the criteria pass, instead of until it feels finished.
7. Review against the spec, not the summary. The reviewer gets the spec, the diff and the check output. It should answer one question: does this change do what the spec says, and nothing else?

If you prefer a ready structure, Spec Kit installs these stages as commands for Claude Code and other agents. I’d still read what it generates as critically as code, because a generated spec has the same failure mode as generated code: it looks complete.

Where spec-driven development goes wrong

The common failure is ceremony. Teams adopt the stages and then fill them with text nobody reads: a twelve-page requirements document for a button, a plan the agent wrote and approved itself. That is slower than vibe coding and not safer.

Three rules keep it honest. The spec is as long as the decision is risky: a typo fix needs one line, a payment flow needs a page. A person edits the spec, even if the agent drafts it, because the point is to put your intent on paper, not to produce paperwork. And every criterion has a command, because a criterion nobody can run is a wish.

The other failure is a spec that freezes. Agents surface gaps fast, and the plan stage often shows that the spec was wrong. Go back and fix the spec rather than patching around it in code, so the next run starts from the truth. For the wider argument on why this discipline matters, see vibe coding vs agentic engineering.

The work that moves to the person

Spec-driven development changes where a developer’s time goes. Less typing, less reading of diffs line by line, more deciding what should exist and how to know it works. That is the part of the job that was always the hardest to delegate, and it turns out to be the part that makes agents productive.

I think this is where most of the gain from AI-assisted development sits right now. A model is only as good as the question it is answering. A team that writes precise intent can keep several agents busy on real work, with people stepping in for the decisions that need them. A team that writes wishes gets plausible code and a long afternoon. If you want help setting up this kind of workflow for a team, write to me.

Questions

What is spec-driven development with AI?

It is a workflow where you write a specification, a technical plan, a task list and checkable acceptance criteria before an AI agent writes code. The agent then implements one task at a time and the criteria decide when it is done.

Does GitHub Spec Kit work with Claude Code?

Yes. Spec Kit supports Claude Code as one of its agent integrations, alongside GitHub Copilot and others, and adds its specify, plan, tasks and implement stages as commands in the agent.

How is a spec for an AI agent different from a normal ticket?

It has to state scope and non-scope, give behaviour as concrete examples, and pair every acceptance criterion with a command that can fail. A human fills gaps from context; an agent fills them with a confident guess.

Isn’t spec-driven development just waterfall again?

No, because the cycle is one feature and often less than a day, and the plan stage regularly sends you back to fix the spec. The writing is short; what it removes is the hour of building the wrong thing.