# Ddd Guide

> Document-Driven Development workflow for existing codebases. Provides systematic planning, documentation-first design, and implementation verification. Use when this capability is needed.

- Skill: `tomevault-io/ddd-guide` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/ddd-guide`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/ddd-guide/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/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.

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/drillan) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-13 -->