What Is Spec-Driven Development? The Spec as Source of Truth

For most of software history the spec was a temporary planning artifact and the code was ground truth. Spec-driven development inverts that: the versioned specification becomes the primary artifact, and code is generated or verified against it. The idea is old — formal methods, design-by-contract, BDD all contain versions. What’s new is the motive: AI agents need explicit, durable intent because prompts evaporate and sessions reset.

Intent written, reviewed, and versioned before any agent writes code

What SDD Actually Means

A versioned specification guides or generates implementation, written and reviewed before agents write code. It captures what to build (problem, goals, non-goals), what correct looks like (acceptance criteria, edge cases, error states), how to build it (architecture, data model, contracts, security constraints), and how to verify it (test strategy, validation rules, traceability back to requirements). The spec is living: when implementation proves it wrong, correct the spec before continuing. Honesty is maintained like code, or the spec becomes confidently misleading documentation.

Three positions on the spectrum: spec-first writes everything upfront (strictest, closest to waterfall if careless); spec-anchored keeps the spec synced through the feature lifecycle (most practical); spec-as-source generates or validates implementation from the spec — the direction Spec Kit and Kiro pull toward, while Superpowers sits nearer spec-anchored, enforcing review discipline automatically.

Why Now: Three Conditions

SDD isn’t worth it for a one-day solo script. It pays when features span multiple sessions, agents make architectural decisions, and someone else reviews or continues the work — increasingly the default under AI-assisted development. Models with vague prompts decide vaguely; models with reviewed constraints, non-goals, and acceptance criteria decide better and correct faster. Generation is cheap, deciding what to build is hard — SDD moves effort to intent before generation. And prompts don’t survive session boundaries while a repo-stored spec does: every fresh session implements against identical intent without re-establishing context.

Four Artifacts

Requirements (problem, users, goals, non-goals, acceptance criteria), design (architecture, data model, contracts, security for this feature), task plan (small slices with dependencies and validation), traceability record (criteria to tests, decisions to files, tasks to commits). Step-by-step production of all four lives in the five-phase SDD workflow; a small feature can hold them in one short markdown file — habit beats format.

What SDD Is Not

Not documentation. Docs describe what exists, written after the fact. Specs constrain what may be built, authoritative before implementation, validated after. A spec describing what was built already failed.

Not TDD. Tests start TDD: failing test, minimum code, unit-level loop — excellent tests, no answer to whether the right thing is being built. SDD starts with intent: who hurts, what correct looks like, what’s out of scope — then informs which tests to write. SDD drives TDD: acceptance criteria become scenarios, design boundaries become contract tests, task plans become unit coverage lists.

Not BDD. Gherkin scenarios bridge business intent and implementation from the user’s perspective — useful as acceptance-criteria language inside a requirements spec, which is the container. BDD tooling makes scenarios executable; SDD makes intent durable across tools, sessions, and teammates.

Not formal methods. Proofs are rigorous and expensive; SDD needs no mathematical notation. Rigor scales with stakes:

  prose spec --> structured markdown + criteria --> machine-readable + schemas
      --> contract tests from spec --> formal proof

Most teams live in the middle: explicit enough to implement against and verify, reviewed by humans. Companion, not substitute: decision records capture why choices were made and what was rejected, while specs capture what to build and how to verify — intent plus reasoning, both in the repo.

Benefits and Costs, Honestly

Less drift (reviewers compare against something), better agent outputs (constraints and non-goals in context), easier PRs (spec as checklist), team alignment across people and agents, test planning falling out of criteria, handoffs that survive sessions and sprints.

Against that: real upfront effort (unjustified on small features), false confidence from unvalidated specs (stale specs mislead readers and agents alike), rot when specs are treated as planning exhaust instead of living documents, generated bureaucracy (a 200-task thirty-second plan is a schedule-shaped fog), and tool lock-in where proprietary formats trap portable intent — prefer markdown with headers and criteria.

Summary

Old discipline, newly practical: write intent down, reviewed and versioned, before agents build; keep it honest when reality differs; review, test, and hand off against it. Small enough to maintain, precise enough to constrain, durable enough to outlast any session. When to pay that overhead versus prompting freely is the prior call in SDD vs vibe coding.

Where does spec discipline pay most in your work — drift prevention, review speed, or handoffs? Share the setup in the comments below!