Test every rule against one question: would a competent new hire need this sentence, and can it be checked. Then give the file an owner, a review trigger, and a real deletion policy.
By JP LeBlanc
An AGENTS.md that survives six months passes one test on every line: would a competent new hire need this sentence, and can somebody check whether it's still true. Most files fail on the second half, not the first, because nobody assigned anyone to check. Give the file a named owner, a review trigger tied to the code it describes rather than the calendar, and a deletion policy nobody's afraid to use, and it stops being the thing that quietly lies to your agents the moment the codebase moves without it.
Write down the operating assumptions a new senior engineer would otherwise have to learn by making a mistake first: which service owns which data, which shortcut is load-bearing and which one is vestigial, where the actual invariants live that the code doesn't enforce on its own. Leave out anything already true from reading the code, because a rule restating what the type system or a linter already guarantees is a second source of truth for a fact that only needed one.
The harder discipline is the second half of the test: can this specific line be checked. "Follow existing conventions" fails it, because nobody can verify compliance with a sentence that vague, least of all an agent. "New endpoints go through the request validator in middleware/validate.ts, no exceptions" passes it, because a reviewer, human or automated, can look at a diff and get a yes or no. This is the same failure intent architecture names in the abstract: a rule a system can't check is an instruction with all the ambiguity of a verbal handoff and none of the person available to ask what you meant.
Context files rot for a specific, boring reason: updating them was never anyone's job. The burst of effort that produces the file usually follows a bad incident, everyone's attention is on it for a week, and then it sits while the codebase keeps moving underneath it.
The fix isn't a better writing process. It's assigning the file the way you'd assign a service: one named owner, and a rule that whoever changes the behaviour the file describes updates the file in the same pull request, not a follow-up ticket that gets deprioritized the moment the incident that prompted it stops feeling urgent. Building this kind of file in-house rather than buying it off the shelf only pays off if somebody is actually accountable for it, because the knowledge that makes it valuable is exactly the knowledge nobody outside the team has.
Picture a rule telling every agent working in the codebase to route billing changes through a specific adapter, written the week that adapter went into production. Eight months later, three engineers have migrated half the billing surface to a newer pattern, none of them touched the file, and the agent has no way of knowing the ground shifted. It follows the old instruction with complete confidence, produces something that would have passed every test that existed when the rule was written, and the wrongness surfaces three steps downstream, disconnected from its actual cause.
The tells are ordinary and probably already on a dashboard you have. Code quality scores drifting down on one service. A pattern of failed builds that all trace back to the same file once someone bothers to check. Neither says "the context file is stale" outright, and that's exactly the problem: nobody's trained to read them that way until they've been burned once.
A review trigger tied to the code closes most of this gap. Not a calendar reminder, which becomes theatre within two quarters, but a rule that the file gets revisited whenever the system it describes changes materially, the same discipline you'd apply to any documentation that has to stay true or actively hurts you.
A single root-level file forces every rule into a lowest common denominator vague enough to apply everywhere, which is a specific way of failing the checkability test above. Directory-level files scoped to one service or package can carry the sharp, specific version instead, and most codebases with genuinely different regions need that.
The cost is a contradiction between a root rule and a directory override, which is worse than one you'd catch inside a single file, because it hides in a diff no one review ever sees both halves of. Whoever changes a directory-level file has to check what the root file already claims. Whoever owns the root file has to know which directories have overridden it, and why. The failure mode isn't exotic: one team writes a sharper local rule, never tells the platform team who owns the root file, and six months later an agent working across the boundary gets two contradictory instructions with equal confidence in both.
These files accumulate rules nobody's willing to remove, because removing a rule feels riskier than leaving a stale one in, and that instinct runs backwards. A rule contradicted by the current code is worse than no rule, because it's confidently wrong at whatever volume your agents are running, and nothing about the file signals which lines to trust.
Set an actual deletion policy: a rule untouched by any change to the code it describes in ninety days gets flagged for review, not automatically deleted, but put in front of the owner for an explicit yes or no. Most of the time the honest answer is that the rule stopped mattering months ago and nobody noticed, because nothing forced the question.
The file that lasts isn't the most thorough one written on day one. It's the one with a name attached, a habit of getting touched alongside the code it describes, and an owner willing to delete a line rather than let it sit there being wrong. Everything else is a documentation project pretending to be infrastructure.