SPEC-DRIVEN DEVELOPMENT

The spec is the prompt.

For approximately fifty years, the specification functioned as scaffolding: authored to secure approval, then set aside once implementation began. The code constituted the artifact of record. The document carried no enforced authority.

Autonomous coding agents have reversed this relationship. An agent produces a plausible implementation of whatever intent it infers — quickly, consistently, and in a fixed house style — without the capacity to verify that inference against the author’s actual requirements. Consequently, the scarce, high-value output of a human contributor is no longer the implementation. It is the specification of intent, articulated with sufficient precision that an automated system cannot reasonably misread it.

This is the governing premise of the discipline documented here. What follows is its methodology.

23 min estimated reading · 10 interactive demonstrations · 7 reproducible artifacts

Press G for the construction grid · ⌘K to search · R to switch reading mode

Everything that follows in this book is a theory of writing. Before the theory, the practice: a single canvas showing where a ticket enters, what gets written at each phase, who owns each decision, and — the detail a whiteboard version of this diagram always omits — what happens when the plan turns out to be wrong partway through.

The starting point is not a blank page. It is a Jira board, because that is where the work already lives. This chapter draws the loop as a phase-gated dependency graph anchored to that board, then shows the board configuration — columns, WIP limits, swimlanes — that keeps the two in agreement.

SEVEN PHASES, ONE BOARD

The four dashed edges are the part a static process diagram cannot show, and the part that answers the question every team asks first: what happens when the plan changes mid-ticket? It does not stall the graph and it does not get silently absorbed into a growing diff. It re-enters at a named point — Specify if the requirement itself was wrong, Plan & Tasks if the requirement holds but the approach doesn’t — and the graph runs forward again from there. A ticket that bounces backward once or twice before release is the loop working, not the loop failing.

The graph above is the argument; the board below is the enforcement. A dependency graph on a slide is a claim about how work should move. A Jira board with WIP limits on its gate columns is that claim made expensive to ignore — a ticket physically cannot sit in Plan Review without either an approval or a visible violation of the column’s limit.

Two columns carry the graph’s four gates: Plan Review enforces plan approval, and In Review enforces the human diff review. Both are WIP-limited on purpose — a low limit makes a bottleneck visible on the board itself, rather than invisible in a diff that quietly grew past what anyone approved.

Swimlanes are drawn by risk tier, not by team or component, because autonomy is a property of the work (the fuller three-tier rubric — what earns Tier 1 autonomy versus what is proposal-only regardless of who is asking — lives at /agentic-sdlc). The same three tiers, read as decision rights and an escalation path rather than board layout, are THE OPERATING MODEL.

A BOARD SETUP NOTE, READY TO PASTE INTO YOUR JIRA ADMIN TICKET

1Board columns, left to right:2  Backlog        (no WIP limit)3  Specify        (WIP 3)4  Clarify        (WIP 3)5  Plan Review ★  (WIP 2  — gate: requires human plan approval to exit)6  In Progress    (WIP 4)7  In Review      (WIP 3  — gate: requires human diff review to exit)8  Done           (no WIP limit)9 10Swimlanes: Tier 1 / Tier 2 / Tier 3, by blast radius — not by team or component.11 12Automations to wire on day one:13  - moving a card OUT of Plan Review requires a "plan-approved" checkbox or a linked ADR14  - moving a card OUT of In Review requires a merged PR link15  - a card that re-enters Specify from Clarify or In Review is auto-labelled "replanned"16    (this is a signal to watch, not a thing to prevent)

A diagram that cannot show what happens when the plan changes is describing a different practice than the one your team is about to run.

The term “vibe coding” — issuing loosely specified prompts and accepting whatever output results — was coined by Andrej Karpathy in early 2025 and was subsequently named Collins Dictionary’s word of the year. The approach is well suited to disposable prototypes and poorly suited to any system requiring ongoing maintenance. By 2026, agent-assisted workflows had matured toward oversight and structure, and use of the term itself had declined accordingly.

Spec-driven development represents a disciplined alternative. Its central claim is narrow and defensible: where an agent generates the majority of an implementation, the specification becomes the highest-leverage artifact a human contributor produces. The relevant skill shifts from authoring implementation code to defining intent with sufficient precision that an automated system cannot misinterpret it.

The underlying practice is not new. Requirements engineering, behaviour-driven development, contract-first API design, and model-based design all precede it by decades. What has changed is the consumer of the document: for the first time, the specification has a reader that will act on it literally, at scale, and in seconds. This changes the standard a specification must meet.

Spec-driven development does not add documentation overhead. It shortens the feedback loop while preserving specified intent.

