AGENTS.md support has finally reached Claude Code. Version 2.1.277, released on 18 September 2026, lets Anthropic’s coding agent read an AGENTS.md file as its project instructions when a project has no CLAUDE.md. It is a one-line entry in the changelog, but it closes one of the longest-running and most popular feature requests in the Claude Code repository.
For teams that use more than one coding agent, this matters. Until now, a repository that kept its rules in AGENTS.md for OpenAI’s Codex, Cursor, Gemini CLI or GitHub Copilot needed a second file, a symlink or an import line before Claude Code would see those rules. Now, in the simplest case, it just works.
This article explains exactly what changed, where the new behaviour stops, how it compares with the way other agents read the same file, and what a team should do with its repositories this week.
Table of contents
- What Changed in Claude Code 2.1.277
- Why AGENTS.md Became the Common Format
- The Long Road to AGENTS.md Support
- How AGENTS.md Support Works Now
- The Documentation Has Not Caught Up
- Claude Code Versus Other Agents on AGENTS.md
- What Teams Should Do With AGENTS.md Now
- Security and Governance Questions
- What AGENTS.md Support Says About the Agent Market
- A Worked Example: One Repository, Three Agents
- Limits and Open Questions
- AGENTS.md in Claude Code FAQ
- References
What Changed in Claude Code 2.1.277
The change is small in code and large in convenience. Here is what Anthropic shipped, in its own words and in practice.
The changelog entry
The Claude Code changelog for 2.1.277 opens with this line: “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)”. The GitHub release was tagged at 18:06 UTC on 18 September 2026.
The announcement
Minutes later, a user posted the news on the original GitHub request, quoting Anthropic’s Thariq Shihipar (@trq212) on X: “We’re adding support for AGENTS.md to Claude Code. Starting today in version 2.1.277, if there is no CLAUDE.md in a folder, Claude will check for and use AGENTS.md. You can toggle this behavior in /config.”
What it means in plain terms
If your repository has a CLAUDE.md, nothing changes. If it has only an AGENTS.md, Claude Code now loads it as the project instructions it previously ignored. The behaviour can be switched in the /config menu under “Project instructions”.
What it does not do
It is a fallback, not a merge. Claude Code does not read both files and combine them. Where a CLAUDE.md exists, that file wins and the AGENTS.md beside it is still not loaded automatically.
Why AGENTS.md Became the Common Format
To see why developers pushed so hard for this, it helps to know where the file came from and how far it has spread.
A README for agents
The official site at agents.md describes the format as “a simple, open format for guiding coding agents” and as “a README for agents: a dedicated, predictable place to provide the context and instructions to help AI coding agents work on your project”. It is ordinary Markdown with no required fields.
Broad adoption
The same site says the format is “used by over 60k open-source projects”. It lists compatible tools including Codex from OpenAI, Jules and Gemini CLI from Google, Cursor, Aider, goose, opencode, Zed, Warp, VS Code, Devin and Windsurf from Cognition, Junie from JetBrains, Amp, RooCode, Kilo Code, Augment Code and GitHub Copilot’s coding agent.
Why a shared name helps
The site states the goal directly: “Rather than introducing another proprietary file, we chose a name and format that could work for anyone.” One AGENTS.md can hold build commands, test steps and code style for every agent a team uses, which is exactly the duplication Claude Code users wanted to end.
What goes inside
A typical AGENTS.md holds setup commands, test instructions, code style rules and pull request conventions. The sample on the official site includes lines such as “Install deps: pnpm install” and “Always run pnpm lint and pnpm test before committing.” Nothing in the format is specific to one vendor, which is the point.
The Long Road to AGENTS.md Support
Claude Code users asked for this for more than a year. The numbers on the GitHub issue show how strong the demand was.
Issue #6235
The request “Feature Request: Support AGENTS.md.” was opened on 21 August 2025 as issue #6235 in the anthropics/claude-code repository. By 19 September 2026 it had 6,652 reactions, 5,167 of them thumbs-up, and 398 comments. That makes it one of the most visible feature requests the project has had.
A closure that angered users
The issue was closed on 17 August 2026, a month before the feature arrived. Commenters were not pleased. One wrote on 9 September, “LOL, you seriously closed this without resolving?”, and another asked on 17 September for it to be reopened “because it has NOT been implemented.”
The follow-up request
A second request, issue #34235, “support AGENTS.md as a native context file alongside CLAUDE.md”, opened on 14 March 2026 and was still open with 130 reactions. Its title asks for both files to be read together, which 2.1.277 does not do.
The chart below shows how the demand stacked up. Each bar is the count divided by the largest figure, 6,652.
393 days from request to release
From 21 August 2025 to 18 September 2026 is 393 days. For a change that amounts to “look for a second filename”, that is a long wait, and it is fair to ask why it took so long.
How AGENTS.md Support Works Now
The fallback rule is simple, but there are details worth knowing before you delete anything.
The lookup order
Claude Code looks for CLAUDE.md first. Only when there is no CLAUDE.md does it check for AGENTS.md. Thariq Shihipar’s wording, “if there is no CLAUDE.md in a folder”, suggests the check happens per folder rather than once for the whole repository.
The /config toggle
The changelog says the behaviour can be changed under “Project instructions” in /config. That gives teams a way to switch the fallback off, for example where an AGENTS.md was written for a different agent and contains instructions that do not suit Claude.
The provider gap
The feature is “not yet on Bedrock, Vertex or Foundry”. Companies that run Claude Code through Amazon Bedrock, Google Cloud Vertex AI or Microsoft Foundry should keep their existing CLAUDE.md or import line until that changes. A repository shared across both kinds of setup will behave differently depending on who opens it.
Before and after, side by side
| Repository contains | Before 2.1.277 | From 2.1.277 |
|---|---|---|
| CLAUDE.md only | CLAUDE.md loaded | CLAUDE.md loaded |
| AGENTS.md only | No project instructions | AGENTS.md loaded |
| Both files | CLAUDE.md only | CLAUDE.md only |
| CLAUDE.md with @AGENTS.md import | Both, via the import | Both, via the import |
| AGENTS.md only, on Bedrock, Vertex or Foundry | No project instructions | No project instructions (not yet supported) |
The Documentation Has Not Caught Up
Anyone reading the official docs today will find advice that the release has partly overtaken.
What the memory page still says
On 19 September 2026, the Claude Code memory documentation still read: “Claude Code reads CLAUDE.md, not AGENTS.md.” It tells users whose repositories already use AGENTS.md to “create a CLAUDE.md that imports it so both tools read the same instructions without duplicating them”.
The import method
The documented import is a CLAUDE.md whose first line is @AGENTS.md, followed by any Claude-specific rules. The docs give the example of adding “Use plan mode for changes under src/billing/” below the import. Claude loads the imported file at the start of a session and then appends the rest.
The symlink method
The docs also suggest ln -s AGENTS.md CLAUDE.md when no Claude-specific content is needed. They note that on Windows “creating a symlink requires Administrator privileges or Developer Mode, so use the @AGENTS.md import instead.”
Why the old advice still matters
Both methods keep working after 2.1.277, and both still have a job. The import is the only way to have Claude read AGENTS.md and extra Claude-only rules together. The fallback only helps when there is no CLAUDE.md at all.
Claude Code Versus Other Agents on AGENTS.md
Supporting the filename is not the same as supporting it the way every other tool does. The way Codex handles the file shows the gap.
How Codex reads the file
OpenAI’s Codex documentation says Codex “reads AGENTS.md files before doing any work”. It reads a global file from ~/.codex, then walks from the project root down to the current directory, checking each folder for AGENTS.override.md, then AGENTS.md. It joins the files “from the root down”, so closer files override earlier guidance.
Size limits
Codex stops adding files once the combined size reaches project_doc_max_bytes, which is “32 KiB by default”. Claude Code’s own guidance is different in style rather than hard limits: its docs advise to “target under 200 lines per CLAUDE.md file”, because “longer files consume more context and reduce adherence”.
Where the two now line up
| Behaviour | Claude Code 2.1.277 | OpenAI Codex |
|---|---|---|
| Primary file | CLAUDE.md | AGENTS.md |
| Reads AGENTS.md | Only when no CLAUDE.md exists | Always |
| Override file | CLAUDE.local.md for personal notes | AGENTS.override.md |
| Global file | ~/.claude/CLAUDE.md | ~/.codex/AGENTS.md |
| Imports | @path, up to four hops deep | Not described in its guide |
| Size guidance | Under 200 lines advised | 32 KiB combined cap by default |
The remaining difference
The biggest gap is the “both files” case. Codex will happily read an AGENTS.md next to a CLAUDE.md. Claude Code will not, so a repository that keeps both still needs the import line for Claude to see the shared rules. That is what issue #34235 is asking Anthropic to fix.
What Teams Should Do With AGENTS.md Now
The right move depends on what your repositories hold today. Here are the four common starting points.
If you already use the import
Keep it. A CLAUDE.md that starts with @AGENTS.md still loads both, and it is the only setup that lets Claude-specific rules sit alongside the shared file. The new fallback changes nothing for you.
If you only have AGENTS.md
You can now leave it alone, provided everyone on the team runs 2.1.277 or later on Anthropic’s own API or a Claude subscription. Anyone on Bedrock, Vertex or Foundry will still see no project instructions, so check how your developers connect before deleting a CLAUDE.md shim.
If you have both files with different content
This is the case to watch. Claude reads only CLAUDE.md, so any rule that lives only in AGENTS.md is invisible to it. Either move the shared rules into AGENTS.md and import it, or merge the two into one file.
If you are starting fresh
A single AGENTS.md is now a reasonable default for a new repository shared across tools. Add a CLAUDE.md with an import only when you have instructions that are truly specific to Claude, such as plan-mode rules or tool permissions.
A migration checklist
| Step | Action | Why |
|---|---|---|
| 1 | Run claude –version on every machine | The fallback needs 2.1.277 or later |
| 2 | List repositories with both files | Claude ignores AGENTS.md there |
| 3 | Check cloud provider routes | Bedrock, Vertex and Foundry lack the fallback |
| 4 | Run /context in a new session | Confirms which instruction files loaded |
| 5 | Review the /config setting | Decide whether the fallback stays on |
Security and Governance Questions
Instruction files shape what an agent does, so they deserve the same scrutiny as any other code a team commits.
Instructions are an attack surface
A project instruction file is a prompt that runs every time someone opens the repository. That makes it a cybersecurity concern as well as a convenience. A malicious or careless line in a shared AGENTS.md now reaches Claude Code users as well as Codex users, where before it reached only one tool.
Imports already have guard rails
Claude Code’s docs describe an approval dialog for imports that point outside the project, which exists “to protect you from files other people commit to a shared project”. Teams should treat a newly loaded AGENTS.md with the same care, and review it in pull requests like any configuration file.
Keep one owner
The more agents that read one file, the more important it is that someone owns it. Our guide to using AI coding assistants safely in large software projects covers review rules and scoping that apply directly to shared instruction files.
Watch for conflicting rules
Claude Code’s docs warn that “if two rules contradict each other, Claude may pick one arbitrarily.” A team that merges a CLAUDE.md into an AGENTS.md should read the result end to end and remove duplicates before relying on it.
What AGENTS.md Support Says About the Agent Market
The feature is small, but it points to a wider change in how coding agents compete.
Portability is now expected
Developers increasingly run several agents on the same codebase, choosing by task or by price. A format that every tool reads lowers the cost of switching, and a tool that ignores it looks awkward. Anthropic has now moved toward the common format, even if only as a fallback.
Anthropic is building migration paths
The docs also describe /import, which “appends a one-time copy of instruction files such as AGENTS.md to the matching CLAUDE.md” and carries over MCP servers, commands, subagents and skills from other agents. That requires Claude Code v2.1.213 or later. Together with the fallback, it makes moving to Claude Code easier.
Claude Code keeps its own layer
Anthropic has not replaced CLAUDE.md. Rules folders, path-scoped rules, imports and managed policy files all remain CLAUDE-specific. Our coverage of the Claude Desktop sessions hub for Claude Code shows how quickly the tool’s own surface keeps growing.
What to watch next
Three things would complete the picture: support on Bedrock, Vertex and Foundry, an update to the memory documentation, and an answer to issue #34235 on reading both files together. For more releases like this one, see our AI models, tools and releases hub.
A Worked Example: One Repository, Three Agents
Rules on paper are easier to follow with a real setup in mind. Here is a typical mid-sized project and how each tool behaves after the update.
The setup
Imagine a web application in one Git repository. The back-end team uses Codex, two front-end developers use Cursor, and the platform team has adopted Claude Code. The shared file at the root lists the package manager, the test command, the lint command and a rule that database migrations need a second reviewer.
Codex and Cursor
Both tools already read the shared file, so nothing changes for them. Codex also reads any override file in the service folder a developer is working in, which lets the payments team keep stricter rules without touching the root file.
Claude Code before the update
Until this week, the platform team had two choices. Either someone kept a CLAUDE.md that repeated the same rules, which drifted out of date within weeks, or someone added a one-line import that nobody else on the project understood. Both options were a small but constant tax.
Claude Code after the update
With version 2.1.277 or later and no CLAUDE.md in the repository, Claude now loads the shared rules on its own. The migration rule, the test command and the lint command reach all three tools from one place. That is the outcome developers asked for in 2025.
Where it still goes wrong
Suppose the platform team later adds a CLAUDE.md for one Claude-only rule about plan mode. The moment that file exists, the fallback stops and the shared rules vanish from Claude’s view. The fix is to start that new file with the import line, so the shared rules load first and the Claude rule sits below them.
Limits and Open Questions
The update is welcome, but several questions remain unanswered in the public material.
Nested folders
Claude Code loads instruction files from the working directory and every directory above it, and it picks up files in subdirectories when it reads code there. Anthropic has not yet documented how the new fallback behaves in each of those places, for example in a monorepo where only some packages have their own CLAUDE.md.
The default setting
The changelog says the behaviour can be changed in /config, and the announcement calls it a toggle. It does not say whether an administrator can lock the setting across a company through managed settings. Enterprises that need a fixed configuration should test this before relying on it.
Content written for other tools
Many shared files include instructions aimed at a specific agent, such as how to use Codex sandboxes or Cursor rules. Claude will now read those lines too. Teams should reword agent-specific steps as general guidance or move them into each tool’s own file.
Documentation lag
Until the memory page is updated, new users will read that Claude does not support the shared file at all. That mismatch will cause confusion in onboarding guides and internal wikis, so it is worth adding a short note to your own developer documentation now.
AGENTS.md in Claude Code FAQ
Does Claude Code read AGENTS.md now?
Yes, from version 2.1.277, but only when there is no CLAUDE.md. If both files exist, Claude Code reads CLAUDE.md and ignores AGENTS.md unless CLAUDE.md imports it.
Can I delete my CLAUDE.md?
Only if it does nothing but point to AGENTS.md, everyone is on 2.1.277 or later, and nobody connects through Bedrock, Vertex or Foundry. Otherwise, keep the import.
How do I turn the fallback off?
The changelog says to change it under “Project instructions” in /config. That is useful when an AGENTS.md was written for another agent and its rules do not suit Claude.
Does it work on every provider?
No. The changelog says the fallback is “not yet on Bedrock, Vertex or Foundry”. Those users still need a CLAUDE.md.
How can I check which file loaded?
Start a new session and run /context. The docs say instruction files appear under “Memory files”, which shows exactly what Claude is reading.
References
Claude Code changelog (Anthropic, GitHub)
Claude Code v2.1.277 release (GitHub)
Feature Request: Support AGENTS.md, issue #6235 (GitHub)
Support AGENTS.md as a native context file alongside CLAUDE.md, issue #34235 (GitHub)
How Claude remembers your project (Claude Code docs)