C² Method6 min read
AGENTS.md vs CLAUDE.md: what Claude Code actually loads (tested)
Six folders, six marker words, one question to the CLI each. Which file Claude Code reads when you have AGENTS.md, CLAUDE.md, both, an import, a symlink or a local file.
If your repo has both an AGENTS.md and a CLAUDE.md, Claude Code reads the CLAUDE.md and ignores the AGENTS.md. If it has only an AGENTS.md, Claude Code reads that. If your CLAUDE.md contains the line @AGENTS.md, it reads both. That is what Anthropic's docs say, and it's what I got when I tested it on 20 November 2026 with Claude Code 2.1.329.
The surprise is a fourth case. Add a personal CLAUDE.local.md to a repo that relies on AGENTS.md, and Claude Code quietly stops reading the AGENTS.md.
This is the head-to-head and the test. For what to put in the file, see how to write an AGENTS.md that agents actually follow. For why a loaded file still gets ignored, see why Claude Code ignores your CLAUDE.md.
Does Claude Code read AGENTS.md?
Yes, since version 2.1.277. The memory docs give the rule. By default Claude reads AGENTS.md only when there's no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in your working directory or any directory above it. Your personal ~/.claude/CLAUDE.md, an organisation's managed CLAUDE.md and .claude/rules/ files don't count for that check. They load alongside AGENTS.md.
The default is called claude-md-or-agents-md. You can change it with Project instructions in /config:
| Setting | What loads |
|---|---|
claude-md-or-agents-md (default) | CLAUDE.md files, or AGENTS.md when there's no CLAUDE.md or CLAUDE.local.md |
claude-md-and-agents-md | Both, each directory's CLAUDE.md first, then its AGENTS.md |
claude-md | CLAUDE.md only |
managed-only | Only the organisation's managed CLAUDE.md and auto memory |
The docs say this setting is read from your user settings, a --settings file or managed settings. A project's .claude/settings.json can't set it. So you can't commit "read both" for your team. Each person chooses.
The test: six folders, six marker words
I wanted the behaviour from the CLI, not from a description. Each folder got a fresh git init and instruction files containing a single unique marker word. Then one non-interactive call per folder:
claude -p "Reply with only the marker words from your project instructions, or NONE" \
--max-turns 1 --tools "" --no-session-persistence --strict-mcp-config
--tools "" turns off every built-in tool, so Claude can't go and open a file. Whatever it reports had to be in its context at startup. One call per folder, six calls in total.
| Folder | Files | Reply |
|---|---|---|
| 1 | AGENTS.md (HERON) | HERON |
| 2 | CLAUDE.md (OTTER) | OTTER |
| 3 | AGENTS.md (FALCON) + CLAUDE.md (BADGER) | BADGER |
| 4 | AGENTS.md (WALRUS) + CLAUDE.md containing @AGENTS.md then LYNX | WALRUS, LYNX |
| 5 | AGENTS.md (MARMOT) + CLAUDE.local.md (QUOKKA) | QUOKKA |
| 6 | AGENTS.md (PELICAN) + CLAUDE.md as a symlink to it | PELICAN |
Claude Code 2.1.329, macOS, 20 November 2026. Every result matches the docs.
- Folder 3 is the one that catches people. Both files present, and FALCON never arrives. If you added a
CLAUDE.mdto a repo that already had anAGENTS.md, Claude Code has been reading only one of them. - Folder 4 shows the import order. The imported file comes first, then the rest of the
CLAUDE.md. That's the documented behaviour and it's what came back. - Folder 5 is the trap.
CLAUDE.local.mdis meant for your private, uncommitted notes. But it counts as a CLAUDE file, so its presence switches theAGENTS.mdoff for you. Your teammates still get it. You don't. The docs flag this and suggestclaude-md-and-agents-mdif you want both. - Folder 6 loaded the content once, not twice.
One thing went wrong first, and it's worth knowing. My first run used folders under Claude Code's own per-session scratchpad, in its temp directory. Every folder answered NONE, including the one with only a CLAUDE.md. Same files copied to an ordinary folder under /tmp, and they loaded. The docs don't explain it and I haven't dug further. If you repeat this test, run it in a normal directory, and check that no parent directory holds a CLAUDE.md or AGENTS.md of its own.
AGENTS.md vs CLAUDE.md: the differences that matter
AGENTS.md | CLAUDE.md | |
|---|---|---|
| Who reads it | 20+ coding agents, plus Claude Code since 2.1.277 | Claude Code |
| Loaded when the other is present | Not by default in Claude Code | Always |
@path imports | Expanded by Claude Code | Expanded |
| Personal variant | AGENTS.local.md is not read by Claude Code | CLAUDE.local.md |
InstructionsLoaded hooks | Don't fire when read directly | Fire |
| Subdirectory files | Loaded when Claude reads a file there, if that folder has no CLAUDE file | Loaded when Claude touches that folder |
The docs also say Claude Code doesn't read AGENTS.override.md or anything under a .agents/ directory. If another tool in your stack relies on those, Claude won't see them.
Which other tools read AGENTS.md?
The AGENTS.md site lists Codex, Jules, Factory, Aider, goose, opencode, Zed, Warp, VS Code, Devin, UiPath's coding agents, Junie, Amp, Cursor, RooCode, Gemini CLI, Kilo Code, Phoenix, Semgrep, GitHub Copilot's coding agent, Ona, Windsurf and Augment Code. It says the format is used by over 60,000 open-source projects, and that it's now stewarded by the Agentic AI Foundation under the Linux Foundation. For monorepos, its guidance is that the nearest AGENTS.md in the directory tree wins, and an explicit instruction in chat overrides everything.
Two details from the site. It shows Gemini CLI being pointed at AGENTS.md through .gemini/settings.json, so that one needs configuring. And Claude Code isn't on the site's list at the time of writing, even though Anthropic's own docs say it reads the file. Trust each tool's own docs over a list.
Last checked: 20 November 2026.
Should I use AGENTS.md or CLAUDE.md?
My rule:
- Only Claude Code touches the repo: a
CLAUDE.mdis enough. - More than one agent touches it, or might: put the shared instructions in
AGENTS.md. If Claude needs anything extra, add aCLAUDE.mdwhose first line is@AGENTS.md, with the Claude-only lines below. - You keep a
CLAUDE.local.md: know that it switches off directAGENTS.mdloading for you. The@AGENTS.mdimport in a committedCLAUDE.mdsidesteps that: per the docs, an import is part of theCLAUDE.md, so it loads whenever theCLAUDE.mddoes.
I prefer the import to the symlink. The docs list two catches with symlinks: Claude's Edit and Write tools refuse to write through one, and a committed symlink can check out on Windows as a one-line text file. The import has neither problem and leaves room for Claude-specific lines.
What C² does by default
The C² starter kit, which I built, ships its router as AGENTS.md by default, the cross-agent name. Its README says to use CLAUDE.md for Claude Code or GEMINI.md for Gemini, and to name the file for your agent so it's read automatically rather than relying on a rename.
My own monorepo predates all of this and uses a CLAUDE.md: a 404-line router with no AGENTS.md beside it. That's fine for a repo where Claude Code is the agent. For a new repo I'd now start with AGENTS.md plus a two-line CLAUDE.md that imports it. Claude Code can read AGENTS.md directly, so the C² default works with it out of the box, as long as nothing else on the path is called CLAUDE.
The filename is the least important decision here. A router is a router: invariants first, pointers instead of paragraphs, everything else in the contextbase. More on that in C² vs native rule files.
How do I check which file Claude Code loaded?
- Run
/memory. The docs say it lists the instruction files loaded, including anAGENTS.mdread directly, from version 2.1.280. - Run
/context alland look under Memory files. - In an interactive session with only an
AGENTS.md, the docs say you'll see a line such asno CLAUDE.md found; AGENTS.md loaded. - Or do what I did: put a marker word in each file and ask.
Start here: how to write an AGENTS.md that agents actually follow, why Claude Code ignores your CLAUDE.md, or run your first C² session.
Questions people ask
- Does Claude Code read AGENTS.md?
- Yes, from version 2.1.277. By default it reads AGENTS.md only when there is no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in your working directory or any directory above it. Your personal ~/.claude/CLAUDE.md doesn't count. I confirmed the behaviour with Claude Code 2.1.329 on 20 November 2026.
- What happens if a repo has both AGENTS.md and CLAUDE.md?
- By default Claude Code reads CLAUDE.md only and ignores AGENTS.md. In my test, the folder with both files returned only the CLAUDE.md marker word. To load both, import AGENTS.md from CLAUDE.md with an @AGENTS.md line, or set Project instructions to claude-md-and-agents-md in /config.
- Should I use AGENTS.md or CLAUDE.md?
- If more than one coding agent works in the repo, keep the shared instructions in AGENTS.md, which over twenty tools read. If you need Claude-specific lines, add a CLAUDE.md that starts with @AGENTS.md and put them below it. If only Claude Code is used, a CLAUDE.md alone is fine.
- Can I symlink CLAUDE.md to AGENTS.md?
- Yes. In my test a CLAUDE.md symlinked to AGENTS.md loaded the AGENTS.md content once. The docs note two catches: Claude's Edit and Write tools refuse to write through a symlink, and on Windows a committed symlink can check out as a one-line text file. The @AGENTS.md import avoids both.
- Why is Claude Code ignoring my AGENTS.md?
- Usually because a CLAUDE.md or CLAUDE.local.md exists in the working directory or a parent, which makes Claude Code read that instead. Also check your version is 2.1.277 or later and that Project instructions in /config isn't set to claude-md. Run /memory to see whether the AGENTS.md path is listed.
Part of the C² Method. Start with the method
Put this in your repo
The C² Method is free and open. Point your agent at the kit and get started in minutes.