Documentation is not a human artifact maintained after the fact — it's the persistence layer that lets knowledge survive context resets, and stale docs are production bugs.

Principle

Documentation is Agent Memory

Why it exists

Humans accumulate. Agents reset.

👤Human engineer

MONlearns auth quirkcarries

TUEdebugs race bugcarries

WEDremembers both✓

Biological memory. Context accumulates across sessions. Docs are a supplement — the human already knows why.

🤖Agent

RUN 1learns auth quirklost

RUN 2debugs race buglost

RUN 3blank slate again✗

No persistence. Every new session is a cold start. The only knowledge that survives is what was written to disk.

A human supplements memory with docs. An agent has no memory except docs.

The unique danger

Agents don't apply skepticism to authoritative sources.

Stale docs don't fail loudly — they produce confidently wrong code.

CLAUDE.md

"6 test tiers"

written 3 months ago

→

Actual repo

7 tiers

added in PR #412

→

Agent ships

6-tier code

confidently wrong

A human reads stale docs and spots the drift.

An agent reads stale docs and builds to them with full confidence.

If docs are load-bearing, keeping them current isn't maintenance — it's production work.

The feedback loop

Documentation is a signal — not a byproduct.

What the previous agent wrote is what the next agent reads. The SDLC closes through docs.

PLAN

describe what to build, why, how

AGENT_SYSTEM.md

→

BUILD

produce code + record what drifted

build-summary.md

→

OPERATE

update ADW scripts, hooks, rules

notes.md

Next agent reads the artifacts — builds with accumulated context.

The loop closes through written state, not shared memory.

A build-summary isn't a formality — it's the handoff signal.

What agent-shaped docs look like

Optimized for grep — not for browsing.

Dense

Keyword-rich, not prose

✗"We should think about updating auth soon"

✓"validate_session_token middleware auth/"

Current

Stale is worse than absent

✗docs say 6 tiers, reality has 7

✓absent → agent asks. stale → agent lies.

Structured

XML, headers, explicit sections

✗wall of paragraphs, implicit structure

✓<constraint> / <example> / <rule>

Specific

Paths, names, function signatures

✗"update the auth module"

✓src/auth/middleware.py::validate_session_token()

Buried concepts don't get found — and what an agent can't grep, it can't use.

The subtle violation

Summarize compresses. Memory distills.

Summary (compression)

"We made several changes to the authentication module today to address various issues discovered during testing."

— fewer tokens, same ambiguity. No load-bearing insight survives.

→

Crystallization (memory)

"validate_session_token() must reject unexpired-but-unsigned JWTs — we learned this the hard way when login_flow.py silently accepted them."

— the next agent can act on this without re-deriving it.

Summaries let the lesson rot. Memory is what you wish the next agent didn't have to relearn.

The discipline

Documentation is production code.

In an agentic system, docs are the persistence layer — load-bearing whether you intended them to be or not. Stale docs are bugs. Writing them is a required phase of the SDLC, not optional cleanup.