• Claude Code reads AGENTS.md on its own as of v2.1.277, released September 18, 2026, but only in a project with no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in the working directory or any folder above it.
• In our tests on v2.1.277, a personal CLAUDE.local.md was enough to hide a team’s AGENTS.md. In a repo whose only instruction file was AGENTS.md, DISABLE_TELEMETRY=1 left Claude Code with no project instructions at all, and our headless runs printed no warning.
• An AGENTS.md that Claude Code reads directly didn’t appear in /context, and our InstructionsLoaded hook never fired for it. One pulled in through a CLAUDE.md import showed up in both.
• Codex, per OpenAI’s docs, reads AGENTS.override.md or AGENTS.md from the Git root down, stops at 32 KiB by default, and reads CLAUDE.md only if you add it as a fallback filename.
• The old one-line CLAUDE.md containing @AGENTS.md loaded the shared file in every setup we tried, and adding Claude Code’s read-both mode on top of it didn’t load the file twice.

What’s the difference between AGENTS.md and CLAUDE.md?

They do the same job under two names. Both are plain Markdown files of project instructions (build commands, conventions, the directories not to touch) that a coding agent loads before it starts work. CLAUDE.md belongs to Claude Code. AGENTS.md is the cross-tool version: agents.md says it’s “used by over 60k open-source projects” and is “now stewarded by the Agentic AI Foundation under the Linux Foundation.” Codex, Cursor, Jules and GitHub Copilot’s coding agent read it, and Gemini CLI and Aider can be pointed at it with one line of config.

Claude Code was the best-known holdout. It read only CLAUDE.md, so teams that mixed tools kept two copies or wired one file to the other, and a feature request for AGENTS.md support collected 5,168 thumbs-up. Several of the guides ranking for this comparison were written in that period and still say Claude Code ignores AGENTS.md.

On September 18, 2026 that stopped being true. The Claude Code changelog entry for 2.1.277 says: “in a project with no CLAUDE.md, Claude Code reads AGENTS.md instead.” The interesting part is that condition, so we tested it the day it shipped.

How we tested it

We built a set of small Git repos in a scratch directory on a Mac, each with a different mix of instruction files, and planted a unique codename in every file (“The project codename is AGENTS-ROOT-7421.”). Then we started Claude Code 2.1.277 in each repo on Haiku 4.5 with every tool disabled and asked it to list the codenames in its instructions:

claude -p "Do not use any tools. List every 'project codename' stated anywhere in the instructions you were given for this session. Reply with the codenames only, comma-separated, or NONE." \
  --model haiku --tools "" --no-session-persistence

Without tools it can’t open a file, so any codename it names came from what Claude Code loaded at startup. The one exception is setup 11 below, where we allowed the Read tool on purpose. The session log shows it opened only the file we asked for, not the AGENTS.md next to it.

For the setups that mattered most we checked without asking the model: the Memory files list in /context, an InstructionsLoaded hook that logged every event it received, and input-token counts from --output-format json. Every run went through Anthropic’s own API, not Bedrock, Vertex or Foundry.

We didn’t run Codex. It isn’t installed on the test machine, so everything we say about Codex below comes from OpenAI’s AGENTS.md docs, and we say so each time.

When does Claude Code 2.1.277 read AGENTS.md?

When no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md sits in the working directory or above it. Those three win wherever they exist, and most of the table follows from that one rule. The rest comes from a directory walk that goes further than we expected.

#	Instruction files in the repo	What Claude Code loaded
1	AGENTS.md only	AGENTS.md
2	AGENTS.md + CLAUDE.md	CLAUDE.md only
3	AGENTS.md + CLAUDE.local.md	CLAUDE.local.md only
4	AGENTS.md + a file in .claude/rules/	Both
5	.claude/AGENTS.md only	.claude/AGENTS.md
6	AGENTS.md + AGENTS.override.md + AGENTS.local.md + .agents/AGENTS.md	AGENTS.md only
7	CLAUDE.md containing @AGENTS.md	Both
8	CLAUDE.md symlinked to AGENTS.md	AGENTS.md, once
9	AGENTS.md in the repo + another in the folder above the Git root	Both
10	Started in a subfolder, AGENTS.md at the repo root	The root AGENTS.md
11	AGENTS.md in pkg/api/, after Claude read a file in that folder	Root + pkg/api
12	Setup 2 with claude-md-and-agents-md	Both
13	Setup 3 with claude-md-and-agents-md	Both

Setup 3 is the trap. CLAUDE.local.md is where you keep personal notes you don’t commit, and nobody adding one is thinking about the team’s AGENTS.md. In our run it was enough for Claude Code to drop the shared file entirely. Anthropic’s memory docs warn about exactly this and point to the fix in setup 13, a Project instructions value called claude-md-and-agents-md. You can pick it from /config in a session, or put it in a settings file:

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

