AGENTS.md vs CLAUDE.md: which one does Claude Code actually read?

The rule, exactly

Anthropic's documentation states it plainly: Claude reads AGENTS.md only when you have no CLAUDE.md in your working directory or above it. Not "in addition to". Instead of.

Which files trigger that check is specific, and the distinction matters more than it looks:

• These suppress AGENTS.md — a CLAUDE.md, a .claude/CLAUDE.md, or a CLAUDE.local.md, in your working directory or any directory above it.
• These do not — your personal ~/.claude/CLAUDE.md, your organisation's managed CLAUDE.md, and .claude/rules/ files. Those keep loading alongside AGENTS.md.

So a personal global CLAUDE.md in your home directory is harmless. A CLAUDE.md anywhere on the project path is not — it takes over, and nothing warns you.

The trap that catches teams

`CLAUDE.local.md` counts. It is the file people are told to use for personal, uncommitted instructions — the one that is gitignored precisely so it does not affect anyone else.

Adding one to a project that relies on AGENTS.md stops Claude reading AGENTS.md for you, and only for you. Nothing errors. Your colleagues' agents keep following the shared conventions; yours quietly stops. You spend a week assuming the instructions are being ignored, or worse, assuming they do not work.

If you want both — your own local file and the team's shared one — the fix is the setting below, not deleting anything.

How to make it read both

Run /config in a Claude Code session and set Project instructions, or set it in settings directly:

{
  "options": { "instructionFiles": "claude-md-and-agents-md" }
}

With that set, each directory's CLAUDE.md files load first and its AGENTS.md after them. An AGENTS.md that a CLAUDE.md already imports or symlinks to is not read twice, so the import pattern below stays safe.

The other value worth knowing is claude-md, which loads your CLAUDE.md files only and ignores every AGENTS.md — useful if a dependency or vendored directory ships one you do not want.

What each format actually gives you

The mechanical difference is breadth against depth, and it is worth being concrete rather than picking a side.

• AGENTS.md is the portable one. It is an open format stewarded by the Agentic AI Foundation under the Linux Foundation, read by around twenty-five tools including Cursor, VS Code, GitHub Copilot, Codex, Aider and Jules, across more than 60,000 open-source projects. It is plain Markdown with no schema — which is exactly why everything can read it.
• CLAUDE.md is the capable one. It gets @path imports, per-directory hierarchy, path-scoped rules in .claude/rules/, a user-level global file, a local override, and session behaviour settings. None of that is portable, because no other tool implements it.

Neither is a successor to the other. AGENTS.md is a convention several vendors agreed on; CLAUDE.md is one vendor's richer implementation. A team using only Claude Code loses nothing by using only CLAUDE.md. A team where two people use different editors loses the shared baseline the moment the conventions live in a file only one tool reads.

What we would do

This part is our recommendation rather than anything the documentation prescribes.

1. 01Put the real content in AGENTS.md — project overview, exact build and test commands, conventions, what must never be touched. Everything that is true regardless of which agent is reading.
2. 02Keep CLAUDE.md thin, and have it import the shared file rather than restate it. One source, no second copy to drift.
3. 03Put only genuinely Claude-specific guidance below the import — hook behaviour, subagent notes, anything that has no meaning in another tool.
4. 04If anyone on the team keeps a CLAUDE.local.md, set instructionFiles to claude-md-and-agents-md across the team so a personal file cannot silently detach someone from the shared conventions.

@AGENTS.md

# Claude-specific notes

Everything above applies to every agent. Only guidance that is
meaningless in another tool belongs below this line.

The import is what makes this work rather than merely look tidy: Claude Code expands @path imports inside these files, and skips an AGENTS.md it has already loaded through one. You get the shared baseline and the Claude-specific layer without maintaining the same rules twice.

What other tools do

Cursor reads both. Its documentation states that it reads CLAUDE.md files the same way it reads AGENTS.md — place either in the project root and Cursor picks it up automatically — and that CLAUDE.md files are always applied to every conversation regardless of any alwaysApply frontmatter, explicitly so that projects using Claude Code keep working.

That makes Cursor the permissive case and Claude Code the strict one, which is the opposite of what most people assume. If you test your setup only in Cursor, it will appear to work and then behave differently in Claude Code.

Everything else in the AGENTS.md ecosystem reads AGENTS.md and has no opinion about CLAUDE.md at all. Check your own tool's documentation before relying on any of this — vendor behaviour is the part of this subject that dates fastest.

If your AGENTS.md is being ignored

Anthropic's own troubleshooting names the usual cause: a CLAUDE.md somewhere on the project path. Work down this list before assuming anything is broken.

1. 01Look for the `no CLAUDE.md found; AGENTS.md loaded: …` line at session start. If it is absent, a CLAUDE.md won.
2. 02Check the working directory and every directory above it for CLAUDE.md, .claude/CLAUDE.md and CLAUDE.local.md — including your own gitignored one.
3. 03Check the Claude Code version. Reading AGENTS.md directly needs v2.1.277 or later.
4. 04Check the filename. AGENTS.local.md, AGENTS.override.md and anything under a .agents/ directory are not read at all.
5. 05If you want both files regardless, set instructionFiles to claude-md-and-agents-md and stop fighting the default.

That prompt settles it in one message. If the paths it names are not the ones you expected, you have your answer without reading a single doc.

Common questions