{"slug": "no-claude-md-and-agents-md-do-not-load-twice-the-docs-say-why", "title": "No, CLAUDE.md and AGENTS.md do not load twice. The docs say why", "summary": "A developer's investigation into claims that CLAUDE.md and AGENTS.md load twice found the opposite: Anthropic's memory documentation states that when both files exist, Claude reads only CLAUDE.md, and an opt-in setting explicitly skips an AGENTS.md already loaded via import or symlink. Measuring the actual files revealed nine unsymlinked instruction files, including a Codex AGENTS.md less than half the size of the Claude canon and untouched since 12 August, plus a project CLAUDE.md of 1.4 MB — fourteen times the assumed 100 KB — with truncation behavior above 401 KB still unmeasured.", "body_md": "**\"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**\n\nThe 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?\n\nThe solution exists and is documented. But first, three measurements, because every premise in the question turns out to be wrong in a different direction.\n\n**⭐⭐⭐⭐⭐ The double read does not happen. Claude's own documentation says so in a table**\n\nFrom the official memory docs:\n\n| Your repository has | Claude reads | \n|---|---|\n| An `AGENTS.md` , and no`CLAUDE.md` above it | Your `AGENTS.md` | \n| An `AGENTS.md`**and** a` CLAUDE.md` | **Your `CLAUDE.md` files only** | \n| A `CLAUDE.md` that imports`AGENTS.md` | `CLAUDE.md` , with`AGENTS.md` through the import | \n\nRow two is his case. **When both files exist, AGENTS.md is not read at all.**\n\nAnd 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.\n\n⭐ 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.\n\n**⭐⭐⭐⭐⭐ The files are not identical either. They are 115 KB, 54 KB and 11 KB**\n\n\"My instructions are the same for CLAUDE.md as for AGENTS.md\" - measured right now, they are not:\n\n| file | size | last modified | \n|---|---|---|\n| `~/.claude/CLAUDE.md` | **115,434 B** | 2 October | \n| `~/.codex/AGENTS.md` | **54,009 B** | **12 August** | \n| `~/.claude/AGENTS.md` | 11,208 B | - | \n| `~/.claude/scripts/AGENTS.md` | 5,732 B | - | \n| vault `AGENTS.md` | 12,667 B | - | \n| vault `CLAUDE.md` | 343 B | - | \n| vault `GEMINI.md` | 386 B | - | \n\nThe 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).\n\nSo 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.\n\n**⭐⭐⭐⭐⭐ And the number that does matter: the project file is 1,474,604 bytes**\n\nHe estimates 100 KB per file. The actual project instruction file on this machine:\n\n|  | size | \n|---|---|\n| `D:\\!CLAUDE-NATALY-June26\\CLAUDE.md` | **1,474,604 B = 1.4 MB** | \n| his estimate | 100 KB | \n| ratio | **14x larger** | \n\nThe 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.\n\n⚠️ 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.\n\n**⭐⭐⭐⭐⭐ The elegant solution he asks for is one line, and it is in the docs**\n\n\"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:\n\n**The import.** Keep AGENTS.md as the single shared file and put one line at the top of CLAUDE.md next to it:\n\n```\n@AGENTS.md\n\n## Claude Code\nClaude-specific instructions go below the import.\n```\n\nClaude reads the imported file first, then the rest. Imports resolve recursively up to **four hops**, and relative paths resolve from the importing file.\n\n**The symlink** - `ln -s AGENTS.md CLAUDE.md` - also works, and the docs warn against it on his setup twice over:\n\n`core.symlinks` is on - leaving that clone with a one-line CLAUDE.md instead of the instructions\nHis fleet is Windows-heavy. So: **import, not symlink.**\n\nAnd 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`:\n\n```\n{ \"pluginConfigs\": { \"cc-plugin-agents-md@builtin\": { \"options\": { \"instructionFiles\": \"claude-md-and-agents-md\" } } } }\n```\n\nOther values: `claude-md` (ignore AGENTS.md entirely), `managed-only` (organization canon plus auto memory only), and the default `claude-md-or-agents-md`.\n\nVerification is one command: **`/context all`**, and CLAUDE.md should appear under **Memory files**.\n\n**⚠️ One more thing the docs settle, since it was never asked**\n\n`~/.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.\n\nWhich 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.\n\n**What I take from this**\n\n**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.\n\n**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.\n\n**The real cost is 1.4 MB in one file**, fourteen times his estimate, and whether all of it even arrives is unmeasured.\n\n**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.\n\nThe full story, in two versions:\n\n📖 For humans, the longread: [https://github.com/tonydzi/clawrush/blob/main/longreads/20261119.md](https://github.com/tonydzi/clawrush/blob/main/longreads/20261119.md)\n\n🤖 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.\n\n🔗 All our channels and contacts in one place: [https://linktr.ee/PaloAltoAI](https://linktr.ee/PaloAltoAI)\n\nInvented by Mycroft and Tony Dzi (Anton Dziatkovskii), Palo Alto AI Research Lab. Proudly made in Silicon Valley.", "url": "https://wpnews.pro/news/no-claude-md-and-agents-md-do-not-load-twice-the-docs-say-why", "canonical_source": "https://dev.to/cryptopunk_dz2_bd054446a6/no-claudemd-and-agentsmd-do-not-load-twice-the-docs-say-why-1j5b", "published_at": "2026-11-19 16:41:16+00:00", "updated_at": "2026-11-19 16:44:16.732183+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "developer-tools", "large-language-models"], "entities": ["Anthropic", "Claude", "Claude Code", "Codex", "Grok", "Antigravity"], "also_reported_by": [], "takeaway": "When both CLAUDE.md and AGENTS.md exist, Claude reads only CLAUDE.md, and the real cost is file size — the measured project CLAUDE.md was 1.4 MB, 14x the assumed 100 KB, with truncation above 401 KB unverified.", "recommendation": {"advice": "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.", "playbook": "llm-cost", "playbook_url": "https://wpnews.pro/playbooks/llm-cost"}, "alternates": {"html": "https://wpnews.pro/news/no-claude-md-and-agents-md-do-not-load-twice-the-docs-say-why", "markdown": "https://wpnews.pro/news/no-claude-md-and-agents-md-do-not-load-twice-the-docs-say-why.md", "text": "https://wpnews.pro/news/no-claude-md-and-agents-md-do-not-load-twice-the-docs-say-why.txt", "jsonld": "https://wpnews.pro/news/no-claude-md-and-agents-md-do-not-load-twice-the-docs-say-why.jsonld"}}