Claude Code AGENTS.md: When It's Read, vs CLAUDE.md, and How to Use Both (Tested)
Claude Code reads AGENTS.md since 2.1.277, but only when no CLAUDE.md or CLAUDE.local.md sits in your project or above it. What I saw in seven folder setups, AGENTS.md vs CLAUDE.md, why Claude Code ignores your AGENTS.md, and how to make it read both.
Yes, Claude Code reads AGENTS.md, since version 2.1.277. But by default it reads it only when there is no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in your working directory or any folder above it. If one exists, Claude Code reads that and skips AGENTS.md without a warning. To have it read both, put @AGENTS.md at the top of your CLAUDE.md, or change Project instructions in /config from its default, claude-md-or-agents-md, to claude-md-and-agents-md. I tested seven folder setups on Claude Code 2.1.302, and each behaved as Anthropic's docs describe.
| Your project has | Claude Code reads | To read both |
|---|---|---|
AGENTS.md only | AGENTS.md | Nothing to do |
AGENTS.md and CLAUDE.md | CLAUDE.md only | @AGENTS.md at the top of CLAUDE.md |
AGENTS.md and CLAUDE.local.md | CLAUDE.local.md only | /config → Project instructions → claude-md-and-agents-md |
CLAUDE.md that contains @AGENTS.md | Both, AGENTS.md first | Already done |
AGENTS.md and your ~/.claude/CLAUDE.md | Both: the user file doesn't count | Nothing to do |
AGENTS.local.md or .agents/AGENTS.md | Neither | Rename to AGENTS.md, or import it |
Last reviewed 21 November 2026, against Anthropic's memory docs and the Claude Code changelog to 2.1.330. I ran the tests on Claude Code 2.1.302 on Windows 11, with claude -p, Haiku 5.5 and default settings, in throwaway folders under my temp directory with no CLAUDE.md above them. Each run cost under a cent at list price.
Does Claude Code read AGENTS.md?
Yes. Claude Code 2.1.277 and later reads AGENTS.md as your project instructions when you have no CLAUDE.md of your own. The changelog entry for 2.1.277 says it in one line: "in a project with no CLAUDE.md, Claude Code reads AGENTS.md instead; change it under "Project instructions" in /config". Before that release you had to import the file from a CLAUDE.md, so older guides that say Claude Code ignores AGENTS.md describe versions before 2.1.277.
Here's which files count for that "no CLAUDE.md" check, from Anthropic's memory docs:
- Count, so Claude Code reads them instead of
AGENTS.md: aCLAUDE.md,.claude/CLAUDE.mdorCLAUDE.local.mdin your working directory or any directory above it. - Don't count, and load alongside
AGENTS.md: your~/.claude/CLAUDE.md, your organization's managedCLAUDE.md, and.claude/rules/files.
That second list matters. My machine has a ~/.claude/CLAUDE.md full of personal rules, and Claude Code still read AGENTS.md in every test folder that had no project CLAUDE.md.
How I tested which file Claude Code reads
I gave every instruction file a different codeword, then asked Claude to list the codewords in its project instructions with all file tools blocked, so it could only answer from what Claude Code had loaded at startup. The command, run inside each folder:
claude -p "Without using any tools, list every codeword that appears in your project instructions (not in user-level instructions). Reply with just the codewords separated by commas, or NONE." \
--model haiku --strict-mcp-config \
--disallowedTools "Read Bash Glob Grep LS PowerShell" --output-format jsonWhat came back, verbatim:
| Folder | Files | Claude's answer |
|---|---|---|
| a | AGENTS.md (FALCON-AGENTS) | FALCON-AGENTS |
| b | AGENTS.md + CLAUDE.md (OTTER-CLAUDE) | OTTER-CLAUDE |
| c | AGENTS.md + CLAUDE.md whose first line is @AGENTS.md | FALCON-AGENTS, OTTER-CLAUDE |
| d | AGENTS.md + CLAUDE.local.md (LYNX-LOCAL) | LYNX-LOCAL |
| e | AGENTS.local.md + .agents/AGENTS.md only | NONE |
| f | Same as b, run with --settings holding the claude-md-and-agents-md JSON shown further down | OTTER-CLAUDE, FALCON-AGENTS |
| g | Run from child/, with AGENTS.md and .claude/AGENTS.md in the parent | GULL-PARENT, WREN-DOTCLAUDE |
Folder d is the one that catches people: one personal CLAUDE.local.md and the team's AGENTS.md silently drops out of your session. Folder f listed the CLAUDE.md codeword first, which is consistent with the order the docs give for the "both" setting: each folder's CLAUDE.md first, its AGENTS.md after. Folder g shows Claude Code walking up the tree for AGENTS.md exactly as it does for CLAUDE.md.
What is AGENTS.md?
AGENTS.md is a plain Markdown file, usually at the root of a repository, that tells AI coding agents how to work on the project: build and test commands, code style, and conventions. It is an open format rather than one vendor's file, so Codex, Cursor, Copilot, Gemini CLI, Claude Code and other agents can all read the same instructions. Think of it as a README written for agents instead of people.
AGENTS.md vs CLAUDE.md: what's the difference?
They hold the same kind of content, project instructions in plain Markdown, but CLAUDE.md is Claude Code's own file and AGENTS.md is a shared format that other coding agents read too. The AGENTS.md project lists Codex, Cursor, Copilot, Gemini CLI, Jules, Aider, Zed, Warp and others as readers, and it is now stewarded by the Agentic AI Foundation under the Linux Foundation. If your team uses more than one agent, AGENTS.md is the file they can all share.
Inside Claude Code, an AGENTS.md that it reads directly behaves like a CLAUDE.md in most ways: @path imports expand, claudeMdExcludes patterns apply, and a subdirectory's file loads when Claude opens a file there with the Read tool. The docs list three places it differs:
CLAUDE.md | AGENTS.md read through Project instructions (not imported) | |
|---|---|---|
InstructionsLoaded hooks | Fire | Don't fire (they do for an AGENTS.md that a CLAUDE.md imports or symlinks to) |
Folders added with --add-dir, with CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD set | Their CLAUDE.md loads | Their AGENTS.md doesn't |
An @path import of a file outside your working directory | Claude Code asks you to approve it | Loads only if you already approved external imports for this project, with no prompt |
If you rely on an InstructionsLoaded hook for auditing, or on --add-dir for a shared folder, import AGENTS.md from a CLAUDE.md rather than letting Claude Code read it directly.
Why is Claude Code ignoring my AGENTS.md?
Almost always because a CLAUDE.md or CLAUDE.local.md exists somewhere on the path from your project folder up to the filesystem root. Work through these in order:
- Look for a blocking file. Check your working directory and every folder above it, other than
~/.claude/, forCLAUDE.md,.claude/CLAUDE.mdorCLAUDE.local.md. In a monorepo, aCLAUDE.mdat the repository root blocks every package'sAGENTS.md. - Check your version. Run
claude --version. You need 2.1.277 or later, and 2.1.281 or later on Amazon Bedrock, Google Cloud's Agent Platform (Vertex AI), Microsoft Foundry, an LLM gateway, or with telemetry off. - Check the setting. Type
/configand find Project instructions. If it saysclaude-mdormanaged-only, change it. If the setting isn't there at all, your session can't loadAGENTS.mddirectly. - Check the plugin. The reader is a built-in plugin,
cc-plugin-agents-md@builtin. If you disabled it in/plugin, re-enable it. - Start a new session. In some cases the first session after upgrading from 2.1.276 or earlier skips
AGENTS.md; the docs say it loads from the next one.
| Symptom | Cause | Fix |
|---|---|---|
Claude follows CLAUDE.md but not AGENTS.md | Default claude-md-or-agents-md picked CLAUDE.md | @AGENTS.md at the top of CLAUDE.md |
AGENTS.md stopped working after you added personal notes | CLAUDE.local.md counts as a CLAUDE.md | Set Project instructions to claude-md-and-agents-md |
No Project instructions row in /config | Version before 2.1.277, plugin disabled, or first session after upgrade | Update, re-enable in /plugin, or start a new session |
| Works locally, not on Bedrock or Vertex AI | Version before 2.1.281 | claude update |
A package's AGENTS.md is ignored in a monorepo | A root CLAUDE.md blocks it | Import it, or use the "both" setting |
Instructions from an unexpected AGENTS.md appear | One sits in a folder above your project | Move or delete it, or add it to claudeMdExcludes |
AGENTS.local.md or AGENTS.override.md ignored | Claude Code doesn't read those names | Rename to AGENTS.md, or move it to CLAUDE.local.md and set Project instructions to claude-md-and-agents-md |
How do I check which file Claude Code loaded?
Run /memory and look for your AGENTS.md path in the list, or run /context all and look under Memory files. Both list a directly read AGENTS.md from 2.1.280 on; before that, the docs suggest asking Claude what its project instructions say, which is what my codeword test does.
Anthropic's docs also say an interactive session shows a line such as no CLAUDE.md found; AGENTS.md loaded: /home/you/repo/AGENTS.md. Reading the bundled code of Claude Code 2.1.329, I found that message sent to the debug log rather than the conversation. That differs from the docs, so if you don't see the line, trust /memory instead.
How do I make Claude Code read both AGENTS.md and CLAUDE.md?
Use an import if you want a setup that works everywhere; use the setting if you only need it on your own machine.
Option 1: import AGENTS.md from CLAUDE.md. This is the one I'd commit to a shared repository, because it works on every version, in every session type, and needs no per-user setting:
@AGENTS.md
## Claude Code
Use plan mode for changes under `src/billing/`.Claude reads the imported file first, then the rest of CLAUDE.md; folder c in my test listed the codewords in that order. Keeping the import never makes Claude Code read AGENTS.md twice, even with the "both" setting on.
Option 2: change Project instructions. Type /config, find Project instructions, and pick one of these four values:
| Value | What Claude Code reads |
|---|---|
claude-md-or-agents-md (default) | CLAUDE.md files, or AGENTS.md when you have no CLAUDE.md or CLAUDE.local.md |
claude-md-and-agents-md | Both: each folder's CLAUDE.md files first, then its AGENTS.md |
claude-md | CLAUDE.md files only |
managed-only | Only your organization's managed CLAUDE.md and auto memory at launch |
To set it in a file instead, add it to your user ~/.claude/settings.json. Claude Code ignores this entry in project and local settings files, so you can't commit it for your team:
{
"pluginConfigs": {
"cc-plugin-agents-md@builtin": {
"options": { "instructionFiles": "claude-md-and-agents-md" }
}
}
}Before 2.1.285 the plugin ID was agents-md@builtin; 2.1.285 and later read either. My folder f test passed the same JSON with --settings, which Claude Code also honours. To start from a template, my CLAUDE.md and AGENTS.md generator builds both files and flags stray @ imports, and the settings builder checks the JSON.
Should I symlink CLAUDE.md to AGENTS.md?
Only if nobody on the project uses Windows. On macOS and Linux, ln -s AGENTS.md CLAUDE.md gives Claude Code a CLAUDE.md that is your AGENTS.md, and Claude Code reads the content once. The docs list two catches:
- Windows: creating a symlink needs Administrator rights or Developer Mode, and Git checks a committed symlink out as a one-line text file unless
core.symlinksis on. That clone ends up with aCLAUDE.mdthat just saysAGENTS.md. - Editing: Claude's Edit and Write tools refuse to write through a symlink and point Claude at the target,
AGENTS.md, instead.
The @AGENTS.md import has neither problem, and it lets you add Claude-only lines underneath. If you already have a symlink, you can leave it: the docs say nothing needs to change.
Where does Claude Code look for AGENTS.md?
In your working directory and every folder above it at startup, and in a subdirectory when Claude opens a file there with the Read tool. In each folder it looks for both AGENTS.md and .claude/AGENTS.md, as my folder g test showed. A subdirectory's AGENTS.md loads only if that subdirectory has none of the three CLAUDE.md files of its own.
It does not read AGENTS.local.md, AGENTS.override.md, or anything under a .agents/ folder, even though some other agents use those names.
There's no separate global AGENTS.md setting. Your global instructions file is ~/.claude/CLAUDE.md, and it loads alongside a project's AGENTS.md without blocking it. But because Claude Code walks upward, an AGENTS.md in your home folder, or in a folder like Downloads where you unpack other people's projects, loads into every project beneath it that has no CLAUDE.md. Check the folders above a project before you trust what Claude has been told.
Should I switch my CLAUDE.md to AGENTS.md?
If you use more than one coding agent, yes: move the shared instructions into AGENTS.md and keep a short CLAUDE.md that imports it. If you only use Claude Code, there's no reason to switch; CLAUDE.md gets the hooks and --add-dir behaviour that a directly read AGENTS.md doesn't.
If you set Claude Code up to read AGENTS.md before 2.1.277, the docs say what to do with each old workaround:
- A
CLAUDE.mdthat says in words "read AGENTS.md": replace the sentence with an@AGENTS.mdimport, or delete the file. Words only work if Claude decides to open the file. - A
SessionStarthook that printsAGENTS.md: remove it, or Claude gets two copies. - A
CLAUDE.mdwith@AGENTS.md, or a symlink: leave them.
Going the other way, from AGENTS.md to a CLAUDE.md, Claude Code has two commands. /init with CLAUDE_CODE_NEW_INIT=1 set reads your AGENTS.md into the CLAUDE.md it generates, and /import appends a one-time copy of AGENTS.md to the matching CLAUDE.md. Both make a copy, so the two files can drift apart afterwards; the @AGENTS.md import doesn't.
Either way, keep the file short. Every line of AGENTS.md or CLAUDE.md loads into context at the start of every session, so a long one costs tokens all session; I measured where Claude Code's tokens go in why Claude Code uses so many tokens. Anthropic's advice for CLAUDE.md is to target under 200 lines per file, and it applies equally to AGENTS.md. My guide to writing a CLAUDE.md applies to an AGENTS.md too.
How does Claude Code's AGENTS.md support compare with Cursor's?
Cursor reads AGENTS.md natively, nested files included, while Claude Code treats it as a fallback for CLAUDE.md. Cursor also has its own .mdc rule files, each declaring when it applies, per Cursor's rules docs. I compared the two loaders in detail in Claude Code vs Cursor: AGENTS.md, CLAUDE.md and Cursor rules, and my Cursor rules converter turns .mdc or .cursorrules files into AGENTS.md or CLAUDE.md and lists what doesn't carry over.
Which Claude Code versions changed AGENTS.md support?
| Version | Change |
|---|---|
| 2.1.277 | Added: with no CLAUDE.md, Claude Code reads AGENTS.md instead; Project instructions in /config |
| 2.1.280 | /memory and /context list an AGENTS.md that Claude Code read directly (per the docs) |
| 2.1.281 | Works on Amazon Bedrock, Google Vertex AI, Microsoft Foundry, LLM gateways and with telemetry off |
| 2.1.285 | Settings ID renamed from agents-md@builtin to cc-plugin-agents-md@builtin; both still read (per the docs) |
| 2.1.290 | Fixed a subdirectory's AGENTS.md not being attached when a file under it is @-mentioned |
| 2.1.290 | Fixed an AGENTS.md symlinked outside the working folders loading despite blockReadsOutsideWorkingDirectories or a Read deny rule |
| 2.1.330 | Fixed the Project instructions picker in /config showing only one of its four choices in a 24-row fullscreen window |
Key takeaways
- Claude Code reads AGENTS.md since 2.1.277, but by default only when no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md is in your project folder or above it.
- A personal CLAUDE.local.md silently turns AGENTS.md off; your ~/.claude/CLAUDE.md does not.
- To read both, put @AGENTS.md at the top of CLAUDE.md (works everywhere) or set Project instructions to claude-md-and-agents-md in /config (your machine only).
- Claude Code walks upward for AGENTS.md and .claude/AGENTS.md, so a file in a parent folder loads too. It never reads AGENTS.local.md or .agents/.
- Check what loaded with /memory or /context all. On Bedrock, Vertex AI or a gateway, you need 2.1.281 or later.
- Prefer the @AGENTS.md import over a symlink if anyone uses Windows.
FAQ
Frequently asked questions
Does Claude Code read AGENTS.md?
Yes, since Claude Code 2.1.277, but by default only when your project has no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in the working directory or any folder above it. If one of those exists, Claude Code reads it and skips AGENTS.md. Your personal ~/.claude/CLAUDE.md doesn't count for that check, so it never blocks AGENTS.md.
What is the difference between AGENTS.md and CLAUDE.md?
AGENTS.md is the shared file; CLAUDE.md is Claude Code's own. Both are Markdown files of instructions a coding agent reads before it works on your repository, and AGENTS.md is an open format that Codex, Cursor, Copilot, Gemini CLI and many other agents read. Claude Code treats an AGENTS.md read through its Project instructions setting much like a CLAUDE.md, with three differences: InstructionsLoaded hooks don't fire for it, --add-dir folders don't load it, and an @path import outside your working directory loads only if you already approved external imports for the project.
Why is Claude Code ignoring my AGENTS.md?
Usually a CLAUDE.md or CLAUDE.local.md sits in your project folder or a folder above it, so Claude Code reads that instead. Other causes: a Claude Code version before 2.1.277, Project instructions set to claude-md or managed-only in /config, the built-in AGENTS.md plugin disabled in /plugin, or the first session right after upgrading from 2.1.276 or earlier. Run /memory to see which files actually loaded.
How do I make Claude Code read both AGENTS.md and CLAUDE.md?
Put @AGENTS.md on the first line of your CLAUDE.md and add any Claude-only instructions below it; this works in every session and on every platform. Or open /config and set Project instructions to claude-md-and-agents-md, which reads each folder's CLAUDE.md files first and its AGENTS.md after them. In my test on Claude Code 2.1.302 both methods loaded both files.
Should I symlink CLAUDE.md to AGENTS.md?
It works on macOS and Linux with ln -s AGENTS.md CLAUDE.md, but Anthropic's docs recommend the @AGENTS.md import if anyone uses Windows: creating a symlink there needs Administrator rights or Developer Mode, and Git checks a committed symlink out as a one-line text file unless core.symlinks is on. Claude's Edit and Write tools also refuse to write through the link.
Is there a global AGENTS.md for Claude Code?
Not as a setting. The global file is ~/.claude/CLAUDE.md, and it loads alongside AGENTS.md without blocking it. But Claude Code reads AGENTS.md and .claude/AGENTS.md in every folder above your project, so one placed in your home folder loads for every project beneath it that has no CLAUDE.md. My parent-folder test loaded both files from one level up.
Does CLAUDE.local.md stop Claude Code reading AGENTS.md?
Yes. CLAUDE.local.md counts as a CLAUDE.md for the check, so adding one for your own uncommitted notes makes Claude Code read it instead of your AGENTS.md. In my test a folder with AGENTS.md and CLAUDE.local.md loaded only CLAUDE.local.md. To keep both, set Project instructions to claude-md-and-agents-md in /config.
Does Claude Code read AGENTS.local.md or .agents/AGENTS.md?
No. Anthropic's docs list AGENTS.local.md, AGENTS.override.md and anything under a .agents/ folder as not read, and in my test a folder holding only AGENTS.local.md and .agents/AGENTS.md gave Claude no project instructions at all.
Related
References
- How Claude remembers your project: AGENTS.md (Claude Code docs)code.claude.com · accessed 2026-11-21
- Claude Code changelog: AGENTS.md support, 2.1.277 to 2.1.330github.com · accessed 2026-11-21
- AGENTS.md: a simple, open format for guiding coding agentsagents.md · accessed 2026-11-21
- Rules (Cursor docs)cursor.com · accessed 2026-11-21
Last reviewed November 21, 2026
Tahir Nazir
Senior AI Engineer & Full-Stack Lead
5+ years shipping AI-powered products — RAG pipelines, agentic workflows, and MCP tooling. Top Rated on Upwork with a 100% job success score.
More about Tahir →Related articles
Claude Code vs Cursor: AGENTS.md, CLAUDE.md and Cursor Rules Compared
Claude Code now reads AGENTS.md, but only when there is no CLAUDE.md, and a personal CLAUDE.local.md quietly turns that off. How both tools load AGENTS.md, CLAUDE.md and Cursor rules, and how to keep one repo working in both.ComparisonAI Engineering13 min readClaude Code Tokens: How Many It Uses, How to See Them, and How to Cut Them
A two-token prompt made Claude Code process about 38,000 tokens before it answered, and 54,000 with my plugins and MCP servers loaded. Where Claude Code's tokens go, how to see them with /usage, /context and the status line, what it costs, why usage climbs while you're idle, and the changes that actually cut it.TroubleshootingAI Engineering19 min readClaude Code Mods: What They Are, Examples, and How to Install or Make One
Claude Code mods are plugins whose JavaScript runs inside Claude Code: they can draw panes, add instant /commands and step into tool calls. What a mod can do, Anthropic's sample and built-in mods, how to install one safely, a first mod tested on Claude Code 2.1.302 with the real validate and test output, and why a mod does nothing.How-toAI Engineering22 min read
Follow along
New posts land here first. Follow along by RSS, or get in touch if you are building something similar.