The most consequential distinction in this discipline, and the one most treatments omit, is this: a specification under this methodology is not documentation describing the system. It is an artifact consumed directly by the agent and enforced by the test suite. If no build fails when the specification and the code diverge, the document produced was a design document, not a specification.

The following three properties distinguish an executable specification from an advisory one:

1. 01

   The specification is versioned with the code.

   It resides in the same repository, the same pull request, and the same review process. A specification maintained in a ticketing system or a chat transcript is invisible to a subsequent agent session — and that session is the one most likely to misinterpret the requirement.

2. 02

   Its acceptance criteria correspond directly to tests.

   One criterion corresponds to one test, identified by a shared identifier. This mapping is what renders drift a detectable condition rather than a matter of interpretation.

3. 03

   It constrains the scope of agent exploration.

   An explicit out of scope section constrains agent behaviour more effectively than any amount of additional detail. An unbounded specification produces an unbounded diff.

Authoritative sources converge on the same three levels of rigor. A common misconception is to treat this hierarchy as a maturity progression to be climbed; it is not. Each level is appropriate for a different category of work, and the highest level remains aspirational for most teams.

This document recommends the spec-anchored level as the appropriate target for most production work. Spec-as-source represents the current locus of industry enthusiasm; spec-anchored represents the current locus of demonstrated value. It retains executable code as the source of truth — the artifact actually deployed to production — and uses the specification as the anchor against which tests verify alignment.

RUNG SELECTOR

Every established toolkit implements substantially the same pipeline, under varying nomenclature, with a human review gate at each phase boundary. The specific names are less significant than the boundaries themselves; the boundaries constitute the actual value of the methodology.

SEVEN PHASES, IN ORDER

Proceeding directly from specification to implementation is not recommended. A plan is inexpensive to read and inexpensive to reject; a diff is neither.

A constitution defines the set of project-wide, always-on constraints governing a repository: language and framework, testing standards, dependency policy, security posture, and paths that must not be modified. It should be committed before the first specification is written. Without it, every agent session must re-infer project conventions, and the codebase drifts incrementally across sessions — a pattern that, from the outside, is indistinguishable from a team with no standards at all.

These two files serve a single purpose. AGENTS.md (or CLAUDE.md) is the agent-facing operating manual: stack, commands, conventions, restricted paths, and known failure modes. constitution.md constitutes the governing principles layer: the rules a team would defend in a design review, independent of any specific tooling. Smaller teams may consolidate both into a single file without loss; the failure mode to avoid is maintaining neither.

A specification exceeding three pages is, in practice, two specifications. A specification that reads as pseudo-code represents a program written twice. Between these two failure modes lies a narrow, learnable format.

The disciplines

• Write in domain language, not implementation detail. “The system shall reject a reused login link” — not “the controller shall verify consumed_at is null”. Once a specification references an ORM or comparable implementation detail, design has begun, and it is occurring in the wrong document.
• One directory per feature: specs/004-magic-link/{spec.md,plan.md,tasks.md}. Numbered, ordered, and searchable by convention.
• Draft collaboratively; decide independently. An effective specification typically results from dialogue: describe the requirement, allow the model to structure it, and challenge any assumptions it introduces. Subsequently remove anything that was not an explicit decision.
• Specify failure behaviour explicitly. Most deficient specifications describe only the primary success path. The failure behaviour of a system is at least as significant as its success behaviour, and it is precisely the portion an agent will infer independently if it is omitted.

The structure

1. 01

   Context

   One paragraph establishing business context: why the feature exists, for whom, and the current state of the system.

2. 02

   Goals

   Three to five outcomes, stated in domain language.

3. 03

   Non-goals / out of scope

   The scope boundary. This section constrains agent behaviour more than any other.

4. 04

   User stories

   One narrative per capability, stated from the user's perspective.

5. 05

   Acceptance criteria

   EARS notation, numbered, testable, one clause each (Chapter 07).

6. 06

   Data & interfaces

   Limited to what the behaviour requires. The schema belongs in the plan, not here.

7. 07

   Open questions

   Each question requires an assigned owner and a resolution date; without both, it is an aspiration rather than a tracked question.

8. 08

   Constitution deviations

   Any departure from a standing rule, with justification.

EARS — the Easy Approach to Requirements Syntax — is the de facto standard for acceptance criteria unambiguous to both human readers and models. The notation consists of five sentence patterns in their entirety, and can typically be learned within several minutes.

THE KEYWORD LEGEND

Two rules distinguish EARS-shaped text from EARS notation proper:

The benefit is structural: criteria written in this form map nearly one-to-one onto test cases. This mapping is what renders a specification executable rather than advisory, and is also why EARS notation outperforms free prose for agent consumption — it leaves no room for a plausible alternative interpretation.

