If you maintain a repository and you are about to paste a template into AGENTS.md, stop at the sections that tell the agent what to do: how to set up the environment, which commands build and test the project, which conventions are non-negotiable, and where the agent may not act. That is the short version of what the evidence supports. The longer version, built from a new October 2026 census of 22,854 GitHub repositories and a handful of evaluation studies, is less flattering to the template ecosystem: much of what popular repos ship in these files, including the repository overviews that model providers recommend, has no measured benefit, the files add inference cost, and a stale file can actively override your current code.
This article reads the census as a description of practice, then filters that practice through the compliance and cost studies to produce a checklist of what is actually worth copying.
The census: what 22,854 repos actually ship
The core source is a census of AGENTS.md and CLAUDE.md files across 22,854 popular, active GitHub repositories in thirteen languages, each with at least 1,000 stars and recent activity, returned by GitHub’s search API. The authors report that “Agent instructions appear in 26.3% of repositories and 59.6% of the most-starred” (the census). Both figures are author-reported from a preprint, so treat them as measured but not yet peer-reviewed.
Two things follow. First, the practice is mainstream, at least among popular projects: roughly six in ten of the most-starred repos in the sample ship a root instruction file. Second, the headline number is also a selection effect. The census only covers repositories with at least 1,000 stars, so it describes what successful, visible projects do, not what a typical repo does. If your project is small and unstarred, the census’s 26.3% tells you nothing about your peers; it tells you where the conventions are being set.
The census also traced the history of 8,393 agent files by walking each file path’s commit history on the default branch, classifying commits as AI-marked when the message or author e-mail carried a co-author trailer or signature from Claude, Codex, Copilot, Cursor, Devin, Aider, or Gemini. The authors are careful to note that AI-marked commits are a lower bound on AI-assisted commits, since plenty of agent-assisted work lands without a trailer. If you see claims circulating that a specific share of instruction-file edits are agent-written, that floor is what the data supports.
AGENTS.md vs CLAUDE.md: why the census counts them as one set
The census treats each repository’s root AGENTS.md and CLAUDE.md as one instruction set, excludes nested agent files, and counts other formats only in its first research question. That is a defensible choice for measurement, and it carries a practical implication for your own repo: these two filenames are converging on the same job. Claude Code reads CLAUDE.md; AGENTS.md is the cross-tool convention that Codex and other agents read. The census authors’ decision to treat them as one set reflects how projects actually use them, as the repo’s single statement of instructions to whatever coding agent shows up.
There is one measurement caveat on any “AGENTS.md is winning” narrative. Path history in the census does not follow renames, so a file renamed from CLAUDE.md to AGENTS.md counts as AGENTS.md-first, and trends over time describe only surviving files. The census bounded that artifact: renames explain 3.8% of AGENTS.md-first cases (95% CI 2.6–5.3), “too few to change the trend”, and the shift it documents is real, from 73.7% of new adopters starting with CLAUDE.md (January to August 2025) to 17.1% since May 2026 (the census). For a maintainer, the actionable version is boring: pick one root file, and if your primary agent has its own filename convention, keep the two in sync or symlink them rather than letting them drift.
What agents follow, and what they ignore
Here is where the census data stops and the evaluation evidence starts, and the two point in different directions.
The sharpest counter-result comes from an evaluation of repository-level context files, which found that “providing context files does not generally improve task success rates, while increasing inference cost by over 20% on average” (the evaluation). “This observation holds across different LLMs, coding agents, and for both LLM-generated and developer-committed context files.” That is a sobering finding for anyone treating AGENTS.md as a free performance upgrade: on average, across the agents and models tested, the file costs more than 20% extra inference and does not reliably lift success.
But the same study contains the distinction this whole article turns on: “while instructions in the context files are well followed by coding agents, repository overviews, although popular and recommended by model providers, are not helpful.” Agents comply with imperative instructions. They do not benefit from the prose overview section, the “this repo is a FastAPI service with a Postgres backend and three main packages” paragraph that sits at the top of most templates. And the cost is not driven by that prose: the study attributes the increase to agents following instructions, which leads to more exploration, testing and reasoning, and its ablations found that removing the overview category did not significantly reduce cost, with file length showing no clear effect (the evaluation). The case for cutting the overview rests on the measured non-benefit, plus a general staleness problem that lands on the whole file: the stale-file study describes instruction files as “written once and seldom revisited, while the code around them keeps changing.”
So the filter for “what yours should copy” is not what most repos include. It is the subset of that content with a measured mechanism: commands and rules the agent executes, versus narrative it reads and discards.
Copy the categories that earn their keep
A parallel study of Cursor rules across open-source repositories gives the best category-level picture of what projects actually write. It reports that about 85% of repositories include Project context, 84% Convention context, and 89% Guideline content, while only about 50% contain LLM-specific instructions in their cursor rules. These are author-reported percentages from a different corpus than the census, so they describe the Cursor-rules ecosystem rather than AGENTS.md specifically, but the shape is consistent with what template authors assume: context-heavy files dominate.
The counterweight is a study of five Python libraries testing whether instruction categories pay off in generated code: “including every instruction category does not reliably reduce agent-file-generation cost or improve generated code quality. Instead, instruction selection should be tailored to the target outcome and the LLM.” Breadth is not neutral, though the cost at issue in that study is agent-file-generation cost, not the per-task inference cost measured above. The study found no reliable payoff for maximal coverage.
Combined with the readability evidence, the case for brevity gets stronger. An empirical study of agent context files measured Claude Code files at a median Flesch reading ease of 42.39, which “classifies them as difficult to read and comparable to high school-level material under the FRE interpretation bands.” These files are already dense and hard for humans to maintain. A long, exhaustive file is not just wasted tokens; it is a maintenance liability that every future agent session pays for.
| Content category | What the evidence says | Verdict |
|---|---|---|
| Build, test, setup commands | Instructions in context files are “well followed by coding agents” (2602.11988v3) | Include, keep exact |
| Conventions and style rules | Present in 84% of Cursor-rules repos (2512.18925v3); compliance evidence is indirect | Include the ones you enforce |
| Guidelines | 89% prevalence for general guideline content, about 50% for LLM-specific directives (2512.18925v3); “well followed” when imperative | Include, phrase as imperatives |
| Repository overview / architecture narrative | “Popular and recommended by model providers” but “not helpful” (2602.11988v3) | Cut |
| Every available category | “Including every instruction category does not reliably reduce agent-file-generation cost or improve generated code quality” (2610.21421v1) | Cut; tailor to outcome and model |
| Prose permission rules (“do not…”) | Interpreted by the model, not enforced (2608.23550v1) | Replace with built-in controls |
Permissions belong in controls, not “do not” prose
One category deserves its own treatment because the failure mode is categorical, not statistical. A study of 481 public CLAUDE.md files draws the line plainly: “In CLAUDE.md, ‘do not’ is a natural-language instruction that the model interprets. Claude Code’s deny is a built-in control that blocks an action before the agent can take it.”
A sentence like “do not commit directly to main” or “never run migrations in production” is a request. The model usually honors it, but usually is not a control, and the study’s framing is that the instruction file is a write-only channel: a natural-language rule returns nothing back, and neither the file nor the agent application signals whether anything will enforce it. If an action would genuinely damage the repo or the environment, the instruction file is the wrong layer to enforce it. Use the tool’s permission system, Claude Code’s deny rules or the equivalent in your agent, and keep the prose file for guidance the agent is allowed to interpret.
Stale instructions override code: the one-sentence fix
The most operationally surprising result among the studies behind this article is the stale-instruction study by Xu and Wu, and it explains a failure many teams have hit without naming. The mechanism is in how Claude Code assembles context: it “inserts CLAUDE.md into a user message directly after the system prompt (Anthropic, 2026) and introduces it with the text ‘Codebase and user instructions are shown below. Be sure to adhere to these instructions. IMPORTANT: These instructions OVERRIDE any default behavior and you MUST follow them exactly as written.’”
When the file disagrees with the current code, the file wins. The authors measured it: in their setup (Claude Code 2.1.302 with Claude Sonnet 5.5, and Codex CLI 0.163.0 with GPT-6 Sol, run non-interactively with file edits auto-approved), a stale instruction drove agents to follow the file over the code in the overwhelming majority of choices, even rewriting correct code to match the outdated text. Then they tested a fix: adding one precedence sentence to the user-level instruction file (~/.claude/CLAUDE.md for Claude Code, ~/.codex/AGENTS.md for Codex CLI), telling the agent that when instructions and code conflict, the code is authoritative. The authors report: “The sentence raised the share of choices that follow the code from 4.2% to 91.4%” (the stale-file study) and “stopped the rewrites and raised the test pass rate from 89.4% to 100%” (the same study).
Those numbers are author-reported from a specific version pairing, and agent harnesses change quickly, so do not treat the stale-file study’s 91.4% as a durable property of Claude Code. Two scope notes matter before you copy the fix. The sentence lived in the user-level file, not the repo file, and the study notes that both tools “put the user-level file and the project file into the same message, with the user-level file first”; writing the same sentence into your AGENTS.md should therefore behave the same way, but that placement was not tested. Treat the mechanism as durable: Claude Code injects the file with explicit override language, and Codex CLI, which adds no such preamble, still followed the file in 93.9% of its choices, so an unpinned instruction file has precedence over your actual codebase by default. One sentence of precedence text is cheap insurance against the day your instructions lag your code, which is every day after you stop editing the file.
The checklist: what to put in your AGENTS.md today
Reading the census through the evaluation evidence, this is the evidence-graded version of the file. I would treat it as the default and deviate only with a reason:
- Environment setup and commands, exactly as a new contributor would run them. Install, build, test, lint, and the one command that runs the project. This is the content class with the clearest compliance evidence.
- The conventions you would actually reject a PR over. Formatting, naming, test placement, commit message shape. Phrase them as imperatives, not descriptions. If you would not enforce it on a human contributor, do not spend context budget enforcing it on an agent.
- Behavioral guidelines the agent cannot infer from the code. Which test suite is authoritative, whether to add tests with every change, what “done” means in this repo. The Cursor-rules data shows guideline content is the most common category in practice; the compliance evidence says imperative versions of it are followed.
- An explicit precedence sentence. State that when this file conflicts with the current code, the code wins and the agent should flag the conflict rather than rewrite the code to match the file. The measured version of this line lived in the user-level instruction file, where it raised code-following from 4.2% to 91.4% (the stale-file study); because both files reach the model in the same message, carrying the sentence into your repo file is a reasonable inference rather than a tested result. It is still the sentence I would write first.
- Nothing that belongs in a permission system. Move hard prohibitions into your agent’s deny controls. Keep the file free of security rules you cannot afford to have interpreted.
- No repository overview. This is the counterintuitive cut, because overviews are popular and provider-recommended. The evaluation evidence found them unhelpful, and an instruction file that is seldom revisited is a poor place for prose describing an architecture that keeps moving. If a human needs the architecture tour, that is what README.md is for.
Keep the whole thing short enough that you would reread it when you edit it. The readability study’s median FRE is 42.39 for Claude Code files, with Codex files easier at 51.41 (2511.12884v2); the ecosystem’s files are already harder to read than they should be. A concise, imperative file is easier to keep accurate, and accuracy is the property that everything else depends on.
What the census cannot tell you
Three limits bound every claim above, and they are worth holding onto because the numbers travel better than the caveats.
The census measures files, not behavior. It counts the presence and content of root AGENTS.md and CLAUDE.md files, explicitly “not agent use or the instructions agents receive at run time”. No census-scale result shows that shipping any particular instruction file improves outcomes; every effectiveness, cost, security, and precedence claim here comes from separate, smaller studies with named agents, models, and versions: Claude Code 2.1.302 with Claude Sonnet 5.5, Codex CLI 0.163.0 with GPT-6 Sol, five Python libraries, 481 CLAUDE.md files, one Cursor-rules corpus. The recommendations above are bounded inferences drawn across those studies, not results any single paper demonstrates end to end.
The sample is the top of GitHub. Repositories under 1,000 stars are absent, so the conventions described are the conventions of projects with maintainers, CI, and contributors to coordinate. That may be exactly why instruction files pay off there, or it may not transfer at all.
And the format-trend numbers have a rename artifact that the census bounded directly: renames explain too few AGENTS.md-first files to change the trend, so the shift toward AGENTS.md among new adopters is real, not an accounting artifact (the census).
The durable conclusion survives all three limits. Instruction files are becoming the repo’s real interface to coding agents, which moves the burden of agent behavior out of tool configuration and into documentation you own. That documentation is followed when it is imperative, ignored when it is narrative, enforced only when it is a control, and dangerous when it is stale. Write it like code that every future agent will execute: short, current, and with an explicit rule for what happens when it is wrong.
Frequently Asked Questions
How do I prevent a stale AGENTS.md from overriding my current code?
Then they tested a fix: adding one precedence sentence to the user-level instruction file (~/.claude/CLAUDE.md for Claude Code, ~/.codex/AGENTS.md for Codex CLI), telling the agent that when instructions and code conflict, the code is authoritative. The authors report: “The sentence raised the share of choices that follow the code from 4.2% to 91.4%” (the stale-file study) and “stopped the rewrites and raised the test pass rate from 89.4% to 100%” (the same study).
Should I include a repository overview in my AGENTS.md?
But the same study contains the distinction this whole article turns on: “while instructions in the context files are well followed by coding agents, repository overviews, although popular and recommended by model providers, are not helpful.” Agents comply with imperative instructions. They do not benefit from the prose overview section, the “this repo is a FastAPI service with a Postgres backend and three main packages” paragraph that sits at the top of most templates.
Where should I put hard prohibitions like “do not commit to main”?
A sentence like “do not commit directly to main” or “never run migrations in production” is a request. The model usually honors it, but usually is not a control, and the study’s framing is that the instruction file is a write-only channel: a natural-language rule returns nothing back, and neither the file nor the agent application signals whether anything will enforce it. If an action would genuinely damage the repo or the environment, the instruction file is the wrong layer to enforce it. Use the tool’s permission system, Claude Code’s deny rules or the equivalent in your agent, and keep the prose file for guidance the agent is allowed to interpret.
Join the discussion
Share a useful perspective or ask a question about this article.