CLAUDE.md vs AGENTS.md: which one Claude Code reads, and why I keep only one

When a repository has both files, Claude Code reads CLAUDE.md and leaves AGENTS.md alone unless you import it. I found five of my repositories set up the wrong way round: the real instructions in AGENTS.md, and a CLAUDE.md that only pointed at it.

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.md line. Claude Code reads CLAUDE.md, and the import pulls AGENTS.md in with it.
  • Your personal ~/.claude/CLAUDE.md loads 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-md loads both.
  • Hooks that watch instruction loading. An InstructionsLoaded hook 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.md import in a CLAUDE.md works everywhere.

What I would do in your place

  1. Only Claude Code? Keep CLAUDE.md, under 200 lines. You do not need AGENTS.md.
  2. Several tools? Keep one real file and make the other name a symlink, or put @AGENTS.md in a short CLAUDE.md that adds only the Claude-specific lines.
  3. Never "see AGENTS.md" in words. Replace it with the import, or delete the CLAUDE.md so Claude reads AGENTS.md directly.
  4. 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.
  5. 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.

More posts

All posts →
  1. 21 Nov 2026

    Same agent, rebuilt workspace, a quarter of the bill: what EnvOpt showsA new arXiv paper leaves the model and the harness alone and lets another AI rebuild the workspace the agent works in. On 200 test tasks, the same Claude Haiku 4.5 agent cost $42.36 before and $11.55 after, and passed more tasks.

    AI · 7 min
  2. 20 Nov 2026

    Running several Claude Code agents at once: worktrees, handoffs and one check per phaseWhat broke when I put many Claude Code agents on the same repositories, and the four rules that stayed: one worktree per agent, small file-disjoint jobs, a rewritten handoff, and one full check per phase.

    How I build · 5 min
  3. 20 Nov 2026

    Your agent finished the task. Did every step work? What prefix executability showsA new arXiv paper replays every tool call an agent made and marks the first one that could not run. On 200 function-calling tasks, one agent finished 94 % of them, yet only 47 % of its runs ran clean from start to end.

    AI · 5 min