AGENTS.md vs CLAUDE.md: Claude Code reads both now, just not at once.

Two files, one job: tell a coding agent about your repo. For a year the answer to "which one?" was simple. Claude Code read CLAUDE.md. Almost everything else read AGENTS.md. If you used both kinds of tool, you kept two files and watched them drift apart.

On 18 September that changed. Claude Code 2.1.277 started reading AGENTS.md natively. Some of the top results for this question still say it doesn't.

Claude Code reads AGENTS.md now. But only when there's no CLAUDE.md, and a single CLAUDE.local.md switches it off.

Here's the current picture, the one setup that works on every version, and the part none of the comparison posts measure: what the file costs you on every turn, and what's missing from it.

The short answer

From Anthropic's memory docs, as of today:

• Claude Code reads AGENTS.md only when there's no CLAUDE.md. That means no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in the folder you're working in or any folder above it. Your personal ~/.claude/CLAUDE.md doesn't count, so that still loads alongside.

• The trap. Add a CLAUDE.local.md for your own notes and your team's AGENTS.md quietly stops loading. Nothing tells you.

• You can change the rule. In /config, "Project instructions" can be set to read either file (the default), both, or only CLAUDE.md.

• Nearly everything else reads AGENTS.md. Codex, Cursor, Copilot, Jules, Amp, Windsurf, Zed and more, per the list at agents.md. Gemini CLI is the odd one out: it reads GEMINI.md unless you point it elsewhere.

One more thing to check before any of that applies to you:

$ claude --version
2.1.257 (Claude Code)

That's the CLI on my own machine. It's older than 2.1.277, so here an AGENTS.md on its own would be invisible to Claude Code, whatever the docs say. If your team updates at different speeds, some of you are reading the file and some aren't.

Which one should you use?

Only Claude Code touches the repo? Keep CLAUDE.md. There's no AGENTS.md in this website's repo, because Claude Code is the only agent that works on it. A second file would be a second thing to keep true.

Several tools, or a team on mixed versions? Make AGENTS.md the one real file, and make CLAUDE.md a single line:

@AGENTS.md

That's the setup Anthropic's docs recommend. Claude Code pulls the file in and never loads it twice, and it works on old versions too, because it doesn't depend on the new support at all. Two details that trip people up: an import inside a code fence is silently ignored, and on Windows a symlink instead of an import needs admin rights or Developer Mode, and Claude's own edit tools refuse to write through one.

What not to do is keep two hand-maintained copies. On the long-running GitHub issue asking for AGENTS.md support, it's a recurring complaint: the copies drift, and each agent ends up following different rules.

What the file costs you

Whichever file you pick, it's read at the start of every session and then sent again on every turn, like everything else in the conversation. So its size isn't a one-off. Here's this repo's CLAUDE.md, checked by a small linter:

$ npx -y github:manpreet171/bridle agents CLAUDE.md
Linting CLAUDE.md

  ✔ 2 runnable command block(s)
  ✘ does not say how to install / set up
  ✘ does not say how to run the tests
  ✔ how to build or run it
  ! 3 angle-bracket field(s), e.g. <slug> — check these are argument syntax, not unfilled template text
  ✔ nothing in here tells the agent to do something dangerous
  ✔ 12 prohibition(s) — the agent knows where the edges are
  ✔ size: 916 words ≈ 1474 tokens, re-sent every turn

FAIL — 2 problem(s). Your agent is reading this file on every run.

The two failures don't apply here: it's a static site with no install step and no test suite. A general linter checks for a general project, so read it as a list of questions, not a verdict.

The size line is the one that matters. About 1,500 tokens, on every turn. This project has run about 9,300 turns of Claude Code, so this one file accounts for roughly 14 million tokens, sent at the cheaper cached rate. That's an estimate, but the shape isn't. I measured where the rest of a session's tokens go in a separate post.

Does a longer file make the agent worse at following it? Anthropic's memory docs say to aim for under 200 lines, and its best-practices guide warns that bloated files get ignored. The research is more mixed. An ETH Zurich study found files written by people raised success rates slightly, files generated by an AI lowered them, and both added roughly 20% to cost. A study of 1,650 Claude Code sessions found no measurable effect of length on following one simple rule. Length isn't proven to hurt. It is proven to cost.

What's missing from it

A file can be long and still not say the thing you actually need it to. Here's the same project from the other direction: not what the file says, but what I keep typing to the AI because the file doesn't say it.

$ npx -y toldya --dry
toldya · 13 sessions (1 Aug – 5 Oct) · 975 of your messages · 58 corrections

You keep telling your AI:
   1.   7×  keep it simple   (6 sessions)
   2.   3×  Don't confuse me   (3 sessions)

And 8 times you told it to try or check again: its first go missed.

916 words of rules, and neither line is in there. The two corrections I gave most often in this repo had never been written down, so every new session started without them and I typed them again.

That's the real answer to "which file?". The name decides which tools read it. What's in it decides whether it was worth reading.

What belongs in it

• What it can't work out on its own. The odd build command, the folder that looks unused but isn't, the deploy that happens on push.

• The edges. What it must never touch, and what needs a person. Those are the lines that prevent damage.

• What you keep correcting. If you've typed it three times, it's a rule. Write it in your own words.

• Not documentation. Explaining the codebase is what the code is for. Every paragraph the agent could have read in the repo is a paragraph you pay for on every turn.

• Not generated filler. The ETH study's sharpest finding was that AI-written context files made results worse. Write it yourself, briefly.

Check your own

$ claude --version                             # 2.1.277 or later to read AGENTS.md
$ npx -y github:manpreet171/bridle agents CLAUDE.md   # or AGENTS.md
$ npx -y toldya --dry                          # what you keep repeating

Both tools are free, read only your own files, and change nothing unless you say yes. bridle reads the instruction file; toldya reads your Claude Code history.

This is how we set agents up for clients. One short file that says what the agent can't guess and where the edges are, checked against what people actually keep correcting. Not a template, and never a generated one.

Sources: every terminal block is a real run in this website's repo on 5 Oct 2026, the toldya one trimmed by one line (a link). Loading rules are from Anthropic's memory docs and the Claude Code changelog for 2.1.277. Tool support is from agents.md. The studies are arXiv 2602.11988 and arXiv 2605.10039.

Read next: The best CLAUDE.md rules are hiding in your chat history · Where your Claude Code tokens actually go. Output is 0.2%.

Originally published at singhlabs.dev.