What is SDD
Spec-Driven Development is a way of working with Claude Code where no feature code is written until you've approved a spec.
Every feature goes through requirements, a design that's checked against your current stack, and a list of small tasks that each name a check to run.
Claude then builds it one task at a time. Your main conversation coordinates, and separate agents do the heavy lifting:
they research the codebase, build each task with a clean slate, and give an independent verdict at the end.
STATE.md, anchored to a git commit, records where every feature stands, even when teammates don't use Claude.
The loop
→
Commit + /clear
fresh context
→
Implement
1 agent per task
→
Validate
independent reviewer
Who does what
You
Start each skill with a slash command. Answer questions, choose between stack options, and approve each spec phase and the implementation plan. Merge branches.
Main conversation
Runs the skill, asks you questions, writes the spec, plans the work, hands out tasks, runs each task's check, commits, and keeps tasks.md and STATE.md current.
Agents
Explore researches the codebase. sdd-implementer builds one task. sdd-reviewer checks the result against the spec. Each starts with a clean slate and reports back a short summary.
Why agents? Claude's working memory (its context) fills up as it reads files and runs commands, and quality drops as it fills.
Handing research and each task to a separate agent keeps the main conversation small. A reviewer that never saw the implementation also judges it without bias.
More on the agents →
Folder map
# once per machine (Setup page)
~/.claude/
├── CLAUDE.md your preferences
├── skills/
│ ├── sdd-startup/SKILL.md
│ ├── sdd-bootstrap/SKILL.md
│ ├── sdd-checkup/SKILL.md
│ ├── sdd-feature/SKILL.md
│ ├── sdd-implement/SKILL.md
│ └── sdd-validate/SKILL.md
└── agents/
├── sdd-implementer.md
└── sdd-reviewer.md
# in each project (generated by the skills)
my-project/
├── CLAUDE.md stack · commands · rules
├── STATE.md feature status + commit
├── .claude/
│ ├── steering/
│ │ ├── product.md what and who
│ │ ├── tech.md stack decisions
│ │ └── structure.md where code lives
│ └── settings.json optional, for parallel
└── specs/
└── csv-export/
├── requirements.md
├── design.md
└── tasks.md tasks + checks
Where to start
Step 0 · Once per machine
Setup
Install the skills and agents with one command, add your personal CLAUDE.md, and pick models.
→
New project
New Project
No code yet. /sdd-startup walks you through purpose and stack trade-offs, then writes the project's context files.
→
Existing project
Existing Project
Code already exists. /sdd-checkup audits what's there, and /sdd-bootstrap writes the context files from the code.
→
Day to day
Workflow
What to type, and when: spec a feature, implement it task by task, validate it, and run features in parallel.
→
Reference
Skills
Read the full SKILL.md of every skill, with arguments and what each one writes.
→
Reference
Agents
How the coordinator delegates work to sdd-implementer, sdd-reviewer and the built-in Explore agent.
→
Skills overview
/sdd-startup
New projects only. Interviews you about the project, then walks through each stack decision with trade-offs.
/sdd-startup [idea] · once per project
/sdd-checkup
Audits an existing project: context files, STATE.md drift, orphaned specs, old task formats, missing agents. Reports before changing anything.
/sdd-checkup · any unfamiliar project
/sdd-bootstrap
Existing code without context files. Maps the code with parallel Explore agents and records what's there, without inventing decisions.
/sdd-bootstrap · once per project
/sdd-feature
Requirements → design (stack-gap check) → tasks with checks. You approve each phase. No code.
/sdd-feature <name> [description]
/sdd-implement
Coordinates the build: one sdd-implementer agent per task, then a check, a commit and a tick for each. Several features can run in parallel worktrees.
/sdd-implement <feature> [and <feature>…]
/sdd-validate
sdd-reviewer gives a pass/fail verdict per acceptance criterion. Then it updates the steering docs, STATE.md, CHANGELOG, README and version.
/sdd-validate <feature>