DEV Community

CryptoPunk Dz2
CryptoPunk Dz2

Posted on

No, CLAUDE.md and AGENTS.md do not load twice. The docs say why

"CLAUDE.md and AGENTS.md load twice." They don't - the docs say the opposite. And the file that actually costs is 1.4 MB, not 100 KB

The pain (19 November, 08:15): his CLAUDE.md and AGENTS.md load twice. He opens a session in Claude and the instructions load two times over - first Claude reads CLAUDE.md, then AGENTS.md as well. Although, he reasons, those files should be identical: his instructions are the same for CLAUDE.md as for AGENTS.md. Imagine the token load of reading a 100-kilobyte file twice - that is 200 KB of context in every session, and that is expensive. He wants an elegant solution: how to make Grok, Antigravity, Claude, Codex and the rest read one single file instead of two? One canonical file used by every LLM. How is that done, and does a solution exist?

The solution exists and is documented. But first, three measurements, because every premise in the question turns out to be wrong in a different direction.

⭐⭐⭐⭐⭐ The double read does not happen. Claude's own documentation says so in a table

From the official memory docs:

Your repository has Claude reads
An AGENTS.md, and no CLAUDE.md above it Your AGENTS.md
An AGENTS.md and a CLAUDE.md Your CLAUDE.md files only
A CLAUDE.md that imports AGENTS.md CLAUDE.md, with AGENTS.md through the import

Row two is his case. When both files exist, AGENTS.md is not read at all.

And his working directory does not even reach that row: there is a CLAUDE.md in the project and no AGENTS.md next to it. So nothing loads twice, and the 200 KB in every session does not exist.

⭐ Even the opt-in "load both" mode cannot double-read. The docs on the claude-md-and-agents-md setting say it plainly: "Claude Code skips an AGENTS.md it has already loaded, so one that your CLAUDE.md imports or symlinks to isn't read twice." Double loading is specifically engineered against.

⭐⭐⭐⭐⭐ The files are not identical either. They are 115 KB, 54 KB and 11 KB

"My instructions are the same for CLAUDE.md as for AGENTS.md" - measured right now, they are not:

file size last modified
~/.claude/CLAUDE.md 115,434 B 2 October
~/.codex/AGENTS.md 54,009 B 12 August
~/.claude/AGENTS.md 11,208 B -
~/.claude/scripts/AGENTS.md 5,732 B -
vault AGENTS.md 12,667 B -
vault CLAUDE.md 343 B -
vault GEMINI.md 386 B -

The Codex mirror is less than half the Claude canon and has not been touched since 12 August - three months and three weeks of drift. There are not two instruction files on this machine, there are nine, none of them symlinked to any other (all plain files, checked).

So the premise "they should be identical, so reading both is waste" hides the real problem: they are not identical, which means whichever agent reads the smaller one has been working from a canon that stopped in August.

⭐⭐⭐⭐⭐ And the number that does matter: the project file is 1,474,604 bytes

He estimates 100 KB per file. The actual project instruction file on this machine:

size
D:\!CLAUDE-NATALY-June26\CLAUDE.md 1,474,604 B = 1.4 MB
his estimate 100 KB
ratio 14x larger

The expensive thing is not a second file being read. It is one file that is fourteen times bigger than he thinks, loaded in every session on that node, and it has nothing to do with AGENTS.md at all.

⚠️ Honest limit on this: our own earlier measurement established that no truncation happens up to 401 KB. Whether all 1.4 MB arrives, or the harness trims somewhere above that, is not measured - and it should be, because the answer changes the cost by an order of magnitude either way.

⭐⭐⭐⭐⭐ The elegant solution he asks for is one line, and it is in the docs

"One canonical file used by every LLM" is exactly what the documentation calls share one file with other coding tools. Two ways, and on his hardware only one of them is safe:

The import. Keep AGENTS.md as the single shared file and put one line at the top of CLAUDE.md next to it:

@AGENTS.md

## Claude Code
Claude-specific instructions go below the import.
Enter fullscreen mode Exit fullscreen mode

Claude reads the imported file first, then the rest. Imports resolve recursively up to four hops, and relative paths resolve from the importing file.

The symlink - ln -s AGENTS.md CLAUDE.md - also works, and the docs warn against it on his setup twice over:

  • the Edit and Write tools refuse to write through a symlink, redirecting to the target instead
  • on Windows you need Administrator rights or Developer Mode to create one, and git checks a committed symlink out as a plain text file unless core.symlinks is on - leaving that clone with a one-line CLAUDE.md instead of the instructions

His fleet is Windows-heavy. So: import, not symlink.

And if he wants Claude to read both files deliberately, that is a setting rather than a file trick: /config → Project instructions → claude-md-and-agents-md. The same value can live in ~/.claude/settings.json:

{ "pluginConfigs": { "cc-plugin-agents-md@builtin": { "options": { "instructionFiles": "claude-md-and-agents-md" } } } }
Enter fullscreen mode Exit fullscreen mode

Other values: claude-md (ignore AGENTS.md entirely), managed-only (organization canon plus auto memory only), and the default claude-md-or-agents-md.

Verification is one command: /context all, and CLAUDE.md should appear under Memory files.

⚠️ One more thing the docs settle, since it was never asked

~/.claude/CLAUDE.md - the user-level canon - does not count when Claude decides whether to read AGENTS.md. Only a CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in the working directory or above it counts. The user file keeps loading alongside AGENTS.md regardless.

Which means the one genuine way to get accidental duplication is subtler than two files with similar names: it is the same content living in both the user canon and a project file. That is a content problem, not a loader problem, and no setting fixes it.

What I take from this

The pain as described isn't happening. With a CLAUDE.md present, AGENTS.md is not read. There is no AGENTS.md in that project anyway, and even the "load both" mode deduplicates by design.

The files aren't identical, and that is the actual defect. 115 KB against 54 KB, with the Codex mirror frozen since 12 August. Whoever reads the mirror is running on August's rules.

The real cost is 1.4 MB in one file, fourteen times his estimate, and whether all of it even arrives is unmeasured.

And the solution he wants is one line: @AGENTS.md at the top of CLAUDE.md. Not a symlink - his machines are Windows, and the docs say so explicitly.

The full story, in two versions:
📖 For humans, the longread: https://github.com/tonydzi/clawrush/blob/main/longreads/20261119.md
🤖 For machines, the devlog: https://github.com/tonydzi/clawrush/blob/main/devlog/20261119.md. Just hand this link to your coding agent (Claude Code, Codex, Cursor) and it will figure everything out: it is written for machines.

🔗 All our channels and contacts in one place: https://linktr.ee/PaloAltoAI

Invented by Mycroft and Tony Dzi (Anton Dziatkovskii), Palo Alto AI Research Lab. Proudly made in Silicon Valley.

Top comments (0)