Anthropic's coding tool Claude Code now supports AGENTS.md, starting in version 2.1.277. The rule is simple: when a folder has no CLAUDE.md, Claude Code looks for an AGENTS.md in that same folder and reads it into context as project instructions. Folders that already have a CLAUDE.md keep using only that file, same as before.
The release shipped on GitHub on September 18. Claude Code team member Thariq announced the change on social media:
Starting today in version 2.1.277, if there is no CLAUDE.md in a folder, Claude will check for and use AGENTS.md.
Four toggle levels
AGENTS.md support ships as a built-in plugin, with its source published in the Claude Code GitHub repo. Users switch between modes under "Project instructions" in /config, across four levels:
| Mode | Behavior |
|---|---|
| claude-md | Reads only CLAUDE.md — effectively turns the feature off |
| claude-md-or-agents-md (default) | If a folder has a CLAUDE.md, its AGENTS.md is ignored; without one, AGENTS.md is read instead |
| claude-md-and-agents-md | Reads both file types throughout the whole directory tree |
| managed-only | Drops both repo-committed and personal instruction files, keeping only rules and memory pushed centrally by the organization |
The default level is a fallback, not a merge. Repos that already have a CLAUDE.md for Claude Code behave exactly the same after the upgrade; only repos that never wrote one — and had an AGENTS.md prepared for other tools — will have it read in for the first time. The same file won't be loaded twice if it's judged a duplicate by path or content.
A few gaps versus CLAUDE.md
The plugin's docs list several differences from CLAUDE.md. An AGENTS.md in a subdirectory is only pulled in when the agent reads a text file in that directory with the Read tool — IDE selections, notebooks, images, and PDFs don't trigger it. Files pulled in this way aren't logged as already-read, so they don't come back automatically after context gets compacted. The /memory command and the # quick-memory shortcut don't touch AGENTS.md either; directories added with --add-dir don't contribute an AGENTS.md; and symlinked paths are compared literally, not resolved.
On the channel side, AWS Bedrock, Google Vertex, and Microsoft Foundry don't support it yet. The same release carries one more instruction-file change: in the SDK and headless mode, the first turn no longer waits for the CLAUDE.md lookup to finish.
One repo, several agents
AGENTS.md is essentially a README written for coding agents — how to build, how to run tests, what code-style conventions apply, which directories to leave alone. The format was originally pushed by OpenAI Codex and a few other tools in 2025, later handed to the Agentic AI Foundation under the Linux Foundation, and is now recognized by Cursor, GitHub Copilot, and others. Claude Code had only ever recognized its own CLAUDE.md, so teams mixing tools had to keep two nearly identical files in sync — a common workaround was a symlink pointing one at the other.
Teams in China often run an even more mixed toolset: besides Claude Code, it's common to also see Kimi Code, Qwen Code, Cursor, and Codex, several of which default to reading AGENTS.md or let you rename the instruction file. Under the default level, old repos don't need a single line changed. Teams that want to maintain just one AGENTS.md can delete CLAUDE.md and consolidate instructions there — but should check the limitations above first, especially that subdirectory instructions don't come back automatically once a long session gets compacted.
The managed-only level targets enterprise admins. An instruction file committed into a repo gets executed by the agent as instructions, which makes it a poisonable entry point on its own; this level lets admins allow only rules pushed centrally by the organization. There's no public usage data yet on how well it performs in large teams.
Sources: Claude Code GitHub release notes, CocoLoop, Anthropic engineer Thariq's public post; agents-md plugin docs checked for the four modes, load order, and limitations.