Claude Code reads AGENTS.md since 2.1.277, but only when the project has no CLAUDE.md. If both exist, CLAUDE.md wins. The four modes, the one-line fix and the limits.
Why this matters #
Claude Code 2.1.277 (09/18/2026) added AGENTS.md support through a built-in plugin with four modes. The default loads AGENTS.md only when the project has no CLAUDE.md in your working folder or any folder above it, so a repo with both files still gives Claude Code only CLAUDE.md. To load both, put @AGENTS.md at the top of CLAUDE.md, which travels with the repo, or change the mode in /config under Project instructions, which only changes it for you. Then run /doctor prompt-audit, which flags a CLAUDE.md and an AGENTS.md that contradict each other.
Claude Code reads AGENTS.md now, but only when your project has no CLAUDE.md. Version 2.1.277 shipped it on 09/18/2026. A project with no CLAUDE.md of its own gets its AGENTS.md instead, loaded exactly where a CLAUDE.md would be. A repo with both files still gives Claude Code only CLAUDE.md. I checked my own blog repo against that rule. It has both files, so Claude Code and any agent that reads AGENTS.md, such as Codex, get two different rulebooks in the same folder.
This is part of the Claude Code workflow track that starts with the Claude Code complete guide.
TL;DR #
The feature is a built-in plugin with an option called instructionFiles and four modes. The default treats AGENTS.md as a fallback, another mode loads both files, and you switch in /config under Project instructions. That setting is per user. For a shared repo I trust one line at the top of CLAUDE.md, @AGENTS.md. Then I run /doctor prompt-audit to catch the two files disagreeing.
Does Claude Code read AGENTS.md? #
Claude Code reads AGENTS.md by default only in a project that has no CLAUDE.md of its own. The changelog entry for 2.1.277 says it plainly. “In a project with no CLAUDE.md, Claude Code reads AGENTS.md instead; change it under ‘Project instructions’ in /config.” On Amazon Bedrock, Google Vertex AI, Microsoft Foundry, LLM gateways and sessions with telemetry turned off, it started working in 2.1.281, on 09/23/2026.
“Of its own” has a precise meaning. Any CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md turns the fallback off if it sits in the folder you work in or in a folder above it. A CLAUDE.md in a subfolder below you only covers that subfolder. Your personal ~/.claude/CLAUDE.md, your organization’s managed file and .claude/rules files do not count.
| What the project has | What Claude Code loads by default |
|---|---|
| CLAUDE.md only | CLAUDE.md, as before |
| AGENTS.md only | AGENTS.md, in CLAUDE.md’s place |
| Both | CLAUDE.md only |
Two consequences are easy to miss. In a monorepo, one CLAUDE.md at the root switches off every AGENTS.md below it, because the root is above every folder you could work in. And CLAUDE.local.md is usually gitignored, so a teammate who keeps a private one gets no AGENTS.md while everyone else does.
Claude Code also reads .claude/AGENTS.md. It does not read AGENTS.override.md, AGENTS.local.md or an .agents/ folder, which are names other tools use.
The fallback answers an old request. Issue #6235 asked for AGENTS.md support, and a commenter there called it the most upvoted Claude Code issue by more than two to one. Until now the thread’s answer was a workaround. You made a CLAUDE.md that contained just @AGENTS.md, or you symlinked one file to the other.
What happens when a repo has both files? #
When a repo has both files, Claude Code follows CLAUDE.md and ignores AGENTS.md, and OpenAI Codex does the opposite. Codex reads AGENTS.md and skips CLAUDE.md by default. Its project_doc_fallback_filenames setting can name CLAUDE.md, but Codex reads only the first non-empty instruction file in each folder, so the fallback is used only where there is no AGENTS.md. Either way, nothing forces the two files to agree.
My blog repo is that case. I run both Claude Code and Codex in it. The CLAUDE.md is 163 lines. It holds the design system, build gotchas and a gate the agent runs before writing any new code. The AGENTS.md is 39 lines, written for a different agent, and it says things the CLAUDE.md never says. Its forbidden actions include “Writing files unless explicitly instructed” and “Publishing content”. Its stop conditions include “Request requires publishing or deployment”.
Under the default mode, Claude Code never loads that AGENTS.md, because the repo has a CLAUDE.md of its own. So one agent was told to stop before writing a file, and the other was never told. It is like two referees working the same game from two different rulebooks. Each one is consistent, and the game is still a mess.
Neither file is wrong on its own terms. The failure is that nothing checked whether they agree, and the fallback cannot fix that, because in this case it correctly does nothing.
Before this release I had solved the same problem a different way. I keep one small file of rules that are the same for every agent. Claude Code’s instruction file and Codex’s both load it by reference. It holds only the shared rules. Never use em dashes. Reproduce a bug before claiming it is fixed. Never call a claim verified unless it cites something checkable. Anything specific to one agent stays in that agent’s own file.
How do I make Claude Code load both files? #
The fix I would use is one line at the top of CLAUDE.md:
@AGENTS.md
Claude Code then loads AGENTS.md in every mode except managed-only, and because the line is committed, every teammate gets the same instructions. When both files load, Claude Code skips duplicates. An AGENTS.md that CLAUDE.md already imports is not loaded a second time. The plugin compares by path, then by content.
A symlink from CLAUDE.md to AGENTS.md also works, and Claude Code reads the content once. I still prefer the import. It does the same job, a reviewer can see it in a diff, and it does not depend on symlinks surviving every checkout, which is not a given on Windows.
After that, run /doctor prompt-audit (Claude Code 2.1.283 or later, also /checkup prompt-audit). It reads CLAUDE.md, CLAUDE.local.md and AGENTS.md and puts files that contradict each other at the top of its report. That is the check my repo was missing, because the import makes both files load but does not make them agree.
To confirm what loaded, run /memory. Since 2.1.280 it lists AGENTS.md files the plugin loaded.
What are the four instructionFiles modes? #
The instructionFiles option has four modes, and the default is claude-md-or-agents-md.
| Mode | What loads | Who it fits |
|---|---|---|
claude-md |
Only CLAUDE.md. The plugin adds nothing. | Teams that want the old behavior exactly |
claude-md-or-agents-md (default) |
AGENTS.md where the project has no CLAUDE.md of its own | Repos written for other agents, now opened in Claude Code |
claude-md-and-agents-md |
Every AGENTS.md beside CLAUDE.md, up and down the tree | Repos with both files that should agree |
managed-only |
Drops the project’s instruction files, your own and .claude/rules files; keeps the organization’s managed CLAUDE.md and auto memory |
Locked-down enterprise setups |
In settings, the mode looks like this:
{
"pluginConfigs": {
"agents-md@builtin": {
"options": { "instructionFiles": "claude-md-and-agents-md" }
}
}
}
That setting is read only from user settings (~/.claude/settings.json), a --settings file or managed settings. A project’s .claude/settings.json and local settings are ignored for this one value. So two people opening the same checkout can load different instructions, and neither of them can see why in the repo. That is why I think the import is the better default for anything shared.
Which fix fits your repo? #
- Only Claude Code touches the repo. Nothing changes. Leave the default.
- Other agents wrote the repo’s AGENTS.md, and there is no CLAUDE.md. The default already works. Do not add an empty CLAUDE.md or a personal CLAUDE.local.md, because either one turns the fallback off.
- Both files exist and should agree. Put
@AGENTS.mdon the first line of CLAUDE.md, move the shared rules into AGENTS.md, and run/doctor prompt-audit. - An organization wants to control what loads. That is what
managed-onlyis for. - It is a personal preference, not a repo rule. Keep it out of the repo’s AGENTS.md. Every teammate’s Codex reads that file, and so does their Claude Code wherever the project has no CLAUDE.md. Personal rules belong in
~/.claude/CLAUDE.mdand~/.codex/AGENTS.md.
What does Claude Code skip in AGENTS.md? #
Claude Code’s AGENTS.md support has limits that look like bugs if nobody tells you about them.
- AGENTS.md files in subfolders attach only when Claude opens a file in that folder with the Read tool. They do not attach for
@-mentions or IDE selections, where a subfolder CLAUDE.md would. - Folders added with
--add-dircontribute no AGENTS.md. - Nested attachments are not part of the read-file state restored after compaction; the plugin re-attaches them.
- An
@import inside AGENTS.md that points outside the working folder loads only if external imports were already approved for the project. No approval prompt appears. InstructionsLoadedhooks do not fire for an AGENTS.md that the plugin loads.- The first session after you upgrade may skip AGENTS.md, so start a second one before you decide it failed.
- Subagents receive nested AGENTS.md files on their own; forks inherit the parent’s.
Why this matters more after Opus 5.5 #
Opus 5.5 became the default Opus model in Claude Code on 09/22/2026, and prompt-audit arrived three days later. That timing is the point. An instruction file tuned for an older model starts steering the new one wrong. Two files that disagree make it worse, because the model gets both sets of orders at once. My Opus 5.5 vs Fable 5.1 post covers what changed in that model.
Instruction files also have a ceiling. A line in a markdown file can ask Claude to hold back. It cannot stop anything. The Claude Code hooks tutorial covers the layer that can, because a hook blocks the action before it runs. If you are deciding which rules belong in an instruction file at all, the skills vs subagents vs hooks comparison sorts each job to the right place, and the Claude Code skills guide covers the instructions that should load only when a task needs them.
· Frequently asked
FAQ #
Does Claude Code read AGENTS.md?
Yes, since version 2.1.277 on 09/18/2026. By default it reads AGENTS.md only in a project that has no CLAUDE.md of its own, and loads it exactly where a CLAUDE.md would load. If there is a CLAUDE.md in the folder you work in or any folder above it, Claude Code uses that and skips AGENTS.md. On Amazon Bedrock, Google Vertex AI, Microsoft Foundry and LLM gateways, support arrived in 2.1.281.
How do I make Claude Code load both CLAUDE.md and AGENTS.md?
Put a line with @AGENTS.md at the top of CLAUDE.md. The import is committed with the repo, so every teammate gets the same instructions, and it works in every mode except managed-only. You can also set Project instructions in /config to load both, but that setting is per user.
What is the difference between AGENTS.md and CLAUDE.md?
AGENTS.md is a shared instruction-file format that many coding agents read, including OpenAI Codex, Cursor and GitHub Copilot's coding agent. CLAUDE.md is Claude Code's own file. They hold the same kind of content. The practical difference is which agent reads which file.
Should I symlink CLAUDE.md to AGENTS.md?
It works, and Claude Code reads the content once. I still prefer an @AGENTS.md import line. It does the same job, a reviewer can see it in a diff, and it does not depend on symlinks surviving every checkout, which is not a given on Windows.
How do I check whether Claude Code loaded my AGENTS.md?
Run /memory. Since Claude Code 2.1.280 it lists AGENTS.md files the plugin loaded. Older versions did not show them, so an AGENTS.md missing from /memory on an old version had not necessarily failed.
· Sources & further reading
Sources & Further Reading #
Further reading
- Claude Code Skills vs Subagents vs Hooks vs CLAUDE.md: Which One Fits Which Job /blog/claude-code-skills-vs-subagents Claude Code skills vs subagents vs hooks vs CLAUDE.md as of 09/29/2026: when each loads, whose context it uses, and a simple decision sequence for picking one.
- Claude Code Skills: What They Are, Where They Live, and How to Write One /blog/claude-code-skills Claude Code skills explained: what a SKILL.md is, where skills live, how to write one, and the skills I actually run. Checked against the docs on 09/29/2026.
- Claude Fable 5 System Card, Annotated: 95% Capability, Documented Fabrication /blog/fable-5-system-card-capability-and-fabrication The Fable 5 system card documents both halves: 95.0% SWE-bench Verified, and fabricated status reports with unverbalized early-stops. The annotated read.
- SvelteKit MCP: The Official Svelte Server, and What Its Autofixer Found in 134 Components /blog/sveltekit-mcp-server-claude-code The official Svelte MCP server gives Claude Code current Svelte 5 docs and an autofixer. I ran it on 134 components: 70 missing keys, 34 files it could not read.
- Fable 5.1 vs Opus 5 in Production: A Whole Day on Fable Used 19% of a Max Weekly Window /blog/claude-fable-5-vs-opus-5 Same harness, same day: 2,443 Fable 5.1 turns and 1,120 Opus 5 turns after a weekly reset consumed 19% of the Max weekly window, and the 5-hour window peaked at 59% without capping. Fable errored less per tool call, hit more permission gates, and would have cost 1.4x per turn on the API, not 2x.
Built from these systems
Claude Code Project Memory Kit $29
Four Claude Code skills and two scripts that keep a knowledge base inside your repo, so the next session starts from what the last one learned.
Want more of this in your Google results?
What do you think? #
I post about this stuff on LinkedIn every day and the conversations there are great. If this post sparked a thought, I'd love to hear it.