Spec-Driven Development

Exhaustively (hopefully) define your program in a spec, then let a coding agent implement it. The paradigm rests on a triangle of three artifacts: specs (.md — defines what, why, and sometimes how), tests (.yaml — measures and validates verifiable behavior), and code (.py — implements and executes the specified behavior). When agents are reliable enough, the durable, shareable artifact can shift from the code to the spec: Drew Breunig's whenwords ships as SPEC.md + tests.yaml with no code at all and still "delivers" a library — posing the question, "if the agents are good enough, do we need to share code?"

The hard part is not the initial generation but the ongoing sync: specs, tests, and code are three redundant representations of the same intent, so they drift. Bug fixes and hot-fixes add code and tests with no spec change; agents make implementation decisions the spec never recorded. Keeping the triangle "true" — detecting the gaps and folding new intent back into the spec — is the standing problem, and it is what a tool like Plumb (see the distillate) exists to manage.

Claims

Spec, tests, and code are redundant representations of one intent, so they inevitably drift; keeping them in sync is the central, ongoing cost — not the initial generation. principle — durable: any time the same intent is expressed in more than one place, the copies diverge under change; the maintenance burden is reconciliation, not authoring.
When agents are reliable enough, the spec (+ tests) can be the durable artifact and code becomes regenerable — you may not need to share code at all. best practice — context: contingent on agent implementation being trustworthy for the domain; demonstrated at toy scale (whenwords), explicitly "untested on large projects," and the same bet failed for Anthropic's 16-Claude/$20k Rust-based C compiler. State the context; do not present as an invariant.
Gaps between spec/tests/code are detectable from signals you already emit: git diffs of code, git diffs of the spec, test-coverage tools, and agent traces. best practice — context: SDD projects under version control with agent implementation; these signals are proxies (coverage says what is tested, not whether tests reflect the spec).
Bug reports and hot-fixes generate new tests and code with no spec change — a systematic source of drift to watch for. observation — a predictable asymmetry: urgent fixes bypass the spec.
Tune the amount of spec ceremony to the project — "just enough" structure, up to —dangerously-approve-all-decisions. best practice — context: SDD overhead only earns its keep on work where drift is costly; on throwaway or tiny work full rigor is waste (the Agentic Simplicity discipline applied to process).
Inventing from first principles often means rediscovering from first principles. observation — SDD echoes formal specification and automated program repair (Dijkstra 1972 on programming-as-gigantic-problem; Claire Le Goues' 2009 genetic-programming approach to automated software repair); the paradigm is a re-derivation, not a clean invention.
Front-load ~90% of your attention onto planning; a solid, decomposed plan makes the review loop mostly unnecessary. best practice — context: most projects (Jaymin West explicitly exempts high-security/compliance work, where a review step stays mandatory); the payoff is that a plan solid enough that "a haiku-class agent could just implement it" produces no surprises to review. A second, independent source now converges on "spec/plan first" as where effort belongs.
When a plan fails after implementation, fix the plan (or the planning template) — not the broken code. best practice — context: templated planning where failures recur as a class; scrapping the output and revising the plan fixes the class "once and for all," whereas patching the code fixes one instance and leaves the template to reproduce it. This is Reusable Workflow Library's "solve a class of problems once" applied to the plan itself. A second source (Buildable) operationalizes exactly this: generate reuses the saved .buildable/phase-plan.*, and its guidance is "not satisfied? revise the saved plan and keep planning before you generate."
Make the spec an audited, ask-first build contract — plan before code, ask blocking questions when product direction or an architecture-changing choice is unclear, don't decide silently. best practice — context: agent app-building where a wrong silent assumption is expensive to unwind; a second source (Buildable) is "audit-first" — plan stops on vague prompts and pauses generate on auth/DB/payments/deploy choices. The Agent Supervision human-gate folded into the plan step; contingent on the cost of a bad silent decision exceeding the friction of asking.
SDD inverts the artifact order: traditional dev is code→docs, TDD is test→code, SDD is spec→design→implement→code — so the spec becomes the primary artifact that drives implementation, tests, docs, and verification. best practice — context: AI-assisted builds where reducing agent ambiguity is worth the up-front planning. A third independent source (IBM Technology, "AI-Assisted Coding Explained") restates the "spec as source of truth" bet and frames it as "TDD and BDD on steroids"; the durable half — replace the model's guess with a written, checkable behavioral contract — is the Eval-Driven Development measure-don't-vibe discipline.
Prompt the behavior and constraints you want, not a specific implementation; nothing is implemented until the spec is approved, which makes the agent's decisions auditable — you know why the implementation turned out as it did. best practice — context: builds where an unrecorded, non-reproducible implementation decision is a liability; the payoff is less ambiguity for the coding agent and a rationale trail. Contrast Vibe Coding, whose decisions are never recorded (an underspecified request is nondeterministic — "30 ways" to build the same /login).
Name the planning artifact for what it actually is — the name steers what gets produced into it. best practice — context: a second source (Matt Pocock, skills v1.1) renamed /to-prd → /to-spec because a "PRD" was leaking non-PRD content and "spec" is the broader, true term for what was being built, and /to-issues → /to-tickets because "issues" was tracker-biased. He accepts the breaking migration cost as good friction "because it names it properly." Contingent on the name being genuinely wrong; renaming for taste alone isn't worth the churn. A precise artifact name is a Leading Words steer at the level of the skill's identity.
The full lifecycle is a fixed pipeline of named skills, not one big prompt: grill-with-docs (or a map-first plan) → to-spec → to-tickets → implement → code-review. best practice — context: the same author operationalizing "what is the flow?"; each stage is its own skill so the spec is the pivot between planning and execution. /to-tickets decomposes the spec into session-sized units (see Agent Task Graph); the pre-spec stage may instead be Map-First Planning when the work is too big and foggy for one grilling session.
A third source forks the same pipeline and inserts a cross-model hardening stage between spec and implementation. observation — grill-me-codex builds on Pocock's MIT-licensed grill-me (Act 1 is his work, unchanged) and adds: a rival vendor's model adversarially tearing the plan apart until both sign off, then building from the frozen spec while the planner reviews the diff. The grilling interview itself corroborates this page as-is — one question at a time, ~8–10 of them, each with a recommended answer drawn from the operator's own project history. The frozen spec is what makes the role flip clean: the builder implements an artifact it argued over but did not author alone. See Cross-Model Independence.
The spec-and-tickets stages are conditional: they exist to carry work across more than one context window, so when the job fits the remaining smart zone you skip them and implement directly. best practice — context: the same author's tutorial makes the fork explicit — after grilling, ask whether what's left of the job fits what's left of the usable window ("we've got 100k of budget here to remove 10 commands — that seems super easy") and if it does, go straight to /implement. He judges his own demo job to fit and runs spec-and-tickets only "in the interest of showing you everything." This is the sharp form of the page's existing "tune the ceremony to the project" claim: the ceremony's trigger is Context Smart Zone overflow, not project importance. Contingent on being able to estimate the work's cost, which the source does by feel.
/to-spec is deliberate context compression — it collapses the grilling session (46.1k tokens on screen) into a durable document, making the spec the destination and the tickets the route. observation — the operator doing on purpose, at a chosen moment, what Context Compression does automatically at the window edge; it is also what lets an Context-Independent Review agent check work it never watched being done.

Decision Log — the mechanism that keeps the triangle in sync: capture the intent behind new code/tests and fold approved decisions back into the spec.
Eval-Driven Development — tests are the executable, verifiable half of the spec; SDD's "tests validate behavior" is EDD's "measure, don't vibe" made structural.
Reusable Workflow Library — the same move one level up: share the definition, not the rebuilt implementation ("if agents are good enough, do we need to share code?").
Agent Supervision — syncing the spec is a human-approval loop over agent-proposed decisions; review bandwidth, not generation, is the bottleneck.
Agentic Simplicity — "just enough" spec structure; add ceremony only where it earns its keep against outcomes.
Meta-Prompt — one way to generate the spec: a templated meta-prompt that expands a short request into a full plan with required sections.
Agent Task Graph — the plan/spec is where a team's task graph is declared (## Team Orchestration, ### Team Members) before the agents implement it.
Agent Rituals — the planning template is one such ritual: a structured, repeatable way for every agent to turn an idea into an actionable, decomposed plan.
Vibe Coding — the foil that defines SDD: the no-spec, prompt-and-iterate loop whose nondeterminism and missing audit trail are exactly what the spec-first discipline removes.
Distillate: Learnings from a No-Code Library: Keeping the Spec-Driven Development Triangle in Sync
Distillate: Spec-Driven Development: AI-Assisted Coding Explained (IBM Technology) — corroborates from a mainstream source (IBM Technology): prompt behavior not implementation; invert to spec→design→implement→code; gate each stage on approval so the spec is the primary artifact.
Distillate: Claude Code Task System: Orchestrating a Team of Agents Through a Task Graph
Distillate: The Agentic Engineering Meta — corroborates "plan-first": front-load 90% of attention on a decomposed plan to avoid the review loop; fix the plan, not the broken code.
Distillate: Buildable — A Local, Build-Verified App-Builder Brain for Coding Agents — the appSpec/phase-plan as an audited, ask-first build contract; generate reuses the saved plan and you revise the plan, not the code.
Golden Templates — a verified implementation the spec adapts; templates supply the code SDD would otherwise regenerate from the spec.
Adversarial Planning Council — the plan-first step, staffed by adversaries: a persona council that pressure-tests the idea before the build begins.
Map-First Planning — the pre-spec stage for oversized, foggy work: chart a map of session-sized unknowns first, then convert the completed map into a spec via /to-spec.
Distillate: Skills v1.1: Wayfinder, the SDLC flow, and naming the artifact right — the same author names the artifact precisely (/to-prd → /to-spec) and makes the full grill→spec→tickets→ implement→review pipeline explicit end-to-end.
Distillate: How Claude Is Creating a New Generation of Millionaires — corroborates plan-first from the non-technical end ("planning is so, so important… make Claude look at everything from every angle first" before letting it build).
Distillate: Claude Fable 5 Bossed 20 Cheap AI Agents. The Whole Site Cost $8. — the "constitution": author done-ness once at the top as a checkable standard (a 14-point accessibility constitution) that the system enforces every build round. "The prompt's not instructions — it's a standard plus a way to check it." Pairs the spec with Agentic UI Testing as the enforcement mechanism.
Cross-Model Independence — the frozen spec is the seam a cross-vendor role flip pivots on: one model plans and reviews, another builds against the written standard, and neither grades its own work.
Distillate: Fable 5 + GPT 5.6 Sol = CHEAT CODE — a fork of Pocock's grill-me that inserts a cross-model plan-hardening stage between spec and implementation, and flips who writes vs who reviews.
Context Smart Zone — what the pipeline is for: specs and tickets are the machinery for work that exceeds one window's usable region, and the fork between "just implement" and "spec it" is decided by measuring the job against the zone that's left.
Distillate: The whole flow, end-to-end: the smart zone is the unit of work — the same author demonstrating the full pipeline end-to-end on a real repo, and naming the condition under which two of its five stages are skipped.

Spec-Driven Development

Claims

Related

Linked from