Theory
Key idea. Spec-Driven Development (SDD) means writing a specification before writing code with AI. The spec becomes the single source of truth for both the human and the AI agent.
Why SDD exists
Standard "vibe coding" often leads to broken code or regressions because the AI lacks full context. SDD uses a specification as the single source of truth, ensuring AI agents execute against a verified roadmap rather than guessing intent.
1. Predictability and Reliability The spec prevents the AI from straying into hallucinations or inconsistent design patterns.
2. Efficiency at Scale By providing AI with unambiguous, executable contracts, teams can generate working features exponentially faster.
3. Traceability and Maintenance The "why" behind architectural decisions is versioned alongside the code. Onboarding and auditing become significantly easier.
4. Solving Context Drift AI models lose project nuance over long-lived sessions. SDD forces technical constraints and success criteria to be defined upfront.
Three levels of SDD maturity
- Spec-First Write specs before implementation begins
- Spec-Anchored Keep specs updated during evolution
- Spec-as-Source The spec is the primary artifact; code is generated from it
The canonical SDD loop
Specify → Plan → Execute → Verify → Integrate → Learn
The core artifact set:
- SPEC.md Intent, constraints, acceptance criteria
- PLAN.md Approach, trade-offs, sequencing
- TASKS.md Atomic tasks with done checks
Practice
Run this in a repository you already know, not a toy project. The point is to feel where the practice helps and where it gets in the way on code that has history.
- Take a feature you recently built (or are about to build).
- Write a one-page SPEC.md for it: include the intent in one sentence, 3–5 constraints, and 2–3 acceptance criteria in Given/When/Then format.
- Share the spec with an AI agent and ask it to generate a PLAN.md. Review how closely the plan matches your intent.
- Reflect: where did the AI make assumptions you hadn't considered?