SDD (Spec-Driven Development)
SDD is about shared understanding — a common mental model that engineers, product managers, and AI agents can follow. The spec is a communication tool, not a blueprint.
Three Roles
| PM | Engineer | AI | |
|---|---|---|---|
| Owns | Business need | Design concept | Implementation |
| Decides | What and why (business) | What and why (technical) | How |
The PM defines the problem. The engineer designs the solution. The AI builds it. For smaller features, the engineer takes both the PM and engineer roles.
What Belongs in a Spec
Include: the problem being solved, why it matters, what interfaces and schemas change, what constraints must be respected.
Leave out: production code, implementation details, step-by-step instructions, anything that prescribes how instead of what.
Specs with production code become a source of bugs. Untested code gets copied blindly. The engineer does the builder’s job poorly. Keep the spec at the design concept level.
A good spec is short enough to read, specific enough to align on, and loose enough to leave room for discovery.
The Iteration Loop
The first spec is never the final answer. Treat the first implementation as a learning tool.
Spec → Build → Discover → Revise → Rebuild.
- Write the spec with the important decisions.
- Let AI implement everything.
- Look at the real code — test it, run it.
- Find the gaps the spec missed.
- Update the spec with what you learned.
- Rebuild.
Implementation is cheap now. Use that speed to iterate on understanding, not to ship the first attempt.
Match Process to Risk
Not every change needs a spec. Match process to risk.
| Change | What it needs |
|---|---|
| Bug fix | Plan mode → fix |
| Small feature | Plan mode → build |
| Large feature | Full spec → plan mode → build |
Always start with plan mode. Even for bug fixes, plan mode surfaces context you might miss. The variable is how much spec work comes before the plan.
One question decides it: can one engineer hold the entire change in their head? If yes, skip the spec. If no, invest in a proper spec.
Smaller Teams, Better Specs
Fewer people need to align → simpler specs → faster decisions → more coherent design. Communication overhead grows fast with team size. One engineer with AI has the output of a small team with zero coordination cost.
When a feature requires multiple engineers, designate one person as the design owner. Others contribute. One person keeps the vision coherent.
Code Is the Source of Truth
Specs capture decisions at a point in time. The code reflects the actual shape of the system. Important decisions should live in the code or as ADRs. Specs are historical records, not living documents.
Decision Criteria
When deciding how much to spec: evaluate the size, ambiguity, and number of people involved. Simple changes with one engineer need plan mode only. Complex changes crossing multiple systems or involving business decisions need a formal spec. The spec exists to align people — if there is only one person, the alignment cost is zero.
When writing a spec: focus on what would be expensive to change later — interfaces, schemas, data contracts. Leave implementation details to AI and plan mode. Over-specifying creates documents nobody reads and bugs from untested code.
Anti-patterns
- Over-specification — generating mountains of markdown nobody reads. If reviewing the spec is harder than reviewing the code, the spec is too detailed.
- Spec as ceremony — writing specs because the process says to, not because the team needs alignment.
- Spec as final answer — treating the first spec as a blueprint instead of iterating. This is waterfall with a new name.
- Spec with production code — untested code in specs gets copied into implementation and introduces bugs.
- Same process for all changes — applying full SDD workflow to bug fixes and small features. Match process to risk.
- Full automation from spec — expecting AI to implement a large feature end-to-end from a spec without human iteration and discovery.
Experience Notes
Previously: detailed specs with production code examples to guide AI implementation. Now: specs focused on what/why with interfaces and schemas only. Moved because specs with code produced bugs — untested code got copied. The implementation details are better discovered through iteration than prescribed upfront.