I have read more AGENTS.md files than I can count, across repos I own and repos I was parachuted into. They almost all follow the same arc. Week one: 25 crisp lines, written by someone who knows the codebase cold. Month three: 80 lines, after three well-meaning contributors each added "just one rule." Month nine: 200 lines of hopes, warnings, tribal knowledge, and several instructions that directly contradict the current code. Nobody noticed. The agent certainly did not file a bug report. It just quietly got worse at its job, and everyone blamed the model.
That is the rot, and it is silent because nothing in the loop checks the file. Your tests check your code. Your linters check your style. Nothing checks whether line 143 of your AGENTS.md is still true.
Here is the reframe: AGENTS.md is not documentation. It is config. Documentation describes the system for humans. Config asserts things about the system that change how a machine behaves. Every line in your AGENTS.md is an assertion: "the repo is structured like this," "never do that," "always run tests this way." Assertions have truth values. Truth values decay with every commit that nobody reconciles against the file. An unverified assertion is not documentation. It is a wish. And wishes do not belong in your agent's context window.
How the rot works
Rot has three favorite modes, and I have seen all three in the same file.
Contradiction. The codebase moves; the file does not. Someone refactors the API client in March. The AGENTS.md still says "all API calls go through the legacy client in lib/api." The agent now faces a choice between its instructions and the code in front of it. Guess which one it should trust, and guess which one it actually trusts. It varies by model, by prompt, by phase of the moon. That variance is the opposite of engineering.
Ghost rules. "Do not use feature flags for checkout experiments." Nobody remembers who added it. Nobody remembers the incident behind it. Nobody dares delete it, because what if it was load-bearing? So it stays, and every agent session spends a little attention on a rule that may have expired a year ago.
Bloat. This is the big one. A 200-line AGENTS.md is not 200 lines of guidance. It is 200 lines competing for a fixed attention budget. Long instruction files get skimmed by the model the same way long prompts do: the middle disappears. I have watched agents follow line 4 and line 197 and ignore everything between. The cruel irony: the more rules you add to make the agent reliable, the less reliably it follows any of them.
Wishlist style is how all three happen. Wishlist style says "it would be nice if the agent knew this." Config style asks "is this true, is it load-bearing, and how would I know if it stopped being true?"
Treat it like config
If AGENTS.md is config, then it gets config discipline.
Version it, and review diffs like behavior changes. An AGENTS.md diff is a behavior change to every agent session in that repo, and it should be reviewed with that gravity. "Added a line telling the agent to prefer the new query builder" is not a docs tweak. It changes what code gets written.
Keep it small enough to be read. My rule of thumb: if your AGENTS.md is longer than the setup section of your README, something has gone wrong. Every line must earn its place by changing behavior on real tasks.
Gate changes on evals. This is the whole game. A proposed AGENTS.md change should answer one question before it merges: does this change agent behavior on a golden set, and is the change good? Keep a small set of golden tasks, the kind of work agents actually do in your repo. When someone proposes an AGENTS.md change, run the agent on the golden set twice, once with the old file and once with the new, and diff the outcomes. If you cannot measure a difference, the line is decoration. Delete it.
Prune on a cadence. Once a quarter, read the file line by line and ask of each: is this still true, and did it change behavior the last time it mattered? Delete what fails. The best AGENTS.md edit most teams can make is a deletion.
What good looks like
A config-style AGENTS.md is short, structural, and verifiable. Pointers beat prose: link to the architecture doc instead of summarizing it, because the summary will rot and the link will not. State facts about the repo, not aspirations about the agent. "Tests run with make test-integration, not pytest directly" is config. "Write clean, well-tested code" is a wish.
A minimal template:
- Repo map: src/api is the public API surface, src/jobs holds background workers with one queue each, migrations run via make migrate.
- Commands: make test (unit), make test-integration (needs docker), make lint (must pass before any PR).
- Hard rules: no new dependencies without an ADR in docs/adr; never commit secrets.
- Evals: changes to this file must pass the golden set; record the last prune date.
Notice what is missing: no philosophy, no "be careful with," no tribal history. Every line is checkable.
The contrast, stated plainly
Wishlist style: "Prefer the new query builder."
Config style: "All queries go through db.Query in src/db; the legacy client was removed in March."
The wishlist version rots: six months later nobody knows what "new" meant. The config version names the thing, states the fact, and timestamps the removal. When the fact changes, the line is visibly wrong, which is the best property a line of config can have. Wrong and visible beats vague and permanent.
In closing
Your AGENTS.md is not documentation. It is config: a set of assertions about your repo that change machine behavior, and assertions rot. Keep it short, keep it factual, version it in git, review diffs as behavior changes, and gate every edit on a golden set that proves the line earns its place. The file that survives this discipline is small, true, and load-bearing. Everything else is a wishlist, and wishes do not ship.
What is the oldest line in your AGENTS.md, and is it still true?