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

> Source: <https://dev.to/cryptopunk_dz2_bd054446a6/no-claudemd-and-agentsmd-do-not-load-twice-the-docs-say-why-1j5b>
> Published: 2026-11-19 16:41:16+00:00

**Recommendation:** Audit your instruction files' actual sizes and modification dates before optimizing context; consolidate drifted copies into one canonical file and measure whether large CLAUDE.md files are truncated.
More in the playbook "Controlling LLM cost": <https://wpnews.pro/playbooks/llm-cost>

**"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.
```

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:

`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" } } } }
```

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](https://github.com/tonydzi/clawrush/blob/main/longreads/20261119.md)

🤖 For machines, the devlog: [https://github.com/tonydzi/clawrush/blob/main/devlog/20261119.md](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](https://linktr.ee/PaloAltoAI)

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