1. The document leads
The spec is the source of truth. Code follows the spec; plans follow the spec; arguments are settled by the spec. If reality disagrees with the spec, the spec is updated deliberately — never silently outrun.
Methodology · Rev 1.0
The spec-driven methodology
A precise account of how spec-driven development works: the principles it rests on, the stages every spec passes through, how it differs from the alternatives, and the failure modes that undo it.
Seven principles
2. Write for the implementer, not the audience
A spec succeeds when the person (or agent) implementing it makes the same decisions you would. Optimize for executability: concrete, checkable statements over persuasive prose.
3. Acceptance criteria are executable
"Should feel fast" is not a criterion; "p95 response under 300 ms on the staging dataset" is. Every requirement ends in a statement that can be verified true or false.
4. Scope is explicit and bounded
Every spec states what is not being built. Non-goals are first-class citizens: they are the cheapest way to prevent a project from growing mid-flight.
5. Decompose to verifiable units
Plans become tasks; tasks are small enough that each one can be checked against its acceptance criteria in isolation. A task that can't be verified is two tasks.
6. Review at the cheapest level
Review the spec before the plan, the plan before the tasks, the tasks before the build. Each review catches errors while they are still ink, not concrete.
7. The spec is a living document
Specs are revised, not abandoned. Every template carries a revision block; every change is dated and described. The spec's history is the project's memory.
The six stages
The homepage shows the working loop in four stages. Here is the full lifecycle, including the two stages that bookend it.
S0 Discover
Before specification comes investigation: user interviews, data sampling, constraint gathering. Output: a problem statement sharp enough to specify. Most projects that fail do so here — they specify a solution before understanding the problem.
S1 Specify
Write the spec: problem, goals, non-goals, requirements, acceptance criteria, constraints, open questions. The spec is reviewed by stakeholders and the implementer before anything else moves. Open questions must be resolved or explicitly deferred with owners and dates.
S2 Plan
Derive the implementation plan from the spec: architecture and component design, data flows, sequencing, dependencies, risks and mitigations. The plan is checked against the spec line by line — every requirement must have a planned home.
S3 Decompose
Break the plan into tasks. Each task names its spec section, its acceptance criteria, and its estimated size. Tasks are ordered by dependency and risk — riskiest, most-uncertain work first, so failure is discovered early.
S4 Build
Execute tasks one at a time, verifying each against its criteria. When implementation reveals a gap in the spec, work stops: the spec is amended, the plan re-checked, and only then does building resume. This is the discipline's hard core.
S5 Verify & close
The review gate: the completed work is verified against the full spec, acceptance criteria are signed off, and the spec is archived as the record of what was decided and why. Unfinished threads become new specs, not loose ends.
Against the alternatives
| Dimension | Ad-hoc prompting | Ticket-driven dev | Spec-driven dev |
|---|---|---|---|
| Source of truth | The last prompt | The ticket thread | The spec document |
| Ambiguity handling | Improvised by the agent | Discovered mid-sprint | Resolved at spec review |
| Scope control | Drifts with each prompt | Grows via ticket comments | Non-goals are explicit |
| Review point | After the code exists | At sprint planning | At spec, plan, and task level |
| AI agent fit | Fast but unreliable | Needs constant steering | Agents execute contracts well |
| Knowledge capture | Lost in chat history | Fragmented across tickets | The spec is the record |
| Upfront cost | Near zero | Low | Moderate — pays back in rework avoided |
When not to spec
Spec-driven development is deliberate overhead. For a throwaway prototype, a spike, or a change so small the spec would exceed the code, write the code. The methodology is for work where being wrong is expensive.
Anti-patterns: how specs fail
The wish-list spec
A list of desired outcomes with no constraints, no trade-offs, and no acceptance criteria. Reads well; builds nothing. Cure: every requirement gets a criterion that can fail.
The design masquerading as a spec
Specifies implementation details ("use a Redis sorted set") instead of requirements ("leaderboard reads under 50 ms"). It constrains the how before the what is agreed. Cure: keep mechanism in the plan, requirements in the spec.
The spec written after the code
Back-filling a document to describe what was already built. It captures decisions but influences none of them. Cure: no code before the spec is reviewed — no exceptions.
The frozen spec
Treating the spec as immutable law, so implementers work around it instead of updating it. The document stops describing reality and becomes fiction. Cure: make amendments cheap and review them fast.
The infinite spec
Specifying to the last detail before any building — analysis paralysis dressed as rigor. Cure: specify to the point where tasks are verifiable, then build; the review gate will catch what's missing.
The unowned spec
A document everyone can edit and nobody maintains. Open questions linger, revisions go unrecorded. Cure: every spec has one owner and a revision block with their name in it.