Blog
Published: October 6, 2026
Yes. Claude Code reads AGENTS.md since v2.1.277, and since v2.1.281 it does so in every session, Bedrock, Vertex and telemetry-off included. By default it reads AGENTS.md only when the project has no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md from the working directory up, and two common moves create one without telling you.
Checked on 2026-10-05 against Claude Code 2.1.289, and again on 2026-10-06 against 2.1.291, using the memory docs, the changelog, the plugin's own README and the open issues linked below. Answers written before September say no. Answers written in the week after launch say it needs telemetry on. Both were right when they were written.
Which version of Claude Code supports AGENTS.md? #
| Version | Published | What changed |
|---|---|---|
| 2.1.277 | 2026-09-18 | “In a project with no CLAUDE.md, Claude Code reads AGENTS.md instead.” The mode is a row in /config . Sessions without fetched feature flags (telemetry off, Bedrock, Vertex, Foundry, gateways) still skipped it. |
| 2.1.281 | 2026-09-23 | “Changed AGENTS.md support to also work on Amazon Bedrock, Google Vertex AI, Microsoft Foundry, LLM gateways, and sessions with telemetry disabled.” |
It closed a long wait. The feature request, anthropics/claude-code#6235, was opened in August 2025 and had over 5,000 thumbs up when it was closed on 2026-08-17. If you are on 2.1.277 to 2.1.280 and run with telemetry off or through a cloud provider, update; that is the whole fix.
What are the instructionFiles modes? #
The support ships as a built-in plugin, agents-md, with one option, instructionFiles. It takes four values.
| Mode | What Claude Code loads | When to pick it |
|---|---|---|
claude-md |
CLAUDE.md files only, exactly as before 2.1.277. |
You want no change in behaviour. |
claude-md-or-agents-md |
The default. CLAUDE.md files, orAGENTS.md files when the project has none. |
A repo set up for Codex or Cursor that never had a CLAUDE.md. |
claude-md-and-agents-md |
Both. In each directory the CLAUDE.md files come first and theAGENTS.md after. A file already imported or symlinked is not read twice. |
Shared rules in AGENTS.md plus Claude-only notes in CLAUDE.md. Also the fix for both traps below. |
managed-only |
Only the organization's managed CLAUDE.md and auto memory at launch. Project, local and user files and everyAGENTS.md are dropped. |
Reviewing an untrusted repo, or a locked-down fleet. |
The option was first keyed projectInstructions, with the values claude, agents-fallback, both and none. The README says a value stored under the old key is still honoured for now, and the transcript says how it was read.
Where do I set it? #
In a session, /config and the row called Project instructions. By hand, in ~/.claude/settings.json, a --settings file, or managed settings. The docs now give the plugin's ID as cc-plugin-agents-md@builtin. Before v2.1.285 it was agents-md@builtin, and 2.1.285 and later read either:
{
"pluginConfigs": {
"cc-plugin-agents-md@builtin": {
"options": { "instructionFiles": "claude-md-and-agents-md" }
}
}
}
A project's .claude/settings.json is not read for this option, and neither is .claude/settings.local.json. You cannot commit the mode to a repo and have every teammate pick it up. Each person sets it for themselves, or an admin sets it in managed settings. A change applies from the next message you send.
What happens if both AGENTS.md and CLAUDE.md exist? #
Under the default, Claude Code reads your CLAUDE.md files and ignores AGENTS.md. The check is narrower than it sounds.
- These count and switch
AGENTS.mdoff: aCLAUDE.md,.claude/CLAUDE.mdorCLAUDE.local.mdin the working directory or any directory above it. - These do not count and load alongside
AGENTS.md: your~/.claude/CLAUDE.md, the organization's managedCLAUDE.md, and.claude/rules/files. - Never read :
AGENTS.local.md,AGENTS.override.md(a Codex convention), and anything under.agents/.
Why is Claude Code ignoring my AGENTS.md? #
Since 2.1.281 the answer is almost always a file that counts as a CLAUDE.md. Two ways to get one are easy to miss, and neither prints a warning.
A CLAUDE.local.md. It is the personal, gitignored file. Add one to keep your own notes in a repo that runs on AGENTS.md, and Claude stops reading AGENTS.md for you, and only for you. anthropics/claude-code#96117 reproduces it five runs out of five, including a CLAUDE.local.md in a subdirectory switching off the root's AGENTS.md. The memory docs now say so in a note.
Running /init. It writes a CLAUDE.md even when the project keeps its instructions in AGENTS.md, and under the default mode that new file takes over. The command a new teammate runs to set up is the one that drops the shared rules. anthropics/claude-code#97004 was still open on 2026-10-05, and the /init prompt in 2.1.286 still targets CLAUDE.md.
The fix for both is the same: set the mode to claude-md-and-agents-md, or put @AGENTS.md at the top of the CLAUDE.md. The rarer causes:
- You are on a version before 2.1.277, or on 2.1.277 to 2.1.280 with telemetry off or a cloud provider.
- It is the first session after upgrading from 2.1.276 or earlier. The docs say Claude reads AGENTS.md from the next session on.
- The built-in
agents-mdplugin is turned off in/plugin.
The quickest tell: if /config has no Project instructions row, this session cannot load AGENTS.md at all. Past that, the sources disagree. The memory docs say a loaded file shows a line such as no CLAUDE.md found; AGENTS.md loaded: /home/you/repo/AGENTS.md in the conversation, and that /memory lists it. The plugin's README, changed on 2026-09-30, says the line goes to the debug log and that /memory does not know AGENTS.md files. If you see neither, run claude --debug, or ask Claude what its project instructions say.
How did you use AGENTS.md with Claude Code before? #
Four workarounds were common. The docs now say what to do with each.
- A
CLAUDE.mdcontaining@AGENTS.md. Keep it if theCLAUDE.mdholds anything else. The import never causes a double read, whatever the mode, and it keeps a laterCLAUDE.local.mdor/initfrom switching the shared file off. - A
CLAUDE.mdsymlinked toAGENTS.md. Harmless; Claude reads the content once. On Windows clones Git checks the link out as a one-line text file unlesscore.symlinksis on. - A
SessionStarthook that printsAGENTS.md. Remove it. With native support it adds a second copy. - A
CLAUDE.mdthat says “read AGENTS.md” . Replace the sentence with an import. In words, Claude only sees the file if it decides to open it.
For a team, the one-line import is still the setup that survives what each person adds to their own checkout:
@AGENTS.md
Is AGENTS.md treated exactly like CLAUDE.md? #
Almost. Per the docs, an AGENTS.md read through the setting does not fire InstructionsLoaded hooks, does not load from --add-dir directories, and loads an @ import from outside the working directory only if you already approved external imports for that project. A nested one attaches when Claude opens a file in that directory with the Read tool, or, since v2.1.290, when a file under it is @-mentioned, as long as the directory has no CLAUDE.md of its own. For most repos none of this matters. For a monorepo with per-package files, it is worth a test.
One file for every agent. Who keeps it true? #
Native support settles where the instructions live. Claude Code, Codex, Cursor, Copilot and Antigravity CLI can now all read one AGENTS.md; the comparison is in AGENTS.md vs CLAUDE.md. It does not settle who writes the file, or when a line in it stops being true.
Take one decision. In #eng-payments the team agrees that webhook handlers acknowledge with a 200 and enqueue, and never do the work inline. That line reaches AGENTS.md only if someone remembers to open a pull request. When the queue is replaced next quarter, the line stays until someone remembers to delete it.
Harbor is built for that gap. It reads where the team already decides: Slack, pull request review threads, docs. A person approves what it finds, or you let policy approve the routine ones; you set the gate. Each agent gets the facts that apply to its task on the first turn, and Harbor counts how often each one was served and how often an answer cited it, so a line that is served and never cited shows up. harbor init installs the hooks for Claude Code, Codex and Cursor in one pass. The quickstart takes a few minutes.
Related: whether to commit CLAUDE.md and the .claude folder, and how long the file should be once every agent is reading it.
Questions #
Why is Claude Code ignoring my AGENTS.md?
Almost always because a CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md exists in the working directory or above it, which switches AGENTS.md off under the default mode. A personal CLAUDE.local.md and running /init both create one without a warning. On 2.1.277 to 2.1.280, telemetry off or a cloud provider such as Bedrock also skipped it; 2.1.281 fixed that.
Does Claude Code read AGENTS.md on Bedrock or Vertex?
Yes, since v2.1.281, published 2026-09-23. Before that, sessions on Amazon Bedrock, Google Vertex AI, Microsoft Foundry, LLM gateways or with telemetry disabled read CLAUDE.md files only.
Can I set instructionFiles in the project .claude/settings.json?
No. Claude Code reads the option only from ~/.claude/settings.json, a --settings file, or managed settings. Project and local settings files are ignored for it, so each person or an admin has to set it.
Do I still need a CLAUDE.md with @AGENTS.md?
On a team, it is still the safest setup. The import never makes Claude read the file twice, and it keeps AGENTS.md when someone adds a CLAUDE.local.md or runs /init, both of which switch the default fallback off.
How do I load both CLAUDE.md and AGENTS.md in Claude Code?
Set Project instructions in /config to claude-md-and-agents-md, or set pluginConfigs cc-plugin-agents-md@builtin options instructionFiles (agents-md@builtin before v2.1.285) to that value in your user settings. Each directory's CLAUDE.md files load first and its AGENTS.md after them.