SDD (Spec-Driven Development): What Teams Get Wrong
AI made writing code almost free. An engineer with an AI agent can build in hours what used to take days.
So teams started investing in specifications. Tell the AI what to build. Give it clear instructions. This is the core idea behind Specification-Driven Development (SDD).
The idea is good. But most teams are doing it wrong.
The Bottleneck Moved
The hard part of software was never typing code. It was deciding what to build.
AI made execution fast. That did not make the decisions easier. Teams that generate code faster without thinking better just arrive at the wrong answer sooner.
SDD tries to fix this. Before writing code, define the what and the why. Make decisions explicit. Then let AI handle the rest.
Simple concept. Hard to get right.
The New Roles
When AI handles implementation, three roles emerge naturally:
| PM | Engineer | AI | |
|---|---|---|---|
| Owns | Business need | Design concept | Implementation |
| Decides | What and why (business) | What and why (technical) | How |
| Focus | Problem, priority, success criteria | Interfaces, schemas, constraints | Code, patterns, conventions |
| Strength | Business context | Technical judgment | Speed and consistency |
The PM defines the problem. The engineer designs the solution. The AI builds it. For smaller features, the engineer often takes both roles — defining the business need and the technical approach.
The spec sits between them. It is not a blueprint. It is a shared understanding of direction.
This works when each side stays in its lane. Problems start when the spec tries to do the builder’s job — including production code, internal algorithms, or step-by-step instructions. The engineer writes code that was never tested. The AI copies it. The spec becomes a source of bugs.
What Belongs in a Spec
A spec has one job: keep the team aligned.
Include:
- What problem are we solving?
- Why does it matter?
- 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
When a spec is too long, nobody reads it. When nobody reads it, it prevents nothing.
A good spec is short enough to read, specific enough to align on, and loose enough to leave room for discovery.
The Iteration Loop
Here is where most teams fail. They treat the first spec as the final answer.
It never is.
The approach that works:
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
The first implementation is not the goal. It is a learning tool. It shows you what the spec could not anticipate.
Implementation is cheap now. Use that speed to learn faster — not to ship the first attempt.
Match Process to Risk
Not every change needs a spec. SDD tools today treat every problem the same way. That is over-engineering the process.
| Change | What it needs |
|---|---|
| Bug fix | Plan mode → fix |
| Small feature (follows existing patterns) | Plan mode → build |
| Large feature (multiple systems, unclear decisions) | Full spec → plan mode → build |
One thing stays constant: always start with plan mode. Even for a simple bug fix, letting the AI agent plan before acting gives you more context than you expected. It surfaces related files, edge cases, and patterns you might miss. Plan mode is cheap and fast — skipping it is not worth the risk.
The question is how much spec work comes before the plan:
- Simple change → go straight to plan mode, no spec needed.
- Complex change → write a spec first, then plan mode for each task.
Most daily work is the first case. Heavy process on simple problems creates overhead and stale documents.
Smaller Teams, Better Specs
Every person added to a project means more meetings, more documents, more misunderstanding.
AI changes this equation. One engineer with AI has the output of a small team — with zero coordination cost.
Why smaller teams write better specs:
- Fewer people need to align
- The spec is simpler because the audience is smaller
- Decisions happen faster
- The design stays coherent — it comes from one mind, not a committee
When a feature requires multiple engineers, designate one person as the design owner. Others contribute. One person keeps the vision coherent.
More documentation is not the answer. Fewer people aligned on a clear direction is.
The Real Goal
SDD is not about writing perfect specs. It is about shared understanding — a common mental model that engineers, product managers, and AI agents can follow.
It works when it keeps a small team pointed in the same direction.
It fails when:
- Documents replace thinking
- The process is heavier than the problem
- Engineers review markdown instead of building software
- The spec becomes ceremony instead of communication
Write the spec. Build. Discover what is missing. Revise. Repeat.
One open question remains: what happens to the spec after implementation? The code is the real source of truth — it reflects the actual shape of the system. Specs capture decisions at a point in time, but they are not living documents. Where to store them, whether to keep them updated, and how they relate to things like ADRs is worth exploring separately.
The teams that get SDD right are not the ones with the best documents. They are the ones who know what to specify, what to leave open, and when to let the code teach them what the spec could not.