Yes, since Claude Code v2.1.277, but only when there's no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in your folder or above it. Here's which files switch it off, how to make Claude read both, and what it costs.
Originally published on clogmeter.vercel.app.
Yes, from Claude Code v2.1.277, but by default only when your project has no CLAUDE.md. If a CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md sits in the folder you start Claude in or any folder above it, Claude reads those files and skips AGENTS.md completely. To get both, either start CLAUDE.md with @AGENTS.md, or set Project instructions to claude-md-and-agents-md in /config.
People have been asking this for months. In an r/ClaudeAI thread, "Do we still need to maintain CLAUDE.md and AGENTS.md?", the poster asks: "Has claude and claude code adopted AGENTS.md? I'm symlinking them but wondering if I can just drop CLAUDE.md all together." When native support was announced in September, the top question was the same one: "Should we delete just CLAUDE.md, and just use AGENTS.md instead?" This post answers both. For who reads which file in general, see CLAUDE.md vs AGENTS.md vs Cursor rules.
Behaviour is taken from Anthropic's Claude Code docs, How Claude remembers your project, and the v2.1.277 changelog (checked 22 Nov 2026). Claude Code changes often, so confirm on your version with the checks at the end.
What Claude reads, by repo layout
| Your repo has | Claude Code reads (default setting) |
|---|---|
AGENTS.md only |
AGENTS.md. You see no CLAUDE.md found; AGENTS.md loaded: … at the start of the session |
AGENTS.md and a CLAUDE.md (or CLAUDE.local.md) in your folder or above |
CLAUDE.md files only. AGENTS.md is ignored |
A CLAUDE.md that starts with @AGENTS.md
|
Both, through the import. AGENTS.md loads once |
CLAUDE.md symlinked to AGENTS.md
|
The content once |
When AGENTS.md is the one being read, Claude treats it the way it treats CLAUDE.md. Every AGENTS.md and .claude/AGENTS.md from your launch folder upward loads at startup. A subfolder's AGENTS.md loads when Claude first reads a file in that folder, as long as that folder has no CLAUDE.md of its own. @path imports inside it are expanded.
The files that switch AGENTS.md off
The check only looks at three project files. Some files that look like they should count don't.
-
Count (Claude reads these instead of
AGENTS.md):CLAUDE.md,.claude/CLAUDE.mdandCLAUDE.local.md, in your working folder or any folder above it. -
Don't count (they load alongside
AGENTS.md): your personal~/.claude/CLAUDE.md, your organisation's managedCLAUDE.md, and.claude/rules/files. -
Never read:
AGENTS.local.md,AGENTS.override.md(a Codex file) and anything under a.agents/folder.
The trap is CLAUDE.local.md. If you add one for your own uncommitted notes in a team repo that relies on AGENTS.md, Claude stops reading the team's AGENTS.md for you, with no error. A CLAUDE.md in a parent folder, for example in a monorepo root or your home folder above the repo, does the same.
How to make Claude read both
Type /config in a session and change Project instructions:
| Value | What loads |
|---|---|
claude-md-or-agents-md (default) |
CLAUDE.md files, or AGENTS.md when there is no CLAUDE.md/CLAUDE.local.md
|
claude-md-and-agents-md |
Both. In each folder CLAUDE.md loads first, then AGENTS.md. A file already pulled in by an import or symlink isn't read twice |
claude-md |
CLAUDE.md only (the old behaviour) |
managed-only |
Only your organisation's managed CLAUDE.md and auto memory at launch |
To set it in a file, add it to your user settings (~/.claude/settings.json) or managed settings. Claude Code ignores this entry in project and local settings files, so you can't commit it for the team:
{
"pluginConfigs": {
"cc-plugin-agents-md@builtin": {
"options": { "instructionFiles": "claude-md-and-agents-md" }
}
}
}
Before v2.1.285 the plugin ID was agents-md@builtin. Later versions accept either ID.
For a team, the setting doesn't help, because each person has to change it themselves. A committed CLAUDE.md whose first line is @AGENTS.md works for everyone on any version.
Can I delete CLAUDE.md and keep only AGENTS.md?
Yes, if all of these are true:
-
Everyone is on v2.1.277 or later. Sessions on Amazon Bedrock or with telemetry turned off needed v2.1.281. Run
claude --version. -
Nobody keeps a
CLAUDE.local.mdor a parent-folderCLAUDE.md, or they've switched toclaude-md-and-agents-md. -
You don't rely on
InstructionsLoadedhooks. They don't fire for anAGENTS.mdthat Claude reads directly. They do fire for an imported one. -
You don't need extra folders' instructions through
--add-dirwithCLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD. TheirCLAUDE.mdloads, but theirAGENTS.mddoesn't.
If any of these fails, keep a one-line CLAUDE.md:
@AGENTS.md
## Claude Code only
- Hooks live in .claude/settings.json; don't duplicate their rules here.
Anthropic's docs say keeping the import never makes Claude read AGENTS.md twice, whichever setting you use.
Clean up old workarounds
-
A
CLAUDE.mdthat only says@AGENTS.md: you can leave it, or delete it if every session can readAGENTS.mddirectly. -
A
CLAUDE.mdthat says "read AGENTS.md" in words: fix this one. Claude only seesAGENTS.mdif it decides to open it, and because theCLAUDE.mdexists, the native read is switched off. Replace the sentence with@AGENTS.md, or delete the file. -
A
CLAUDE.mdsymlink toAGENTS.md: it still works and loads once. Claude's Edit and Write tools won't write through the link and editAGENTS.mdinstead. On Windows clones withoutcore.symlinks, the link becomes a one-line text file, so use the import there. (Cursor is a separate case: see when symlinks double your tokens.) -
A
SessionStarthook that printsAGENTS.md: remove it. Now that Claude reads the file itself, the hook adds a second copy every session.
What it costs
Whatever Claude reads at startup is paid for in every session, before your first prompt. Switching to native AGENTS.md doesn't make the file cheaper. It only changes which file you pay for. The setting that can raise your bill is claude-md-and-agents-md: if your CLAUDE.md and AGENTS.md were maintained as separate copies of the same rules, both now load. Claude Code dedupes files (by import, symlink, or the same file loaded twice), not repeated paragraphs, so overlapping text in two files is paid for twice. It also gives you two places for an "always" and a "never" to contradict each other.
For size limits, see How long should CLAUDE.md / AGENTS.md be?
How to check what Claude read
-
Start a fresh session and look for the line
no CLAUDE.md found; AGENTS.md loaded: /path/to/AGENTS.md. -
Run
/memoryand look for theAGENTS.mdpath in the list. Before v2.1.280,/memoryand/contextdidn't list a directly readAGENTS.md, so ask Claude what its project instructions say instead. -
Not loading? Look for a
CLAUDE.md,.claude/CLAUDE.mdorCLAUDE.local.mdin your folder or above (other than~/.claude/CLAUDE.md). Then checkclaude --version. Finally, check that/config→ Project instructions isn't set toclaude-mdormanaged-only. If the setting isn't there at all, your session can't loadAGENTS.md, so use the import. On your first session after upgrading from v2.1.276 or earlier, it can take one more session to start working.
If you want to see what your own AGENTS.md and CLAUDE.md cost in tokens, and where they repeat or contradict each other before you turn on both, we built a free browser-only checker: Clogmeter. For a single file there's the AGENTS.md / CLAUDE.md token counter, and for Cursor rules the Cursor rules token counter.
Top comments (0)