Document-Driven Development: Overview¶

Understanding the core principle and why it works

What is Document-Driven Development?¶

Document-Driven Development (DDD) is a systematic approach where:

1. Documentation comes first - You design and document the system before writing code
2. Documentation IS the specification - Code must match what docs describe exactly
3. Approval gate - Human reviews and approves design before implementation
4. Implementation follows docs - Code implements what documentation promises
5. Testing verifies docs - Tests ensure code matches documentation

Core Principle: "Documentation IS the specification. Code implements what documentation describes."

The Traditional Problem¶

Traditional approach: Code → Docs

What happens:

• Docs written after code (if at all)
• Docs lag behind code changes
• Docs and code diverge over time
• AI tools load stale/conflicting docs
• Context poisoning leads to wrong implementations
• Bugs from misunderstanding requirements

Result: Documentation becomes untrustworthy. Developers stop reading docs. More bugs.

The DDD Solution¶

DDD approach: Docs → Approval → Implementation

What happens:

• Design captured in docs first
• Human reviews and approves design
• Only then write code
• Code matches docs exactly
• Tests verify code matches docs
• Docs and code never diverge

Result: Documentation is always correct. Single source of truth. Fewer bugs.

Why This Works (Especially for AI)¶

1. Prevents Context Poisoning¶

Context poisoning = AI loads inconsistent information, makes wrong decisions

How DDD prevents it:

• Single source of truth for each concept
• No duplicate documentation
• No stale docs (updated before code)
• Clear, unambiguous specifications

2. Clear Contracts First¶

Problem: Implementation complexity obscures design intent

How DDD helps:

• Docs define interfaces before implementation
• Contracts clear before complexity added
• Easier to review design than code
• Cheaper to fix design than implementation

3. Reviewable Design¶

Problem: Design flaws discovered after expensive implementation

How DDD helps:

• Design reviewed at approval gate
• Catch flaws before coding
• Iterate on docs (cheap) not code (expensive)
• Human judgment applied early

4. AI-Optimized¶

Problem: AI tools rely on docs for context

How DDD helps:

• Docs always current
• No conflicting information
• Clear specifications
• AI can't guess wrong (spec is clear)

5. No Drift¶

Problem: Docs and code slowly diverge over time

How DDD helps:

• Docs come first, so can't lag
• If code needs to differ, update docs first
• Always in sync by design
• Drift is impossible

6. Modular Alignment¶

Problem: Unclear module boundaries and interfaces

How DDD helps:

• Docs define "studs" (interfaces) first
• Then build "bricks" (implementations)
• Clear contracts between modules
• Regeneratable from specs

7. Human Judgment Preserved¶

Problem: Critical decisions made during coding under pressure

How DDD helps:

• Design decisions at planning phase
• Time to think through trade-offs
• Expert review before commitment
• Better decisions

Philosophy Foundation¶

DDD builds on these principles:

From PHILOSOPHY.md¶

Ruthless Simplicity:

• Start minimal, grow as needed
• Avoid future-proofing
• Question every abstraction
• Clear over clever

Applied in DDD:

• Simple docs easier to maintain
• No speculative features in docs
• Each doc has one clear purpose
• Progressive organization

Bricks and Studs:

• Self-contained modules
• Clear interfaces (studs)
• Regeneratable from spec
• Human architects, AI builds

Applied in DDD:

• Docs define interfaces (studs)
• Code implements modules (bricks)
• Can regenerate from docs
• Human reviews design, AI implements

The Complete Process¶

Phase 0: Planning & Alignment
    ↓
    • Problem framing
    • Reconnaissance
    • Proposals and iteration
    • Shared understanding
    ↓
Phase 1: Documentation Retcon
    ↓
    • Update ALL docs to target state
    • Write as if already exists
    • Maximum DRY enforcement
    • Progressive organization
    ↓
Phase 2: Approval Gate ←─────┐
    ↓                         │
    • Human reviews design    │
    • Iterate until right     │ (iterate if needed)
    • THEN commit docs        │
    ↓                         │
    ├─────────────────────────┘
    ↓
Phase 3: Implementation Planning
    ↓
    • Code reconnaissance
    • Detailed plan
    • Right-sizing check
    ↓
Phase 4: Code Implementation
    ↓
    • Code matches docs exactly
    • Load full context
    • Commit incrementally
    ↓
Phase 5: Testing & Verification
    ↓
    • Test documented behaviors
    • Test as user would
    • AI is QA entity
    ↓
Phase 6: Cleanup & Push
    ↓
    • Remove temporary files
    • Final verification
    • Push to remote

When to Use DDD¶

✅ Use DDD For¶

Large changes:

• New features requiring multiple files
• System redesigns or refactoring
• API changes affecting documentation
• Any change touching 10+ files
• Cross-cutting concerns

