Docs/Concepts/Spec-Driven Development

Spec-Driven Development

Spec-Driven Development (SDD) flips the usual order of work: you write a precise specification first, and treat the code as a disposable artifact generated from it. This page explains the idea from scratch - no prior experience assumed.

New here? Read this page top to bottom once. Everything else in the docs assumes these five ideas.

Why not just prompt and code?

When you hand an AI agent a vague idea, it guesses the parts you left out - and it guesses confidently. Those guesses become bugs you discover weeks later, when nobody remembers what the code was even supposed to do. A spec removes the guessing: it states the behavior, the edge cases, and the constraints before a line is written.

The tradeoff is real but favorable. You spend more time up front deciding what to build, and far less time debugging code that does the wrong thing correctly.

The five ideas

The spec is the output

Your real work is the spec (requirements, schemas, contracts). Code is generated from it and can be regenerated.

Code is disposable

With a solid spec you can scrap the code and rebuild it - even switch languages - without losing progress.

Define failure, not just success

Every requirement states its edge and failure cases up front, as Given / When / Then scenarios.

Propose before you build

The agent proposes structure and a plan; a human approves it before any code is generated.

How Throughspec applies it

Throughspec turns these ideas into an enforced workflow. The spec lives in claude/srs.md, the plan in claude/plan.md, and a compressed memory layer keeps the agent consistent across a long project. Each phase gates the next - you cannot plan before the spec is frozen, or build before the plan is written.

Requirements

/spec-requirements cross-questions you, then freezes claude/srs.md with acceptance scenarios.

Design + Plan

/spec-design and /spec-plan turn the spec into a design system and an 8-10 step build plan.

Build

/spec-feature implements one plan stage at a time, updating the memory layer after each.

Deeper dive: see The Memory Layer for how Throughspec keeps token cost flat as a project grows, and Workflows for the full cycle.