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.
One file, every task, all day
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.
What is actually in there
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.
What a typical AGENTS.md contains, and who reads each part. The bottom third is the team's undocumented process, written down once, by one person, for the first time.
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.
The failure modes are already visible
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 worked example, from a file we were asked to look at
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.
Treat it like what it is
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.
The instruction file, run like the load-bearing document it has become.
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 larger point
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.
Sources
- Claude Code now reads AGENTS.md if there is no CLAUDE.md (changelog) (HN, 715 points, 18 Sep 2026)
- Your company does not have processes. It has habits. (Levelbrook) (the earlier essay this one builds on)
- Towards Self-Driving Codebases (detail.dev) (HN, 119 points; the agent-memory cargo-cult comment is from the thread)
Originally published on the Levelbrook playbook. Levelbrook is a principal-led Rails and AI-systems consultancy; the playbook is where we write down what we see.
Top comments (0)