Issue #1 · 2026 · Free / Open Source · documentationfirst.ai
Documentation-Driven
Development V2
Documentation First for AI — 2026
A field manual for developers,
POs, and AI agents working together.
Stop explaining. Start documenting.
DDD Fanzine #1
Documentation-Driven Development
v1.1 — June 2026
github.com/documentationfirst
FREE
fork it
Code is temporary · Docs are forever · #DDD #ContextEngineering
The AI
Amnesia
Problem.
Every time you open a new session, the agent forgets everything. You re-explain the stack, the conventions, the last three weeks of decisions. Again.
We've been building powerful AI tooling on top of a broken assumption: that the agent will somehow remember. It won't. Context windows close. Sessions expire. Memory is expensive and unreliable.
The industry's answer has been prompts: longer, smarter, more elaborate prompts. But prompts are ephemeral. They vanish. They aren't versioned. They can't be reviewed, corrected, or shared with your team.
AI agents are not dumb.
They are amnesiac.
The fix is not a better prompt.
It's infrastructure.
Documentation-Driven Development (DDD) is the answer. Not a framework. Not a tool. A discipline: write the context before you write the code.
This fanzine is a field manual. Tear it apart. Fork it. Disagree with it. But try it first.
The Five Principles
1. Docs before code
Every feature, migration, or architectural change starts as a .md file. The agent reads the doc. Then it acts.
2. Version your context
Documentation lives in Git alongside the code. It is reviewed, branched, and tagged. It has history. It is a first-class citizen.
3. The agent writes back
After execution, the AI updates the documentation. What was done. What changed. What it learned. The loop closes.
4. Knowledge is capital
The real IP of a team is not the code — it's the accumulated decisions, mistakes, and conventions encoded in the docs. Protect it. Grow it.
5. Language agnostic
Docs describe intent, not syntax. When the stack changes, the docs survive. Angular → React, Python → Go: the knowledge travels.
6. Agent agnostic
All you need is a high-IQ adaptive AI agent with a clear view in an instant. Any agent is expandable. Copilot today, Claude tomorrow, local model next week: the context stays intact.
The DDD Loop
PO → specification/specs-functional.md
Dev → technical/specs-technical.md
AI → reads, executes, writes done/*.md
Steps as Mini-Retrospectives
Each step closes with 3 lines in dev-context.json → lastSession: what was done · what remains · what blocked. The next session picks up instantly — no re-reading the full history.
Six
Types.
One System.
📜 Contract
Agent profile: strict / standard / permissive. Permissions. Written once. Never reset.
🎯 Context
Current unit of work: title, description, todo list. Read first. Reset on each new context.
📋 Specification
Functional specs (PO). User stories, acceptance criteria. Reset — except permanent-*.
⚙️ Technical
Architecture decisions, API contracts (Dev). Reset — except permanent-*.
✅ Done
Execution report. Written by the AI after each task. Fully reset on new context.
🎓 Skills
Role, stack, conventions — persists across all contexts. The agent's permanent identity.
Getting Started
- 🎓 Write your first skill →
skills/permanent-dev-stack.md
- 📄 Write functional specs →
specs-functional.md
- 📄 Write technical specs →
specs-technical.md
✦ The 3S Rule — Every Context Doc Must Be
S1
Selected
Only what the agent needs. No noise. No dump.
S2
Synthetic
As short as possible. Distilled, not transcribed.
S3
Structured
Headings, bullets, tables. Structure is clarity.
Noise kills context. A 3S doc is a doc the agent can actually use.
Skills/
Persistent
Knowledge.
Specs describe what to build. Skills describe who the agent is on your project. They survive every context switch.
Documents = what to do now.
Skills = how to work here, always.
What goes in a skill?
🎭 Role
Senior dev? Architect? PO writer? Define the persona before the first line of code.
🛠️ Stack
Languages, frameworks, forbidden libs, build tools. What exists. What must not appear.
📐 Conventions
Naming, file structure, patterns to follow and avoid. The unwritten rules — now written.
🗺️ Architecture
Where things live. What touches what. How to navigate without getting lost.
The 'permanent-' convention
skills/
├── permanent-dev-typescript.md ← survives
├── permanent-architecture.md ← survives
└── onboarding-notes.md ← reset on new context
Any file prefixed permanent- in skills/, specification/ or technical/ is kept when switching to a new context. Everything else is cleared.
Harness
the
Agent.
Memory is the .md files. Context is the documentation. Harnessing is done by the context itself.
🧠 Memory = docs
Not in someone's head. Not in a chat log. In a versioned file you can read, edit, commit, and fork.
🔗 Context = harness
The .ai_context/ folder doesn't inform the agent — it constrains it. Role. Rules. History. The agent cannot drift.
Documentation is the constant.
The agent is a variable.
SEAL — Self-Evolving Agent Learning
The agent doesn't get smarter because its model changed, it gets smarter because its context gets better.
👻 Documental Engineering
The practice of treating the document layer as the primary engineering artifact. Not the code, not the prompt. The invisible infrastructure that makes the agent coherent, consistent, and trustworthy across every session as a fresh new one coworker.
Legends of the Future Past
🕹️ A MUD from 1992 — resurrected in 2026
A text-based multiplayer game went offline. The server code was lost. Yet the game came back — 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.
Microsoft Research — 2026
🔬 "LLMs Corrupt Your Documents When You Delegate"
DELEGATE-52 benchmark — 19 models, 52 documents, 20 interactions each.
Top frontier models: ~25% of content corrupted after 20 interactions.
Average across all models: ~50%. No plateau at 100 interactions.
Agentic tool use (web, code): +6% additional degradation.
Only Python code — mechanically verifiable — held at 98%+.
Everything else? Silently corrupted.
DDD's answer: the AI adds to done/.
The human reviews and commits.
Git tracks everything. No silent writes.
Knowledge
is
Capital.
🌐 Language Agnostic
Docs describe intent, not syntax. They survive every migration, every rewrite. Angular → React, Python → Go: the knowledge travels.
📦 Fully Portable
Plain Markdown in Git. Switch agents, switch IDEs, switch companies. Zero lock-in. The context travels with you.
🔄 Contextual Adaptation
Every correction sharpens the docs. Every mistake documented never repeats. The system learns — because the team writes it down.
Code is a snapshot.
Docs are the source of truth.
⚖️ A Call for a New Kind of License
MIT, Apache, CC BY — all designed for software artifacts. A DDD repository is not an artifact. It is a living, evolving context — co-authored by developers, product owners, and AI agents over months or years.
We need a Living Knowledge License: one that acknowledges collective authorship, protects the integrity of the context, and enables fair use by AI systems without erasing attribution.
⚠️ malus.sh proposes AI robots that reconstruct any open source lib from its docs alone — "zero attribution, zero copyleft." Real or not, it proves the point: when docs outlive code, IP law hasn't caught up.
A team that loses its codebase can rebuild. A team that loses its Knowledge Capital starts from zero.
The idea
The conversation is the raw material. The plugin reads it, structures it, and proposes a versioned document. The developer reviews and commits. The knowledge is captured — not lost in a chat log.
DDD ⊃ SDD
Spec-Driven Development (spec-kit, Kiro, Tessl) turns intent into specs — an excellent generation engine. But those tools are feature-scoped and their specs are ephemeral. They all emit Markdown.
DDD is the superset: it hosts, versions and compounds those specs across the whole project lifecycle. Drop requirements.md straight into specification/, design.md into technical/ — then add what SDD lacks: the contract, the execution memory, the Knowledge Capital.
SDD asks, DDD answers
SDD: "how do I turn intent into a spec?" — DDD: "and where that spec lives, versions and compounds — for the whole project, forever."
DDD + MCP
The Model Context Protocol (MCP) by Anthropic formalises what DDD does informally: structured context injection for AI agents. DDD is a human workflow built on the same principle — and a natural fit for MCP-compatible tooling.
As MCP matures, .ai_context/ becomes a portable context server that any MCP-compatible agent can consume. Write once, serve everywhere.
Memory vs. Documentation
Vector memory tools (MemPalace, etc.) are powerful — but expensive, opaque, and non-portable. DDD's hypothesis: well-structured versioned Markdown outperforms implicit memory for most software teams. Transparent, diffable, auditable. Always.
#DDD
#ContextEngineering
#SDD
#MCP
#IDEPlugin
#KnowledgeCapital
#OpenSource
Docs
Are
Forever.
Code will be rewritten. Frameworks will be replaced. AI models will change. Your .md files will outlive all of it — if you treat them as the infrastructure they are.
||| ||| | ||| | || ||| || | || ||| | ||| || | || ||| | ||| || | || |||
documentationfirst.ai — DDD FANZINE #1 — 2026 — FREE
☕
Ko-fi
ko-fi.com/
documentationfirst
🎁
Patreon
patreon.com/
documentationfirst
🏆
Certification
Founding spots
open now
Fork the manifesto → github.com/documentationfirst
Improve it → open an Issue or a Pull Request
Share it → print it, post it, pin it on your wall
documentationfirst.ai · #DocumentationFirst · #DDD