Claude Code reads AGENTS.md only when there is no CLAUDE.md. More precisely, since version 2.1.277 it reads AGENTS.md when no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md sits in your working directory or any directory above it. If one does, Claude Code reads the CLAUDE.md files and ignores AGENTS.md. Your personal ~/.claude/CLAUDE.md does not count and loads alongside either file.
There was a second condition nobody announced. Until 2.1.281, the sat behind a remote feature flag, tengu_agents_md_mod. With telemetry switched off, the flag never arrived, and Claude Code skipped AGENTS.md without a warning. Anthropic's memory docs now say the gap is closed from 2.1.281. If you run an older version with telemetry off, or through a cloud provider such as Bedrock, your AGENTS.md may still not be .
Which file does Claude Code read when both exist? #
By default, CLAUDE.md, and only CLAUDE.md. AGENTS.md stands in when CLAUDE.md is missing, and the two are not merged unless you import one into the other or change the setting below. The documentation gives the full table:
| Files in your working directory or above it | What Claude Code reads by default |
|---|---|
| AGENTS.md, and no CLAUDE.md or CLAUDE.local.md | Your AGENTS.md |
| AGENTS.md, plus a CLAUDE.md or CLAUDE.local.md | Your CLAUDE.md files only |
A CLAUDE.md that imports AGENTS.md with @AGENTS.md |
Your CLAUDE.md, with AGENTS.md included through the import |
Three details catch people out:
- CLAUDE.local.md counts. Add one for your own uncommitted notes in a repository that relies on AGENTS.md, and Claude Code stops reading AGENTS.md for you.
- "Above it" means every parent directory. A stray CLAUDE.md in a parent folder, even your home directory, switches AGENTS.md off for every project below it. Only
~/.claude/CLAUDE.mdis exempt. - Subdirectories follow the same rule. A nested AGENTS.md loads when Claude Code opens a file in that folder with its Read tool, as long as the folder has no CLAUDE.md of its own.
You can change the default under Project instructions in /config. claude-md-and-agents-md reads both files, each directory's CLAUDE.md first and its AGENTS.md after it, and never loads the same file twice. claude-md restores the old behaviour. The setting only counts in your user settings, a --settings file or managed settings. Claude Code ignores it in a project's own .claude/settings.json, so a repository cannot switch it for you.
Claude Code never reads AGENTS.local.md, AGENTS.override.md or anything under .agents/. Codex reads AGENTS.override.md first, so a repository that relies on it gets different instructions in each tool.
What changed in Claude Code 2.1.277? #
AGENTS.md support shipped on 18 September 2026. The changelog entry reads: "in a project with no CLAUDE.md, Claude Code reads AGENTS.md instead". It was not yet available on Bedrock, Vertex or Foundry. Thariq Shihipar of the Claude Code team announced it the same day, and the Hacker News thread passed 700 points.
The feature request is from 2025, and until last week the standard answer was a symlink or a one-line CLAUDE.md. As Simon Willison noted, the is a built-in mod, an example of Claude Code's upcoming way to change the harness itself. Two later releases finished the job. From 2.1.280, /memory and /context list an AGENTS.md that was read directly. From 2.1.281, sessions with telemetry off, and sessions on Bedrock, load it too.
Why did AGENTS.md silently fail with telemetry off? #
Because a local file was gated on a remote switch. On 23 September, Przemysław Szypowicz published a measurement. He put a canary word in an AGENTS.md, in a directory with no CLAUDE.md, and asked Claude Code for it. In the 2.1.280 bundle, the mod's availability came from a remote flag, tengu_agents_md_mod, which defaulted to off. Setting DISABLE_TELEMETRY or CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC to any value, 0 included, meant the flag was never fetched, so the file never loaded.
His summary: "None of these cases print a warning. The session starts, the model answers without the project instructions, and nothing tells you that a file was skipped." That hits hardest for the people most likely to turn telemetry off: companies with strict data rules, and anyone running Claude Code through a cloud provider.
The fix came the same day. On a separate Hacker News thread, which reached 476 points, a commenter who said they made the change called it "a rollout artifact" and said it was fixed in 2.1.281. I could not confirm who they are. The docs now carry the same claim: "Before v2.1.281, some sessions, such as those on Amazon Bedrock or with telemetry disabled, read CLAUDE.md files only." A GitHub issue on the flag was still open on 24 September.
How do you check whether your instruction file loaded? #
Run claude --version first. You need 2.1.277 for AGENTS.md at all, and 2.1.281 if you run with telemetry off or through a cloud provider such as Bedrock. Then pick whichever check fits:
- Watch the session start. An interactive session prints a line like
no CLAUDE.md found; AGENTS.md loaded: /path/to/AGENTS.md. - Run
/memoryor/context. From 2.1.280, both list the AGENTS.md path. On older versions they leave it out even when it loaded. - Open
/config. IfProject instructions is missing from the panel, your session cannot load AGENTS.md at all. - Plant a canary. Put an unusual word in the file and ask, without letting it open files:
claude -p 'What is the canary word from the project instructions? Answer NONE if you have none. Do not read files.'Szypowicz ran every setup twice, because a first session after an upgrade may only fetch settings.
If you need a guarantee on every version and every provider, use the old import. A CLAUDE.md with the single line @AGENTS.md loads the file through the import mechanism, which never depended on the flag. The docs say the file will not load twice when direct is also on, so you can leave the import in place.
What belongs in AGENTS.md, and what belongs in CLAUDE.md? #
Put the facts every agent needs in AGENTS.md. Put what only Claude Code understands in CLAUDE.md, below an @AGENTS.md import:
- AGENTS.md: build and test commands, the repository layout, code conventions, what not to touch. TheAGENTS.md project describes it as a README for agents, and it now sits under the Linux Foundation's Agentic AI Foundation.
- CLAUDE.md:
@pathimports, pointers toskills and hooks, subagent notes, anything that refers to Claude Code's own commands. - CLAUDE.local.md: your personal notes. Remember that it switches off direct AGENTS.md .
Keep both files short. Everything in them loads at the start of every session, and startup context was the clearest cost driver in the harness study covered in the harness explainer. The Stackness move Context engineering is about this discipline. Tools like DOX go the other way and build a tree of small nested AGENTS.md files, so each folder carries only its own context.
If you already symlinked CLAUDE.md to AGENTS.md, it still works. Claude Code's Edit and Write tools refuse to write through the link itself and edit its target, AGENTS.md, instead. On Windows, use the import. A committed symlink checks out there as a one-line text file unless git's core.symlinks is on.
Which other coding agents read AGENTS.md? #
Most of them now, with different rules for which file wins:
| Agent | What it reads | CLAUDE.md |
|---|---|---|
| OpenAI Codex | AGENTS.override.md, then AGENTS.md, one per directory from the repo root down | Only if you add it as a fallback name |
| Cursor | AGENTS.md at the root and in subfolders, plus .cursor/rules |
Not documented |
| GitHub Copilot coding agent | AGENTS.md, CLAUDE.md, GEMINI.md and .github/copilot-instructions.md |
Read as well |
| OpenCode | AGENTS.md, else CLAUDE.md | Only when there is no AGENTS.md |
| Gemini CLI | GEMINI.md by default, AGENTS.md if you add it to context.fileName |
Only what you configure |
| Windsurf | AGENTS.md at the root always, subfolder files as scoped rules | Not documented |
| Zed | The first match from a list that includes .rules , AGENTS.md and CLAUDE.md |
Read if it is the first match |
| Amp | AGENTS.md in the working directory, its parents and subtrees | Read in a folder with no AGENTS.md |
| [Jules](https://stackness.dev/tools/jules) | AGENTS.md at the repository root | Not documented |
| [Aider](https://stackness.dev/tools/aider) | Nothing by default. Load it with `--read AGENTS.md` | Only what you pass |
Claude Code and OpenCode now mirror each other: each prefers its own file and falls back to the other's. With both files present, the two tools read different instructions. Sources: the Codex, Cursor, Copilot, OpenCode, Gemini CLI, Windsurf, Zed, Amp and Aider documentation, checked on 24 September 2026.
How many people does the precedence rule affect? #
On Stackness, most people who list Claude Code also list another agent. As of 24 September 2026, 12 real public profiles list at least one coding agent, after removing accounts that say they are bots. Seven list Claude Code. Four of those seven also list an agent that reads AGENTS.md:
- Cursor: three of them.
- Codex: two, one of them the founder of Stackness.
- GitHub Copilot, OpenCode and Windsurf: one profile, which lists five agents.
These are small numbers, and I am not reading market share into them. They do show who this change is for: people who switch between agents in one repository and want a single file to describe it. If that is you, keep the shared facts in AGENTS.md, keep a one-line CLAUDE.md that imports it, and check /memory after every upgrade.
Key numbers #
- 2.1.277 , released18 September 2026 , is the first Claude Code version that reads AGENTS.md (changelog ).
- 2.1.280 is the first version whose
/memoryand/contextlist a directly loaded AGENTS.md.
- **2.1.281** is the first version that loads AGENTS.md with telemetry off or on Bedrock, according to the[memory docs](https://code.claude.com/docs/en/memory#when-agents-md-support-is-unavailable) .
- **`tengu_agents_md_mod`** is the remote flag that gated the , measured on**23 September 2026** ([Szypowicz](https://blog.szypowi.cz/p/claude-code-reads-agents.md-only-when-telemetry-is-on/) ).
- 3 file names count as CLAUDE.md for the check:
CLAUDE.md,.claude/CLAUDE.mdandCLAUDE.local.md. - 4 of 7 real Stackness profiles with Claude Code also list an agent that reads AGENTS.md, as of 24 September 2026 (seedata sources ).
Quick answers #
Does Claude Code read AGENTS.md? Yes, since version 2.1.277, but only when there is no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in the working directory or above it.
What happens if a repository has both AGENTS.md and CLAUDE.md? By default Claude Code reads only the CLAUDE.md files. Import AGENTS.md from CLAUDE.md with @AGENTS.md, or set Project instructions to claude-md-and-agents-md in /config.
Why is my AGENTS.md not ? Usually a CLAUDE.md or CLAUDE.local.md somewhere on the path. On versions before 2.1.281, telemetry being off or running on Bedrock also blocked it, with no warning.
How do I check that Claude Code loaded AGENTS.md? Run /memory on 2.1.280 or later and look for its path. On older versions, ask Claude Code for a canary word you put in the file.
Should I symlink CLAUDE.md to AGENTS.md? It works on macOS and Linux. On Windows, or for anyone who clones there, a one-line CLAUDE.md with @AGENTS.md is safer.
Which agents read AGENTS.md? Codex, Cursor, GitHub Copilot, OpenCode, Windsurf, Amp, Jules and Zed read it on their own. Gemini CLI and Aider read it once you configure them to. Claude Code reads it as a fallback.