CLAUDE.md is the instruction file Claude Code reads. AGENTS.md is the open format that Codex, Cursor and several other coding agents read. If you only ever use one tool, the choice hardly matters. Once a repository has both files, it matters a lot, because the tools do not read each other's file the way you might expect.
I touched on this in CLAUDE.md, hooks, skills or the task. This post is about what I found when I looked at my own repositories, and the one rule I keep now.
What each tool reads
From the Claude Code docs, checked on 21 November 2026:
- Only AGENTS.md, no CLAUDE.md. Claude Code (version 2.1.277 or later) reads your AGENTS.md as the project instructions.
- Both files. Claude Code reads CLAUDE.md only. AGENTS.md is not loaded.
- A CLAUDE.md with an
@AGENTS.mdline. Claude Code reads CLAUDE.md, and the import pulls AGENTS.md in with it. - Your personal
~/.claude/CLAUDE.mdloads in every case, next to whichever project file wins.
Codex goes the other way. It looks for AGENTS.md (and an AGENTS.override.md) in each directory, and ignores CLAUDE.md unless you add it to its list of fallback file names.
So with two separate files, each tool reads only its own, and the two drift apart.
What I found in my own repositories
On 21 November I checked the repositories on my machine. Five had both files as two separate, real files. The pattern was the same in all five: a CLAUDE.md of 123 to 206 lines that said, in words, "see AGENTS.md for the full guidelines", and an AGENTS.md of 135 to 727 lines with the substance.
None of the five CLAUDE.md files had an @AGENTS.md import. A link in words is not an import. The docs say it plainly: with a CLAUDE.md that tells Claude to read AGENTS.md, "Claude sees AGENTS.md only if it decides to open the file". The longer, more detailed file was the one Claude Code did not load on its own.
Two more things came up:
- The files had drifted. In one repository the first lines of the two files described the product differently. Each had been edited by whoever happened to open it, and nobody compared them.
- One AGENTS.md was too long for Codex. Codex stops adding instruction files once their combined size reaches its limit, 32 KiB by default. One of my AGENTS.md files was 32,823 bytes on its own, so the end of it would not reach Codex either.
The rule I keep now
On 2 November I wrote down a docs standard for all my repositories. Two lines of it cover this:
- One instruction file, CLAUDE.md, under 150 lines. Anthropic's target is under 200; I keep a margin.
- AGENTS.md only as a symlink. If another tool needs the other name, it gets a link to the same file, never a second copy.
One of my repositories, which other agents work in as well, does it the other way round: AGENTS.md is the real file and CLAUDE.md is the symlink. With the default setting, Claude Code reads the content once either way. What matters is that there is one real file.
The five repositories above are not moved yet. The plan is the same for each: merge the two into one short file, move the long reference parts into docs pages it links to, and replace the other name with a symlink.
Why one short file and not two long ones
More instruction text is not free. A February 2026 study of AGENTS.md files on real tasks (arXiv 2602.11988) found that context files did not generally raise task success, while they raised inference cost by over 20 % on average. Instructions in them were followed; repository overviews were not helpful.
That matches what I see. The file is read on every step, so every line has to earn its place. What earns it: the exact test, type-check and lint commands, the traps the code does not show, and decisions that live nowhere else. The rest goes into docs pages that the agent opens when a task needs them. I wrote up the cost side in My CLAUDE.md, and the failure behind each rule.
Three traps from the docs
- A CLAUDE.local.md switches AGENTS.md off. If your project relies on AGENTS.md alone and you add a CLAUDE.local.md for your own notes, Claude Code counts it as a CLAUDE.md and stops reading AGENTS.md for you. The setting
claude-md-and-agents-mdloads both. - Hooks that watch instruction loading. An
InstructionsLoadedhook fires for CLAUDE.md, and for an AGENTS.md that CLAUDE.md imports or symlinks to, but not for an AGENTS.md that Claude reads directly through the setting. - Older versions and some sessions read CLAUDE.md only. Before 2.1.277, or with the built-in AGENTS.md plugin switched off, AGENTS.md is not read directly at all. An
@AGENTS.mdimport in a CLAUDE.md works everywhere.
What I would do in your place
- Only Claude Code? Keep CLAUDE.md, under 200 lines. You do not need AGENTS.md.
- Several tools? Keep one real file and make the other name a symlink, or put
@AGENTS.mdin a short CLAUDE.md that adds only the Claude-specific lines. - Never "see AGENTS.md" in words. Replace it with the import, or delete the CLAUDE.md so Claude reads AGENTS.md directly.
- Check the size. Under 200 lines for Claude Code, under 32 KiB in total for Codex by default. Long reference text belongs in docs pages.
- Put the rules that must hold in a check. Either file is context, not enforcement. A rule that must hold every time belongs in a hook; mine are in Claude Code hooks: run each one in warn mode for a week first.
If you run several agents at once, the same file is read by every one of them. More on that set-up in Running several Claude Code agents at once.