Spec-Driven Development

Spec-Driven Development

A gated, six-phase workflow for shipping real software with an AI coding agent. Each phase has a goal, exit criteria, and a rationalization table for the excuses an agent will invent to skip it. Do not advance until the current gate is closed.

When to Use

• Starting a new project, service, or significant feature
• Requirements arrive as a paragraph, screenshot, or vague idea
• The change touches more than one file or subsystem
• You are about to make an architectural decision
• An agent is about to write more than ~100 lines without a plan
• Picking up half-finished work from another session

When NOT to Use

• One-line typo or copy fix
• Renaming a single local variable
• Changes fully scoped by a one-line request where "done" is unambiguous
• Pure dependency bumps with no behavior change
• Throwaway spikes clearly marked as experiments and never merged

If unsure, do the spec phase anyway. A 10-minute spec is cheap insurance.

The Gated Workflow

  SPEC  ──▶  PLAN  ──▶  BUILD  ──▶  TEST  ──▶  REVIEW  ──▶  SHIP
   │          │          │          │          │           │
   ▼          ▼          ▼          ▼          ▼           ▼
 What &     Tasks &    Thin       Prove it   Five-axis   Deploy,
  why       order      slices     works      quality     observe,
                                   by test    gate       roll back
   │          │          │          │          │           │
   └──────────┴──────────┴──────────┴──────────┴───────────┘
            human or reviewer approves each gate

Rules of the gate:

1. You may loop backward (Test reveals a broken spec — return to Spec).
2. You may not skip forward. No building without a plan. No shipping without review.
3. Each gate produces a named artifact committed to the repo: SPEC.md, PLAN.md, code + tests, a review note / PR description, a launch + rollback note.

Phase 1: SPEC

Goal. Turn a vague request into a written contract that answers what, why, for whom, and how we know it is done. Surface assumptions before they become bugs.

Inputs. User request, existing codebase, any prior specs, constraints.

Steps.

1. Restate the request in one sentence. Confirm with the human.
2. List assumptions explicitly. Example: ASSUMPTIONS: web app, Postgres, session cookies. Correct me or I proceed.
3. Reframe vague requirements as measurable success criteria. "Make it fast" becomes "dashboard LCP < 2.5s on 4G, initial data < 500ms".
4. Write the spec using templates/spec.md and save it in the repo.
5. Define Always / Ask First / Never boundaries.
6. Log open questions. Do not guess answers.

Exit criteria.

• Spec file saved in the repository
• Human has read and approved it
• Success criteria are specific and testable
• Boundaries are explicit
• No unanswered blocking questions

Common Rationalizations

Phase 2: PLAN

Goal. Convert the spec into an ordered list of small, verifiable tasks with an explicit dependency graph. No code is written in this phase.

Inputs. Approved spec, relevant source files, existing conventions.

Steps.

1. Enter read-only mode. Read the spec and the code it will touch.
2. Draw the dependency graph: what must exist before what.
3. Slice vertically. Thin end-to-end slices beat horizontal layers (schema → all APIs → all UI is the wrong shape).
4. Write tasks using templates/plan.md. Each task fits one focused session and touches ~5 files or fewer.
5. Insert verification checkpoints between task groups.
6. Call out risks and parallelization coordination (e.g. agree an API contract before splitting frontend/backend).

Task sizing.

Exit criteria.

• Plan file saved in the repository
• Every task has acceptance criteria and a verify step
• Dependencies are ordered correctly
• No task is XL
• Checkpoints exist between phases
• Human approved the plan

Common Rationalizations

Phase 3: BUILD

Goal. Implement the plan in thin, compilable, revertible increments. Every increment leaves the tree green.

Inputs. Approved plan, the current task.

The increment cycle: implement → test → verify → commit → next slice

Rules.

0. Simplicity first. What is the simplest thing that could work? Three similar lines beat a premature abstraction. Do not generalize before the third use case demands it.
1. Scope discipline. Touch only what the task requires. Note unrelated issues; do not fix them. No "while I'm here" refactors.
2. One thing per commit. Feature, refactor, and config change are three commits, not one.
3. Always compilable. Build and existing tests must pass after every slice.
4. Feature flags for WIP. Merge behind a flag if users should not see it yet.
5. Rollback-friendly. Additive > destructive. Each increment revertable alone.

Exit criteria for each increment.

• Does one thing, completely
• Build passes
• Lint and type checks pass
• Existing tests still pass
• Committed with a descriptive, imperative message

Common Rationalizations

Phase 4: TEST

Goal. Prove the code works with tests that will survive refactoring. "Seems to work" is not done.

Inputs. Built code, spec's success criteria, bug reports (if any).

Steps.

1. New behavior: write the test before the code (RED → GREEN → REFACTOR).
2. Bug fixes: Prove-It pattern. Write a failing test that reproduces the bug. Only then fix it. The test becomes the regression guard.
3. Follow the pyramid: ~80% unit, ~15% integration, ~5% end-to-end.
4. Test state, not interactions. Assert on outcomes, not on which private methods were called.
5. Prefer real > fakes > stubs > mocks. Mock only at boundaries you cannot control (external APIs, clocks, randomness).
6. Name tests like a spec: it('sets completedAt when task is completed').
7. Browser work: verify in an actual browser (DOM, console, network, screenshots). Unit tests alone do not prove a page renders.

Exit criteria.

• Every behavior in the spec has a test
• Bug fixes include a reproduction test that failed before the fix
• Full suite green: <test command>
• No skipped or disabled tests
• Coverage did not regress
• No flaky tests introduced

Common Rationalizations