CLAUDE.md and AGENTS.md: How 1,292 Public Repos Link Them

I read the agent instructions in a random sample of 19,776 public GitHub repos, all with 10 or more stars and a push in the 30 days to 9 November 2026. 1,292 of them have both a CLAUDE.md and an AGENTS.md at the root. In 508 of those, 39%, I found no import or symlink between the two files: CLAUDE.md doesn't import AGENTS.md, and neither file is a symlink to the other.

That measures automatic loading, not whether the rules agree or what the agents end up reading. With default settings, Claude Code reads CLAUDE.md and skips AGENTS.md whenever a CLAUDE.md exists. Codex reads AGENTS.md and doesn't load CLAUDE.md at all. So without an import or a symlink, each agent starts with only its own file. Some of these pairs are copies of each other, and some point to the other file in a sentence the model may or may not follow. The sections below take them one at a time.

The fix is already the most common CLAUDE.md in the sample. 324 of these files, 25%, are a single line that imports AGENTS.md, and 317 of them are exactly @AGENTS.md. Claude Code and Codex in one repo explains why that line works and covers the rest of the setup.

The other findings, from the same sample:

• Copies drift. 109 repos keep two copies of the same instructions. Of the 62 that are no longer identical, 25 give one agent rules the other doesn't get, and 14 contradict each other.
• These checks found few clashes on the basics. Scripted checks for seven kinds of clash, from package managers to banned commands, flagged 26 candidates in 600 pairs of files, and reading each one confirmed 2. Reading the 62 near-copies in full turned up 14 contradictions, one of them a pair the checks had already caught, so 15 pairs in all. Checks like these miss clashes worded some other way, so read 15 as a floor. Among the near-copies, rules only one file has were more common than contradictions: 25 against 14.
• 5.4% of root AGENTS.md files are over Codex's default 32 KiB limit, and past it Codex drops the rest without a warning. Counting nested AGENTS.md files on the same path, 7.2% of repos go over.
• AGENTS.override.md is rarely committed. No sampled repo with a root AGENTS.md has one, out of 3,107. Code search finds 816 across all of GitHub.
• Skills are split too. 64% of repos with both instruction files and a skills folder keep their skills where only one of the two agents loads them.

How the two files relate

One more repo symlinks one of the files to something other than its partner.

Imports. Claude Code expands @AGENTS.md when the session starts, so Claude gets AGENTS.md plus anything else in CLAUDE.md, and Codex reads AGENTS.md as usual. 324 of the 485 imports are the whole file. 39 run to more than ten lines, so they carry instructions of their own as well. Claude Code is strict about the syntax: the @ has to start the line or follow a space, and the path runs to the next space. So @AGENTS.md. at the end of a sentence names a file called AGENTS.md. and imports nothing, and so does (@AGENTS.md). 6 CLAUDE.md files in the sample write @AGENTS.md in a way Claude Code doesn't import, and I counted them as pointers.

Symlinks. Both tools read the same bytes. 233 of the 299 make CLAUDE.md the link, 59 go the other way, and 7 link both names to a third file. Without symlink support, which Windows lacks by default, git checks a link out as a small text file that holds the path. 6 repos have a plain CLAUDE.md or AGENTS.md whose whole text is the other file's name, which is what such a checkout looks like. Git keeps a checked-out link recorded as a link when you commit it, though, so I can't tell how these files were made. Either way, the agent reads a file name, not rules.

Pointers. Usually a line in CLAUDE.md like "Read AGENTS.md before making any change." 85 of these CLAUDE.md files are five lines or fewer and say little else. A pointer works when the model decides to open the file, and nothing makes it. Claude Code doesn't load AGENTS.md for it. In 59 repos the only pointer sits in AGENTS.md, aimed at a CLAUDE.md that Codex doesn't read by itself. 5 AGENTS.md files write it as @CLAUDE.md, as if Codex followed imports. It doesn't, and the line reaches the model as text.

Separate files. Two rulebooks that don't mention each other. Separately written pairs barely overlap: where both files have 20 lines or more and aren't copies, the median pair has about 1% of its distinct lines in common.

The share with no import or symlink was 41% in repos with 10 to 499 stars and 32% in repos with 500 or more. Another 38 repos keep Claude's instructions in .claude/CLAUDE.md instead of the root. Claude Code treats that file like a root CLAUDE.md, so the same logic applies, but I left them out of the counts above.

Copies drift

47 pairs are identical, and 62 more are near-copies: once whitespace is normalized and the tool names are masked, at least half of all their distinct lines are shared. I had a Claude Code agent read all 62 diffs in full and label each one by fixed definitions:

• 23 differ only in a title, the tool's name, a generated-file banner or a line rewritten for each tool
• 25 have rules, commands or facts that only one of the two files has
• 14 contradict each other

