spec-driven-development

1# Spec-Driven Development
2 
3## Overview
4 
5Write a structured specification before writing any code. The spec is the shared source of truth between you and the human engineer — it defines what we're building, why, and how we'll know it's done. Code without a spec is guessing.
6 
7## When to Use
8 
9- Starting a new project or feature
10- Requirements are ambiguous or incomplete
11- The change touches multiple files or modules
12- You're about to make an architectural decision
13- The task would take more than 30 minutes to implement
14 
15**When NOT to use:** Single-line fixes, typo corrections, or changes where requirements are unambiguous and self-contained.
16 
17## The Gated Workflow
18 
19Spec-driven development has four phases, preceded by a scope check (Phase 0) that activates only when one request bundles several independently testable capabilities. Do not advance to the next phase until the current one is validated.
20 
21```
22SPECIFY ──→ PLAN ──→ TASKS ──→ IMPLEMENT
23   │          │        │          │
24   ▼          ▼        ▼          ▼
25 Human      Human    Human      Human
26 reviews    reviews  reviews    reviews
27```
28 
29### Phase 0: Scope Check
30 
31Most requests describe one capability. If this one does, skip this phase and go straight to Specify — Phase 0 exists for the exception, not the rule, and it puts no hierarchy on single-capability features.
32 
33**Detection.** Decompose before specifying when a single requirement bundles several independently testable capabilities:
34…