DEV Community

Roei
Roei

Posted on Originally published at gethrbr.com AI-assisted

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

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.

  • In about 1 in 6 repos that keep both files at the root (16%), the CLAUDE.md never mentions the AGENTS.md, so Claude Code never loads it. In another 15%, a sentence asks Claude to read it, which works only if Claude decides to open the file.
  • In 7%, the two files started as copies and have drifted apart, so Claude and Codex follow different rules in the same repo.
  • About 1 in 5 CLAUDE.md files (19%) is longer than the 200 lines Anthropic suggests. The median is 81 lines.
  • About 30,000 AGENTS.md files on GitHub (2.6%) are larger than the 32 KiB Codex reads by default, so the end of each one never reaches the model.

Does Claude Code read AGENTS.md?

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.

How long are these files?

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.

The Codex size limit

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.

Three more things worth cutting

  • A directory tree: 17% of CLAUDE.md files and 11% of AGENTS.md files. The agent can list the folder itself, the tree goes stale with the first move, and the largest study so far found repository overviews did not help agents find the relevant files.
  • HTML comments: 6% of CLAUDE.md files. Claude Code strips block-level comments before the file reaches Claude, which suits notes for maintainers and silently drops an instruction written inside one.
  • A sentence pointing at AGENTS.md instead of an import: 6% of all CLAUDE.md files, whether or not an AGENTS.md sits beside them.

How we sampled

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.

Other studies of these files

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.

Limitations

  • Public repositories only, forks excluded. Private company repos may look different.
  • Every figure is a weighted estimate from GitHub's relevance-ordered search, good to a point or two.
  • One snapshot, October 18, 2026.
  • The pair labels are rules a script applies; a reworded line counts as missing.
  • It measures whether instructions reach the agent, not whether the agent follows them.

Every figure is in one CSV (aggregates only, no repository names): 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. 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.

Top comments (1)

Collapse
 
gapmine profile image
Balance •

I've been running into the drift problem in my own repos — I started with a single AGENTS.md, then someone added a CLAUDE.md for the Claude Code workflow, and now the two files disagree on our test conventions. The 15% 'asks in a sentence' case is the one that worries me most, because it looks like it's working until the agent decides not to open the file. I've since moved to a symlink so there's only one source of truth, and the 200-line suggestion makes a lot of sense once you see how much context gets eaten before the agent even starts the task.