Spec-Driven Development
Spec-driven development (SDD) is an approach to building software in which a written specification of what the system should do is created before any code, and that specification then guides and constrains the implementation. In AI-assisted development, the spec becomes the shared source of truth for both the humans and the AI coding agents, replacing loose, one-off prompts.
How Spec-Driven Development Works
Most SDD workflows move through a sequence of reviewed artifacts. GitHub's open source Spec Kit, for example, uses four phases:
- Specify: describe what is being built and why, in terms of users, journeys, behavior and success criteria. Technology choices stay out of this step.
- Plan: decide the technical approach, including architecture, stack, data flow and constraints.
- Tasks: break the spec and plan into small, reviewable units of work that can be built and tested independently.
- Implement: an agent or developer builds each task, checking the work against the spec.
Humans review at each checkpoint, so a misunderstanding is caught in a few lines of text instead of hundreds of lines of code.
A spec in this sense is a structured, behavior-focused document in natural language. It usually includes requirements, defined states, acceptance criteria, edge cases and what is out of scope. It differs from standing project instructions (sometimes called a memory bank or steering files), which apply to every task in a codebase. A spec is specific to the functionality it describes.
Writer and engineer Birgitta Boeckeler, writing on martinfowler.com, distinguishes three levels of commitment:
- Spec-first: a spec is written before the work, then set aside after the task.
- Spec-anchored: the spec is kept and updated as the feature evolves.
- Spec-as-source: the spec becomes the main maintained artifact, and humans edit the spec rather than the generated code.
Why Spec-Driven Development Matters
AI coding agents are good at following instructions and poor at guessing intent. Given a vague prompt, an agent fills gaps with plausible assumptions, and across many tasks those assumptions drift from what the business approved. SDD moves the important thinking into a document people can review, so the agent has less to guess.
GitHub's announcement put the shift plainly: the move is from code being the source of truth to intent being the source of truth. That has practical benefits. Decisions are written down once. New tasks and new agents start from the same reference. Changes happen in the spec first and flow into tasks and code, which supports requirements-to-code traceability.
SDD has costs too. Writing and maintaining specs takes time, and an overly heavy spec process can slow down small changes. Teams usually match the depth of the spec to the size and risk of the change.
Spec-Driven Development Example
A team needs a feature that lets customers export their invoices. Instead of prompting an agent with "add invoice export," the product manager writes a short spec: users can export invoices from a selected date range, formats are CSV and PDF, exports over 1,000 invoices run in the background and send an email, and deleted invoices are excluded. It also states that scheduled recurring exports are out of scope.
An engineer reviews it and adds a plan: reuse the existing reporting queue, store files for seven days. The agent then breaks the work into tasks, each tied to a line of the spec, and implements them one at a time with tests that check the stated rules. When the team later decides to keep deleted invoices in exports for accounting reasons, they change the spec, and the affected task and test are updated from it. For the requirement side of this, see how to write a PRD an AI coding agent will not misinterpret, and for staging decisions before handing work to an agent, the multi-stage vibe coding architecture for Claude Code.
Spec-Driven Development vs. Vibe Coding
Vibe coding starts from a prompt and judges the result by running it. Spec-driven development starts from a reviewed description of intended behavior and judges the result against that description. Both use AI to write code; the difference is where the decisions are made and recorded. SDD also differs from test-driven development: TDD writes failing tests first at the code level, while SDD writes a human-readable specification first at the product and behavior level. The two are often combined.