Documentation-Driven Development

The Problem

AI agents are not dumb. They are amnesiac. Every session starts from zero. No context, no history, no conventions. You spend 20 minutes re-explaining the project before getting anything useful done.

DDD ⊃ SDD

Spec-Driven Development (spec-kit · Kiro · Tessl) generates specs from intent — feature-scoped, ephemeral, all Markdown. DDD is the superset: it hosts and versions those specs for the whole project, and adds what SDD lacks — contract, execution memory, Knowledge Capital.

SDD: "how do I turn intent into a spec?" · DDD: "and where it lives, versions & compounds — forever."

The Flip

Every architectural decision in a .md file. Every migration step written before execution. Every convention versioned alongside the code.

The Loop

PO writes specs → specification/ Dev enriches → technical/ AI reads, executes → done/*.md Step closes → lastSession in dev-context.json PO / Dev reviews → loops

Documental Engineering

Memory = the .md files. Documental context = the harness.

Documental Engineering — the ghost in the machine.

🎓 Write your first skill → skills/permanent-dev-stack.md
📄 Functional specs (PO) → specs-functional.md
📄 Technical specs (Dev) → specs-technical.md
📄 AI report → DONE.md
📁 Group by context in versioned subfolders
🎫 Prompt = User Story referencing the docs

The Six Document Types

📜 Contract Agent profile + permissions. Written once. Never reset.

🎯 Context Current unit of work: title, todos. Reset each context.

📋 Specification Functional specs (PO). Reset — except permanent-*.

⚙️ Technical Architecture & decisions (Dev). Reset — except permanent-*.

✅ Done AI execution report. Every change, every decision. Fully reset.

🎓 Skills Role, stack, conventions. Persists across all contexts.

Four Superpowers

🌐 Language Agnostic — docs describe intent, not syntax. Survives every migration.
🤖 Agent Agnostic — any high-IQ adaptive agent works. Any agent is expandable.
📦 Fully Portable — plain Markdown in Git. Switch agents? Docs follow. Zero lock-in.
🔄 Contextual Adaptation — every correction sharpens the docs. Errors don't repeat.

Reconstruction Guarantee

If you lost the codebase tomorrow, your .md files must allow you to:

Understand the project's purpose and architecture
Know every rule and convention to follow
Reproduce every migration or refactoring step
Make correct decisions in ambiguous situations

Real-World Proof

🕹️ Legends of the Future Past — 1992

A MUD from 1992 came back online in 2026. Not because someone had the original server code — because the structured text files describing the world had survived: zones, characters, rules, quests, lore.

The executable was gone. The documentation was not. The game was rebuilt from its data files alone.

Your .md files are those data files.

Knowledge Capital

In DDD, the real intellectual property lives in the documentation — not the code. The code is a snapshot. The .md files encode why decisions were made, what failed, and what the team learned.

A team that loses its codebase can rebuild. A team that loses its Knowledge Capital starts from zero.

⚠️ malus.sh proposes AI robots that reconstruct any lib from its docs alone — zero attribution. Real or not: when docs outlive code, IP law hasn't caught up.

Scientific Proof — 2026

🔬 Microsoft Research — DELEGATE-52

19 models · 52 documents · 20 interactions

Top models: ~25% corrupted. Average: ~50%. No plateau. Agentic tools: +6% worse.

Only Python (verifiable) held at 98%+. Prose? Silently degraded.

DDD answer: AI adds to done/ — human reviews — Git tracks. No silent writes.

✦ The 3S Rule

Selected — only what's relevant to the task
Synthetic — distilled, not dumped
Structured — headings, bullets, tables