Agent Skills: Document-Driven Development (DDD) Guide

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:

1. Generate index with [ ] checkboxes
2. Process one file per iteration
3. 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 methodologies
• phases/ - Step-by-step phase guides
• philosophy/ - 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.