Spec-driven development (SDD) is a way of working with an AI coding agent where a structured, reviewed specification, not a chat prompt, is the source of truth: you write and validate the spec first, turn it into a plan and a list of tasks, and only then let the model generate code against it. It is a direct answer to what "vibe coding" breaks once a project grows past a weekend prototype: fast in the first few prompts, then drifting as requirements pile up undocumented in a chat history the model cannot fully hold onto.

Why use spec-driven development

Prompt-only coding works well for small, disposable scripts. Past that, the failure mode is consistent: intent lives only in a chat thread, decisions made twenty prompts ago get silently contradicted by prompt twenty-five, and a reviewer has to reverse-engineer what the code was supposed to do before judging whether it does it. SDD moves intent into a document that survives the session: the spec becomes shared memory for you, your teammates and the model, and review shifts from guessing intent out of a diff to checking a diff against a page that already states the intent.

• ✓Traceability: every piece of generated code maps back to a written requirement, so review becomes "does this match the spec" instead of "what was this supposed to do."
• ✓Consistency over a long task: re-reading the spec re-anchors the model at each step, instead of relying on an ever-growing chat history it can only partially attend to.
• ✓Cheaper reviews: a reviewer reads a short document before code exists, which is faster than reconstructing intent from a large diff after the fact.
• ✓Parallel work: once a spec is broken into scoped tasks, several tasks (or several agents) can run against the same shared contract without colliding.
• ✓Built-in tests: acceptance criteria written into the spec convert almost directly into regression tests, often before the feature is implemented.

Spec-driven development on existing code and for bug fixes

SDD's biggest wins are on bounded, greenfield-shaped work: a new endpoint, a new module, a feature with a clear edge. On existing code it still helps, but the spec changes shape: instead of describing a whole feature, you write a short document stating the current behaviour that must not change, the target behaviour that must change, and the constraints (performance budget, backward compatibility, data migrations). That contract is exactly what prevents the biggest risk of letting an agent restructure internals: silent behaviour drift that only shows up in production.

For a bug, full SDD ceremony is overkill on a one-line, obviously-scoped fix; writing a spec would cost more than the bug. It earns its place once the root cause is unclear or the fix touches several call sites: a short spec of reproduction steps, expected behaviour, constraints, and the regression test to add gives the agent a concrete target to converge on, and gives you something to check the diff against instead of trusting that it "looks right." The rule of thumb: reach for SDD when a change crosses a module boundary or touches a public interface; skip it for a trivial, local fix.

Using SDD to build a new feature

The workflow popularized by current SDD tooling runs in four steps, each producing an artifact the next step consumes.

• ✓Specify: describe what the feature does and why in plain language, focused on user-visible behaviour and constraints, not implementation.
• ✓Clarify: an assisted pass where the model flags ambiguity and open questions in the spec, resolved before any code exists.
• ✓Plan: turn the validated spec into a technical plan: architecture, data model, endpoints, libraries chosen.
• ✓Tasks and implement: break the plan into small, independently checkable tasks, then let the coding agent implement them one at a time, checking each against the spec and running tests before moving on.

## Feature: password reset

### User story
As a user who forgot my password, I can request a reset link by
email and set a new password from it.

### Acceptance criteria
- Link expires after 30 minutes.
- Old password stops working only after the new one is confirmed.
- Rate-limited to 3 requests per hour per account.

### Out of scope
- Password strength meter (existing rule reused as-is).

Spec-driven development tools

How spec-driven development integrates with the LLM

The spec is not dropped into one giant prompt and forgotten. Each step of the workflow compiles part of it into the model's working context: the plan step feeds the validated spec back in to produce a technical plan, the tasks step further compiles that plan into units small enough to fit one agent turn, and the implement step re-injects the specific task plus the relevant slice of the spec, not the whole document, on every turn. That keeps the agent anchored to the same requirements many turns later, which a long freeform chat cannot guarantee once earlier decisions scroll out of context.

The other half is verification: after generation, the output is checked back against the spec's acceptance criteria, either by the model in a self-check pass or by the actual test suite the criteria were turned into. A mismatch reopens the task instead of silently shipping a drifted implementation. In practice, an SDD workflow usually runs as slash commands inside an agentic coding tool, which is itself a model in a tool-calling loop (see our guide to building an AI agent); when a task needs to reach outside the repository, that is typically wired through MCP servers rather than one-off integrations (see what MCP is). The model doing the planning and generation still has to be capable of reliable multi-step reasoning, which is part of what to weigh when you choose an LLM for a product.

Advantages and limits

Spec-driven development is not a way to skip technical judgment, it is a way to write that judgment down before the model starts generating code, so it can be checked, reused across tasks, and re-read by the agent at every step instead of falling out of a chat history. Reach for it on anything that crosses a module boundary or defines a new feature; skip the ceremony on a trivial fix where a spec would cost more than the bug.