Spec-Driven Development
Spec-Driven Development is a workflow where requirements, tasks, and specifications drive your development process while maintaining full traceability to implementation.
Overview
In a typical development workflow with AI coding assistants, you might:
- Describe what you want to build
- Have the AI implement it
- Review and iterate
But this creates a gap: there's no persistent record linking requirements to the code that implements them. If you come back weeks later, you've lost the context of why code was written the way it was.
Spec-Driven Development solves this by:
- Capturing specs - Requirements, tasks, and implementation notes
- Linking to code - Connecting specs to the functions, classes, and files that implement them
- Tracking changes - Recording which git commits implement which specs
- Maintaining context - Preserving the full history of decisions and iterations
Key Concepts
Specs (Notes)
A spec is any piece of documentation that describes what should be built:
- Feature requirements
- Bug reports
- Implementation tasks
- Design decisions
- Technical notes
Specs live in the Notes panel and can be organized by status:
- Note - General documentation
- Todo - Work to be done
- In Progress - Currently being worked on
- Complete - Finished work
Code Links
Specs can be linked to code at two levels:
- Symbol links - Connect to specific functions, classes, or interfaces
- Line range links - Connect to arbitrary code sections
When code is refactored (renamed, moved), symbol links automatically update because they use content-based hashing rather than file paths.
Git Commit Links
When work on a spec is completed, the implementing git commit is linked to the spec. This provides:
- Full audit trail from requirement to implementation
- Ability to trace back from code to the original requirement
- History of changes related to a specific feature
Workflow
- Create a spec describing what needs to be built
- Link to existing code if modifying existing functionality
- Implement the changes (with AI assistance or manually)
- Mark complete when implementation is done
- Commit is linked automatically or manually
- Verify the implementation meets the spec
Getting Started
- New projects: Start creating specs for new features as you build them
- Existing projects: Import existing specs from Claude Code conversation history
AI Integration
The MCP server exposes spec management tools to AI coding assistants:
| Tool | Description |
|---|---|
list_notes | View all specs with optional filtering |
get_note | Get details of a specific spec |
update_note_status | Mark specs as in_progress or complete |
get_next_task | Get the next queued task to work on |
create_spec_link | Link a spec to code |
link_commit_to_spec | Link a git commit to a spec |
This enables AI assistants to:
- Pick up tasks from the queue
- Mark them in progress while working
- Link their changes to the spec
- Mark complete when done