Study
CLAUDE.md vs AGENTS.md in 596 repos: 1 in 8 keep copies, and 4 in 10 copies differ
We read both files in 596 public GitHub repos that keep a CLAUDE.md and an AGENTS.md at the root. Most link the two, with an import line or a symlink. But 1 repo in 8 keeps two copies, and 33 of those 76 copies already say different things, even ignoring tool names.
What the differences look like
From the copies that differ:
- A CLAUDE.md says the project uses Spring Boot 4.0.7; its AGENTS.md still says 4.0.5.
- A "don't write tests for now" rule that's in CLAUDE.md but not in AGENTS.md.
- Deployment options listed differently: one file says Vercel, the other adds Docker and Cloudflare Workers.
- An AGENTS.md whose only extra lines say it's identical to CLAUDE.md and that both must change together.
The other 43 copies match apart from tool names, so every edit has to be made twice to keep them that way. Separate texts are often deliberate: a short Claude-specific file next to a long shared one.
Startups keep files for several tools, in several repos
We also searched the public GitHub organizations of 276 Y Combinator companies (active, 10 to 120 people, in the US or Europe, mostly developer tools and infrastructure). 60 have a CLAUDE.md, AGENTS.md or Cursor rules file in a public repo. 39 of those have both a CLAUDE.md and an AGENTS.md, and 28 have agent files in more than one repo.
Why it matters
An import line or a symlink fixes one repo, for the tools that follow it. Copies have to be edited twice, and the work grows with every repo, tool and teammate. For which file each agent reads, see which coding agent reads which instruction file.
How we counted
On 24 October 2026, Sourcegraph's public code search listed 5,000 repos with CLAUDE.md at the root and 5,000 with AGENTS.md at the root (its result limit); 1,429 were in both lists. We read both files from the default branch of a random sample of 600, and 596 were still there. Each pair got the first class whose rule fits, in this order:
| Class | Rule | Repos |
|---|---|---|
| Symlink | One file holds only the other's name | 154 |
| Identical copy | Same text, ignoring spacing | 31 |
| Copy, only tool names differ | Same text once tool names (Claude, Codex, CLAUDE.md, AGENTS.md) are set aside | 12 |
| Imports the other | @AGENTS.md in CLAUDE.md, or @CLAUDE.md in AGENTS.md |
166 |
| Copy that differs | 80% or more of the lines the same, tool names set aside | 33 |
| Points to the other in words | A file under 600 characters that names the other near the top | 58 |
| Partly the same text | 30 to 80% of the lines the same | 16 |
| Points to the other, adds its own text | Names the other near the top, then 600+ characters of its own | 32 |
| Two separate texts | Under 30% of the lines the same | 94 |
Limits: public repos only, root files only, one point in time. Both searches hit Sourcegraph's 5,000-result cap, so the 1,429 aren't every repo with both files. A snapshot shows that copies differ today, not which file was edited. Some copies are written by sync tools such as Ruler or rulesync rather than by hand, and line-based similarity misses reordered text. The startup numbers come from a Sourcegraph search of those 276 organizations on 23 October 2026, counting CLAUDE.md, AGENTS.md, .cursorrules and .cursor/rules/ files.
We're building Tape, one live document in every app and every agent. It's in early access.
FAQ
What's the most common way to keep CLAUDE.md and AGENTS.md in sync? An import line, @AGENTS.md, at the top of CLAUDE.md, followed closely by a symlink.
Do copies of CLAUDE.md and AGENTS.md drift apart? In our sample, 33 of the 76 repos that keep the two files as copies already had texts that differ, even ignoring tool names. One snapshot can't show which file changed.
Do I still need CLAUDE.md? Not for shared rules. Claude Code (v2.1.277 or later) reads AGENTS.md when there's no CLAUDE.md, so many repos can keep a single AGENTS.md.