Claude Code Now Reads AGENTS.md: What Changed
Anthropic shipped AGENTS.md support in Claude Code 2.1.277 on 18 September 2026. It is a fallback rather than a merge, and that distinction changes who it helps.
Claude Code Now Reads AGENTS.md: What Changed
Anthropic shipped Claude Code 2.1.277 on 18 September 2026 with AGENTS.md support: in a project with no CLAUDE.md file, Claude Code now reads AGENTS.md instead. The official changelog entry is one line, and the practical effect is that a repository shared by several AI coding tools can keep a single instructions file rather than one per vendor. The fallback is configurable under "Project instructions" in /config, and it is not yet available on Bedrock, Vertex or Foundry.
What Claude Code AGENTS.md support actually does
From the Claude Code changelog, version 2.1.277:
Added AGENTS.md support: in a project with no CLAUDE.md, Claude Code reads AGENTS.md instead; change it under "Project instructions" in /config (not yet on Bedrock, Vertex or Foundry).
Three details in that sentence matter more than the headline. It is a fallback, not a merge. It is per folder, not per repository. And it is gated on the managed cloud platforms, so a team on Bedrock or Vertex does not get it yet.
Fallback, not merge: the detail most coverage skipped
Claude Code does not read both files and combine them. If CLAUDE.md exists in a folder, AGENTS.md in that same folder is ignored. That is the opposite of what a lot of teams assumed when the news broke, and it has a concrete consequence: a repository that already carries a CLAUDE.md gets no behaviour change from this release at all. The new path only opens when you delete CLAUDE.md, or when you are working in a project that never had one.
So the upgrade is not automatic in any meaningful sense. If you want the single-file setup, you have to actively remove the Claude-specific file and fold anything unique in it into AGENTS.md. Our guide on how to write an AGENTS.md file covers what belongs in there, and the merge is usually less work than it sounds because most CLAUDE.md files are 80% generic project orientation.
Who this actually helps
Situation | Effect of 2.1.277 |
|---|---|
Repo has CLAUDE.md only | Nothing changes. AGENTS.md is never consulted. |
Repo has AGENTS.md only | Claude Code now picks it up where it previously ignored it. |
Repo has both | CLAUDE.md wins in that folder. AGENTS.md is ignored. |
Monorepo, mixed per package | Resolved folder by folder, so a package can use either. |
Team on Bedrock, Vertex or Foundry | Not available yet, per the changelog. |
The monorepo row is the interesting one. Because the lookup is per folder, a large repository can migrate one package at a time instead of doing a single atomic switch, which is a much easier change to get through review.
Why a shared instructions file matters
The argument for a common file is not tidiness. It is that instructions drift. When a team keeps one file per tool, the files start identical and then diverge, because whoever fixes a wrong instruction fixes it in the file their own tool reads. Six weeks later two agents are working from different rules about the same codebase, and nobody notices until they produce contradictory pull requests.
That failure mode is worth more attention than the convenience angle. A single file does not make your instructions good, it just removes one way for them to silently disagree. If you want the instructions themselves to be better, the constraint to understand first is what an agent harness actually does with the file once it has read it.
What to do this week
Check which file each of your repositories currently carries. A repo with both is now ambiguous to a reader even though the tool resolution is deterministic.
If you want the shared setup, move the content into AGENTS.md and delete CLAUDE.md in that folder rather than leaving both.
Re-read what you moved. Instructions written for one tool often name that tool, and those lines read strangely to a different agent.
If you are on Bedrock, Vertex or Foundry, keep CLAUDE.md for now and revisit when the changelog says the gate has lifted.
Frequently asked questions
Does Claude Code merge CLAUDE.md and AGENTS.md?
No. The changelog describes a fallback. If CLAUDE.md is present in a folder, that file is used and AGENTS.md in the same folder is not read.
Which version added AGENTS.md support?
Version 2.1.277. The following release, 2.1.278, was unrelated and covered auto mode classifier billing.
Can I turn the fallback off?
Yes. The changelog points at "Project instructions" in /config as the toggle for the behaviour.
Does this mean the two formats are now a standard?
It means one more tool reads one more filename. The formats are conventions, not a specification, and reading how the major tools differ underneath is still worth doing: see how the major coding agents compare.
How do I keep track of changes like this?
Vendor changelogs beat news roundups for anything this specific. We wrote up an approach to keeping up with AI tooling news without drowning in it that leans on primary sources for exactly this reason.
How did this land?
About the author
Senior Editor, AI & Product
Cecilia leads the Swarmz editorial desk. She has spent a decade turning complex AI and product topics into writing people actually finish, and she owns the blog's quality bar.
