Reference · Intermediate · 10 min

AGENTS.md vs CLAUDE.md in Claude Code: which one it reads

Since 2.1.277 Claude Code reads AGENTS.md when there's no CLAUDE.md. What it reads in each case, the CLAUDE.local.md trap and one file for all AI tools.

Tested with Claude Code 2.1.316 · reviewed 2026-11-01

See the files on GitHub Free · MIT license

Summary

Since 2.1.277 (18 Sep 2026) Claude Code reads AGENTS.md, the instructions file used by Codex, Cursor and other agents, when the project has no CLAUDE.md. If you have both, by default it only reads CLAUDE.md, and a personal CLAUDE.local.md is enough for it to ignore AGENTS.md.

This reference explains what it reads in each combination, how to change it in /config > Project instructions, how to keep a single file for all your AI tools, how to migrate from Codex or Cursor and how to check what was loaded. To write a good CLAUDE.md, see the CLAUDE.md that works recipe.

What changed and what Claude reads depending on your files

AGENTS.md is a project instructions file shared by several coding agents. Asking for Claude Code to read it was the most upvoted issue in its history (#6235, 6,689 reactions) and it arrived in 2.1.277: "in a project without CLAUDE.md, Claude Code reads AGENTS.md instead". The default rule, according to the official docs:

What counts for that check: CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in your folder or any parent. What doesn't count and still loads alongside AGENTS.md: your ~/.claude/CLAUDE.md, your organization's managed CLAUDE.md and the files in .claude/rules/. You need 2.1.277 or later; check yours with claude --version.

The CLAUDE.local.md trap

Many teams keep AGENTS.md in git and each person adds a CLAUDE.local.md for private notes (test URLs, sample data). Since CLAUDE.local.md counts as a CLAUDE.md, as soon as you create it Claude stops reading the team's AGENTS.md, without warning you.

We checked it with an AGENTS.md giving a project keyword: with nothing else, Claude answered with the keyword; after creating a one-line CLAUDE.local.md, it answered "none". This is the test, to repeat it in a scratch folder with a cheap model (the repository's en/test-agents.sh runs the same three cases):

# Reproducible test (in a scratch folder, with a cheap model)
mkdir -p /tmp/test-agents && cd /tmp/test-agents && git init -q
printf '# Project rules\nThe project keyword is APPLE.\n' > AGENTS.md
P="Reply only with the project keyword according to your project instructions, or NONE if you have none."

# 1) Only AGENTS.md → it reads it
claude -p --model haiku "$P"            # APPLE

# 2) Add a CLAUDE.local.md → it stops reading AGENTS.md
echo 'I prefer short answers.' > CLAUDE.local.md
claude -p --model haiku "$P"            # NONE

# 3) Remove the local file and create a CLAUDE.md that imports it → it reads it again
rm CLAUDE.local.md
printf '@AGENTS.md\n\n## Claude Code\nUse plan mode for big changes.\n' > CLAUDE.md
claude -p --model haiku "$P"            # APPLE

There are two ways out. The first: set Project instructions to claude-md-and-agents-md (next section), which loads both. The second: import AGENTS.md from your local file or from a project CLAUDE.md with @AGENTS.md.

The same happens if someone commits a CLAUDE.md to the repo or if there's one in a parent folder (for example, in your general work folder): Claude looks for CLAUDE.md, .claude/CLAUDE.md and CLAUDE.local.md along the whole path up to the root, except the one in ~/.claude/.

/config > Project instructions: the four values

Type /config in a session and look for Project instructions:

The change applies from your next message and in every new session. You can also set it in a file: in pluginConfigs, under cc-plugin-agents-md@builtin (the built-in plugin that reads AGENTS.md), with instructionFiles. For example, in ~/.claude/settings.json, to always read CLAUDE.md and AGENTS.md:

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

It's only read from ~/.claude/settings.json, --settings or managed settings; in project settings it's ignored. Before 2.1.285 the identifier was agents-md@builtin; newer versions accept both. We didn't test the /config panel ourselves: the values come from the official docs.

When it loads and in which subfolders

At session start, Claude loads every AGENTS.md and .claude/AGENTS.md in your working directory and its parent folders. In an interactive session you'll see a line like no CLAUDE.md found; AGENTS.md loaded: /home/you/repo/AGENTS.md.

While it works, a subfolder's AGENTS.md is added when Claude opens a file in that subfolder with the Read tool and that subfolder has none of the three CLAUDE.md files of its own. It's useful in monorepos: apps/web/AGENTS.md and apps/api/AGENTS.md with different rules. 2.1.290 fixed a subfolder's AGENTS.md not being attached when @-mentioning a file inside it.

Inside each AGENTS.md, @path imports are expanded and claudeMdExcludes patterns apply. Subagents that start without project instructions (like the built-in Explore and Plan) also start without AGENTS.md. Before 2.1.281, some sessions (Bedrock, Vertex, Foundry, gateways or with telemetry off) didn't read AGENTS.md: that was the 486-point HN thread. Update if you're below it.

We didn't verify the on-screen load line or subfolder loading ourselves; they come from the official docs and the CHANGELOG.

One file for all your AI tools

If your team mixes Claude Code, Codex and Cursor, make AGENTS.md the source of truth: build and test commands, conventions, structure. For Claude-specific things (using plan mode in a certain folder, a skill), create a CLAUDE.md next to it that starts with @AGENTS.md and adds its own content below:

@AGENTS.md

## Claude Code

Use plan mode for changes in src/billing/.

Claude reads the imported file first and then the rest. This is the most robust option: it works even if you have a CLAUDE.md, even if someone sets Project instructions to claude-md, and in sessions that can't read AGENTS.md directly. Keeping the import never makes it load twice.

If you don't need anything Claude-specific, a symlink works:

# Alternative without Claude-specific content: a symlink (not for teams with Windows)
ln -s AGENTS.md CLAUDE.md

It has two drawbacks: the Edit and Write tools refuse to write through the link and Claude edits AGENTS.md instead; and on Windows creating links requires admin rights or developer mode, and git checks them out as a one-line text file if core.symlinks isn't enabled. With either option, check in the next session with /context that CLAUDE.md shows up under "Memory files".

If you already had a workaround before 2.1.277

Many people built their own solution while there was no support. The official docs say what to do with each:

Differences worth knowing between an AGENTS.md read through the setting and a CLAUDE.md: it doesn't fire InstructionsLoaded hooks, it doesn't load from folders added with --add-dir even if you have CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD, and an import from outside the project only loads if you already approved external imports, without asking you.

Coming from Codex or Cursor: migrate and check

If you're bringing setup from another tool, /import accepts codex, gemini or cursor and brings instruction files, MCP servers, commands, subagents and skills into Claude Code; with --dry-run you see what it would bring without writing anything. Watch out: it adds a one-time copy of files like AGENTS.md to the matching CLAUDE.md, so from then on you have two files to maintain; if you want just one, the @AGENTS.md import is better. The version in which /import arrived isn't listed in the CHANGELOG.

/init, when generating a starting CLAUDE.md, already reads Cursor rules (.cursor/rules/ or .cursorrules) and Copilot's (.github/copilot-instructions.md); with CLAUDE_CODE_NEW_INIT=1 also AGENTS.md, .windsurfrules, .clinerules and Devin's rules.

# Coming from Codex, Gemini CLI or Cursor? First see what it would bring (writes nothing)
/import codex --dry-run
/import cursor --dry-run
# One-time copy of instructions (e.g. AGENTS.md → CLAUDE.md), MCP, commands, subagents and skills
/import codex

# /init also reads .cursor/rules/, .cursorrules and .github/copilot-instructions.md;
# with this variable, also AGENTS.md, .windsurfrules, .clinerules…
CLAUDE_CODE_NEW_INIT=1 claude

# Check which instructions the session loaded
/memory      # lists the paths of loaded CLAUDE.md / AGENTS.md files
/context     # "Memory files" section

To check what Claude loaded, /memory lists the path of every instructions file it read (before 2.1.280 it didn't list an AGENTS.md read directly). If it isn't there, check in order:

1. A CLAUDE.md or CLAUDE.local.md along the path.
2. Your version.
3. The Project instructions value.

If that setting doesn't even appear in /config, your session can't read AGENTS.md (old version, built-in plugin disabled in /plugin or first session after updating). We didn't test /import or /memory ourselves: they come from the official commands and memory docs.

What we checked

On 1 Nov 2026 on Linux with Claude Code 2.1.316, with claude -p --model haiku (3 calls, Spanish version of the test): only AGENTS.md → the keyword; with CLAUDE.local.md → "none"; with a CLAUDE.md containing @AGENTS.md → the keyword. The debug log confirmed the built-in cc-plugin-agents-md plugin. We didn't test the /config > Project instructions panel, the "AGENTS.md loaded" line on screen, subfolder loading, /import or /memory; those come from the official docs and the CHANGELOG.

FAQ

If I have CLAUDE.md and AGENTS.md, which one wins?

By default only CLAUDE.md is read. It's not that they merge with a priority: AGENTS.md simply isn't loaded. To use both, import @AGENTS.md from the CLAUDE.md or set Project instructions to claude-md-and-agents-md.

Does my personal ~/.claude/CLAUDE.md block the project's AGENTS.md?

No. The user CLAUDE.md, the organization's managed one and .claude/rules/ don't count for that check and load alongside AGENTS.md. CLAUDE.md, .claude/CLAUDE.md and CLAUDE.local.md in your folder or its parents do block it.

Can I set Project instructions for the whole team in the repo?

No: the pluginConfigs entry is ignored in project and local settings. The robust option for a team is a CLAUDE.md in git with @AGENTS.md.

Does AGENTS.md work on Bedrock or with telemetry off?

Since 2.1.281, yes (also on Vertex, Foundry and gateways). On older versions, import @AGENTS.md from a CLAUDE.md or update.

Does AGENTS.md have the same features as CLAUDE.md?

Almost: it supports @path imports and claudeMdExcludes, but it doesn't fire InstructionsLoaded hooks or load from --add-dir folders. Path rules (.claude/rules/) and auto memory belong to Claude Code and keep working separately. To see where each piece fits, check which piece to use.

What about .cursorrules or .cursor/rules?

Claude Code doesn't read them in every session. /init uses them to generate your CLAUDE.md, and /import cursor brings Cursor's setup over once.

The whole library