diff --git a/CLAUDE.md b/CLAUDE.md
index 476940c..4c61b50 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -42,6 +42,7 @@ If this is a new project:
    - **FUTURE.md** — Ideas and improvements not on the active roadmap (Problem/Idea/Open questions/Depends on format)
    - **README.md** — Human-readable overview, quick start, milestones, and scripts reference
 4. Parse the other CLAUDE.md files from sibling project folders in `~/dev/claude/`, and based on the type of project being considered, bring over related practices, guidelines, and learnings
+5. **For coding projects with multiple milestones:** Read `best-practices/spec-driven-development.md` and `best-practices/test-driven-development.md`. Create `SPEC.md` and `spec/` directory. Write specs before writing code. See the "Spec-Driven Development" section below.
 
 ## Source Control
 
@@ -189,6 +190,44 @@ This file becomes the implementation reference for the session that follows plan
 
 This ensures the plan stays accurate as a living document — useful for resuming across sessions, reflecting on the milestone, and understanding what actually happened vs. what was planned.
 
+## Spec-Driven Development
+
+**Any coding project with multiple milestones MUST have specs before code.** This is a hard requirement, not a suggestion. The workflow is: Plan → Spec → Test → Code.
+
+**At project start (or when starting a new milestone), always read:**
+- `best-practices/spec-driven-development.md` — spec structure, requirement numbering, scenarios, maintenance
+- `best-practices/test-driven-development.md` — edge case discovery, property-based testing, AI agent testing patterns
+
+### Required Artifacts
+
+Every multi-milestone coding project must have:
+
+1. **`SPEC.md`** — Index file at the project root. Lists all spec files with a "when to read" column. Same thin-index pattern as MEMORY.md.
+2. **`spec/` directory** — One spec file per subsystem. Each spec follows the required structure: Overview, Responsibilities, Dependencies, Data Model, Requirements (numbered), Scenarios (given/when/then).
+3. **Numbered requirements** — Each spec uses a prefix (e.g., `IG-1` for ingestion, `DB-1` for database). Requirements must be independently testable and unambiguous.
+4. **Test files that reference spec IDs** — Every test function name includes its requirement ID: `test_ig3_dedup_by_message_ts`.
+
+### The Workflow
+
+1. **Plan** — Architecture decisions, milestone breakdown, technology choices (PLAN.md)
+2. **Spec** — Detailed contracts, data models, interfaces, requirements, scenarios (spec/)
+3. **Test** — Write tests from the spec before code exists. They should all fail.
+4. **Code** — Implement until tests pass. Minimum code to satisfy the spec.
+5. **Update** — If implementation reveals spec issues, update spec → test → code in that order.
+
+### When to Write Specs
+
+- **Before M1 implementation begins** — write specs for all subsystems in M1's scope
+- **Before each subsequent milestone** — write specs for new subsystems, update existing specs for changes
+- **Spec changes and test changes ship in the same commit**
+- **Code changes that affect interfaces require spec changes in the same commit**
+
+### What Does NOT Need a Spec
+
+- Infrastructure-only projects (Helm values, Kustomize manifests, Ansible playbooks) — these are declarative, not behavioral
+- Single-script utilities — a well-commented script with a test is sufficient
+- Documentation-only changes
+
 ## Milestones
 
 Break projects into numbered milestones (M1, M2, ...). Every milestone completion MUST include: