Blog · 2026-11-06

CLAUDE.md and AGENTS.md in one repo: Claude Code reads only CLAUDE.md, and 1,072 of 2,744 public repos with both never pass AGENTS.md on

Since 2.1.277 Claude Code reads AGENTS.md, but only when there is no CLAUDE.md. Of 2,744 public repos with both files, 1,072 keep different instructions in an AGENTS.md that Claude Code doesn't load. Tested on 2.1.314.

Summary

If your repo has both a CLAUDE.md and an AGENTS.md, put @AGENTS.md on its own line in CLAUDE.md, or make one file a link to the other.

The reason is simple. Since version 2.1.277 (September 18), Claude Code can read AGENTS.md, the instruction file Codex and other agents use. But by default it reads AGENTS.md only when the repo has no CLAUDE.md. When both exist, Claude Code loads CLAUDE.md and leaves AGENTS.md out, unless CLAUDE.md imports it.

How often does that leave instructions behind? We read the instruction files in 5,864 active public repos. 2,744 have both files. In 1,072 of them, AGENTS.md holds different text, and CLAUDE.md neither imports it nor links to it. Claude Code starts those sessions without it.

How we tested

  1. The loading rule. In four empty projects we put a codeword in AGENTS.md and asked Claude Code 2.1.314 (claude -p, Haiku, with file tools turned off) for it:
    • CLAUDE.md and AGENTS.md, no import: Claude had no codeword.
    • CLAUDE.md with @AGENTS.md on its own line: Claude gave the codeword.
    • CLAUDE.md with `@AGENTS.md` in backticks: no codeword. The docs say imports inside code spans are skipped.
    • AGENTS.md only: Claude gave the codeword.
  2. The repos. The same sample as our project settings review: 5,864 public repos with at least 5 stars, pushed to since October 7, not forks, as of November 6, 2026. Every one has a .claude/settings.json, so these are repos already set up for Claude Code. We downloaded the root CLAUDE.md, .claude/CLAUDE.md, CLAUDE.local.md, AGENTS.md and .claude/rules/ files at the sampled commit, 15,063 files.
  3. What loads at session start. We followed the docs: the root CLAUDE.md files, or AGENTS.md when there is none; every @path import that points at a file in the repo, up to four hops; and rules without a paths field. Imports inside code blocks and code spans don’t count, and block HTML comments are stripped, as the docs describe. A file whose whole content is another file’s path counts as a link.

Results

Which instruction files the repos have

Repos (of 5,864)
A root CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md4,709 (80.3%)
A root AGENTS.md3,333 (56.8%)
Both2,744 (46.8%)
AGENTS.md only, read by Claude Code since 2.1.277589 (10.0%)
Neither566 (9.7%)

In the 2,744 repos with both, does Claude Code get the AGENTS.md text?

Repos
Yes: CLAUDE.md imports AGENTS.md972
Yes: CLAUDE.md is a link to AGENTS.md448
Yes: AGENTS.md is a link to CLAUDE.md208
Same text in both files, so nothing is missed44
No: different text, no import, no link1,072 (39.1%)

Of those 1,072, 465 mention AGENTS.md in the text of CLAUDE.md, so Claude may open it when it follows that line. The other 607 never mention it. The AGENTS.md that goes unread has a median of 4,970 characters. Twelve repos wrote the import inside backticks, which turns it off.

How much loads at the start of every session

Quick guess: how much text does a typical repo here put in front of Claude before you type anything? Among the 5,322 repos that load anything at start, the median is 9,766 characters, counting imports and rules. 10.4% load more than 40,000 characters, and 2.7% more than 100,000.

Root CLAUDE.md, median length91 lines
Root CLAUDE.md over 200 lines, the length the docs recommend staying under24.5%
Root CLAUDE.md over 500 lines6.4%
Repos where any file loaded at start is over 200 lines33.7%
Repos with .claude/rules/ files that load at start (no paths)787
Repos with path-scoped rules that load only for matching files79
Repos with a nested CLAUDE.md in a subdirectory1,035 (17.7%)
Repos with an @ import pointing outside the repo, which asks for approval17

Our picks

What we now do with instruction files:

  1. Keep one source of truth and import it. If AGENTS.md is the shared file, start CLAUDE.md with @AGENTS.md on its own line and add only Claude-specific notes below it. Don’t wrap the line in backticks.
  2. Use a link only if nobody clones on Windows. ln -s AGENTS.md CLAUDE.md works, but the docs warn that Git on Windows checks a symlink out as a one-line text file unless core.symlinks is on. That clone gets a CLAUDE.md that says AGENTS.md and nothing else.
  3. Or change the setting. In /config, set Project instructions to claude-md-and-agents-md to read both files, CLAUDE.md first.
  4. Check what loaded. Run /context all and look under Memory files.
  5. Move long sections into path-scoped rules. The docs suggest under 200 lines per file. A rule with a paths field loads only when Claude works on matching files, and only 79 of these repos use one.

Which instruction file does your agent of choice read in your repo, and does the other one say something different?

What to ignore

Splitting a long CLAUDE.md into @ imports to save context. The docs say imported files load together with the file that imports them, so it helps you organize but loads the same text.

HTML comments. Block comments in CLAUDE.md are stripped before Claude sees the file, so maintainer notes in them cost nothing.

Limitations

  • Repos set up for Claude Code. Every repo here has a .claude/settings.json, so they are heavier Claude Code users than GitHub as a whole.
  • Default settings. We counted what loads with Project instructions at its default. A user who set claude-md-and-agents-md gets both files.
  • Static reading. We parsed imports the way the docs describe and checked four cases live on Claude Code 2.1.314. We did not open each repo in Claude Code.
  • Characters, not tokens. Lengths are characters after stripping comments. Token counts depend on the language and the model.
  • A sample. Active repos with 5 or more stars, as of November 6, 2026, chosen by code search relevance. It is not a random sample.

Reproduce it

The counts are in claude-md-agents-md-2026-11.json, with repo names and file contents left out. To check your own repo, put a codeword in AGENTS.md, start Claude Code, and ask for it.

For the rest of what a cloned repo brings, see what 5,864 public repos turn on in .claude/settings.json.

Sources

  1. Claude Code docs: Memory (AGENTS.md, Import additional files, How CLAUDE.md files load, My CLAUDE.md is too large) · official
  2. Claude Code CHANGELOG, 2.1.277: AGENTS.md support · official
  3. AgentCraft: Before you trust a cloned repo, read its .claude/settings.json · blog