Claude Code started reading AGENTS.md this week, which means one file is now consulted by every coding agent on every task, hundreds of times a day, more than any wiki page has been read in the history of your organisation. Most of them are forty lines of contradictions written in an afternoon.
The changelog entry was one line and it got seven hundred points. Claude Code now reads a repository’s AGENTS.md when there is no CLAUDE.md. The top comments were what you would expect: relief that the one-line CLAUDE.md files that just said “read AGENTS.md” can go, a joke about who borrowed the idea from whom, and a grumble that the skills directory is still proprietary. Standards converging. Nice.
Step back from the tooling and look at what just happened to your documentation.
For twenty years the most-read document in a software company was, depending on the company, the onboarding wiki, the README, or the runbook that everyone opened during the outage. Read, in each case, by a handful of humans a handful of times a year, mostly in their first month. Nobody measured it because the number would have been embarrassing.
AGENTS.md is read by every agent, on every task, before it does anything. If your team runs a few hundred agent sessions a day, and many do now, that file is consulted a few hundred times a day. Its contents shape every change that gets made. It is, by a margin that is not close, the most consequential piece of writing in the building. And in most of the repositories we have seen this year it was written in forty minutes by whoever set up the tool, has never been reviewed by anyone, and contains at least two instructions that contradict each other.
We have read a lot of these files. The pattern is remarkably consistent.
The first third is tooling trivia. Run the tests with this command. Use this package manager. Do not touch the generated directory. This is fine and it is the part that gets maintained, because when it is wrong the agent breaks loudly.
The second third is the accumulated scar tissue of things that went wrong. Never run the migration directly. Always check the feature flag first. Do not use the old client library. Each line was added after an incident by whoever was on call, in the language of that incident. Nobody has gone back to check whether the flag still exists.
The last third is the interesting part: the habits. Prefer small functions. We do not use that pattern here. Follow the existing style. Ask before adding a dependency. This is the oral tradition of the team, written down for the first time in its history, by one person, from memory, in the voice of a Slack message.
We wrote earlier this month that companies do not have processes, they have habits, plus a document that describes an idealised version of some of them. AGENTS.md is that document, except that this time the reader is not a new hire who will paper over the gaps by watching the person at the next desk. The reader is a system that will follow the instruction literally, hundreds of times, and will resolve the contradictions by picking one, silently, differently each time.
There was a comment under the self-driving-codebases piece this week that describes the shape of the thing perfectly. An engineer running their own agent loops watched the first agent try to run an enormous dependency inspection command, run out of memory, and record a workaround in the agent’s memory. The workaround was a way to make the enormous command succeed. Every subsequent agent inherited the workaround. The instruction file had learned to do the wrong thing more reliably. They called it cargo-cult behaviour, and the name is right.
Instruction files accrete. That is what they are for. But accretion without review produces a document whose instructions were each correct on the day they were written and which, taken together, describe a codebase that no longer exists. The agent does not know that. It reads the file fresh every time and does its best.
The second failure mode is contradiction. “Always add tests” and “do not modify files outside the task scope” are both reasonable lines and they conflict on roughly a third of tasks. A human resolves that with judgement and a quick message. An agent resolves it by weighting, and the weighting is not something you configured.
The third is the one that should worry whoever owns the codebase. The file is unowned. It has no review process, no owner in the CODEOWNERS sense, no changelog and no tests. Anybody who can push can add a line, and the line will be obeyed by every agent from then on. If you have ever worried about supply-chain risk in your dependencies, the highest-privilege dependency in your repository is now a Markdown file.
A composite, assembled from several files we have reviewed this year, with the details changed. The file was 61 lines long. Line 9 said to always run the full test suite before opening a pull request. Line 34, added after an incident in the spring, said never to run the integration tests locally because they hit a shared staging database. The full suite included the integration tests. Every agent that read the file resolved the contradiction in one of two ways: it ran the full suite and hit staging, or it skipped the suite and opened the pull request untested. Which one it chose depended on the model, the day, and how much else was in the context window. Nobody had noticed for four months because both outcomes looked like normal agent behaviour.
Line 22 said to use the internal HTTP client wrapper rather than the raw library. The wrapper had been deleted in a refactor in July. Agents that obeyed line 22 searched for the wrapper, failed to find it, and either recreated it from the description or fell back to the raw library with a comment apologising. Three copies of a near-identical wrapper had accumulated in the repository, each written by an agent trying to comply with an instruction about a thing that no longer existed.
None of this is exotic. It is what happens to any document that is executed without being maintained, and the fix for all of it took one person one afternoon: read the file, delete eleven lines, rewrite four, add the reason to each remaining rule. The next month’s agent sessions were measurably cleaner, and the person who did it described the afternoon as the highest-return work they had done all quarter.
The remedy follows from taking the file seriously, and it is mostly process rather than tooling.
Give it an owner. A named person, in CODEOWNERS, whose approval is required to change it. Not because the changes are dangerous individually but because somebody has to hold the whole file in their head and notice when line 14 and line 31 disagree.
Review it on a cadence, as a document. Once a month, read the whole thing top to bottom, with a model if you like, and for every instruction ask three questions. Is this still true? Is it still needed? Does it conflict with anything else in here? Delete generously. A shorter file that is all true beats a longer one that is mostly true, because the agent cannot tell which lines are the mostly.
Separate the layers. Tooling facts, safety rules and stylistic preferences are different kinds of instruction with different failure costs, and they should look different on the page. A safety rule that the agent must never violate should not be sitting in the same list as a preference about function length, in the same font, with the same weight.
Write the why. This is the one that turns the file from scar tissue into process. “Never run migrations directly” is a rule. “Never run migrations directly, because production runs them through the deploy pipeline with a lock, and a direct run in 2025 took the API down for forty minutes” is a rule an agent can reason about, including reasoning about when it does not apply. It is also, incidentally, the first time that piece of institutional knowledge has been written down anywhere a new human could find it.
And test it. This sounds odd for a Markdown file and it is the most useful thing on the list. Keep a short set of tasks that went wrong in the past, the ones that produced the scar-tissue lines. Once a month, run an agent against them with the current file and see whether the lines still do their job. If the agent makes the old mistake, the instruction has rotted or been contradicted. If it does not, the line is earning its place. This is the same idea as a regression test, applied to the document that governs the thing that writes your code.
The reason this deserves an essay rather than a checklist is what the file reveals. For the first time, the habits of an engineering team have been written down in a form that is executed rather than merely consulted. That is uncomfortable, because the writing is bad and the habits are inconsistent and everybody can now see both. It is also the largest documentation opportunity a software organisation has ever had, because for once there is an immediate, measurable cost to the document being wrong, and an immediate, measurable benefit to it being right.
The wiki was never read, so it never mattered that it was wrong. This file is read constantly. Write it like something that is.
Support automation, AI phone agents, n8n back-office work, and the engineering loop itself — always behind a gate you control.