In software development circles, a familiar text file has quietly established itself across thousands of repositories: AGENTS.md. Conceived as a simple way to guide artificial intelligence coding assistants through the unique quirks of a specific codebase, these instruction files have rapidly become ubiquitous. Developers write them to help large language models navigate project structures, adhere to style guidelines, and avoid common pitfalls. However, a growing consensus among engineers points to a hidden failure mode that is undermining the reliability of AI-assisted development: these files are rotting from the inside out, and the damage is entirely silent.
The lifecycle of an AGENTS.md file has grown predictable across the industry. It typically begins in week one as a crisp, twenty-five-line document written by a senior engineer who knows the codebase inside and out. By month three, after a few well-meaning contributors have each appended "just one rule," the file expands to eighty lines. By month nine, it often balloons into a two-hundred-line monolith composed of hopes, warnings, tribal knowledge, and several outdated instructions that directly contradict the current state of the underlying code.
Nobody notices the decay because nothing in the standard development loop checks the file. While automated testing suites continuously verify code correctness and linters enforce style guidelines, no tool evaluates whether a specific instruction buried deep within an agent configuration file remains true. The language model certainly does not file a bug report when it encounters an obsolete rule. It simply becomes subtly worse at its job, leading frustrated development teams to blame the underlying artificial intelligence model rather than the unmaintained text file feeding it instructions.
This silent degradation stems from a fundamental misunderstanding of what AGENTS.md actually is. Most teams treat these files as documentation meant to inform humans, but in practice, they function as machine configuration. Documentation describes a system for human readers, whereas configuration asserts specific properties about a system that actively dictate how a machine behaves. Every line written in an AGENTS.md file is an assertion about the repository—claims such as how the project is structured, which APIs to avoid, or how tests must be executed.
These assertions carry truth values that inevitably decay with every code commit that goes unreconciled against the file. An unverified assertion is not documentation; it is a wish. And wishes, industry practitioners argue, do not belong in an artificial intelligence model’s context window.
How the Rot Works
Software engineering veterans have identified three distinct modes in which instruction file rot manifests, often appearing simultaneously within the same repository.
The first and most damaging mode is direct contradiction. As a codebase evolves organically over time, the configuration file frequently remains static. For example, a team might refactor their API client entirely in March, replacing a legacy system with a modern architecture. Yet, several months later, the repository’s agent instructions may still explicitly state that all application programming interface calls must go through the deprecated legacy client located in a specific directory. Faced with this direct conflict between its static instructions and the actual code residing in front of it, the model is forced to choose. Different models, prompts, and sessions will resolve this ambiguity in unpredictable ways. This operational variance represents the exact opposite of rigorous software engineering.
The second mode involves ghost rules—enigmatic directives left behind by engineers who have long since departed the project. Instructions such as prohibiting feature flags for checkout experiments linger indefinitely because nobody remembers the specific security or stability incident that originally prompted the rule. Out of an abundance of caution, current developers dare not delete the instruction, fearing it might be load-bearing. Consequently, the rule remains, forcing every subsequent agent session to expend valuable attention budget processing a constraint that may have expired years prior.
The third and most pervasive mode is outright bloat. An instruction file spanning two hundred lines does not represent two hundred units of effective guidance. Instead, it creates a crowded environment where numerous rules compete for a strictly limited attention budget. Long instruction files suffer from the same cognitive dilution in language models that long prompts do, causing the middle sections to effectively disappear from the model’s focus. Instances have been observed where an agent successfully follows a rule at the very beginning and another at the very end while completely ignoring everything in between. This introduces a cruel irony to modern workflows: the more rules a team adds in an attempt to make an agent reliable, the less reliably the model follows any of them at all.
This wishlist style of writing instructions—operating under the assumption that it would simply be nice if the agent knew a particular piece of information—is the root cause of all three failure modes. Treating the file like configuration, by contrast, requires asking stringent questions: Is this statement true? Is it load-bearing? And how would the team know if it stopped being true?
Treating It Like Config
If AGENTS.md functions as configuration, it must be subjected to the same rigorous discipline applied to system configuration and source code.
First, these files must be strictly version-controlled, and their diffs should be reviewed with the same gravity applied to behavioral code changes. Modifying an agent instruction file is not a minor documentation tweak; it fundamentally alters the behavior of every AI session operating within that repository. A line instructing an agent to prefer a newly implemented query builder actively changes what code gets generated and committed.
Second, the file must be kept small enough to be thoroughly read and comprehended. A reliable rule of thumb used by experienced teams is that if the agent instruction file is longer than the setup section of the project’s primary README, something has gone structurally wrong. Every single line must actively earn its place by demonstrably changing the agent’s behavior on real tasks.
Third, proposed changes should ideally be gated on empirical evaluations. Before a modified instruction file is merged into the main branch, teams can run the agent against a small, curated set of golden tasks representative of the actual work performed in that repository. By executing the agent twice—once with the legacy instruction file and once with the proposed version—developers can directly diff the outcomes. If the evaluation reveals no measurable difference in performance, the added line is merely decorative and should be discarded.
Finally, teams should establish a routine pruning cadence. At least once a quarter, engineers should read the instruction file line by line, evaluating each statement to determine whether it remains true and whether it actively influenced behavior the last time it mattered. Deleting obsolete instructions often yields immediate improvements in agent reliability.
What Good Looks Like
A properly maintained, config-style instruction file is short, structural, and verifiable. In practice, architectural pointers consistently outperform lengthy prose summaries. Linking directly to a main architecture document prevents the decay that inevitably affects summarized text, as the link remains valid even as the underlying details evolve. Furthermore, effective instructions state objective facts about the repository rather than expressing vague aspirations about how the agent should behave. Directives telling the model precisely how tests must be executed function as rigorous configuration, whereas generic commands to write clean and well-tested code amount to little more than wishes.
The stark contrast between the two approaches becomes evident when comparing their phrasing. A wishlist-style instruction might vaguely advise an agent to prefer the new query builder. Over time, this rots because future developers will have no context regarding what "new" originally meant. A config-style instruction, conversely, explicitly states that all queries must go through a specific database function in a designated directory, while noting the historical context of when the legacy client was removed.
When the underlying facts of the codebase inevitably change, a config-style line becomes visibly incorrect, which represents an ideal property for configuration data. Having a line that is explicitly wrong and immediately visible proves far more valuable than maintaining instructions that remain vague, permanent, and quietly harmful.
As artificial intelligence deepens its integration into software development pipelines, the maintenance of context files will only grow in importance. Teams that apply rigorous engineering standards to their agent configurations will find their AI assistants operating with greater precision and predictability, while those that continue relying on unchecked wishlists will continue chasing phantom errors of their own making.
Comments (0)