AGENTS.md vs CLAUDE.md: which one Claude Code actually reads

If your repository serves more than one coding agent, you probably have an AGENTS.md for Codex, Copilot and Cursor and a CLAUDE.md for Claude Code, often with the same rules copied into both. Since September 2026 you may not need both: Claude Code added AGENTS.md support in version 2.1.277, answering a feature request with more than 6,600 reactions. The catch is in the default: when a session starts, Claude reads your CLAUDE.md files or your AGENTS.md files, not both.

Which file each agent reads

AGENTS.md is an open format that came out of work across several agent makers, including OpenAI Codex, Amp, Jules from Google, Cursor and Factory, and is now stewarded by the Agentic AI Foundation under the Linux Foundation. CLAUDE.md is Claude Code's own file. Here is what three widely used agents document today.

Sources: Claude Code's memory docs, GitHub's repository instructions docs and support table, VS Code's custom instructions reference and the Codex AGENTS.md guide.

When Claude Code reads AGENTS.md

By default Claude Code reads AGENTS.md only when you have no CLAUDE.md in your working directory or above it. Three files count for that check: CLAUDE.md, .claude/CLAUDE.md and CLAUDE.local.md. Three things do not count and keep loading alongside AGENTS.md: your personal ~/.claude/CLAUDE.md, your organization's managed CLAUDE.md, and files in .claude/rules/.

When nothing counts, Claude reads every AGENTS.md and .claude/AGENTS.md from your working directory upwards at the start of the session. A subdirectory's AGENTS.md loads later, when Claude reads a file there with the Read tool and the folder has no CLAUDE.md files of its own. Claude Code does not read AGENTS.local.md, AGENTS.override.md or anything under a .agents/ folder.

Some sessions can't read AGENTS.md at all: versions before 2.1.277, sessions where Claude Code's built-in AGENTS.md plugin is disabled, and in some cases the first session after upgrading from 2.1.276 or earlier. Before v2.1.281, some other sessions, such as those on Amazon Bedrock, also read CLAUDE.md only. In all of these, an import from a CLAUDE.md still works.

The Project instructions setting

Type /config in a session and set Project instructions to change the default. It takes effect from your next message.

The setting can't go in the repository's own settings files. In a settings file it goes in your own ~/.claude/settings.json, a file you pass with --settings, or your organization's managed settings, under pluginConfigs → cc-plugin-agents-md@builtin → options.instructionFiles. Versions before 2.1.285 used the ID agents-md@builtin and ignore the new one, so use the old ID if you might run an older version; 2.1.285 and later read either. Claude Code ignores the setting in a project's .claude/settings.json and .claude/settings.local.json, so you can't share it there with your team, which is one more reason the file layout itself should make the answer obvious.

One file for every agent: import or symlink

The tidy setup is one AGENTS.md that every tool reads, and a CLAUDE.md that points at it. Two popular repositories show both ways. In astral-sh/ruff, CLAUDE.md is the single line @AGENTS.md. Claude's docs suggest putting any Claude-only instructions below the import, where they load after the imported file:

@AGENTS.md

## Claude Code
Use plan mode under `src/billing/`.

In pnpm/pnpm, CLAUDE.md is a symlink to AGENTS.md instead:

ln -s AGENTS.md CLAUDE.md

• Import when anyone clones the repo on Windows. Git checks a committed symlink out as a plain text file unless core.symlinks is enabled, which leaves that clone with a CLAUDE.md containing only the text "AGENTS.md". Because a CLAUDE.md now exists, Claude doesn't read AGENTS.md either, so with the default setting that person's sessions don't load either file's rules.
• Symlink when you have nothing Claude-specific to add. Claude's Edit and Write tools refuse to write through the link, and the refusal tells Claude to edit AGENTS.md instead.
• Neither way loads the content twice, whichever Project instructions value you use.

One thing to retire: a CLAUDE.md that only says, in words, "read AGENTS.md". Claude then sees AGENTS.md only if it decides to open it. Replace the sentence with @AGENTS.md or delete the file.

Check what actually loaded

Run /context all in a Claude Code session and look under Memory files: that is the list of instruction files loaded at launch (an AGENTS.md that Claude reads directly is listed there from v2.1.280). When Claude reads AGENTS.md because no CLAUDE.md exists, an interactive session also prints a line such as no CLAUDE.md found; AGENTS.md loaded with the path. A CLAUDE.md in a subfolder loads on demand, so it doesn't appear under Memory files; when it loads, a Loaded line with its path appears in the terminal. Check again after you add or remove any CLAUDE.md.

Size matters as much as which file wins, because everything that loads at launch is read in every session. We measured 18 real instruction files from open-source repositories in how long should CLAUDE.md be.

MonoVue, our VS Code extension, shows the instruction files each agent loads for the file you have open. Pick Claude Code, Copilot, Cursor, Codex or Gemini CLI and it lists that agent's files in load order with an estimated token count for each, following the Project instructions value in your ~/.claude/settings.json. It is a quick way to spot a CLAUDE.md that hides your AGENTS.md before you run /context all to confirm what Claude itself loaded.