Spec-Driven Development (SDD)
Spec-Driven Development emerged as a response to an increasingly visible limitation of AI-assisted development: the ease of generating code does not guarantee that the code is correct, maintainable, secure, or consistent with the product's architecture.
In approaches such as vibe coding, the practitioner describes what they want in natural language, the AI generates a solution, and the team tests, fixes, and asks for changes again until something seems to work. This approach can be very useful for prototypes, rapid exploration, or low-risk internal tools. The problem arises when the same way of working is used for production code.
SDD changes the order of work: first you specify, then you implement. The spec becomes the operational contract between the human team and the AI agent.
The spec is not just a preliminary document: it is the primary artifact of development, the one a person reviews and approves and the one the agent consumes to generate code. That is why review shifts from the code to the spec, and SDD is organized around approval gates between phases.
What problem it solves
AI can generate code very quickly, but that speed shifts the bottleneck toward review. The team no longer spends as much effort writing code from scratch; instead, it spends that effort understanding, verifying, correcting, and integrating code produced by another system.
SDD helps reduce that burden because it provides an explicit benchmark against which to review the result. The team does not review the code wondering "what has the AI done?" but compares the implementation against a previously agreed specification.
In practice, SDD aims to reduce three common problems of AI-assisted development:
- Ambiguity: when the prompt is vague, the agent makes implicit decisions that may not match the team's intent.
- Review burden: the greater the volume of generated code, the harder it becomes to detect subtle errors.
- Technical debt: if the AI generates plausible solutions that are inconsistent with the architecture, the cost shows up later in maintenance, security, or the evolution of the product.
The evidence on AI's real productivity is under review. METR's controlled trial from July 2025 found that experienced developers took longer with AI while believing they were going faster; in February 2026 METR announced it was redesigning the experiment, and its own author considers it likely that the real speedup is greater. The finding is cited with its date and its caveat, and the argument rests on the gap between perception and measurement, not on the figure. What does hold up, with more recent evidence, is the diagnosis of the cost: DORA's report on the return on AI describes the verification tax (reviewing generated code consumes what generation saves) and the J-curve (productivity drops before it rises). DORA supports the problem; it does not name specifications among the return factors, so it should not be credited with endorsing SDD.
How it works
SDD is not a specific tool or plugin. It is a working methodology that can be implemented with different tools, agents, or development workflows.
The method has a stable backbone: four phases, with one document per phase.
- Requirements: what problem is being solved, for whom, with what expected behavior, and what is out of scope.
- Design: technical decisions, architectural constraints, integration with what already exists, data, APIs, and non-functional criteria.
- Tasks: the implementation broken down into small units that can be reviewed and executed by an agent or by a person.
- Implementation: the agent generates the code following the spec, and the team reviews, tests, and integrates the result.
Reference implementations have also established two wrappers around that core. Before the requirements, the project constitution captures what is decided once for the whole project (principles, standards, architecture, and limits on what the agent may do) and persists above the individual specs. GitHub Spec Kit creates it with the first command of its workflow, and in the rest of the ecosystem it lives in an agent instructions file at the root of the repository. After implementation, the convergence review checks that what was built matches what was specified. It is the only review in the method that looks at code, and without it no one has verified that the implementation meets the spec, which is where drift between the two begins.
The key is not writing extensive documentation, but writing operational documentation: just enough for humans and agents to share the same interpretation of the work.
Approval gates
Between each pair of phases there is a point where a person with sound judgement reviews and approves the document produced before moving on to the next one. The first gate checks that the right problem is being solved; the second, that the design is viable and consistent with the existing code; the third, that the tasks, in that order, produce the design. All three review text, not code, which is why people who do not program can take part. The reason is economic: an ambiguous acceptance criterion is fixed at the requirements stage by rewriting a sentence, and at the implementation stage by discarding and regenerating code. A gate that is crossed without reading detects nothing and gives a false guarantee.
Proportionality
The intensity of the process is scaled to the size of the problem. A minor defect does not need a four-phase spec; a feature that affects several parts of the system does. A single question does the calibrating: what happens if the agent makes the wrong decision at this point? If the answer is "I'll fix it in two minutes," that point does not need to be specified; if it is "I'll lose hours or introduce a subtle defect," it does. Poorly calibrated, SDD turns into specification bureaucracy, and the team ends up avoiding the entire workflow, including the gates that actually protected it.
Adoption levels
Not all teams apply SDD with the same intensity. A useful way to understand it is to distinguish three levels:
| Level | How it works | When it makes sense |
|---|---|---|
| Spec-first | The spec is written before coding, used for the current task, and can be discarded once it is finished. | It is the simplest entry point. Useful for teams starting to organize their work with AI. |
| Spec-anchored | The spec is kept after implementation and updated as the feature evolves. | Useful when the feature will be maintained, extended, or reviewed later on. |
| Spec-as-source | The spec is treated as the primary artifact. Code is generated or regenerated from it. | It is the most advanced level and still experimental in many contexts. It requires a great deal of discipline and mature tooling. |
Most teams start with a spec-first approach. Trying to jump straight to spec-as-source can create more rigidity than value if the team lacks solid validation, testing, and review practices.
Ecosystem tools
The tooling around SDD is the most volatile layer of the method: the reference implementation releases new versions frequently, and alternatives come and go, so any list of names and versions goes out of date within weeks. What does remain stable are the criteria for choosing a tool:
- Lightweight or full workflow. Some implement the entire workflow (constitution, phases, gates, and convergence); others are limited to organizing specs and their changes. The principle of proportionality also applies to choosing the tool.
- New project or existing code. Some tools are designed for starting from scratch, while others describe themselves as brownfield first and can describe what already exists.
- Command line or integrated environment. The former plugs into the team's workflow and works with the agent it already uses; the latter imposes its own workflow and its own agent in exchange for a more guided experience.
- Governance and traceability. How much the team needs the tool to record, version, and make auditable; this carries more weight when the product falls within the scope of the EU AI Act.
GitHub Spec Kit, the most widely adopted implementation, released version 1.0 in August 2026, and the method now has its own entry in the Thoughtworks Technology Radar, formal training, and academic literature. No tool is essential for applying SDD, and mastering a tool is not the same as mastering the method.
Relationship with user stories
SDD does not replace user stories. It complements them.
The user story helps express intent, user, need, and value. It is an artifact for conversation between people. The spec translates that intent into a more precise, verifiable format that an AI agent can execute.
A simple way to tell them apart:
| Artifact | Main function | Question it answers |
|---|---|---|
| User story | Communicate value and need from the user's perspective. | Who are we building this for, and why does it matter? |
| Spec | Define behavior, constraints, and verification criteria. | What exactly must be produced, and how will we know it is right? |
In AI-enabled teams, a story can still be the starting point of the backlog, but the tasks an agent is going to carry out need a sufficiently clear spec.
Relationship with TDD and BDD
SDD does not compete with TDD or BDD. The three approaches are complementary and can be applied together:
| Practice | Focus | Question it answers |
|---|---|---|
| SDD | Specification. Defines the what and the why before implementation. | What exactly must be built, and under what constraints? |
| TDD | Unit-level quality. The test comes before the code. | Does this unit of code do what it is supposed to do? |
| BDD | System behavior. Scenarios in Given-When-Then format. | Does the system behave the way users and stakeholders expect? |
In practice, a team can use:
- SDD to define a complete feature,
- TDD for each individual implementation task,
- and BDD for end-to-end validations.
SDD acts as a shared context layer that keeps humans and agents aligned throughout the entire process.
SDD in Scrum Teams with AI
In Scrum with AI, specs serve as a bridge between the classic artifacts and the work carried out by agents.
The spec does not replace the backlog or refinement. In the Product Backlog and during refinement, the team agrees on the goal, context, and priority; the detailed contract (requirements, design, and tasks) matures within the sprint, as part of doing the work and with information that only emerges once the work begins. The most common integration mistake is putting the full spec into the Product Backlog: this turns it into a repository of documents that become outdated before they are executed and gives the team a sense of waterfall once again. The approved spec is the Definition of Ready for that feature, expressed in the language of SDD.
The sprint now contains two types of items, specs to be written and approved specs ready to be implemented, and Sprint Planning decides how many of each type are taken in. Estimation splits in two: specification effort is human and consumes the team's real capacity, while implementation effort falls mainly on the agent. The Daily Scrum focuses on the status of the specs and their deviations, and code review is carried out against the spec, not just against the reviewer's judgement.
They also connect to a strengthened Definition of Done. AI-generated code should not be considered done just because it compiles or because the agent claims it works. It must pass technical reviews, tests, security checks, and human review.
In teams working with AI, the spec does not eliminate human responsibility. The agent can generate the implementation, but the team remains responsible for validating that the increment meets the expected quality, security, and value criteria.
SDD and Agility
A common objection is that SDD "sounds like waterfall": requirements, design, tasks, and implementation before there is any working software.
The objection deserves to be taken seriously. If SDD turns into heavy documentation, bureaucratic approval, and blocked learning, it conflicts with agility. But SDD does not have to be applied that way.
The difference lies in how the spec is used. In an agile approach, the spec is not a contract closed off to change, but a living artifact for reducing ambiguity before delegating work to an AI. It can be iterated on, broken down, checked with users, and revised as new information emerges.
SDD shares sequentiality with waterfall, but differs along three axes. Scope: the sequence applies to each increment, not to the entire project, and the full cycle is measured in hours or days. Feedback: it arrives at each approval gate, not at the end. Reversibility: the phases prior to implementation are text documents, and modifying them is trivial compared to rewriting code. Furthermore, the spec is a new category of documentation, operational documentation: it does not inform a person or fulfill a formality; it is the input the agent consumes to produce working software, and that is why the Agile Manifesto's preference ("working software over comprehensive documentation") does not apply to it in the same way.
The objection has named advocates, and they are worth reading. François Zaninotto (Marmelab, November 2025) titled his critique "Spec-Driven Development: The Waterfall Strikes Back" and lists real failures: huge documents that nobody reads, loss of code context, duplicated review, and a false sense of security. These are the method's antipatterns seen from the outside. The Thoughtworks Technology Radar keeps SDD in the "Assess" ring without promoting it to "Trial": it recommends evaluating it when requirements are ambiguous, teams are distributed, or traceability is needed, and warns that it may not pay off for trivial problems.
The practical test is simple: if the spec helps deliver working software with fewer errors, better learning, and less technical debt, it reinforces agility. If it becomes a documentation requirement that delays validation, it weakens it.
When to use SDD
SDD is especially useful when:
- AI-generated code is going to reach production;
- the feature affects data, security, permissions, billing, or critical user experience;
- there are architectural constraints the agent must respect;
- the team is working on an existing product, especially in brownfield contexts;
- several people or agents need to coordinate on the same feature;
- the cost of reviewing ambiguous code is higher than the cost of writing a good spec.
It may be overkill when the goal is to explore a very early idea, build a throwaway prototype, or validate a hypothesis in a fast learning lane. In those cases, it may make more sense to start with vibe coding and move to SDD once the idea deserves to become a robust product.
SDD and AI
SDD becomes especially relevant with generative AI because coding agents are highly sensitive to the quality of the context. When the instruction is vague, the agent fills in the gaps with likely patterns. Sometimes it gets it right. Other times it introduces invisible decisions that the team discovers too late.
A good spec reduces that unwanted freedom. It defines expected behavior, boundaries, dependencies, acceptance criteria, technical constraints, and edge cases. It does not make AI infallible, but it improves the quality of delegation.
In this sense, SDD transforms the role of the developer. The value does not disappear: it moves elsewhere. What gains weight is the ability to write specs, design architecture, critically review AI outputs, and decide what should be automated and what should remain under human control.
Limitations
SDD has limitations worth knowing before adopting it:
- Writing good specs is hard. It requires clarity of thought, domain knowledge, and the discipline to think before acting. In projects where requirements are rarely fully formulated before implementation, the spec can become an aspirational artifact rather than an operational one.
- The overhead can be disproportionate for small tasks. For simple features or minor bug fixes, the specification process can create more work than it saves. SDD makes the most sense when the complexity of the feature justifies the upfront investment.
- Specs do not eliminate model non-determinism. A detailed specification reduces the agent's unwanted freedom, but does not eliminate it. Language models can ignore instructions, overreach in their interpretation, or generate outputs that meet the spec to the letter but not in spirit. Human review is still necessary.
Common mistake
Confusing SDD with waterfall documentation. SDD is not about writing lengthy documents to freeze the plan before building. It is about creating operational specifications that are reviewable and precise enough for an AI agent to carry out work without inventing critical decisions. If the spec prevents learning, iterating, or responding to change, it is being misapplied.
Resources
📊 Guía didáctica SDD [SDD Teaching Guide, in Spanish]Resources · Scrum Manager
🏦 SDD en equipos ágiles [SDD in Agile Teams, in Spanish]Skill Arena · Scrum Manager
References
- AGENTS.md.
- Beck, Kent et al. (2001). “Manifesto for Agile Software Development”, AgileManifesto.org.
- Becker, Joel; Rush, Nate; Barnes, Beth; Rein, David. (2025). “Measuring the Impact of Early-2025 AI on Experienced Open-Source Developer Productivity”, METR.
- Böckeler, Birgitta. (2025). “Understanding Spec-Driven-Development: Kiro, spec-kit, and Tessl”, MartinFowler.com.
- Díaz, Gayoso, Cimmino, and Pérez (2026), “Spec-Driven Development for Agentic Software Engineering”, ArXiv.
- DORA. (2026). “ROI of AI-assisted Software Development”, DORA.
- GitClear. (2025). “AI Copilot Code Quality: 2025 Look Back at 12 Months of Data”, GitClear.
- GitHub. (2025). “Spec-driven development with AI: Get started with a new open source toolkit”, GitHub Blog.
- Mavin, Alistair. EARS.
- METR. (2026). “We are changing our developer productivity experiment design”, METR.
- OpenSpec.
- Scrum Manager. (2026). SDD – Spec Driven Development en equipos ágiles [SDD – Spec-Driven Development in Agile Teams; in Spanish]. Scrum Manager.
- Scrum Manager. (2026). Scrum en equipos con IA [Scrum in Teams with AI; in Spanish]. Scrum Manager.
- Thoughtworks. Technology Radar, “Spec-driven development”, Thoughtworks.
- Wessling, Jens. (2025). “We Asked 100+ AI Models to Write Code. Here’s How Many Failed Security Tests”, Veracode.
- Yeret, Yuval. “Is Spec-Driven Development a step forward or back for product development?”, YuvalYeret.
- Zaninotto, François. (2025). “Spec-Driven Development: The Waterfall Strikes Back”, Marmelab.
See also
Want to grow in agility? You can search for course and exam calls, or go at your own pace by becoming a member of the Agile Club. This membership includes exclusive resources, e-learning classrooms, and access to Skill Arena: a space to practice and measure your agile skills at your own pace.