We checked 3,905 CLAUDE.md and AGENTS.md files on GitHub. In 1 in 6 repos, Claude never reads the AGENTS.md

A developer analyzed 3,905 CLAUDE.md and AGENTS.md files from public GitHub repositories and found that in roughly 1 in 6 repos with both files, Claude never reads the AGENTS.md because the CLAUDE.md neither imports nor links it. The study recommends adding a single `@AGENTS.md` import line at the top of CLAUDE.md, since a sentence asking Claude to read the file only works if the agent chooses to open it. It also found that 19% of CLAUDE.md files exceed Anthropic's 200-line target and that Codex silently truncates AGENTS.md files past its 32 KiB default limit.

On October 18, 2026 we pulled 3,905 CLAUDE.md and AGENTS.md files from public GitHub repositories and ran each one through the same checks. We wanted to know something simple: does the file actually reach the agent? Four results stand out. Not by default. Anthropic's memory docs say that when there is a CLAUDE.md or .claude/CLAUDE.md , or CLAUDE.local.md in the folder you start in or above it, Claude reads your CLAUDE.md files only. That case is common: 36% of the AGENTS.md files at a repository root have a CLAUDE.md beside them. This is what those CLAUDE.md files do with it 745 repos : | The CLAUDE.md beside it | Repos | Does AGENTS.md reach Claude? | |---|---|---| | Imports it with @AGENTS.md | 25% | Yes | | Is a symlink to AGENTS.md | 23% | Yes | | Copies its lines | 7% | Yes, as a second copy | | Copied it once, then drifted | 7% | Partly | | Asks Claude in a sentence to read it | 15% | Only if Claude opens it | | Never mentions it | 16% | No | | Holds it all; the AGENTS.md is a stub under five lines | 5% | Nothing to miss | | Imports other files, so we could not tell | 2% | Unknown | Some of the 16% is deliberate: a few of those AGENTS.md files say they are written for Codex, Cursor and the rest, with Claude covered by its own file. Deliberate or not, Claude and Codex then work from different rules in the same repo, and a rule added to one file reaches only some of the agents. The sentence case is the one people expect to work. A line such as "Read AGENTS.md before starting any task" is text, not an import: it works only if Claude decides to open the file. A copy that drifted fails more slowly. Both files began as one, someone edited one of them, and nothing in either file says which is current. We counted a pair as drifted when the CLAUDE.md held some of the AGENTS.md's lines but was missing at least five, and not more than 90% of them. The fix is one line: @AGENTS.md on its own line at the top of CLAUDE.md, with anything Claude-specific below it. A symlink also works, but Anthropic notes that a Windows clone without core.symlinks checks it out as a one-line text file. The median CLAUDE.md is 81 lines, and 1 in 10 is longer than 309. 19% are past the 200 lines Anthropic's docs set as the target, and 4% are past 500. Anthropic's reason is adherence: a longer file uses more context and is followed less. AGENTS.md files run shorter, with a median of 63 lines, though 18% are past 200. This one needs no sample. GitHub's count is 30,080 AGENTS.md files over 32 KiB, 2.6% of all of them, and 51,840 over 24 KiB, where one more nested file pushes a repo past the limit. Codex joins AGENTS.md files from the root down and stops adding them at 32 KiB by default project doc max bytes . The rest never reaches the model, and in our tests the terminal said nothing. Cut the file, or raise the limit in ~/.codex/config.toml . GitHub code search counts 839,680 CLAUDE.md files and 1,142,784 AGENTS.md files in public repositories, forks excluded. A search returns at most 1,000 results, in GitHub's own relevance order, so we split each file name into ten size bins, from under 500 bytes up to 384 KB, the largest file GitHub indexes. From each bin we took the first 100 results and 100 more from a random narrow size window inside it. We fetched every file at the commit GitHub had indexed and weighted each bin by GitHub's count for it. GitHub's counts are themselves estimates, so read every figure to the nearest point or two. Pairs were read from the AGENTS.md side: for each AGENTS.md at a repository root, we fetched the CLAUDE.md beside it at the same commit. Search almost never returned a symlinked file, yet nearly a quarter of the CLAUDE.md files beside an AGENTS.md were symlinks, so starting from CLAUDE.md would have missed them. Four arXiv papers study the same files and ask what is in them, how they change, or whether they help: arXiv:2509.14744 253 CLAUDE.md files , arXiv:2510.21413 466 projects with AGENTS.md , arXiv:2511.12884 2,303 context files and arXiv:2601.20404 agents with and without AGENTS.md on 124 pull requests . From their abstracts, none checks whether a CLAUDE.md beside an AGENTS.md loads it, or how many files pass Codex's size limit. The samples differ, so the percentages are not comparable. Every figure is in one CSV aggregates only, no repository names : https://gethrbr.com/data/claude-md-agents-md-study-2026-10-18.csv https://gethrbr.com/data/claude-md-agents-md-study-2026-10-18.csv If you want to see where your own repo lands, the same checks run free at https://gethrbr.com/check https://gethrbr.com/check . Does your CLAUDE.md import its AGENTS.md? I work on Harbor gethrbr.com , shared memory and rules for AI coding agents. The full write-up, with links to every source, is at https://gethrbr.com/blog/claude-md-agents-md-github-study https://gethrbr.com/blog/claude-md-agents-md-github-study .