Manpreet Singh

Posted on Oct 5 Edited on Oct 16 Originally published at singhlabs.dev AI-assisted

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

#claude #ai #productivity #devtools

AGENTS.md is a plain Markdown file in your repo that tells AI coding agents how to work on it. CLAUDE.md is Claude Code's own version.

Two files, one job. 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.

Does AGENTS.md work with Claude Code?

Yes, from version 2.1.277, as long as no CLAUDE.md is in the way. The rules, 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.
Telemetry off? Update. Before 2.1.281, sessions with telemetry disabled, or on Bedrock, Vertex or an LLM gateway, skipped AGENTS.md without a word (issue #95690). 2.1.281 fixed it, per the changelog. The docs add one more: the first session after upgrading from 2.1.276 or earlier can skip it too.
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 (I priced what each line costs), 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 · 15 sessions (1 Aug – 9 Oct) · 727 of your messages · 44 corrections

You keep telling your AI:
   1.   3×  keep it simple   (3 sessions)

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

916 words of rules, and that line isn't in there. The correction I gave most often in this repo had never been written down, so every new session started without it and I typed it 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.

AGENTS.md vs SKILL.md

Different jobs. AGENTS.md holds facts the agent needs on every turn, and you pay for them on every turn. A skill is a folder with a SKILL.md in it: a procedure that loads only when the job comes up. Until then, only its name and description ride along.

Anthropic's skills docs draw the line: make a skill when a section of CLAUDE.md "has grown into a procedure rather than a fact." The deploy happens on push: a fact, so it goes in the file. The steps of a release: a skill.

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.

Sources: every terminal block is a real run in this website's repo on 5 Oct 2026, except toldya's: re-run on 9 Oct with 0.3.5 (0.3.3 stopped counting resumed sessions twice, 0.3.4 fixed how it groups rewordings, 0.3.5 skips "I don't get it"). Loading rules are from Anthropic's memory docs and the Claude Code changelog for 2.1.277 and 2.1.281; the telemetry bug is from issue #95690. Skills are from Anthropic's skills docs. Tool support is from agents.md. The studies are arXiv 2602.11988 and arXiv 2605.10039.

Where this fits: memory and context, layer 2 of the Agent Ops Stack.

Originally published at singhlabs.dev.

DEV Community