Spec-Driven Design
Using specification files to guide Claude Code toward consistent, high-quality output.
Why Spec-Driven Design
Instead of jumping straight into code generation (vibe coding), spec-driven design creates a specification document first that describes the application, use cases, and requirements. Claude Code then references this spec during implementation, which optimizes the context window and produces more consistent results.
The Workflow
- ▸Switch to Plan mode (Shift+Tab) — read-only research and planning, no file writes
- ▸Ask Claude to research and write an initial specification
- ▸Review and refine the spec — adjust scope, data models, UI requirements
- ▸Store the spec as a CLAUDE.md file under a spec/ or memory/ directory
- ▸Switch to a code-generation model (e.g. Sonnet) and reference the spec with @ when prompting
- ▸Claude implements according to the specification
What Goes in the Spec
| Section | Purpose |
|---|---|
| Project Overview | What the application is and who it's for |
| MVP Scope | What's in and what's explicitly out |
| Data Model | Entity structure, relationships, fields |
| UI/UX Requirements | Layout, components, interactions |
| Technical Architecture | Stack choices, patterns to follow |
| User Stories | Key user flows for the MVP |
| Future Considerations | Acknowledged but deferred features |
Plan Mode vs Code Mode
Plan mode is designed for research and planning. It uses read-only tools and heavier reasoning models (like Opus) for deep thinking. Code mode is for implementation — it uses code-generation-optimized models (like Sonnet) and has write access. Separating these phases improves both planning quality and code quality.
After implementing, start a fresh session to avoid context rot. Exit with /exit, reopen Claude Code, and reference the spec again for the next task. This keeps the context window clean.