If your repo has an AGENTS.md, a CLAUDE.md, or both, a new preprint has numbers on what teams actually put in them, and what they leave out.
On November 2, 2026, four researchers (Shanto, Islam, Asaduzzaman and Ngom) 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, drawn from the public AIDev dataset of agent-authored pull requests. It's version 1 of a preprint that hasn't been peer reviewed, so treat the numbers as a first look.
Popular repos pile up formats
- 66.2% of the higher-star half had at least one instruction file, against 50.2% of the lower-star half.
- AGENTS.md led in both: 50.0% of popular repos had one, ahead of CLAUDE.md at 40.4%.
- 42.2% of instruction-bearing popular repos keep more than one format (21.6% in the other half). AGENTS.md plus CLAUDE.md is the most common pair, in 231 repositories.
Two files, two sets of instructions
The authors compared 386 pairs of sections covering the same topic in two formats of the same repo. 32.6% said the same thing in different words and 51.3% complemented each other, but 16.1% gave divergent guidance. None contradicted outright.
A plain diff won't catch it: for AGENTS.md/CLAUDE.md pairs, median overlap was 0.273 at the heading level but 0.929 at the category level. Same content, different headings.
Why it matters: by default, Claude Code reads only CLAUDE.md when both files exist (unless CLAUDE.md imports @AGENTS.md), while Codex reads AGENTS.md. So in the most common pair, the two agents can work from different briefs.
Files get written once
40.4% of files had only one recorded modification (47.7% for Copilot instructions, 34.4% for CLAUDE.md), and every format had a median of one author.
What most files leave out
Do's and don'ts appear in 81.2% of files. Four categories fall well below half:
| Missing category | Share of files | What to add |
|---|---|---|
| Git and PR conventions | 43.8% | Branch naming, commit format, what a PR needs |
| Security and secrets | 29.9% | Where secrets live, files never to print or commit, commands that need a human |
| When to update this file | 26.6% | A trigger (build, test or conventions change) and a reviewer |
| Ownership and contacts | 18.8% | Owning team per directory, who to ask about risky changes |
What to do this week
-
Pick one source of truth. 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. Walk build, test, style and structure across files and resolve divergent lines.
- Add the security and secrets section first. It's in fewer than a third of files, and it's the one that protects you.
- Treat generated files as drafts. 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 study's limits: public GitHub repos only, and it didn't measure whether divergent or incomplete files change what agents produce. Still, combined with earlier work showing agents follow stale instruction files over the code, the message is that these files matter and rarely get maintained.
The full write-up, with charts, a table of which agent reads which file and the 16-category template, is here: Agent Instruction Files Study 2026 on StackChief.
This post was written with the help of AI, as a summary of the StackChief article above.
Top comments (0)