What is Spec-driven development?
Writing the specification first — requirements, design, tasks — and having agents implement from it, so the spec is the source of truth, not chat history.
Agents are literal: the brief carries all the context they will ever get, so a disciplined spec is the cheapest way to get work that is right the first time.
On this page
Spec-driven development is the practice of writing a structured specification before implementation — what to build and why, how it should work, and how it breaks into tasks — and having AI coding agents implement from that specification, treating the spec as the source of truth rather than a chat transcript. The specification is written to be read by a machine: precise enough that an agent can implement it without asking questions, and durable enough that the finished work can be checked against it.
The practice went mainstream in 2025 as coding agents made the cost of a bad brief obvious. A chat-driven agent implements the wrong reading of a vague prompt as diligently as the right one; the fix is to move the ambiguity upstream, into an artefact that can be reviewed before any code exists.
Why spec-driven development matters
Two forces make the spec first-class with agents, where it was optional with humans.
First, agents cannot lean over and ask. A human developer fills gaps in a ticket from hallway context — the Slack thread, the memory of a standup conversation. An agent gets only what the brief says, so gaps become guesses. Everything the agent needs — goal, constraints, scope, how to verify — has to live in the artefact.
Second, the spec is the only thing verification can be measured against. Acceptance criteria written before implementation give review and QA an independent yardstick: work is checked against what was asked, not against what was built. When criteria are written afterwards — or never — review drifts toward checking the code against itself, which is how false greens survive.
The economics also shift. Reviewing a spec is minutes; reviewing a wrong implementation is hours, plus the rework loop. Moving the argument before the code is the cheapest quality intervention available in agent-driven work.
How spec-driven development works
The public toolkits converge on the same three artefacts. GitHub's open-source Spec Kit runs agents through structured phases — /speckit-specify, /speckit-plan, /speckit-tasks, /speckit-implement — each producing a documented outcome. AWS's Kiro generates three files per spec: requirements (user stories with acceptance criteria in EARS notation), design (architecture and sequence diagrams), and tasks (a tracked implementation plan with a dependency graph).
| Stage | Artefact | What it answers |
|---|---|---|
| Specify | Requirements | What should be true when this is done? User stories, acceptance criteria |
| Plan | Design | How will it work? Files touched, architecture, trade-offs |
| Tasks | Task breakdown | In what order? Dependencies, what can run in parallel |
| Implement | Code + tests | The work itself, checked against the spec at review |
The stages are a funnel: each one narrows ambiguity while changes are still cheap. A wrong requirement caught at specify costs a paragraph edit; caught after implement, it costs a rework loop through review.
Spec-driven vs chat-driven work
| Chat-driven | Spec-driven | |
|---|---|---|
| Where intent lives | Scattered across messages | One versioned artefact |
| When ambiguity is caught | During code review — or after | At the spec, before code exists |
| What the next person sees | Whatever the chat log preserved | The spec, the tasks, and their status |
| Verification target | "Looks right" | The acceptance criteria, mechanically checkable |
| Best fit | Exploration, one-off questions | Production features, multi-agent work |
The approaches are complementary. Exploration genuinely is chatty — you do not write a spec to find out whether an idea is any good. Spec-driven development starts when the idea graduates into work someone will build and maintain.
Best practices for spec-driven development
1. Write acceptance criteria that can be checked mechanically
"Works correctly" is not a criterion. "Missing key returns 401; invalid key returns 401; a busy agent's row carries its current ticket, the rest null" is. Every criterion should be phrased so that review or QA can pass or fail it without judgement calls.
2. Keep the spec versioned, not alive in chat
The spec is an artefact with history: what was believed when the work was written, and what changed since. A spec that lives in a scrolling thread cannot be reviewed later and cannot settle arguments about what was asked.
3. Let the spec decide scope arguments, not the implementer
When review and the implementing agent disagree about what was asked, the spec settles it. If the spec cannot settle it, the spec is the defect — fix the criterion, not the code.
4. Size specs to one reviewable outcome
A spec that covers six features gets implemented in six directions at once and reviewed nowhere. One spec, one coherent outcome, a task breakdown small enough to finish before the requirements move.
5. Don't gold-plate the document
A spec is not a 40-page design doc. The test is coverage of the decisions the agent cannot make on its own — scope, constraints, acceptance — not thoroughness for its own sake. Everything else is noise the agent will dutifully read.
Spec-driven development in YATFA
YATFA runs this pipeline as its core loop: a direction is proposed and sliced, each slice becomes a ticket whose description carries the requirements and acceptance criteria of record, agents implement from the ticket, and review plus QA verify against those criteria — with the evidence attached. The spec and the ticket are the same document on purpose: see directions and tickets and how YATFA reviews changes.
Frequently asked questions
Is spec-driven development only for AI agents?
No — it is good discipline generally. Agents simply raise its value: they cannot fill gaps with hallway context, so the spec's completeness stops being optional. Teams that wrote tickets for humans will find agents need the same things, stated more explicitly.
Does writing a spec first slow down agent work?
It moves time, it does not add it. Minutes of specification replace the expensive loop — implement, review bounce, re-implement — that vague briefs produce. The research on agent productivity shows output is not the bottleneck; absorption and verification are, and the spec is what makes both tractable.
What goes in the spec vs the ticket?
They can be the same document. If they are separate, the spec holds what should be true (requirements, design, criteria) and the ticket holds the unit of dispatch (who builds it, in what order, against which dependencies). YATFA merges them: the ticket's description is the requirements of record.
How detailed should acceptance criteria be?
Detailed enough that a checker could fail the work. A useful habit: write each criterion as a sentence whose negation is observable. "The API docs page lists every public route with a description" fails visibly when a route is missing its entry — that is a good criterion.