spec-driven-development

Spec-Driven Development for AI Software Factories

A methodology for building software where specifications are the executable input to an AI code generation pipeline. The factory model: specs are blueprints, AI agents are the assembly line, verification is quality control, and gates catch defects before they compound.

Pipeline Overview

INCEPTION → [SPECIFY] → REVIEW → [DECOMPOSE] → REVIEW → [IMPLEMENT] → REVIEW → [VERIFY] → DELIVER
                 ↑         ↑          ↑            ↑           ↑           ↑          ↑         ↓
            Phase 1    Gate 1    Phase 2       Gate 2    Phase 3      Gate 3    Phase 4   Gate 4

Each phase passes through a gate before the next begins. A defect caught at Gate 1 costs minutes to fix; the same defect found at Gate 4 costs hours.

Use an existing approved PRD, architecture document or issue set as the specification when it supplies the minimum handoff in references/factory-review-lanes.md. Throughout this workflow, SPEC.md denotes that authoritative specification; it need not be a new file or competing copy. Validate equivalent content and traceability. Run format-specific scripts only when their expected input format applies; otherwise record the equivalent content checks and any missing information explicitly.

SDD Core Principles

1. Make consequential intent explicit. Keep specifications readable and testable. Agents can ask for clarification; unresolved consequential choices need an owner and must stop dependent work before its decision boundary.
2. Completeness over brevity. Every missing acceptance criterion is a missing feature. Specifying an edge case upfront costs minutes; discovering it in production costs hours or days.
3. Testability over descriptiveness. An AC that cannot produce CLEAR PASS or CLEAR FAIL is not an AC — it's a hope.
4. Gates catch defects early. A Gate 1 (spec review) fix costs minutes. A Gate 4 (acceptance review) fix costs hours — the entire implementation may need to be discarded.
5. Spec is the single source of truth. Every downstream artifact traces back to the spec. Deviations are defects unless explicitly documented.
6. Specs guide test oracles. Gherkin-style ACs can become executable cases, but still need implementation, coverage and oracle review. Independent and withheld scenarios can reveal gaps in visible examples.