Document-Driven Development (DDD) Guide
Core Principle
Documentation IS the specification. Code implements what documentation describes.
DDD inverts traditional development: update documentation first, then implement code to match.
Why DDD?
- Catches design flaws early - Before expensive code changes
- Prevents documentation drift - Docs and code stay synchronized
- Enables human review - Humans approve specs, not code
- AI-friendly - Clear specifications reduce hallucination
Six-Phase Workflow
| Phase | Name | Command | Deliverable |
|---|---|---|---|
| 0-1 | Planning | /ddd 1-plan | plan.md |
| 2 | Documentation | /ddd 2-docs | Updated docs |
| 3 | Code Planning | /ddd 3-code-plan | code_plan.md |
| 4 | Implementation | /ddd 4-code | Working code |
| 5-6 | Finalization | /ddd 5-finish | Tested, committed |
Core Techniques
Retcon Writing
Document features as if they already exist. No future tense.
- Bad: "This feature will add..."
- Good: "This feature provides..."
File Crawling
Process files one at a time to avoid context overflow:
- Generate index with
[ ]checkboxes - Process one file per iteration
- Mark
[x]when complete
Context Poisoning Prevention
Eliminate contradictions:
- One authoritative location per concept
- Delete duplicates, don't update
- Resolve conflicts before proceeding
When to Use DDD
Use DDD for:
- Multi-file changes
- New features in existing codebases
- Complex integrations
Skip DDD for:
- Typo fixes
- Single-file changes
- Emergency hotfixes
References
See @skills/ddd-guide/references/ for detailed documentation:
core-concepts/- Techniques and methodologiesphases/- Step-by-step phase guidesphilosophy/- Underlying principles
Remember
Documentation first. If it's not documented, it doesn't exist.
Retcon, don't predict. Write as if the feature already exists.
One source of truth. Delete duplicates, don't update them.