What happened

Claude Code’s 2.1.277 update adds support for AGENTS.md, a plain-text file that tells a coding agent how to work in a project: which commands to run, which conventions to follow, which files matter most. Until now, Claude Code only read its own file for this, CLAUDE.md. As of this release, if a project has no CLAUDE.md, Claude Code reads AGENTS.md instead.

The fallback isn’t automatic in every setup. You can see and change which file Claude Code is using under “Project instructions” in /config, the command that opens Claude Code’s settings menu. The feature also isn’t available yet if you run Claude Code through Bedrock, Vertex, or Foundry, the enterprise cloud platforms some companies route their AI tools through instead of connecting directly to Anthropic.

BuilderWithin covered AGENTS.md two weeks ago, when OpenAI told Codex users to rewrite theirs for GPT-6 Astra. That file format isn’t tied to one company. Anthropic, OpenAI’s Codex, and other coding agents have been converging on AGENTS.md as a shared standard, the same way most projects now include a README file that any tool can open and expect to find basic setup instructions in. Claude Code adding read support is a small technical change with a bigger implication: fewer builders will need to maintain two nearly identical instruction files just because they use more than one coding agent.

Why it matters

The catch is in the word “instead,” not “also.” Claude Code doesn’t merge the two files or read both. If a CLAUDE.md exists in your project, Claude Code reads that one and ignores AGENTS.md completely, even if AGENTS.md is newer or more complete.

That matters for anyone who has used Claude Code before and also uses a second coding agent, like Codex, that reads AGENTS.md. If you already have an old CLAUDE.md sitting in your repository from a previous setup, and you build out a fresh AGENTS.md to share instructions across both tools, Claude Code will keep quietly following the stale CLAUDE.md and never look at the file you actually maintained. You won’t get an error. Claude Code will just behave as if your AGENTS.md updates never happened, because from its side, they didn’t.

Who should care

Anyone running more than one coding agent against the same repository, and anyone who has an old CLAUDE.md they haven’t touched in a while. If you’ve only ever used Claude Code and never created an AGENTS.md, nothing changes for you yet.

What builders should do next

Open a project you work in with Claude Code and run /config. Look for “Project instructions” and check which file it says it’s reading. If you intend to standardize on AGENTS.md across tools, delete or rename the old CLAUDE.md first, then confirm in /config that Claude Code has switched over. Don’t just create the AGENTS.md and assume it’s live.

If you’re on Bedrock, Vertex, or Foundry, this fallback doesn’t apply to you yet. Keep maintaining CLAUDE.md directly until Anthropic extends support to those platforms.

The bottom line

A shared instructions file across coding agents is a real convenience if you use more than one. It only works if the agent is actually reading the file you think it’s reading. Check /config before you trust it.

End of article