The one-sided rules are ones you'd want both agents to follow: a changelog entry for every user-facing change, a ban on customer-identifying details in code and commit messages, a mutation-testing gate in CI, and running the linter and the tests before every commit. Each was in one file and missing from the other.

The contradictions are what happens when one file gets edited and the other doesn't. In one repo, CLAUDE.md forbids regenerating a shared package list with a forced dump, because that wipes other machines' entries, and AGENTS.md, the older of the two, still gives the forced dump as the way to update it. In another, CLAUDE.md says never to hard-code the front-end dev port, and AGENTS.md hard-codes it. In nine of the other twelve, the two files name different CI services, disagree on whether a push to main deploys, disagree on which generated files may be committed, link different plans as the current one, give module paths from an older layout, disagree on what the serving engine can do, disagree on which docs get bundled, describe a cleanup command differently, or name different files as the canonical rules. In the last three, one AGENTS.md describes a feature that its CLAUDE.md says was removed, one tells the agent to leave TODO markers that its CLAUDE.md forbids, and one has the agent set a risk level that its CLAUDE.md says isn't the agent's to set.

The edit dates fit. 45 of the 47 identical pairs were last changed on the same day. 9 of the 14 contradicting pairs were not.

A copy stays identical only while someone keeps it that way. With an import or a symlink there's no second copy to keep.

Where the files disagree

The clash people describe most is CLAUDE.md saying pnpm and AGENTS.md saying npm. I checked 600 pairs where the two files say things separately: pointers, separate files, near-copies, and imports whose CLAUDE.md has lines of its own. I looked for that clash and six other kinds. A script flagged candidates with deliberately loose patterns, and the same agent read every flag:

The ban conflict is the package-list command above. In the other, CLAUDE.md tells Claude to commit, push and open a pull request on its own, and AGENTS.md tells Codex to wait to be asked before pushing or opening one. That one may be deliberate. With the 14 contradicting near-copies, that makes 15 pairs whose files contradict each other.

These checks only catch what their patterns describe, so they can miss conflicts worded some other way. In the 261 pairs with no import or symlink where both files are full rulebooks of 20 lines or more, 52 give a test command in only one of the two, and 40 name the package manager in only one.

AGENTS.md files over 32 KiB

167 of 3,084 root AGENTS.md files, 5.4%, are over 32 KiB, Codex's default limit. Past it, Codex reads the first 32,768 bytes and drops the rest with no warning on screen, and a nested AGENTS.md under an oversized root never loads at all. Another 59 repos have a root file under the limit that goes over once the nested AGENTS.md files on the same path are added, so 7.2% of repos with a root AGENTS.md hit the limit somewhere.

Most files are nowhere near the limit. The median root AGENTS.md is 5.5 KiB. Popular repos go over less often: 2.9% of those with 500 or more stars, against 5.7% of those with 10 to 49. Code search, which covers all of GitHub, counts about 18,300 root AGENTS.md files over 32 KiB, 2.9% of the 627,000 root AGENTS.md files it indexes. 4 of the 167 oversized repos in the sample commit a .codex/config.toml, and none of them raises project_doc_max_bytes.

To check yours, run wc -c AGENTS.md, and add the nested AGENTS.md files on the path where you start Codex.

AGENTS.override.md is rarely committed

None of the 3,107 repos in the sample with a root AGENTS.md commits an AGENTS.override.md, at the root or anywhere in the 3,092 trees I could list in full. Code search finds 816 such files across all of GitHub, against about 1.2 million AGENTS.md files, so a few repos do commit one.

Codex's docs suggest an override in a subdirectory when the team working there needs different rules, and Codex then reads it instead of that directory's AGENTS.md. Claude Code never reads it. So an override suits rules that really are Codex-only. Anything both agents should follow belongs in AGENTS.md, where CLAUDE.md can import it.

Skills: two folders, mostly unlinked

Claude Code loads skills from .claude/skills and Codex loads them from .agents/skills. 1,082 repos in the sample have one or both:

Shared means one folder, or the folder above it, is a symlink to the other, both point to one third folder, or every skill in one folder is a symlink into the other. I followed each link to check where it goes. 45 of the 82 pairs of separate folders hold the same skill names. In 22 of them every skill is identical in both folders, file for file, and in 23 at least one has already changed. Across all of GitHub, code search counts about 516,000 SKILL.md files under .claude/skills and 495,000 under .agents/skills.

Among the 404 repos that ship both instruction files and a skills folder, 259, or 64%, keep their skills where only one of the agents loads them.

What I'd change

If your repo has both files:

