Every comparison of these two files asks the same question (which one should I use?) and answers it with a feature table. The table is fine. The question is wrong.
Here's what the tables bury: if your team runs more than one coding agent, you don't choose. You end up with both. And the moment two files describe the same project, you have a drift problem nobody is watching.
Facts first, then the part that actually costs you.
What each one is
AGENTS.md is the cross-tool standard. OpenAI released it in August 2025; it's since been folded into the Agentic AI Foundation under the Linux Foundation, with 60,000+ repositories using it. It's deliberately dumb: plain Markdown, no required schema, dropped at the repo root, with nested files in subdirectories where the nearest one wins. Codex, Cursor, Copilot, Gemini CLI, and most other agents read it natively. It's the closest thing the ecosystem has to a lingua franca.
CLAUDE.md is Claude Code's native memory file. It predates the standard and does more: a project file plus a personal ~/.claude/CLAUDE.md, @-imports to pull in other files, path-scoped rules, and exclusion controls. Richer, and Claude-specific.
Roughly:
| AGENTS.md | CLAUDE.md | |
|---|---|---|
| Read by | Codex, Cursor, Copilot, Gemini CLI, most agents | Claude Code |
| Origin | OpenAI, Aug 2025; now Linux Foundation | Anthropic |
| Schema | None, plain Markdown | Markdown + extras |
| Imports | No | Yes (@file) |
| Scoping | Nearest file in tree wins | User + project + path-scoped |
| Best at | Working across tools | Getting the most out of Claude Code |
If you're a Claude-Code-only shop, CLAUDE.md is genuinely fine. Ignore the standard and move on. All-Codex or all-Cursor? AGENTS.md, done. The pain is for everyone in between, which is a growing share of teams as running several agents at once becomes normal.
The one fact that decides this
Claude Code does not read AGENTS.md. As of mid-2026 it loads CLAUDE.md and ignores AGENTS.md entirely. The request to change that (issue #6235 on the anthropics/claude-code tracker) is one of the most-upvoted open issues Anthropic has. It's still open.
Read the failure mode carefully, because it's worse than "unsupported":
If a repo contains only AGENTS.md, Claude Code doesn't warn you. It doesn't error. It loads zero project context and produces worse output while you wonder why the agent that works fine for your teammate keeps ignoring your conventions.
That's not a missing feature. It's a silent misconfiguration, the kind that never shows up in a test and survives for weeks.
So you keep both, and now they drift
Because Claude Code won't read the standard, the multi-tool answer is to keep AGENTS.md for the world and hand Claude Code a CLAUDE.md too. Two ways people do it:
- A symlink.
ln -s AGENTS.md CLAUDE.md. One file of truth, two names. Clean, until a Windows checkout or a CI runner doesn't preserve the link, or git commits a copy instead of the link, and the two diverge without anyone touching them. And by definition you can't put anything Claude-specific in it, because it is the other file. - A thin shim. A short CLAUDE.md that imports the standard with
@AGENTS.md, so you can layer Claude-only rules on top. Which is exactly the moment the two start saying different things.
Either way, you've gone from "which file" to "two files that are supposed to agree." Nobody owns keeping them in sync. Nothing errors when they don't. And the richer the CLAUDE.md gets (imports, path rules, personal overrides), the more surface area there is to quietly contradict the AGENTS.md every other tool is reading.
This is the real story of CLAUDE.md vs AGENTS.md, and no feature table shows it: the choice isn't between two formats. It's between one source of truth and several that drift apart.
What actually matters
The format question is close to settled. AGENTS.md won the shared-baseline slot, CLAUDE.md stays the richer Claude-native layer, and most serious teams will carry both for a while. Arguing about which is "better" is arguing about syntax.
What decides whether your agents behave isn't the file you picked. It's whether the instructions across your files still agree, with each other and with reality, and whether anyone would notice when they stop. A CLAUDE.md rule that contradicts AGENTS.md. A path that moved. A convention you changed in one file and forgot in the other. None of these throw an error. All of them degrade output.
An exercise worth doing today: open your AGENTS.md and CLAUDE.md side by side and read them as the agent would. Do they agree? Would you know if they stopped?
That's the real question: not which file, but who's watching the seam between them. Which is the part we work on at Blume.