# Claude Code Reads AGENTS.md, but Only as Plan B **Summary:** Claude Code 2.1.277 can read AGENTS.md when CLAUDE.md is absent. That cuts duplicate setup for multi-agent repos, but teams still need one declared source of truth. - Canonical: https://markhuang.ai/news/claude-code-agents-md-is-plan-b - Language: en - Author: [Mark Huang](https://markhuang.ai/about) - Published: 2026-09-18 - Section: News - Tags: Claude Code, AGENTS.md, Coding Agents, Developer Tools, Repository Instructions - Source: [Claude Code Docs](https://code.claude.com/docs/en/changelog) - License: https://creativecommons.org/licenses/by-nc/4.0/ --- ![Two blank instruction documents follow separate illuminated paths into one coding-agent core](https://cdn.markhuang.ai/news/claude-code-agents-md-is-plan-b/hero.webp) *Claude Code now has a second path for project instructions, but the two paths do not carry equal weight.* Claude Code [version 2.1.277](https://code.claude.com/docs/en/changelog), dated September 18, 2026, adds native support for `AGENTS.md`. The important clause sits after the colon: Claude Code reads it in a project with no `CLAUDE.md`. Anthropic also says the feature is not yet available on Amazon Bedrock, Google Vertex AI, or Microsoft Foundry. I like the change because it removes a small but persistent tax for repositories used with more than one coding agent. Calling it instruction-file convergence would oversell it. Claude treats `AGENTS.md` as a backup, so teams still need to know which file the session loaded. ## One file can cross another tool boundary The case for `AGENTS.md` is deliberately unglamorous. The [format's official site](https://agents.md/) describes it as a predictable place for build steps, tests, and repository conventions, and says more than 60,000 open-source projects use it. A team can keep human onboarding in `README.md` and put agent-specific working rules in a separate file. That becomes useful when the repository moves between tools. [GitHub's Copilot CLI documentation](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-custom-instructions), for example, lists `AGENTS.md`, `CLAUDE.md`, and `GEMINI.md` among the instruction files it can discover. Claude Code joining the convention means a repository that has standardized on `AGENTS.md` can now open in Claude Code without immediately adding a vendor-named duplicate. The clearest benefit is for maintainers who want to try several agents without copying the same rules. Open-source projects also cannot predict which tool a contributor will bring. Fewer near-identical instruction files means fewer chances for a test command or review rule to drift. It is a welcome quality-of-life improvement with a sharper boundary than the headline suggests. ## The fallback rule creates a quiet fork Anthropic's wording establishes a simple precedence rule: if `CLAUDE.md` exists, the new fallback condition is not met. The release note does not say Claude Code merges the two files or warns when both are present. It says users can change the choice under "Project instructions" in `/config`. That makes an old compatibility shim surprisingly important. A repository might already contain a short `CLAUDE.md` that points at shared guidance, adds Claude-only behavior, or has simply been forgotten. After upgrading, a maintainer may add a complete `AGENTS.md` and assume Claude Code has adopted it. The stale vendor file can still keep the fallback from activating. > **Info:** > > Treat the upgrade as a precedence change that needs verification before deleting anything. Open `/config`, inspect "Project instructions," and give the agent a harmless task whose expected behavior depends on one distinctive rule. This is the same product boundary I care about when [separating Claude's model prompt from the Claude Code harness](https://markhuang.ai/news/claude-public-system-prompt-product-boundary). A rule can sit in Git and have no effect because the product never loaded it into the active context. I want the product to show me both discovery and precedence. ## The first reaction was migration anxiety The early public discussion is small, so I would not turn it into a referendum. It is still revealing. In one [r/ClaudeAI thread](https://www.reddit.com/r/ClaudeAI/comments/1wjxvwz/claude_code_is_getting_native_agentsmd_support/), the first practical question was whether users should delete `CLAUDE.md`. A reply argued for keeping Claude-specific structure and pointing one file at the other. In a separate [r/ClaudeCode thread](https://www.reddit.com/r/ClaudeCode/comments/1wk2q8v/agentsmd_now_supported_in_claude_code/), one user praised the portability for people using both Claude Code and Codex, while another wanted Claude Code to discover skills under `.agents/skills` too. People are using "support" to mean two different things. The first is basic filename compatibility: can the tool read the shared root instructions at all? Version 2.1.277 says yes, under its fallback condition. The harder expectation is that nested instructions, skills, imports, and precedence work consistently across tools. This changelog entry makes no such promise. The skeptical objection is fair: teams could already maintain two small Markdown files, use a link, or make one file import the other. Native support saves little work in a single repository. My answer is that conventions earn their value across repositories and contributors. Every private workaround is another thing that can break in a clone, a different operating system, or a tool that interprets links and imports differently. ## I would choose one canonical file For a repository meant to work across coding agents, I would make `AGENTS.md` the canonical home for shared commands, architecture notes, review expectations, and safety limits. If Claude needs extra guidance, I would keep `CLAUDE.md` short and explicit about where the common rules live. I would not maintain two full copies. Then I would test the setup in every supported surface the team actually uses. The provider caveat matters here. A local Claude Code session can support the fallback while a Bedrock, Vertex, or Foundry deployment does not yet have it. Until Anthropic closes that gap, deleting `CLAUDE.md` could fix portability on one machine and remove instructions somewhere else. I welcome Claude Code's adoption of `AGENTS.md` because repository instructions should travel with the repository. Success looks like one maintained set of rules that I can prove each agent loaded. Version 2.1.277 gets Claude Code closer. For now, I would still check `/config` and run one small behavioral test.