Documentation is King: Docs Are the Agent Interface

The Flip That Changes Everything

For most of software history, documentation was a good intention with a structural problem. You wrote the docs at implementation time, the implementation drifted, the docs lagged, nobody read the outdated docs because they were wrong, nobody updated the docs nobody read — and eventually the documentation was declared useless. This was the rot loop, and it was stable for decades.

Then something changed. Not a new documentation format. Not a better static-site generator. Not a culture initiative about "treating docs like code." What changed is that a new category of reader emerged — one that reads every word, cannot route around outdated information, and acts immediately on whatever it finds.

Coding agents — tools like Claude Code, Cursor, and similar environments — read your documentation before they touch your code. Not once during onboarding. Every session. Every dispatch. Every time a new agent is spawned to fix a bug, add a feature, or run a review.

That diagram is the architecture shift in one view. The human intent layer — your PRDs, your READMEs, your ADRs — now runs before the execution layer. An agent that doesn't find orientation context will invent it. An agent that finds a stale context file will follow it. An agent that finds accurate, terse, hard-rule documentation will build at a level of quality that scales.

The Rot Loop vs. The Compounding Loop

The original rot loop had a specific structure: because humans could route around bad docs (by asking colleagues, reading source code, relying on memory), there was no immediate cost to letting docs decay. The decay was invisible. The docs gradually drifted from reality, someone was eventually misled badly enough to complain, and a one-time update was made. Then the cycle repeated.

Look at step 4 in the compounding loop column. When an agent follows a stale doc, it produces a wrong implementation that surfaces in the same PR — often the same session. The feedback cycle has collapsed from months to hours. This is not a problem with agents; it is the mechanism that breaks the rot loop.

The concrete version: Knox's setup once had two machines — a dev laptop and a production server — sharing the same repo layout, the same file paths, the same localhost URLs. For months, the missing distinction in the documentation was invisible. Engineers knew which box was which. Then an agent built and "verified" a full session of fixes on the dev laptop. Every test passed. Knox reloaded the production dashboard and hit a crash immediately, because the production server had never received those changes. The fix was 15 minutes once the topology mismatch was understood: SSH to the production box, pull the same changes already on main, rebuild. But the session had been wasted.

The rule extracted from that incident — a hard host-check at the top of the context file that runs before any deploy claim is made — became the first thing every subsequent agent session reads. The mistake became impossible to repeat. One correction, compounding across every future session.

That is the compounding loop in practice: a correction becomes a rule, the rule is loaded at session start, the mistake cannot recur. The only mechanism by which agent quality compounds instead of resetting to zero each session is the documentation layer between them.

Documentation as Executable Context

The most useful mental model for this track is: a doc is executable context. It is not a description of something for a human to glance at and interpret loosely. It is a precise input that an agent will parse literally and act on.

This has sharp implications for how you write:

Precision over completeness. An agent does not need everything — it needs the things that will cause it to make mistakes if missing. A 30-line context file that covers five hard rules and a key-files table does more work than a 200-line essay that buries the rules in paragraphs.

Rules over observations. "The dev laptop is not the production machine" is an observation. "Before any deploy, verify which machine you are on using the host-check command" is a rule. Agents act on rules. Observations require interpretation.

Earned lines. Every line in a context file costs tokens on every session. The question for each line is not "is this true?" but "does removing this cause a mistake?" If removing it loses nothing, remove it.

Timeliness matters. A context file that says "we are in the middle of the Phase 3 migration" was accurate when written and stale two days later. Stale information that a human would recognize as outdated is read literally by an agent. Document states that don't decay — rules, constraints, topology facts — not states that do.

What This Track Covers

This track walks every doc type in the stack, from the README that greets every new session to the CI gates that keep docs honest over time. The prerequisite track — spec-driven-development — covers PRDs in depth; this track starts where PRDs end.

The ten lessons cover:

• The documentation taxonomy — seven doc types, seven jobs, one principle (one doc, one job)
• The README — the 60-second orientation test and the key-files table pattern
• Agent context files — the newest doc type: session-start operating instructions
• ADRs — writing decisions down before they become folklore
• Runbooks — docs written for 3am, for a stranger, for an agent under pressure
• The learning loop — lessons files and post-mortems as the compounding mechanism
• Docs as contracts — API references that cannot drift
• Keeping docs alive — freshness signals, ownership, and CI gates

By the “Capstone” lesson, you will have a model for a repository that a brand-new agent session can orient, operate, respect history, and improve — with zero human hand-holding. That is the goal: a codebase that improves agent output quality automatically, every session, compounding forward.

Start with the taxonomy. Before building any specific doc type well, you need the map of what exists and what each piece is for.