The brief caught a one-line Claude Code changelog entry at 566 Hacker News points within seven hours. That response is far larger than the patch sounds: teams using several coding agents can finally stop copying the same build rules into a Claude-specific file. Yet release 2.1.277 does not make AGENTS.md universal inside Claude Code. By default, one project CLAUDE.md on the path to the working directory causes Claude Code to use its own files instead, according to Anthropic's release note and the resulting Hacker News thread.
The discussion is a measure of pent-up developer interest, not independent confirmation of how the feature works. Commenters mostly talked about deleting imports and symbolic links used to keep CLAUDE.md aligned with AGENTS.md. The factual center is narrower: Anthropic shipped direct support on September 18 in version 2.1.277, exposed a Project instructions setting in /config, and excluded Bedrock, Vertex, and Foundry at launch, as the official changelog states.
Why mixed repositories can miss the file
Take a repository with both files at its root. Under Claude Code's default claude-md-or-agents-md mode, the presence of CLAUDE.md means AGENTS.md is left out. The same happens if Claude finds .claude/CLAUDE.md or CLAUDE.local.md in the current directory or any directory above it. A personal ~/.claude/CLAUDE.md, an organization's managed file, and files under .claude/rules/ do not trigger that fallback, Anthropic explains in its project memory documentation.
A clean repository containing only AGENTS.md gets simpler behavior. At session start, Claude Code reads every AGENTS.md and .claude/AGENTS.md from the working directory upward. When it later opens a file in a subdirectory, it can attach that directory's AGENTS.md, provided the same directory does not claim the scope with a Claude instruction file. Anthropic's loading rules also say that AGENTS.local.md, AGENTS.override.md, and files inside .agents/ are not read through this feature.
That last detail matters in a monorepo. A root AGENTS.md may load when Claude starts, while a package-level file appears only after the Read tool enters that package. The open-sourced agents-md module documents another edge: nested files attach on text reads, while IDE selections, images, PDFs, and notebook reads do not get the same plugin path. A shared filename removes a maintenance chore, but it does not guarantee that two agent tools assemble identical instruction context.
The default also creates a quiet migration trap. A team may add AGENTS.md, test it in a fresh repository, and assume Claude Code will use it everywhere. An older CLAUDE.local.md higher in a developer's checkout can switch that project back to the Claude file without changing anything in Git. Anthropic's troubleshooting sequence therefore starts by checking the entire path for Claude instruction files, then checking the installed version and the Project instructions setting.
One filename still has several meanings
AGENTS.md is deliberately plain Markdown. It has no required fields, and its public site says more than 60,000 open-source projects use it for setup commands, test procedures, coding conventions, and repository-specific cautions. The format's documentation lists a growing set of compatible tools and describes nested files as the way to narrow instructions for a package or subproject. That broad adoption explains why a small Claude Code patch drew so much attention: the filename has become shared infrastructure for agent-assisted development.
The shared part stops at the file's name and human-readable contents. Codex, for example, searches from the project root down to the current directory, recognizes AGENTS.override.md, and caps its combined project guidance at 32 KiB by default. Files closer to the working directory appear later in its prompt. Those are Codex's documented discovery rules, while Claude Code 2.1.277 uses the fallback and lazy-loading behavior described above. A repository can contain sound instructions and still expose them differently to each harness.
Teams should therefore put the portable core in AGENTS.md: commands that really run, boundaries around generated files, and the tests required for a change. Product-specific controls belong in the product's own configuration when another tool cannot interpret them. The AGENTS.md guide calls the file a place for project context rather than a formal schema, and Anthropic says its instruction files shape model behavior instead of enforcing policy in the client.
This distinction also limits what a migration can promise. Renaming a file does not prove that an agent followed its contents, loaded every nested scope, or resolved two conflicting sentences the same way. Anthropic advises users to make instructions specific and to check for conflicts across loaded files in its memory guide. Portability is useful here because it reduces duplicate text. Reliability still needs observation and tests.
The safest migration keeps an escape hatch
For a repository with only an old shim, the cleanup is straightforward. Anthropic says a CLAUDE.md containing an @AGENTS.md import can remain without causing the shared file to load twice. It can also be removed once every Claude Code environment that touches the repository supports direct loading. The migration guidance recommends keeping the import for sessions that cannot use the built-in feature. A minimal compatibility file is enough:
@AGENTS.md
## Claude Code
Use plan mode for changes under `src/billing/`.
That pattern preserves one common instruction body and leaves room for a Claude-only note. A symbolic link is another documented option, though Anthropic warns that its Edit and Write tools refuse to write through the link. Windows adds a second snag: creating a symbolic link may require Administrator privileges or Developer Mode, and Git can check it out as a plain text file when core.symlinks is disabled. The same migration section recommends the import for teams with Windows users.
Repositories that genuinely need both instruction systems can choose claude-md-and-agents-md under Project instructions in /config. Claude Code then loads both, placing each directory's Claude file before its AGENTS.md, and avoids a duplicate when one file already imports or links to the other. Anthropic says the setting applies from the next message and persists into new sessions. Its configuration example stores the option under the built-in agents-md plugin in user or managed settings. Project-local settings cannot set that plugin option.
Availability remains uneven. Direct loading needs version 2.1.277 or later, and Anthropic says sessions that cannot fetch its feature flags may fall back to Claude files alone. Its examples include Amazon Bedrock, other third-party providers, and sessions with telemetry disabled. The first session after an upgrade can also miss AGENTS.md. Support begins with the following session, according to the documented exceptions. Keeping the one-line import is cheap insurance until every environment in a team has been checked.
Verification has its own wrinkle. A directly loaded AGENTS.md does not appear in /memory or under Memory files in /context. Anthropic tells users to look for the AGENTS.md loaded line at startup or ask Claude to report its project instructions. InstructionsLoaded hooks also do not fire for a directly loaded shared file, though they do when CLAUDE.md imports or links to it. Those differences are listed in Anthropic's comparison of the two file types.
Instructions remain advisory
Neither filename is a security boundary. Claude Code loads these files as context, and the company says the model may decide how to apply them. A rule that must block a tool, command, or path belongs in client-enforced settings. A check that must run at a fixed point belongs in a hook. Anthropic makes that separation explicit in its memory and policy documentation. Moving a denial rule from CLAUDE.md into AGENTS.md does not turn it into enforcement.
Concise files are easier to carry across tools. Anthropic warns that a CLAUDE.md over 200 lines consumes more context and may reduce adherence, while one over 4 MiB is skipped. Its open-sourced agents-md module documents different mechanics for nested shared files, so those numeric limits should not be assumed for every loading path. Anthropic's troubleshooting advice still travels well: exact commands and narrowly scoped rules are easier to verify than a large handbook.
The next useful evidence will be mundane: wider provider support and consistent visibility into which nested instructions reached a session. Watch those details before deleting every compatibility file. Claude Code has joined the common filename, which removes real work for mixed-tool teams. The remaining test is whether a checkout produces the same operative guidance when a developer changes agents, directories, or providers. Anthropic's current support matrix still leaves those cases with different answers.