The specification deliberately omits any reference to the technical stack. plan.md is where that constraint is lifted — and where a reviewer performs the least costly, highest-leverage work available anywhere in this methodology.

Tasks follow the plan. Decomposition is not administrative overhead — it is the mechanism by which one unreviewable change is converted into a series of reviewable ones. A well-formed task is atomic (addressing one concern), ordered (with explicit dependencies), independently verifiable, and — non-negotiably — cites the acceptance criterion it satisfies.

The refs column is the operative mechanism. It forms the thread connecting business intent, task, commit, and test. When a failure occurs in production, the relevant question is not what the code does, but which specified intent has been violated — and that answer is retrievable with a single search.

Every abandoned wiki constitutes evidence for this objection, and the objection is correct by default: documents drift because no mechanism fails when they do. The remedy is not discipline, which degrades under deadline pressure, but ensuring that drift causes a build to fail.

A COMMIT TRAILER, CH.1 · CITATION

1feat(auth): magic link issue + verify2 3refs specs/004-magic-link/spec.md AC-01, AC-02

Four mechanisms, in increasing order of cost:

1. 01

   1 · Citation

   Tests reference their corresponding criterion, and commits reference their specification path. This costs nothing to implement and immediately answers which intent failed.

2. 02

   2 · Coverage check in CI

   A script verifies that every acceptance criterion identifier declared in spec.md appears in at least one test name. An unreferenced criterion causes the build to fail with an enumerated list. This check requires roughly forty lines of code and represents the highest-return automation in this methodology. A template is provided in Appendix D.

3. 03

   3 · Contract enforcement

   Where a specification declares an interface, that interface should be generated or verified directly: OpenAPI schema validation within tests, Pact or Specmatic for consumer-driven contracts, Protobuf for wire formats. The specification thereby ceases to be prose describing the interface and becomes the interface itself.

4. 04

   4 · Convergence review

   Periodically instruct the agent to compare the codebase against the specification, plan, and tasks, and report divergences as a task list. This check is inexpensive to run and surfaces drift that citation alone cannot detect: behaviour present in the code that was never anyone's specified intent.

One practice remains that no tool can replace: when a requirement changes, update the specification first, within the same pull request as the corresponding code. Not afterward, and not in a subsequent ticket. A specification that records a decision made weeks earlier is not serving its function; it must represent the current statement of intent, or it serves no function at all.

Every tool listed below implements substantially the loop described in Chapter 04. They differ along three dimensions of practical significance: whether specifications are living or static, whether orchestration operates at the workspace or organizational level, and the degree of procedural ceremony required.

Every demonstration of this methodology begins with an empty directory. In practice, adoption more often begins with an existing codebase of several hundred thousand lines, no test coverage on the path requiring modification, and an imminent deployment deadline. The accurate answer to how the methodology should be adopted under these conditions is: progressively, one feature at a time, and never as a full rewrite.

THE FIVE-STEP ON-RAMP

1. 01

   Step 1 — Write the constitution from the code that exists

   The constitution should describe the code that exists, not the code that is aspired to. Direct an agent to examine the repository and infer conventions, commands, module boundaries, and known failure modes, then review and correct its output. This requires approximately one hour and improves every subsequent agent session immediately, before any specification has been written.

2. 02

   Step 2 — Spec the next change, not the system

   Retrospectively specifying the entire application is not recommended. Instead, take the next ticket and write a one-page specification for it. The specification directory grows one feature at a time, and after roughly one quarter, the most frequently modified parts of the system are also the most thoroughly specified — the coverage distribution that is actually desired.

3. 03

   Step 3 — Characterize before you change

   For untested legacy code, direct the agent to write characterization tests that record current behaviour before any change is made. The specification should then be written as a delta describing what remains, what changes, and what must not change. The must-not-change list is the one that prevents regressions.

4. 04

   Step 4 — Add the CI coverage check on new specs only

   The drift check should be scoped to specifications created after adoption began. A build should never be retroactively failed over documents that did not exist prior to adoption.

5. 05

   Step 5 — Let the map assemble itself

   Every specification produced leaves a durable description of one part of the system. After roughly twenty features, documentation exists for the twenty most frequently modified areas of the system — assembled as a by-product of required work, rather than as a separately funded documentation initiative.

The following objections should be weighed before an organization standardizes on this methodology.

This procedure requires ninety minutes, addresses one feature, and requires no tooling purchase. In the following week, add the CI drift check described in Appendix D, and add the AI-involvement line to the pull request template. This constitutes the complete adoption procedure; no subsequent phase is required.

The specification is now where analytical work occurs. Everything downstream of it is execution — and execution is the part of the process a human contributor no longer performs alone.

