There is one thing worse than a codebase with no documentation: a codebase with documentation that used to be correct.

The README that explains how to set up the development environment, with three commands that no longer exist. The architecture diagram from 2022 that shows services your team has since deleted, alongside two that have been renamed. The API reference whose example payloads have the wrong field names. The onboarding doc whose first link is broken. All of these existed for a reason. All of them, having outlived the world they described, are now lying to anyone who reads them.

Stale documentation is not a small problem. It is worse, in specific and measurable ways, than no documentation at all. And agents make the situation more acute, because agents read documentation eagerly and trust it.

Why this is worse than nothing

A codebase with no documentation produces honest uncertainty. New contributors know they have to learn the system from the code. They ask questions. They read until they understand. The absence is visible and it sets the expectation correctly.

A codebase with stale documentation produces confident wrongness. New contributors read the doc and believe they understand. They proceed on assumptions that the doc made true at some point in the past. They write code that fits those assumptions. The wrong work ships before anybody notices that the doc was wrong.

The dynamic is the same with agents, except faster. An agent reading a doc that describes a function signature that no longer exists will produce calls to that signature. The build fails, sometimes. Or worse, the agent constructs plausible code based on the doc and produces something that compiles but does not work, because the actual function expects different arguments.

The "no docs" case is easier to navigate than the "stale docs" case, every time. Absence is honest; staleness is not.

Why docs go stale

Documentation goes stale because it lives separately from the code it describes, and because nothing forces the two to stay in sync.

A function changes. The developer updates the function. The doc that describes the function lives in a wiki, in a Notion page, in a separate markdown file in a docs/ directory, in a comment three layers of indirection away from the function itself. Updating it requires a separate action. The separate action is easy to skip. Most of the time, it is skipped.

The doc continues to describe the old version of the function. New readers, human and agent, pick up the wrong information. The drift compounds across releases until the doc and the code are different artifacts describing different systems.

The teams that have functional documentation have one of two properties: either the documentation is generated from the code (so it cannot drift), or the documentation is treated as part of the code (so changes to one require changes to the other).

What "generated" can do

The strongest documentation is documentation the team does not write by hand.

API references generated from OpenAPI specs or schema definitions. If the schema is correct, the doc is correct. The schema is correct because the running service uses it.

Type signatures rendered as docs. Languages with good type systems can produce reference documentation that reflects the actual code. The doc and the code cannot disagree because the doc is the code.

Examples extracted from tests. The test runs. The test demonstrates how the function is used. The example in the doc is the test. When the function changes in a breaking way, the test breaks, and the example is no longer in the doc.

The shift toward generated docs is the cheapest large win available for documentation accuracy. It does not cover everything: there is still hand-written prose explaining concepts, walkthroughs, decision records. But it removes the largest source of staleness, which is API reference material that drifts because nobody is paid to keep it in sync.

What "treated as code" means

For everything that cannot be generated, the practice is to treat documentation changes the same way you treat code changes.

Docs live in the repository, near the code they describe. A README per significant directory. Comments that explain non-obvious choices. Decision records in docs/decisions/. The PR that changes behavior is the same PR that updates the relevant docs. The reviewer's job includes catching the case where the doc was not updated.

The mechanical version of this is to add a checklist item to the PR template: "Did this change require a doc update?" The author confirms or explicitly says "no." A reviewer who suspects a doc update was needed can push back, just like they would on a missing test.

The deeper version is to delete docs aggressively. A document that nobody is willing to maintain is a document that is going to go stale. If the team will not commit to keeping it current, the document should not exist. It is better to have a one-paragraph note that links to the code than to have a long doc that nobody reads and nobody updates.

How the agent fits in

The agent's relationship with documentation is asymmetric. The agent reads docs into context at the start of a session. The agent does not, by default, update docs as it goes.

The way to fix this is to make documentation updates part of the change. The same rule that goes into AGENTS.md for any other concern: "If you change a function's behavior, signature, or location, update any documentation that references it." The agent, given that rule, will produce diffs that touch both files. Without the rule, the agent will produce diffs that touch only the code, because the code is where the failing test will surface.

A related rule is worth adding: "If documentation in this repository contradicts the code, the code is the source of truth. Update the documentation to match, or flag the discrepancy in a comment for human resolution." The agent encountering stale documentation should not pattern-match against it; it should treat the code as authoritative.

First steps

If you have an accumulation of stale docs and you want to start fixing it:

Audit your top-level README today. Walk through every command in it. Delete or fix every one that does not work. The README is the document most readers see first; making it accurate is the highest-leverage change.

Find your most-linked-to doc. One that gets referenced in onboarding, in PR comments, in Slack threads. Walk through it. For each claim, check whether the code still matches. Either fix the doc or delete the claim.

For your API reference, if you have one and it is hand-written, switch to generated. OpenAPI from your routes, type-generated docs, whatever fits. The work to switch is real; the work it saves over the next year is larger.

Add to your PR template: "Did this change require a doc update? If yes, which docs were updated?" The question forces a moment of thought. Some PRs will say "no" and be correct. Others will discover, on being asked, that the answer was actually yes.

Add one rule to AGENTS.md: "When you change behavior, signatures, or names, update any documentation that references them in the same change. If you find documentation that contradicts current code, flag it explicitly in the PR description."

The most valuable documentation is the documentation you can trust. The work to make documentation trustworthy is small, ongoing, and almost never urgent. Doing it anyway is what separates teams whose docs are an asset from teams whose docs are a trap.