The catch is where that file can live. The docs say ~/.claude/settings.json, a --settings file or managed settings, and that “Claude Code ignores it in project and local settings files.” A team can’t commit it for everyone. Each person sets it on their own machine, or an admin pushes it. Your global ~/.claude/CLAUDE.md is a different story: per the docs it doesn’t count against AGENTS.md, and neither do .claude/rules/ files, which is why setup 4 loaded both.

Setup 9 surprised us. We put an AGENTS.md in the folder that contains the Git repo, expecting the walk to stop at the repo root. Claude Code loaded both files. The docs do say it reads every AGENTS.md “in your working directory and the directories above it,” and they mean all of them. A forgotten AGENTS.md in a parent folder becomes part of every project underneath it that has no CLAUDE.md. The docs imply the reverse trap as well: a stray CLAUDE.md in a parent folder counts too, and hides AGENTS.md in every repo below it.

Setups 7 and 8 are the workarounds people used before this release, and both still work. A third one ages badly. If you had a SessionStart hook that prints AGENTS.md, the docs say to remove it, because once the direct read kicks in, the hook adds a second copy.

Which settings stop Claude Code from reading AGENTS.md?

Four settings stopped Claude Code from reading AGENTS.md, and none printed a warning in our headless runs. We ran each one against setup 1, where the only instruction file is an AGENTS.md, so “nothing” means the session started with no project instructions at all:

Setting	AGENTS.md alone	CLAUDE.md with @AGENTS.md
DISABLE_TELEMETRY=1	Nothing loaded	Both loaded
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1	Nothing loaded	Both loaded
"disableAllHooks": true	Nothing loaded	Both loaded
Project instructions set to claude-md	Nothing loaded	Not tested

The last row is the documented off switch, so it did what it says. The first two are the ones that will catch people, because plenty of developers disable telemetry on principle. Anthropic’s docs explain the link. Direct AGENTS.md reading needs a session that fetches feature flags from Anthropic, and a session with telemetry disabled doesn’t, nor does one on “Amazon Bedrock or another third-party provider.” The third row follows from how the feature ships: it’s a built-in plugin named agents-md, and the docs list disableAllHooks among the settings that turn it off. Turning on claude-md-and-agents-md didn’t rescue the one case we tried. With telemetry off, setup 13 went back to loading CLAUDE.local.md alone, and per the docs these sessions don’t even show the Project instructions setting in /config.

The docs list three more cases we didn’t reproduce. An organization that sets allowManagedHooksOnly turns the direct read off, and so does disabling the built-in agents-md plugin in /plugin. And the first session after you install or upgrade to a version with AGENTS.md support reads CLAUDE.md files only; AGENTS.md loads from the next session on.

You also can’t confirm the direct read with the usual tools. In setup 1, /context printed no Memory files section at all, and our InstructionsLoaded hook logged zero events. In setup 7, the CLAUDE.md that imports AGENTS.md, the hook fired twice (once with load_reason: session_start, once with include) and /context listed both files. This is its output, with our scratch path shortened:

### Memory Files

| Type | Path | Tokens |
|------|------|--------|
| Project | .../I/CLAUDE.md | 26 |
| Project | .../I/AGENTS.md | 20 |

The docs mention an interactive-session line reading no CLAUDE.md found; AGENTS.md loaded: …, but our headless -p runs never printed it, even with --verbose on. The check that worked every time is the one the docs fall back on: ask Claude what its project instructions say.

How Codex reads AGENTS.md differently

Codex walks down from the Git root, the opposite of Claude Code. OpenAI’s docs say it starts at the project root, “typically the Git root,” and walks down to your current directory, and that it “includes at most one file per directory”: AGENTS.override.md if one exists, otherwise AGENTS.md, otherwise any fallback names you’ve configured. It joins them root-first, so the file nearest your directory speaks last, and it stops adding files once they reach project_doc_max_bytes, 32 KiB by default. We haven’t run any of this ourselves.

That’s also the answer to the Codex version of this question. The docs put fallback names in ~/.codex/config.toml, so for a repo that only has a CLAUDE.md the line is project_doc_fallback_filenames = ["CLAUDE.md"]. Because Codex takes one file per directory and checks AGENTS.md first, that fallback never fires next to an AGENTS.md.

Put the two descriptions side by side and the same repo can hand each tool different instructions:

	Claude Code 2.1.277	Codex (from its docs)
