Key Takeaways
- On November 2, 2026, four researchers posted to arXiv a study of 3,387 agent instruction files (AGENTS.md, CLAUDE.md, copilot-instructions.md and .cursorrules) from 1,000 GitHub repositories.
- Among repositories with instruction files, 42.2% of the more popular half keep more than one format. AGENTS.md plus CLAUDE.md is the most common pair, found in 231 repositories.
- When the same topic appears in two formats, 16.1% of 386 matched sections give divergent guidance. None of the pairs contradicted each other outright.
- Security and secrets guidance appears in only 29.9% of files, ownership in 18.8%, and "when to update this file" in 26.6%. 40.4% of files were modified only once.
- By default, Claude Code reads only CLAUDE.md when a repository has both files, while Codex reads AGENTS.md. When those two files diverge, the two agents work from different instructions.
The agent instruction files study from Mehedi Hasan Shanto, Md. Anaytul Islam, Muhammad Asaduzzaman and Alioune Ngom is the first large look at what teams actually write in the files that brief their coding agents. Most files cover how to build and test, the repository layout and the do's and don'ts. Far fewer cover security, ownership or when to update the file. In repositories that keep two formats, one matched section in six says something different.
What happened
The preprint, "Toward an Evidence-Based Template for Agent Instruction Files: An Empirical Study of Adoption, Consistency, and Maintenance", was submitted to arXiv's software engineering section on November 2, 2026. It asks four questions: who adopts instruction files, what they contain, whether coexisting formats agree, and how the files are maintained. From the answers, it derives a 16-category template.
The sample is 1,000 repositories drawn from AIDev, a public dataset of 932,791 agent-authored pull requests across 116,211 repositories. The authors split it at the median star count into two cohorts of 500 and found 1,677 AGENTS.md files, 1,107 CLAUDE.md files, 538 copilot-instructions.md files and 65 .cursorrules files.
What the agent instruction files study found
Popular repositories adopt more formats
66.2% of the higher-star cohort had at least one instruction file, against 50.2% of the lower-star cohort. AGENTS.md led in both: 50.0% of popular repositories had one, ahead of CLAUDE.md at 40.4%. C# was the exception, where Copilot instructions led at 53.4%.
The popular half is also where formats pile up. 42.2% of its instruction-bearing repositories keep more than one format, against 21.6% in the other half. That usually happens for a simple reason: different people on the team use different agents.
Two files, two sets of instructions
The authors compared 386 pairs of sections that cover the same topic in two formats of the same repository. 32.6% said the same thing in different words and 51.3% complemented each other. 16.1% (62 pairs) gave divergent guidance. None contradicted each other outright.
Headings rarely match even when the content does. For AGENTS.md and CLAUDE.md pairs, the median overlap was 0.273 at the heading level and 0.929 at the category level. A simple diff of the two files won't tell you whether they agree.
Files get written once
40.4% of files had only one recorded modification. The rate was 47.7% for Copilot instructions and 34.4% for CLAUDE.md. Every format had a median of one author. CLAUDE.md was the most likely to change alongside code: 65.2% of its edits were proactive co-changes. Copilot instructions were the most reactive: 48.2% of edits followed a failed or heavily reviewed agent pull request.
The numbers behind it: which agent reads which file
A divergent pair matters most when different agents read different files. The paper doesn't map that, so we checked each tool's documentation on November 3, 2026. The table shows what each agent reads by default.
| Agent | Reads by default | If the repo has both AGENTS.md and CLAUDE.md | Documented limit |
|---|---|---|---|
| Claude Code | CLAUDE.md, or AGENTS.md when there's no CLAUDE.md | Only CLAUDE.md, unless CLAUDE.md imports @AGENTS.md or you change the setting | Target under 200 lines per file |
| OpenAI Codex | AGENTS.override.md, then AGENTS.md, per directory from root down | Only AGENTS.md (CLAUDE.md only if listed as a fallback filename) | 32 KiB combined by default |
| GitHub Copilot | .github/copilot-instructions.md, plus AGENTS.md (nearest wins), or a root CLAUDE.md or GEMINI.md | Docs list both as options and don't say which wins | Onboarding prompt asks for no more than 2 pages |
| Cursor | .cursor/rules (.mdc) and AGENTS.md in root and subdirectories | The rules page doesn't mention CLAUDE.md | Not stated on the rules page |
Put the two sources together. In the paper's sample, AGENTS.md plus CLAUDE.md is the most common pair. That's exactly the pair where Claude Code and Codex split by default. If one matched section in six diverges, a team using both agents is giving them different briefs.
The study has limits. It covers public GitHub repositories only. It didn't measure whether divergent or incomplete files change what agents produce, and the authors avoid causal claims. The consistency figure comes from a sample of 386 section pairs, some from the same repository.
The gaps: what most instruction files leave out
The template has ten Required categories, each found in at least half of files, and two Recommended ones. The four Gap categories are the interesting part: under half of files include them, and the authors flag them as missing from current practice. We set each one against what to write.
| Gap category | Share of files with it | What to add |
|---|---|---|
| Git and PR conventions | 43.8% | Branch naming, commit format, what a PR description needs, what not to push |
| Security and secrets | 29.9% | Where secrets live, files the agent must never print or commit, commands that need a human |
| Maintenance: when to update this file | 26.6% | "Update this file when build, test or conventions change," plus who reviews it |
| Ownership and contacts | 18.8% | Owning team per directory, who to ask about a risky change |
Across the four, the average is 29.8%, our calculation from the paper's per-category figures. Compare that with do's and don'ts, which appear in 81.2% of files.
What this means for you
If your repo has more than one instruction file
- Pick one source of truth. Claude Code's docs show the pattern: keep AGENTS.md as the shared file and put
@AGENTS.mdat the top of CLAUDE.md, followed only by Claude-specific lines. - Compare by topic, not by diff. Headings rarely line up, so walk each topic (build, test, style, structure) across files and resolve divergent lines.
- In Claude Code,
/doctor prompt-auditchecks CLAUDE.md, AGENTS.md and rules for outdated or conflicting content and proposes edits.
If you own one file
- Add the four Gap sections from the table above. Security and secrets is the one to do first.
- Add a maintenance line and a reviewer. A file with one author and one edit is the norm in this sample, and our earlier coverage showed what a stale file does.
- Treat a generated file as a draft. In the paper's generation test, a template raised category coverage from 18.7% to 82.8%, yet only 19.4% of generated sections fully preserved the developer's intent. The authors write that developers should "treat automatically generated instruction files as drafts requiring verification."
How this connects
This study measures what instruction files say. Our October coverage measured what agents do with them: in a separate preprint, coding agents followed stale instruction files over the code in 90.1% of choices, until one added sentence flipped them. Put together, the two studies say the file is both influential and rarely maintained.
Instruction files are also only one layer of agent context. Skills are another, and an agent skills security study found that about one in seventeen public skills tells the agent to ask you less. For how teams moved from prompts to loops around agents, see loop engineering vs prompt engineering.
How this comes up in interviews
AI engineering interviews increasingly ask how you'd set up an agent on a real codebase: what context it gets, how you keep that context current, and how you stop it from touching secrets. "We keep one AGENTS.md, import it everywhere, and review it when the build changes" is a concrete answer with numbers behind it. For practice questions in that style, see our AI engineer interview questions with worked answers and how coding interviews changed in the age of AI.
FAQ
Should I use AGENTS.md or CLAUDE.md?
If your team uses more than one agent, keep AGENTS.md as the shared file, since Codex, Copilot and Cursor all read it. Claude Code reads AGENTS.md only when there's no CLAUDE.md. If you need both, make CLAUDE.md import it with @AGENTS.md.
What should an AGENTS.md file include?
The study's template lists ten Required categories, led by do's and don'ts, build and run commands, repository structure, and tooling config. It flags four Gap categories most files skip: git and PR conventions, security and secrets, when to update the file, and ownership.
Does Claude Code read AGENTS.md?
Yes, when the working directory and the directories above it have no CLAUDE.md or CLAUDE.local.md. If a CLAUDE.md exists, Claude Code reads only the CLAUDE.md files by default, unless CLAUDE.md imports AGENTS.md or you change the Project instructions setting.
Do better instruction files make coding agents perform better?
This study doesn't test that. It measures adoption, content and maintenance, and the authors avoid causal claims. A separate October 2026 preprint found that agents follow a stale instruction file over the code, which suggests the file's contents matter.
Further Reading
- Shanto, Islam, Asaduzzaman and Ngom, "Toward an Evidence-Based Template for Agent Instruction Files" (arXiv:2611.02383): the study, the template and the AGIT-Instruct benchmark.
- Claude Code docs: How Claude remembers your project: CLAUDE.md, AGENTS.md loading rules and the prompt audit.
- Codex docs: AGENTS.md: discovery order, overrides and the size limit.
- GitHub docs: Adding repository custom instructions for Copilot: copilot-instructions.md and AGENTS.md support.
- Cursor docs: Rules: project rules and AGENTS.md.