Chapter 01 drew the loop as a dependency graph anchored to a Jira board. This chapter runs it forward, in steady state, naming the two interfaces a ticket actually crosses — a card and an agent — instead of seven abstract phases. Six stations, three of which rewrite the specification rather than merely reading it, plus the two questions steady-state operation actually raises once the tooling is out of the way: where does a team’s accumulated judgment live, and how far is the agent allowed to go before it has to stop and ask.

SIX STATIONS, ONE LOOP

Three of the six stations carry the ✎ SPEC mark, and each is a failure mode this book has already named under a different heading. Station 3 is Chapter 06’s constitution and Chapter 07’s spec structure, applied before implementation starts rather than reconstructed after. Station 4 is the discipline Chapter 09 asks for: a task’s diff and its spec citation land in the same commit, so no reviewer ever reconciles two histories. Station 5 is the bounce path Chapter 01 already drew from In Review back to Specify — reused here verbatim, because a review that changes acceptance criteria is a new specification event whether or not anyone bothers to call it one.

WHAT ACTUALLY WIRES STATION 6, READY TO PASTE INTO A JIRA AUTOMATION RULE

1# Jira Automation rule — "Tier 1: hand back to Claude Code"2Trigger:    card moved to Done AND tier = T13Condition:  no comment containing "stop" in the last 10 minutes4Action:     webhook POST to the agent runner5 6  { "event": "card.done", "key": "{{issue.key}}",7    "tier": "{{issue.tier}}", "next": "pull-next-in-queue" }8 9Tier 2, Tier 3, and any card with no tier label fire nothing. The10runner never polls the board — the board tells it when to move.

A board that lets an agent close its own ticket without a human ever opening it is not efficient by itself. It is a governance gap wearing a kanban skin — unless the tier that allowed it was decided by a human, in writing, before the ticket started.

The loop above assumes Claude Code already knows how this team writes a spec, where its drift check lives, and which paths the constitution forbids. Chapter 06 put the always-on rules in one file; the same argument extends to narrower, more procedural knowledge — the kind that is really “how we do the release,” not “what we believe.” That belongs in a skill, versioned in git like everything else this chapter has asked you to commit, not in one engineer’s session history.

A SHARED SKILLS DIRECTORY, IN THE REPO EVERYONE ALREADY CLONES

1skills/2├── ears-criteria/3│   └── SKILL.md4├── cut-a-release/5│   ├── SKILL.md6│   └── scripts/changelog.mjs7└── open-a-migration/8    ├── SKILL.md9    └── templates/migration.sql.tmpl

ONE SKILL, WRITTEN THE WAY THIS BOOK ALREADY WRITES ACCEPTANCE CRITERIA

1---2name: ears-criteria3description: >4  Use when drafting or reviewing acceptance criteria for a spec.md in5  this repo. Applies the team's five EARS sentence patterns and flags6  criteria that read as implementation detail rather than behaviour.7---8 9# Writing acceptance criteria for this repo10 11Apply the five patterns from Chapter 08 — ubiquitous, event-driven,12state-driven, unwanted-behaviour, optional-feature. Prefer the13event-driven form (WHEN … THE system SHALL …) unless the requirement14is genuinely always-on.15 16Every criterion cited in a plan or a task must trace to a test name —17see Appendix D's drift check. Flag any criterion that names a library,18a function, or a file path: that is an implementation decision, and19belongs in plan.md, not spec.md.

Every station in Fig.15A eventually asks the same question: is the agent allowed to keep going, or does it stop? Chapter 01’s kanban swimlanes already answer it, by risk tier, drawn there as board configuration. Read the same three tiers as a decision-rights table instead of a board layout, and they say who decides, what the agent may do unasked, who it escalates to when it can’t decide alone, and — the part a swimlane can’t show — what actually stops it if the label on the ticket turns out to be wrong.

The tier is not a courtesy label on a dashboard. It is the only thing standing between “Claude initiates” and an agent that finishes a ticket nobody asked it to start.

Three figures, three separate lenses on the same six stations: a loop, a pipeline, a ladder. None of them, on its own, is what actually happens to a ticket — what happens is all three firing on the same six stations at once. The figure below walks one concrete ticket through Fig.15A’s loop a final time, this time carrying its tier from Fig.15C and its skill citation from Fig.15B at every station that needs one, with nothing left behind a hover or a click — everything below is on the page.

The tier sets how fast the agent may go. A named human and a clock decide whether it actually does.

The following four artifacts constitute the primary reference value of this document. Each is complete and identical, byte-for-byte, to what the COPY control places on the clipboard and the DOWNLOAD control writes to disk; nothing shown here has been retyped for display.

RELATED STANDARDS