1. Make CLAUDE.md the one line @AGENTS.md, with anything Claude-only below it.
2. If you keep two copies, delete one and import the other.
3. Run wc -c on AGENTS.md and on every nested AGENTS.md on the path, and keep the total under Codex's default of 32,768 bytes, or raise project_doc_max_bytes in .codex/config.toml.
4. Keep skills in .agents/skills and symlink .claude/skills to it.
5. Put shared rules in AGENTS.md, and use AGENTS.override.md only for rules that really are Codex-only.

The commands, and the permissions that stop each agent rewriting the other's config, are in Claude Code and Codex in one repo.

How I counted

All of it ran on 9 November 2026, between 06:22 and 07:40 UTC, read-only, through GitHub's REST and GraphQL APIs.

• The frame. Public repos with at least 10 stars, not forks and not archived, with a push between 10 October and 9 November 2026. Repository search counted 317,587 of them.
• The sample. I drew 420 creation dates at random, with a fixed seed (20261103), from 1 January 2008 to 2 November 2026, and listed every repo in the frame created on those days: 19,776 repos. Every repo in the frame created in that range had the same chance of being drawn, 420 in 6,881. The 2,448 created after 2 November, 0.8% of the frame, couldn't be. Repository search returns at most 1,000 results per query, and the busiest day drawn had 888, so every day was listed in full.
• Why not code search. It ranks its results and returns at most 1,000 per query, so it can't give a random sample, and it can't see symlinks. Its top results also skew away from small files. 3 of its top 99 CLAUDE.md results are under 100 bytes, against 21% of the root CLAUDE.md files in the random sample, and 89% of those small files import AGENTS.md. A sample built from top results would miss most of the imports.
• What I read. For every repo, the root file list on the default branch, which shows symlinks. For the 4,432 repos with any agent config at the root: CLAUDE.md, AGENTS.md, .claude/CLAUDE.md, AGENTS.override.md, and the .claude, .agents, .claude/skills and .agents/skills folders, with a content hash for each skill folder and the target of each symlink. For the 1,293 with both files, the date of the last commit to each. For the 3,107 with a root AGENTS.md, the full file tree, for nested AGENTS.md files and their sizes, and for the 167 whose root AGENTS.md is over 32 KiB, any committed .codex/config.toml. That's why the AGENTS.md counts differ. 15 trees were too large for the API to return in full, so nested files come from 3,092 trees, and 23 root AGENTS.md files are symlinks to something other than a plain root CLAUDE.md, so sizes come from 3,084 files. One repo with both files is left out of the pair counts because the API wouldn't return its CLAUDE.md or AGENTS.md text.
• How I classified. Symlinks come from git file modes, and I followed each one to where it points. An import is what Claude Code's own parser treats as one. I copied its rule from Claude Code 2.1.220 and ran it with the markdown library Claude Code uses: the @ starts the line or follows a space, the path runs to the next space, and nothing inside code or HTML counts. In 2.1.317, the newest version I could inspect, the same function reads the same markdown tokens with the same pattern; what changed is an added check that skips special paths, such as device files. The release notes for 2.1.318 and 2.1.319 don't mention imports. A near-copy is a pair whose files, once whitespace is normalized and tool names are masked, have a Jaccard similarity of at least 0.5 over their distinct lines: the lines they share are at least half of all the distinct lines in the two. Two skill folders count as the same only if git's hash of their contents matches. The conflict checks are scripts. A Claude Code agent then read every flag and every near-copy diff in full and labelled each one by definitions written down before the run, and the labels and its notes on every contradiction are in the published data. The diffs themselves were deleted with the rest of the raw data, so the labels can't be read against them again. The counts above are what held up.
• Intervals. Repos created on the same day were drawn together, so I resampled days to get 95% intervals: 35.6% to 42.6% for the share of pairs with no import or symlink, and 4.3% to 6.5% for root AGENTS.md files over 32 KiB.
• Code search counts come from filename: queries on the same day. They count files, not repos, include nested files and are estimates that move from day to day, so I've rounded them.
• Code and data. The scripts, the seed and one anonymized row of labels per sampled repo are at github.com/pulore/agents-md-study, so you can check every count or rerun the study.
• What the API can't see. Private repos and branches other than the default. Files kept out of git, such as CLAUDE.local.md, ~/.claude/CLAUDE.md and ~/.codex/AGENTS.md. Personal settings, including the Claude Code option that loads CLAUDE.md and AGENTS.md together, which would link two separate files for the one person who sets it. And what happens in a session: whether a model follows a sentence that tells it to read the other file, or which rule it follows when two files disagree.

No repo is named here. The repo names and file contents the study downloaded were deleted once the counting was done. What I kept, and published with the code, is the counts and one row of labels per repo under a salted hash, and the salt was deleted too.