Claude Code Reads AGENTS.md Only When CLAUDE.md Is Missing: An Ops Playbook for the Fallback

AGENTS.md: the instructions file 20-plus tools now agree on

AGENTS.md is an agent-facing README dropped at a project's root, carrying the operational context — build commands, test steps, coding conventions — that a human-facing README doesn't. OpenAI, Google, Cursor, Factory, and Sourcegraph finalized the format together in August 2025, and a little over a year later more than 20,000 repositories have adopted it. Governance now sits with the Agentic AI Foundation under the Linux Foundation. Codex, Cursor, GitHub Copilot's coding agent, Gemini CLI, Windsurf, Aider, Zed, and more than 20 other tools read the file natively, with no extra setup.

Claude Code's choice: a fallback, not a merge

Claude Code 2.1.277, shipped September 18, added support for reading AGENTS.md only when no CLAUDE.md is present. The two files are not merged — if CLAUDE.md exists, it wins outright — and which file takes precedence can be changed under "Project instructions" in /config. The fallback isn't yet available through Bedrock, Vertex, or Foundry, so the same repository can behave differently depending on which access path an agent uses.

After the standard lands: an ops baseline for teams running multiple agent CLIs

Teams running more than one agent CLI should set a target metric: one instructions file per repository. Fix your rollout bar at 100% of repos migrated and a 100% pass rate on agent-behavior regression tests after any instructions change, and document per repository which file is the source of truth — usually a single AGENTS.md, with CLAUDE.md reduced to a short pointer if it has to stay at all.

The most common failure is updating AGENTS.md with the latest rules while leaving CLAUDE.md untouched. Because Claude Code reads only CLAUDE.md when it exists, none of the AGENTS.md changes the team believes are live actually take effect. A second failure shows up on paths without the fallback yet — Bedrock or Vertex, for instance — where deleting CLAUDE.md and keeping only AGENTS.md leaves those agents running with no instructions at all.

If AGENTS.md is your source of truth, the safer move is deleting CLAUDE.md outright to force the fallback to trigger. Teams that must keep both files for a transition period should add a pre-commit hook that diffs the two on every commit, so a change landing in only one of them never slips through. Track fallback support per deployment path — local CLI, Bedrock, Vertex, Foundry — in a table, and flag the unsupported paths explicitly.

Every time a new agent tool joins the stack, re-check instructions-file precedence, and add a CI step that checks whether both AGENTS.md and CLAUDE.md exist and flags a gap between their last-modified dates. Write down each repo's /config "Project instructions" setting in team docs rather than leaving it to drift across individual local setups.

Check the Agentic AI Foundation's spec changes and the Claude Code release notes on a monthly cadence to catch when Bedrock, Vertex, or Foundry support expands. When an incident traces back to an instructions file, log the root cause in a dedicated change log so the same mistake doesn't repeat the next time a tool is onboarded.

The takeaways at a glance

AGENTS.md is now a de facto standard shared by more than 20 tools, and Claude Code's support is a fallback rather than a merge, which turns precedence management into a real operational task. One instructions file per repo, a support table by deployment path, and a pre-commit sync check are enough to absorb the next tool the same way.

Reference links

AGENTS.md — official standard site

Claude Code Changelog — Anthropic