AGENTS.md, measured
There are 943,232 public AGENTS.md files. The median runs 67 lines, two in three never name the test command, and 61.4% have been committed once and never edited since. We pulled the numbers because every guide to this file argues from anecdote.
What AGENTS.md is
AGENTS.md is a plain markdown file that tells a coding agent how to work in your repository: the commands that actually run, the conventions review enforces, the directories to leave alone. It has no required fields and no schema. Roughly two dozen tools read it, including Codex, Cursor, Aider, Zed, Jules and the GitHub Copilot coding agent, and each one reads the file nearest the code it is editing.
Think of it as the README for the machine. The README explains the project to a human who will ask follow-up questions. This file tells an agent the things it will otherwise get wrong silently.
Which tools read it, and what happens when there are two
Roughly two dozen tools support the file. They do not agree on what to do when they find more than one.
| Tool | Reads | When it finds more than one | Where it looks |
|---|---|---|---|
| Claude Code | CLAUDE.md, or AGENTS.md when no CLAUDE.md is present | Concatenates every file it finds, root first | ~/.claude, the repo root, and subdirectories on demand |
| Codex, Jules, Aider, Zed and 19 others | AGENTS.md | Nearest file in the tree wins | Any directory, closest to the file being edited |
| Cursor | .cursor/rules/*.mdc, plus AGENTS.md | Frontmatter decides: always, glob-matched, agent-picked or manual | Nested .cursor/rules apply to their own directory tree |
| GitHub Copilot | .github/copilot-instructions.md, AGENTS.md, CLAUDE.md | Nearest AGENTS.md wins; personal beats repo beats org | AGENTS.md and CLAUDE.md are read by the coding agent only |
Row one and row two are the difference worth internalising. The AGENTS.md convention is that agents read the nearest file in the directory tree, so the closest one takes precedence. Claude Code does the opposite: it concatenates every file it discovers into context rather than letting one override another. Write a root file and a package-level file that contradict each other, and Codex will quietly follow the package one while Claude Code receives both and picks. Our CLAUDE.md reference goes through that resolution order in detail.
What is actually in them
Sampled across the whole size range, then weighted so each size bucket counts for its real share of the 943,232 files.
67 lines
The median file, at 402 words and 7 headings. Shorter than the discussion around it suggests.
n = 680, weighted to the full population
35%
Name a test command. The single most useful line in the file is missing from two thirds of them.
Same sample
12.2%
Sit in a repository with more than one AGENTS.md. Nesting is far rarer in practice than the spec implies.
n = 246 repositories
| Contains | AGENTS.md | CLAUDE.md |
|---|---|---|
| Median length | 67 lines | 88 lines |
| Median word count | 402 | 533 |
| Median headings | 7 | 11 |
| Names a test command | 35% | 40% |
| Names a build command | 19% | 23% |
| Names a lint command | 28% | 29% |
| Sets code style rules | 51% | 47% |
| Sets commit or PR rules | 41% | 25% |
| Mentions secrets or security | 30% | 24% |
| References the other file | 9% | 15% |
AGENTS.md carries commit and PR rules more often than CLAUDE.md does, 41% against 25%, which fits its origin as a shared team file rather than a personal one. It is thinner on structure: 7 headings at the median against 11, and 402 words against 533.
Writing one that earns its place
The file has no schema, so the only test that matters is whether a line changes what the agent does.
## Commands- Tests: pnpm test (pnpm test:e2e needs Docker running)- One test: pnpm test -t "name pattern"- Typecheck before pushing: pnpm build ## Conventions- Server state goes through TanStack Query, client state through Zustand.- Never mix the two in one component.- Commits follow Conventional Commits. CI rejects the rest. ## Do not touch- src/generated/ is generated. Edit the schema instead.- legacy/ ships to two customers. Changes need an owner's review.Every line above names something an agent gets wrong without being told. What to leave out is easier to state: anything true of software in general, anything the agent can read off package.json, and anything you would not enforce in review. Instructions the model can safely ignore teach it that this file is ignorable.
Where to put it
Root first. Add a second file only where a package genuinely needs a rule that would be wrong elsewhere, which our sample says is uncommon: 12.2% of repositories had more than one, and the largest had 21. Commit it. A file that explains why an agent did what it did belongs where the reviewer can see it.
The case against
The objections are worth reading before you spend an afternoon on this.
Claude treats them as context, not enforced configuration. To block an action regardless of what Claude decides, use a PreToolUse hook instead.
Anthropic, Claude Code memory docs
The file as written just seems to assume an authority that open source software explicitly relinquishes.
FeepingCreature, lobste.rs
At some point, you will end up in a situation where Claude Code cannot read it because it's too large.
Stanislav Silin, dev.to
A related complaint from the same thread, that AGENTS.md is a sign your project is underdocumented, has a straightforward answer. Models lack the intuition a human reader brings, so the file earns its keep on token efficiency alone even in a well-documented repository. The authority objection is harder, and it is fair: the convention arrived with a website and a logo rather than through the usual route.
The failure nobody argues about
We pulled the commit history for 246 repositories with a root AGENTS.md. 61.4% of the files have exactly one commit. Meanwhile 74.8% of those repositories kept shipping code for at least a month afterwards, with a median gap of 76 days between the last edit to the file and the last push to the repository. The file was written on a Tuesday and then the project moved on without it.
A stale file is worse than none, because the agent has no way to tell that the test command changed six months ago. That is the maintenance problem, and writing a better file on day one does not solve it.
What people ask first.
What is Agents.md for?
Giving every coding agent one place to read instead of one file per vendor. Before it existed a team running Codex, Cursor and Claude Code maintained three copies of the same conventions. In the 680 files we measured, the most common contents are project structure (56%), how testing works (44%), code style (44%) and the commands to run (41%).
Is Agents MD the same as Claude md?
Same shape, opposite resolution. The AGENTS.md convention is that the nearest file in the tree wins, so a subdirectory file replaces the root one. Claude Code concatenates every file it discovers, root first, so nothing is replaced and contradictions travel into context together. Claude Code reads AGENTS.md when no CLAUDE.md is present, and ignores it when both exist unless you change the project instructions setting.
Should agents MD be committed?
Yes, with one carve-out. The file describes the repository, so it belongs to the repository, and a reviewer who cannot see it cannot tell why an agent did what it did. Keep personal preferences out of the committed file: AGENTS.local.md is the usual gitignored companion, though Claude Code does not read it, so Claude users want CLAUDE.local.md instead.
Where do you put agent md?
Repository root first, then one per subdirectory where the rules genuinely differ. Nesting is rarer than the spec implies: only 12% of the repositories we checked had more than one, and the largest had 21. Start with one file and split when a monorepo package needs a rule that would be wrong everywhere else.
How we measured this. Measured 28 September 2026 against the public GitHub corpus. Size distribution from code search result counts across 17 size buckets, which covers every public file rather than a sample. Content from 40 files per bucket, 680 per filename, reweighted to that distribution. Upkeep from the commit history of 246 root-level files per filename. Private repositories are out of reach, and code search ranks by popularity, so the upkeep figures describe repositories with some traction rather than the long tail.
Counts are from a single day, and the corpus grows weekly, so treat the shares as stable and the absolute counts as a floor.
Writing the file is the easy day.
Keeping it true is the rest of them.
Trail reads your commits, your PR history and the corrections you keep repeating, then proposes the rules worth adding to AGENTS.md. You approve each one. The rules that must never break become hooks instead of notes.
Or read how Trail works for coding agents first.