Claude Code Now Reads AGENTS.md, and the Config-File Split Is Ending
Quick verdict
Claude Code just started reading AGENTS.md. In v2.1.277 it checks for that file when no CLAUDE.md is present, so the instructions you write once for one agent now work in another without a second copy. It is a small change with an outsized payoff for anyone who bounces between Claude Code, Codex, and Cursor, because it ends the busywork of keeping three files that say the same thing. The config-file format war has been quietly settling on AGENTS.md, and this is the biggest holdout falling in line.
What changed
The update came from @trq212, who announced that Claude Code v2.1.277 now looks for an AGENTS.md file when a project has no CLAUDE.md, with a config-level toggle to control the behavior. CLAUDE.md still wins when it exists, so nothing breaks for people who already have one. The new part is the fallback: point Claude Code at a repo that only carries AGENTS.md and it will read your setup notes, conventions, and guardrails from there.
That reframes AGENTS.md from one tool's idea into a convention Claude Code is willing to honor. The practical read came from @simonw, who pointed out the obvious upside: fewer shim files whose only job is to point one format at another. If you have ever kept a CLAUDE.md that just says "see AGENTS.md," you can delete it.
Why AGENTS.md exists at all
Every coding agent wants the same thing from your repo. How do you run the tests, what is the build command, which directories are off limits, what style rules matter. For a while each tool invented its own file for it. Claude Code read CLAUDE.md, other agents read AGENTS.md, and teams running more than one ended up maintaining duplicates by hand. AGENTS.md is the attempt to make that one file, an open format any agent can parse, documented at agents.md. The value was never the markdown. It was getting the tools to agree on where to look.
Video: what the AGENTS.md standard is
A short walkthrough of the format and why coding agents are converging on it.
What it means if you run more than one agent
The people this helps most are the ones testing several tools at once, which is a growing share of developers. If you compare Claude Code against Cursor and Codex on the same project, you no longer maintain a separate instruction file for each. Write one AGENTS.md with your build steps, test commands, and house rules, and every agent that respects the convention reads the same brief. That makes head-to-head trials cleaner too, because each tool is working from identical context instead of whatever you last remembered to update in its own file.
It also lowers the switching cost. One reason a coding agent feels sticky is the pile of setup you built around it. When that setup lives in a shared file, moving to a different tool, or keeping a backup one on hand, gets easier. If you are weighing options, our rundown of the best AI coding agents and the list of Claude Code alternatives both get more useful once your project config travels with you instead of the tool.
FAQ
Do I need to rename my CLAUDE.md?
No. Claude Code still reads CLAUDE.md first when it exists. AGENTS.md is only the fallback for repos that do not have one, so nothing changes unless you want it to.
Which tools read AGENTS.md now?
It started as a cross-tool convention that several coding agents adopted, and Claude Code v2.1.277 joining it is the notable addition. The point of the format is that any agent can read the same file, so the list keeps growing rather than fragmenting.
What goes in an AGENTS.md file?
Project setup an agent needs before it touches your code: build and test commands, directories to avoid, coding conventions, and any guardrails. Keep it short and specific. If you are new to running agents on a real codebase, our coding-agents guide covers where these files fit.
Sources
- @trq212 - Claude Code v2.1.277 checks AGENTS.md when no CLAUDE.md is present
- @simonw - the payoff is fewer shim files pointing one format at another
- AGENTS.md - the open cross-tool agent config format
Further reading
Try all the models mentioned in this article
Admix gives you GPT-5, Claude, Gemini, and 350+ AI models in one app. Compare responses side by side. Free to start.
Start free on Admix