AGENTS.md and CLAUDE.md are executed literally by a system that can't ask what you meant, yet almost nobody reviews, owns, or deletes them the way they would any other code that ships.
By JP LeBlanc
AGENTS.md, CLAUDE.md, the skill files, the rules a repo hands to whatever agent touches it: these are the guardrail half of what most teams end up building in-house rather than buying, because nobody outside the company has the knowledge to write them. They're read by a system that executes what they say, literally, every time, with no ability to ask what you meant. That makes them production code, not documentation, and almost no engineering org reviews, owns, or deletes them the way it does anything else fitting that description. The gap between how these files get treated and what they actually do is where the drift lives, and drift in this particular file is the quiet kind.
A README is read by a person who brings judgment to what's stale. A comment that's wrong gets noticed the first time somebody trips over it, because a human reading code has an instinct for "that doesn't match what I'm looking at," and complains loudly enough that someone fixes it.
A context file has no such reader. An agent doesn't experience wrongness the way a person does. It follows the line with complete confidence, produces something subtly off, and the wrongness surfaces three steps downstream, disconnected from the sentence that caused it. Nobody traces a failed build back to a stale paragraph in a markdown file, because nobody thinks to open the markdown file. That's exactly what makes this different from an out-of-date comment.
Most orgs write the context file once, under real pressure, right after an agent did something wrong for lack of it. That's a reasonable moment to write it. It's a terrible moment to decide it's finished, because the file gets treated afterward the way documentation usually gets treated: something you write, not something you maintain, updated when someone happens to remember rather than when the thing it describes changes.
That's the mistake. Documentation drifting for six months produces a mildly annoying wiki page. A context file drifting for six months produces an agent executing yesterday's architecture with today's confidence, against a codebase that's already moved on, and nothing in the pipeline throws an error, because nothing about a stale instruction looks like a bug from the outside.
The instinct is to schedule it. A quarterly audit, someone assigned to review the file every few months. Tidy on paper, and it doesn't survive a busy quarter. A scheduled review competes with everything else on that person's plate, loses most weeks, and the file drifts anyway, just on a documented cadence instead of an undocumented one.
The rule that actually holds is smaller. Whoever changes the behavior a context file describes updates the file in the same change, the same pull request, not a follow-up ticket. Migrating a service to a new pattern means the line describing the old pattern is part of what's being changed, the same way a test asserting the old behavior would be. It isn't a new category of discipline. It's documentation required before merge, applied to a file that happens to be markdown instead of prose.
The habit is easy to describe and slower to install than it sounds. The first few pull requests after this rule lands, someone forgets, and the fix is a comment on the diff, not a lecture in a meeting.
Team maintenance and individual accountability are different things, and conflating them is how a file everyone's responsible for ends up drifting exactly like a system everyone owns and nobody runs.
The team does the maintaining, because they're the ones touching the code it describes. One named leader carries whether the file is still telling the truth, the same way they'd carry whether a service is up. That name should be able to answer, in a sentence, when the file was last confirmed accurate and what would tell them if it wasn't.
At CircleCI, where these files lived per repo, the rule was plain: I need someone to be accountable, because distributed accountability rarely works. The Director is accountable, team members are responsible. A named owner on a markdown file can look like process for its own sake. It isn't. A file with no owner doesn't fail to get maintained through malice. It fails because "everyone's job" reliably becomes nobody's Tuesday, and a context file is exactly specific enough to need one and exactly boring enough that nobody claims it unless asked.
Some drift gets through even with the rule in place, because not every change is obviously a change to something the file describes. The cheap backstop: when an agent gets something wrong in a way that traces back to bad context, treat it as a bug against the file, not just against the output.
That failure is a gift. It tells you exactly which paragraph lied.
None of this is expensive. A line in a pull request template. A name on a wiki page next to a file path. A habit of treating a bad agent output as two bugs instead of one.
Skipping it is the expensive option, and the reason it feels free is that the cost doesn't show up on the day you skip it. It shows up two months later, as a build failure nobody can explain at first, that traces back to a sentence somebody wrote in June and never looked at again, describing a system that stopped existing in August.