The short answer
Spec-driven development is a workflow where an explicit, reviewed specification is the input to implementation and verification. Code stays the executable system; the spec stays the shared record of intended behaviour and constraints.
- Agree the contract before writing the implementation
- Ambiguity surfaces while it is still cheap to fix
- Every task points at named acceptance cases
- Discoveries during build become reviewed revisions
On this page · 5 sections
The contract comes before the implementation
Detailed enough that two engineers build compatible behaviour. No more than that.
A useful specification defines the observable contract: who can start a flow, which inputs are valid, how decisions branch, what data changes, which failures are expected, and how success gets verified.
That sequence exposes product ambiguity while changes are still cheap. It also gives design, engineering, and QA one artifact to argue with — before three separate interpretations harden into code, mockups, and a test plan that disagree with each other.
A six-step operating loop
A loop, not a handoff. Each step leaves something the next can inspect.
Frame the outcome
State the user problem, the scope, the non-goals, and the result you could measure.
Model the behaviour
Capture actors, flows, branches, data, permissions, and failure states as structured entities.
Review the decisions
Resolve the contradictions, name the approver, and publish the revision.
Implement from bounded context
Give each person or agent the entities and acceptance tests for their task, and nothing adjacent.
Verify the contract
Test observable behaviour, including negative paths and permission boundaries.
Reconcile discoveries
When implementation proves an assumption wrong, propose the change rather than absorbing it into the code.
The last step is the one teams drop first and miss most. Without it, the code and the specification start describing different products, and you find out during an incident.
How coding agents fit
More than a ticket title. Much less than the whole workspace.
An agent needs the goal, the affected flow, the related models and roles, the acceptance tests, and the repository's own instructions. Keep unrelated product context out of the prompt so the boundary of the task stays legible.
Unbounded prompt
- The whole planning document, pasted
- Ticket titles as the only statement of intent
- Draft ideas mixed in with approved behaviour
- The agent picks product behaviour when the text is silent
Bounded task context
- One flow with its branches and outcomes
- The roles and models that flow references
- Named acceptance cases to verify against
- The agent stops and reports a conflict instead of resolving it
Treat a proposed spec edit and a code change as separate decisions, even when the same agent drafts both in the same sitting.
Where teams usually go wrong
Four failure modes, all of them recoverable if you name them early.
| Failure mode | What it looks like | The correction |
|---|---|---|
| Writing before learning | Forty pages of background before the first decision is made | One thin, complete slice of behaviour, then iterate |
| Approval as a label | A status field says approved; nobody remembers agreeing | Name the approver in the revision itself |
| Tickets as a shadow spec | The real product lives in comment threads | Point tickets at entities instead of restating them |
| Freezing after kickoff | Implementation finds an edge case; the code decides alone | Confirm the contract or approve a revision, then move on |
Implementation is a source of evidence, not a threat to the plan. When it turns up something new, the team either confirms the existing contract or approves a revision — and then keeps code, tests, and published intent pointing the same direction.
Choosing the right level of detail
Spend detail where mistakes are expensive. Spend nothing where they are not.
Go deep on the areas where being wrong costs real money or trust:
- Access control and permission boundaries.
- Financial calculations, billing, and anything with an invoice attached.
- State transitions, especially irreversible ones.
- Integrations, where another team depends on your behaviour.
- Data deletion and retention.
Keep routine presentation details lighter, unless they carry an accessibility or brand requirement. A good test is whether the specification helps a reviewer find a wrong assumption. If more prose makes that harder, replace the prose with a table, a flow, a typed model, or an explicit acceptance case.
Before implementation starts
- The desired outcome is clear before any solution detail.
- Decision branches and failure states are explicit.
- Every implementation task points to relevant acceptance cases.
- An agent will surface a product conflict instead of inventing behaviour.
- Discoveries get reconciled into a reviewed revision.