CLAUDE.md vs AGENTS.md: what Claude Code loads, in 11 setups and 7 versions

Search "CLAUDE.md vs AGENTS.md" today and the first page cannot agree with itself. Some pages say Claude Code ignores AGENTS.md, so you need a symlink or an import. Others say it reads AGENTS.md now. The search engine's own summary says the sources disagree.

Both camps are right, about different versions. So we stopped asking pages and asked Claude Code.

How we checked

/context is a command built into Claude Code. It prints a table of the Memory Files it put into the session, with their paths. It runs locally, makes no model call, and does not care whether you are logged in. So claude -p "/context" tells you which instruction files load, without asking a model and trusting its answer.

We built 11 throwaway repositories, each with a different mix of CLAUDE.md, AGENTS.md, CLAUDE.local.md and .claude/ files. Then we ran /context in each one on 7 versions of Claude Code, from 2.1.123 to 2.1.295. We ran it in a clean environment with MCP servers off, then ran it all again. Both runs matched byte for byte. The script is in this site's repository.

The answer, by version

On 2.1.123 and 2.1.276, Claude Code reads CLAUDE.md only. An AGENTS.md on its own loads nothing. The changelog dates AGENTS.md support to 2.1.277, so that holds for every version before it. The pages that say "Claude Code doesn't read your AGENTS.md" describe this.

From 2.1.277, the changelog says it reads AGENTS.md when there is no CLAUDE.md. In our runs it did not load until 2.1.280. On 2.1.277 and 2.1.278, AGENTS.md alone still loaded nothing. 2.1.279 was never published. On 2.1.280, 2.1.281 and 2.1.295 it loaded.

That gap matches something the documentation admits. Before 2.1.281 some sessions read CLAUDE.md only, "such as those on Amazon Bedrock or with telemetry disabled". Ours were neither. They were -p sessions on a machine whose login had expired. We cannot tell you which condition switched it off. What we can say is that "2.1.277 or later" is not enough to guarantee it.

So check your version first:

claude --version

The machine we ran this on had 2.1.123 installed, from May. Whatever a blog says Claude Code does today, that copy was not doing it.

What loads, file by file

On a version that reads AGENTS.md, the rule is simple and strict. Claude Code reads AGENTS.md only if no CLAUDE-family file exists where you start the session, or in any directory above it.

Every row from "CLAUDE.md and AGENTS.md" down gave the same result on all 7 versions, old and new.

Three of these will catch people:

CLAUDE.local.md switches AGENTS.md off. It is the file you create for your own uncommitted notes. Add one to a repository that relies on AGENTS.md and, for you only, the team's instructions stop loading. Nothing warns you.

A CLAUDE.md higher up does the same. In a monorepo with a CLAUDE.md at the root, a package's AGENTS.md is not read when you start the session inside that package.

A nested AGENTS.md is not read at start. The documentation says it loads once Claude reads a file in that directory. We only measured session start, so we did not see that happen.

The setting that changes the rule

The rule is configurable. Run /config and set Project instructions, or put it in ~/.claude/settings.json. The documentation gives this ID from 2.1.285 on; earlier versions read the same entry under agents-md@builtin:

{
  "pluginConfigs": {
    "cc-plugin-agents-md@builtin": {
      "options": { "instructionFiles": "claude-md-and-agents-md" }
    }
  }
}

We passed it with --settings on 2.1.295. With claude-md-and-agents-md, both files loaded side by side, and CLAUDE.local.md no longer pushed AGENTS.md out. When CLAUDE.md also imported AGENTS.md, it still loaded once. With claude-md, an AGENTS.md on its own loaded nothing again.

The documentation says this key is ignored in a project's own settings files. It has to live in your user settings or be managed. So it fixes the problem for you. It does not fix it for a teammate.

So which one should you write?

If the people and agents on your project use only Claude Code, CLAUDE.md is read by every version we tested and needs nothing else.

If the project also serves other agents that read AGENTS.md, keep the instructions in AGENTS.md. Then add a CLAUDE.md whose first line is:

@AGENTS.md

That import loaded AGENTS.md on all 7 versions, including the old one. It does not depend on the default, the setting or the session type, and it gives you a place for Claude-only rules below the import. A symlink worked on every version too. It just leaves you nowhere to put those extra rules.

Reading AGENTS.md directly is the cleanest setup when it works. But it works only when nobody on the team has an older version, a CLAUDE.local.md or a CLAUDE.md higher up. The import works in all of those cases.

What this does not cover

• Which files are loaded, not whether the model then follows them. That is a different question, and we wrote it up separately
• Session start only, in -p mode, on one macOS machine whose login had expired. Interactive sessions and logged-in machines may pass the gate that 2.1.277 and 2.1.278 did not pass here
• No ~/.claude/CLAUDE.md, managed settings or .claude/rules/. The documentation says none of them count against AGENTS.md. We did not test that
• No other coding agent was tested reading CLAUDE.md