AGENTS.md has won the fight to become the standard place to brief a coding agent, and deservedly so. It is a simple, open format for guiding coding agents, described by its own maintainers as "a README for agents: a dedicated, predictable place to provide the context and instructions to help AI coding agents work on your project." It is used by over 60,000 open-source projects, it works across a large ecosystem (Codex, Cursor, Copilot, Gemini CLI, Jules, Windsurf, Devin, and more), and it is now stewarded by the Agentic AI Foundation under the Linux Foundation. If you run coding agents and you do not have one, write one today.
And yet, for a whole class of what we actually want agents to get right, a Markdown file of prose instructions is a workaround for a problem it cannot solve. It is a good workaround. It is not the solution. The difference matters, because teams are starting to treat a well-tended AGENTS.md as if it were governance, and it is not.
What AGENTS.md is genuinely good at
Give it full credit first. AGENTS.md is excellent for the stable, operational facts about a project: how to install dependencies, how to run the tests, how to start the dev server, what the PR title format is, which commands must pass before a merge. Those things are true regardless of which file the agent is editing, they change slowly, and they are exactly the kind of "anything you'd tell a new teammate" knowledge the format was designed to hold. For that job, a static file in a predictable place is the right tool.
The trouble starts when the same file is asked to carry the things that are neither stable nor simple: your architecture, your evolving coding standards, your security posture, and the judgment of what to reuse instead of rewrite. The AGENTS.md site suggests exactly these sections ("Code style guidelines," "Security considerations"). That is where the format hits a ceiling, and the ceiling is structural, not a matter of writing a better file.
The tell is in the format's own FAQ
Asked whether there are required fields, the AGENTS.md maintainers answer: "No. AGENTS.md is just standard Markdown. Use any headings you like; the agent simply parses the text you provide." That single sentence contains the three limits.
It is static. The same FAQ says to "treat AGENTS.md as living documentation," which is a polite way of saying a human has to keep it alive. It is only as current as the last time someone remembered to edit it, while the codebase it describes changes every merge. This is the well-understood failure mode of any prompt file. As Sonar puts it, prompt files "are static and must be maintained as the codebase changes." The map drifts from the territory, and the agent confidently follows the map.
It is unstructured prose. A Markdown file can say "respect our layering" or "reuse existing utilities before writing new ones," but it cannot be your architecture graph, your call flows, or the concrete list of rules your own history says you violate most. Prose describing structure is not structure. Telling an agent "we use a hexagonal architecture" is not the same as giving it the dependency graph that shows which module is actually allowed to call which, and an instruction to "reuse existing code" does nothing if the agent has no reliable way to find the existing code by meaning rather than by grep.
It is always-on, not at-the-right-moment. AGENTS.md does scope by location — agents read the nearest file in the directory tree, so the closest one takes precedence and every subproject can ship tailored instructions. But directory is not a task. Whichever file applies is loaded whole, regardless of the edit in front of the agent, so it is simultaneously too generic for the specific change and, as it grows, too big to be reliably used. The workaround for that is more files: OpenAI's own Codex repository ships, in the format maintainers' words, "88 AGENTS.md files" at the time of writing. Large, always-present instruction blocks run straight into two well-documented properties of language models.
Bigger file, not better behavior
The instinct when an agent ignores your rules is to write more rules. The research says that backfires.
The 2024 "Lost in the Middle" study (Liu et al., published in TACL) found that model "performance is often highest when relevant information occurs at the beginning or end of the input context, and significantly degrades when models must access relevant information in the middle of long contexts, even for explicitly long-context models." A rule buried on line 400 of a growing AGENTS.md is precisely the information most likely to be underused.
More recently, Chroma's "Context Rot" report evaluated 18 leading models, including GPT-4.1, Claude 4, and Gemini 2.5, and found that "models do not use their context uniformly; instead, their performance grows increasingly unreliable as input length grows." The comforting assumption that a model handles the ten-thousandth token as reliably as the hundredth "does not hold." So the more context you cram into a static file to cover every case, the less dependably any single instruction in it lands.
There is a deeper point underneath the position effects: instruction-following is probabilistic, not guaranteed. A rule in a file is a suggestion the model weighs against everything else it has seen, and its priors are strong. Sonar's study of the coding personalities of leading LLMs, based on 4,442 identical tasks per model, found that "all models have a fundamental lack of security awareness and a bias for messy code," with code smells — the maintainability problems that accumulate as technical debt — making up roughly 90% or more of every model's issues, from 89.9% to 94.9% depending on the model. Every one of those models has been told, in countless system prompts and instruction files, to write clean and secure code. They do it anyway. And the codebase-level consequences are visible in the wild: GitClear's analysis of 211 million changed lines found code cloning roughly quadrupling and refactored or moved code falling from about 25% of changed lines in 2021 to under 10% in 2024. "Reuse before you rewrite" is in a thousand AGENTS.md files. It is not what is happening.
You cannot out-write this with prose. Telling a probabilistic system the rules, and hoping the rules survive a long context window, is not a control. It is a wish with good intentions.
What actually closes the gap
The alternative is not a better file. It is a different mechanism: deliver structured code intelligence at the moment of generation, scoped to the task at hand, and derived from analysis so it is always current.
This is the "Guide" phase of Sonar's Agent Centric Development Cycle (Guide, Generate, Verify, Solve), and the contrast with a static file is exact. Instead of prose the agent may or may not read, context augmentation gives the agent, before it writes:
- coding guidelines selected from your project's own history of issues and filtered to what the agent is about to do, rather than a generic style section;
- your actual architecture map plus the relationship you have defined as intended, so the agent can align with the design instead of a paragraph describing it;
- semantic navigation over ASTs and control flow, so the agent finds the right place to change by meaning and surfaces "every relevant location that needs updating so nothing is missed," rather than reusing code it happened to grep; and
- dependency health checks before a package is introduced, not after it ships.
Every one of those is structured, not prose, and each is available where your language and configuration support it. The coding guidelines are scoped to the task at hand rather than prepended wholesale. And because the architecture is derived from analysis rather than hand-maintained, it refreshes with each analysis instead of waiting for someone to remember to edit a file That is the substantive difference between a README for agents and a guidance layer that knows your codebase: one tells the agent what you remembered to write down, the other shows it what is actually true right now, at the point where it matters.
The line for engineering leaders
None of this means delete AGENTS.md. Keep it, and keep it good, for the operational instructions it was built for. The mistake is category, not tooling: do not let a well-maintained instructions file stand in for the thing it is impersonating. A file that says "follow our architecture" is documentation of an intention. It is not the enforcement of one, and it is not knowledge of what your architecture currently is.
For a platform team, the practical test is simple. If your answer to "how do we keep agents aligned with our standards" is "we wrote it in AGENTS.md," you have a workaround: a static, unstructured, always-on artifact that degrades as it grows and that the model is free to underweight. The solution is to make your standards, your architecture, and your history available to every agent as structured context, delivered at the moment of generation and kept current by analysis rather than by memory. AGENTS.md tells the agent how to run your project. It was never going to tell the agent how to belong in it.