Spec-Driven Development for AI Coding Agents
Spec-driven development (SDD) is a practice where a written, testable specification — requirements and acceptance criteria — is the source of truth that code is built against and verified against. Instead of going straight from a prompt or a ticket to code, you first agree on what the software must do, then build to that spec. With AI agents now writing much of the code, the spec is what keeps them building the right thing.
- The spec is the source of truth; code is derived from it and checked against it.
- Requirements pair with explicit acceptance criteria, so "done" is testable, not subjective.
- AI agents query the spec for intent instead of guessing from code — fewer wrong builds.
- It is complementary to test-driven development, not a replacement for it.
Last updated: May 2026
What is spec-driven development?
Spec-driven development inverts the usual order of work. Rather than treating the specification as documentation written after the fact — or skipping it entirely — SDD makes the spec the primary artifact. Code, tests, and review all trace back to it.
A spec in this sense is not a wall of prose. It is structured: a set ofrequirements, each with explicit acceptance criteriathat state, in testable terms, what must be true for the requirement to be satisfied. That structure is what lets a reviewer, a test suite, and an AI agent all interpret the same document the same way.
The spec is also a living artifact. When requirements change, the spec changes first, and the code follows — so the spec never drifts into fiction.
Why it matters now: AI raised the stakes
AI coding agents generate code far faster than a human can read it. That shifts the bottleneck. The hard part is no longer typing the implementation — it isspecifying intent clearly enough that the generated code is the code you wanted. An agent given a vague prompt will confidently produce something plausible and wrong, and at machine speed.
A spec is the guardrail. When the intended behavior and acceptance criteria are written down, the agent has an unambiguous target to build toward and a checklist to verify against — and a human reviewer has a fixed thing to approve before any code exists. SDD is how teams keep AI velocity from turning into AI rework.
How spec-driven development works
The workflow is a loop, not a one-time document:
- Capture intent. Record the half-formed direction — the problem, the goal, open questions — before committing to a solution.
- Specify behavior. Turn the agreed direction into requirements, each with explicit, testable acceptance criteria.
- Decompose into a plan. Break the spec into ordered tasks, each citing the acceptance criteria it satisfies.
- Implement. Build task by task — a human or an AI agent — against the spec.
- Verify against the criteria. Check the result against the acceptance criteria, not against a vibe.
- Keep the spec living. When requirements change, update the spec first; the code follows.
Benefits of spec-driven development
- Disagreements surface during spec review — cheap — instead of after implementation — expensive.
- "Done" is objective, because acceptance criteria are testable.
- The spec is shared context for everyone: product, engineering, and AI agents.
- Changes are traceable — every task points back to the criteria it satisfies.
Why it specifically helps AI agents
- Machine-readable intent: the agent reads requirements directly instead of inferring them from code.
- Less context to load: the agent queries the relevant slice of the spec rather than the whole repository.
- Verifiable output: acceptance criteria give the agent a concrete pass/fail target.
- Traceability: generated code can be tied back to the requirement that motivated it.
Spec-driven development vs related practices
| Practice | Source of truth | Relationship to SDD |
|---|---|---|
| Test-driven development | Failing tests at the code level | Complementary — acceptance criteria become the tests. |
| Traditional PRD | Prose written for humans | Less structured; not directly testable or machine-readable. |
| Prompt-only ("vibe coding") | The prompt and the model's guess | No durable, reviewable target — what SDD exists to fix. |
For a detailed comparison of SpecScore against other spec tooling, seethe comparison pages.
Tradeoffs and when not to use it
Spec-driven development is not free. It front-loads effort into thinking and writing before any code runs, which is the wrong trade for a one-off script or a throwaway experiment. And a spec only helps if it stays current — a spec left to rot becomes misleading, worse than none. SDD pays off when the work is large enough to plan, will be maintained, or will be handed to an AI agent to build at scale.
Doing spec-driven development with AI agents in practice
To run SDD with AI agents you need two things: a machine-readable spec format both your team and your agents understand, and a way for agents to read, write, and validate those specs.
SpecScore is one implementation of exactly that. It is an open Markdown + YAML format for features, requirements, and acceptance criteria — plain files in your repo — paired with a CLI your agents call to query, edit, and lint them. Because the structure is machine-readable, an agent can ask "what should I build next?" and get back the open requirements and their acceptance criteria, then check its work against them. It is tool-agnostic and open source.
Get started with AI Skills for your coding agent orinstall the CLI.
Frequently asked questions
Is spec-driven development the same as test-driven development?
No. TDD drives implementation from failing tests at the code level. SDD works one level up: it fixes the intended behavior and acceptance criteria in a written spec first. They are complementary — acceptance criteria in a spec often become the tests TDD then drives.
Does spec-driven development slow you down?
It adds time before code is written and removes time spent rebuilding the wrong thing. For throwaway scripts the overhead is not worth it. For anything an AI agent generates at scale, or that a team must maintain, writing the spec first is usually faster end to end.
What is the difference between a spec and a PRD?
A PRD is usually prose aimed at humans. A spec in SDD is structured and testable — discrete requirements with explicit acceptance criteria — so both reviewers and AI agents can act on it precisely.
How do AI coding agents use a spec?
When the spec is machine-readable, an agent queries it for the requirements and acceptance criteria relevant to its current task instead of loading the whole codebase, then checks its output against those criteria — a guardrail against plausible-but-wrong code.