Everything You Need to Know About Spec-Driven Development

Spec-driven development starts with a written description of what the software must do, and uses that description to drive the code. With AI agents, the spec becomes the input the agent works from, and the code becomes a result you check against it.

The idea is older than agents. What is new is that a spec now produces working code in minutes, which makes an unclear spec expensive in a new way.

What a spec contains

A useful spec is short and specific. It usually covers:

• The goal: what the feature is for and who uses it.
• The behaviour: what happens in the normal case, and in each important failure case.
• The interfaces: the inputs, outputs, and any API shapes that other code depends on.
• The constraints: performance, security, data handling, and what must not change.
• The acceptance checks: the tests or steps that prove the feature works.

A spec that lists acceptance checks is far more useful than one that describes intent in prose.

Writing for an agent

An agent can work from a vague spec, but it will fill the gaps with guesses. Write each requirement so it can be checked. "Users see an error" is vague. "If the payment service times out after five seconds, show a retry message and do not charge the card" can be tested.

Keep the spec in the repository, next to the code. A spec that lives in a chat thread is lost when the thread ends.

The loop

1. Write or update the spec.
2. Give the agent the spec and the acceptance checks.
3. Let the agent implement, and run the checks.
4. Review the diff against the spec, not against your memory of the conversation.
5. When the spec changes, change the spec first, then the code.

The order matters. If the code changes and the spec does not, the spec becomes a description of the old system.

Where it goes wrong

• The spec is too long to read. A spec nobody reads is not a spec. Keep it short and link to detail.
• The spec is too vague to test. Requirements without checks invite guessing.
• The spec drifts. When people change the code and forget the spec, the two disagree, and the agent follows whichever one it reads last.
• The spec is written after the code. A spec written to describe existing code records its mistakes.

Generated infrastructure

Some parts of a system are best driven by a spec too. In TDK CLI, each service's service.json is the input, and the runtime files are generated from it. Editing the generated output is the mistake, because the next generation overwrites it. Drift checks compare the generated files with saved snapshots, so a hand edit is reported before the stack starts.

Summary

Spec-driven development makes the intended behaviour explicit and checkable before code is generated. Keep specs short, testable, stored with the code, and updated before the implementation changes. A good spec is the cheapest way to make an agent's work reviewable.