Documentation Is Now Maintained for the Only Teammate Who Reads It

SATIRE — The documentation revival has arrived at last, driven by the only colleague with both unlimited curiosity and no ability to remember a conversation from Tuesday: the AI coding agent. Across the industry, engineers are reopening README files, documenting service boundaries, and writing down why InvoiceFacadeV2 must never call InvoiceFacade directly—not for onboarding, compliance, or the fragile human spirit, but because the robot otherwise starts a helpful new billing subsystem in src/utils/.

The change has been widely welcomed by the fictional Institute for Organizational Recall, whose annual report found that 94,000% of codebase knowledge previously existed as a sigh emitted during a screen share. Its recommended remedy is a document called AGENT_CONTEXT.md, which must describe every architectural decision since 2017, every exception to every architectural decision, and the emotional history of the one directory called legacy-final-final-DO-NOT-TOUCH.

The new audience has exacting standards

Human readers used to tolerate a README that said, “Run the app locally.” The agent requires an operational biography. It needs to know which runtime to install, which environment variable is secretly mandatory despite having a default, why tests fail between 12:03 and 12:11 a.m., where generated code lives, and whether “do not modify migrations” means do not modify migrations or merely do not modify them without making eye contact with the database administrator.

Accordingly, teams have updated their writing style. Architecture documents now begin with a purpose statement, continue through dependency constraints, and end with explicit tool instructions: “Before changing authentication, inspect packages/auth, packages/session, and the abandoned prototype in archive/identity2. Do not infer that similar filenames indicate interchangeable behavior. They do not. This is not a puzzle.”

The instruction is not melodrama. It is preventative maintenance. An agent given only a ticket reading “add SSO” can inspect 1,842 files, discover three auth libraries, correctly identify none of them as authoritative, and propose a fourth. The proposal will be impeccably formatted, include a migration plan, and leave behind a new AuthProviderFactory with interfaces so abstract that it can authenticate only concepts.

A mature documentation workflow

At fictional payments platform Ledger Moth, the engineering handbook now has a required section titled “Things That Look Like Bugs but Are Invoices.” Every new service must include a brief explanation of its data ownership, failure modes, and the ancient event topic it consumes because a founder once connected it during a hotel-lobby incident. The policy is enforced by a bot named Clerk, which rejects pull requests lacking sufficient context for another bot named Deputy to understand.

“The documentation has never been better,” said no one at Ledger Moth, because that would be an invented quotation from a real-sounding company. But the imaginary policy has produced measurable improvements, including a 700-page guide to renaming one environment variable and a team-wide agreement that the word “canonical” should be prohibited until someone can point to the canon.

The daily ritual is straightforward. Before asking an agent to make a multi-file change, an engineer updates the project instructions with the relevant invariants. Before asking it to run tests, they mention that integration tests require a local object store, a message broker, and a ceremonial restart of the emulator. Before accepting its patch, they explain that a green test suite is evidence of something, although the organization is still determining what.

1. Write down the intended behavior, including the awkward exception that everyone knows but nobody has named.
2. Name the files and modules that own the behavior, rather than inviting a recursive tour of every folder called common.
3. State the forbidden shortcuts: direct production access, schema edits without review, and copying a nearly identical implementation from 2021.
4. Ask the agent for a plan before edits, primarily to discover which crucial fact the documentation forgot again.
5. Turn that fact into documentation, so the next session can discover a different crucial fact.

What this is bad at

Documentation written for agents has weaknesses. It can turn a small repository into a museum audio guide narrated by a compliance officer. It can encourage teams to preserve every historical contingency instead of deleting the code that created it. And it can create the uniquely modern failure mode in which an engineer spends forty minutes explaining a five-line change to a machine, receives a flawless plan, then remembers they could have made the edit in ninety seconds.

It is also poor compensation for unclear ownership. No quantity of carefully composed Markdown can answer whether the Platform group owns the retry policy when the Platform group believes it owns “enablement,” a word invented to allow meetings to survive without decisions. An agent may read every document in the repository and still be unable to identify the human authorized to say yes.

The documentation is technically for everyone

Still, teams persist. They tell themselves the documents are for onboarding. They say they are capturing institutional knowledge. They insist that an engineer six months from now will appreciate the section explaining why webhook signatures are verified before parsing. All of this is true in the same way that the office fire extinguisher is technically for warming hands: it can happen, but it is not the primary use case anyone sees day to day.

The agent is now the most reliable reader of internal documentation because it is summoned directly from the editor, asked to inspect it, and unable to escape into a calendar invitation. That is the joke, but the useful part remains: writing down constraints, ownership, and the reason a tempting shortcut is wrong makes code changes safer whether the next reader is a model or a person.