Reads natively	CLAUDE.md; AGENTS.md when no CLAUDE.md exists	AGENTS.md
Reads the other tool's file	Yes, by default or through @AGENTS.md	Only if CLAUDE.md is in project_doc_fallback_filenames, and only in a directory with no AGENTS.md or AGENTS.override.md
Walk direction	Working directory upward, past the Git root in our test; subfolders load when Claude reads a file there	Project root down to the working directory, then stops
AGENTS.override.md	Ignored (our setup 6; the docs list it as not read)	Replaces AGENTS.md in that directory
Personal file	~/.claude/CLAUDE.md or CLAUDE.local.md	~/.codex/AGENTS.md or ~/.codex/AGENTS.override.md
Size	Docs recommend under 200 lines per CLAUDE.md and skip a file over 4 MiB	Combined files stop at 32 KiB by default
Check what loaded	/context for CLAUDE.md and imports; ask Claude for a direct AGENTS.md	codex --ask-for-approval never "Summarize the current instructions."

If Codex behaves the way its docs say, three of those rows can split a team without anyone noticing. An AGENTS.override.md gives Codex the override and Claude Code the plain file. An AGENTS.md above the Git root reaches Claude Code and, per OpenAI’s docs, never reaches Codex. And once instructions pass 32 KiB combined, Codex stops adding files, while Claude Code’s docs only mention skipping a single file over 4 MiB. If both tools run on the same repo, keep instruction files inside the repo, skip override files, and keep the total under 32 KiB. For how the two agents compare beyond configuration, see our Claude Code vs Codex breakdown, the Codex CLI review, or the rest of our developer guides.

Should you keep AGENTS.md, CLAUDE.md or both?

Keep AGENTS.md as the real file and add a CLAUDE.md that imports it. It loaded the shared file in every run we tried it in, including under the three settings that left the direct read with nothing. Claude-specific instructions go below the import:

@AGENTS.md

## Claude Code

- Rules only Claude Code should follow go here.

Files in .claude/rules/ work for Claude-only rules too: in setup 4 they loaded alongside a bare AGENTS.md without hiding it.

That cuts against the headline. The native support that shipped on September 18 is the less reliable way for Claude Code to read AGENTS.md. Deleting CLAUDE.md works for a teammate on Anthropic’s API with default settings. It fails silently for the one on Bedrock, the one with DISABLE_TELEMETRY in their shell profile, the one who just added a CLAUDE.local.md, and anyone still on 2.1.276. The import depends on none of that.

The import costs almost nothing. With an 11.5 KB, 201-line AGENTS.md, reading it directly added 3,748 input tokens over an empty repo, and reading it through a one-line CLAUDE.md added 3,841. Then we switched on claude-md-and-agents-md with the import in place, the one case where a duplicate could show up. The count was 85,034 tokens with and without it, identical, so the docs’ promise that an imported AGENTS.md “isn’t read twice” held. (The totals are high because our test machine carries plugins and skills. The differences are what to compare.)

Deleting CLAUDE.md still makes sense when everyone on the project runs Claude Code 2.1.277 or later on Anthropic’s API, nobody has turned off telemetry, nonessential traffic or hooks, and nobody keeps a CLAUDE.local.md. A symlink works too, and in our test it survived DISABLE_TELEMETRY like the import did. The docs steer Windows teams away from it, though: Git checks a committed symlink out “as a plain text file unless core.symlinks is enabled,” and that clone ends up with a one-line CLAUDE.md where your instructions should be. Codex has its own reason to keep AGENTS.md current, since its review command applies your instruction files to the paths it reviews.

• claude-code
• codex
• agents-md
• ai-coding-assistants
• cli

Frequently asked questions

Can Codex read CLAUDE.md?

Not by default. OpenAI's docs say Codex checks each directory for AGENTS.override.md, then AGENTS.md, then any names listed in project_doc_fallback_filenames, and takes at most one file per directory. Adding CLAUDE.md to that list in ~/.codex/config.toml should make Codex read it, but only in directories without an AGENTS.md. That's from the docs: we didn't run Codex for this article.

Is CLAUDE.md still useful now that Claude Code reads AGENTS.md?

Yes, as a one-line wrapper. A CLAUDE.md containing @AGENTS.md loaded the shared file in every setup we tried on Claude Code 2.1.277, including DISABLE_TELEMETRY=1 and disableAllHooks, where the direct read loaded nothing. Claude-specific rules can go below the import. A CLAUDE.md without the import hides AGENTS.md; files in .claude/rules/ don't, and in our test they loaded alongside it.

Does Claude Code read AGENTS.override.md?

No. Anthropic's docs list AGENTS.local.md, AGENTS.override.md and anything under a .agents/ directory as not read, and our test agreed: with all three present, Claude Code 2.1.277 loaded only the plain AGENTS.md. Codex's docs say it reads AGENTS.override.md instead of AGENTS.md in the same directory, so a repo with an override file hands the two tools different instructions.