High-stakes work:

• User-facing features
• Breaking changes
• Complex integrations
• Architecture decisions

Collaborative work:

• Multiple developers involved
• Need clear specification
• External review required

❌ Don't Use DDD For¶

Simple changes:

• Typo fixes
• Single-file bug fixes
• Trivial updates
• Documentation-only changes

Emergency situations:

• Production hotfixes
• Critical security patches
• System down scenarios

When uncertain: Lean toward using DDD. Process prevents expensive mistakes.

Key Benefits¶

Prevents Expensive Mistakes¶

• Catch design flaws before implementation
• Review is cheap, rework is expensive
• Philosophy compliance checked early
• Human judgment applied at right time

Eliminates Context Poisoning¶

• Single source of truth
• No duplicate documentation
• No stale information
• Clear, unambiguous specs

Optimizes AI Collaboration¶

• AI has clear specifications
• No guessing from unclear docs
• Can regenerate from spec
• Systematic file processing

Maintains Quality¶

• Documentation always correct
• Code matches documentation
• Examples always work
• New developers understand from docs

Reduces Bugs¶

• Fewer misunderstandings
• Clear requirements
• Tested against spec
• Integration verified

Success Criteria¶

You're doing DDD well when:

Documentation Quality:

• ✅ Docs and code never diverge
• ✅ Zero context poisoning incidents
• ✅ Examples all work when copy-pasted
• ✅ New developers understand from docs alone

Process Quality:

• ✅ Changes require minimal rework
• ✅ Design flaws caught at approval gate
• ✅ Philosophy principles naturally followed
• ✅ Git history is clean (no thrashing)

AI Collaboration:

• ✅ AI tools make correct decisions consistently
• ✅ No "wrong approach implemented confidently"
• ✅ Can regenerate modules from specs

Team Impact:

• ✅ Implementation time decreases (better specs)
• ✅ Bug rate decreases (fewer misunderstandings)
• ✅ Questions about features, not "which docs are right?"

What Makes DDD Different¶

Not Just "Write Docs First"¶

DDD is more than writing documentation before code:

Traditional "docs first":

• Write docs
• Write code
• Docs drift over time
• No systematic process

DDD:

• Systematic process with phases
• Approval gate before implementation
• Specific techniques (file crawling, retcon, etc.)
• Built-in prevention of drift
• AI-optimized workflow

Not Just "Spec-Driven Development"¶

DDD differs from traditional spec-driven development:

Traditional specs:

• Often separate from user docs
• Written in formal specification language
• Rarely updated after initial write
• Developers don't read them

DDD:

• User docs ARE the specs
• Written in clear human language
• Always current (updated first)
• Single source of truth
• Developers AND AI use them

Learning Path¶

If you're new to DDD:

1. Understand the principles (this document)
2. Why docs first matters
3. How context poisoning happens

4. What the process flow is

5. Learn the core techniques (core_concepts/)

6. File Crawling - Processing many files systematically
7. Context Poisoning - Understanding and prevention

8. Retcon Writing - Writing as if already exists

9. Practice with small project

10. Follow phase guides step by step
11. Use checklists to verify completion

12. Learn from common pitfalls

13. Apply to real work

14. Start with medium-sized feature
15. Reference tips for success
16. Use FAQ when questions arise

If you're an AI assistant:

1. Load overview (this document) to understand the process
2. Load relevant phase docs as you work through each phase
3. Reference core concepts when using those techniques
4. Use checklists to verify completion
5. Follow tips for AI assistants in each phase

Common Misconceptions¶

"This is too much process"¶

Reality: Process prevents expensive rework. An hour in planning saves days of coding wrong thing.

"We don't have time for this"¶

Reality: You don't have time NOT to do this. Rework from misunderstanding costs far more than upfront clarity.

"Our docs are already good"¶

Reality: If docs and code can diverge, they will. DDD makes divergence impossible by design.

"AI doesn't need perfect docs"¶

Reality: AI makes wrong decisions confidently when docs conflict. Context poisoning is real and expensive.

"This only works for big projects"¶

Reality: Works at any scale. Small projects benefit from clarity. Large projects require it.

Next Steps¶

Ready to start?

1. Read core concepts: core_concepts/

2. Essential techniques you'll use throughout

3. Follow the process: phases/

4. Start with Phase 0: Planning & Alignment

5. Work through each phase systematically

6. Use reference materials: reference/

7. Checklists to verify completion
8. Tips to avoid common mistakes
9. FAQ for quick answers

Have questions? See FAQ or common pitfalls.

Related Resources¶

Philosophy Foundation:

• PHILOSOPHY.md - Ruthless simplicity and modular design principles

Return to: Main Index

Document Version: 2.0 Last Updated: 2025-10-25 Ported From: microsoft/amplifier Document-Driven Development methodology