AGENTS.md vs CLAUDE.md: which one should you use?
Use AGENTS.md: 6 of the 9 agents we score read it, and Claude Code falls back to it. If you also need a CLAUDE.md, start it with @AGENTS.md, or Claude Code skips AGENTS.md.
Both hold the same content. AGENTS.md is the shared name; CLAUDE.md is Claude Code's.
Which agents read AGENTS.md and which read CLAUDE.md?
| Agent | AGENTS.md | CLAUDE.md |
|---|---|---|
| Claude Code | When there is no CLAUDE.md | Yes |
| Cursor | Yes | No |
| Devin | Yes | No |
| GPT-5 Codex | Yes | No |
| Kimi CLI | Yes | No |
| Gemini CLI | When configured to | No |
| Aider | When configured to | No |
| OpenHands | Yes | No |
| Pi | Yes | Yes |
Every file each agent reads, with links to their docs.
What does Claude Code do when a repo has both?
- AGENTS.md onlyAGENTS.md
- AGENTS.md and CLAUDE.mdCLAUDE.md only
- AGENTS.md, and a CLAUDE.md that imports it with @AGENTS.mdBoth
Needs Claude Code v2.1.277 or later. A CLAUDE.local.md counts as a CLAUDE.md. Claude Code's docs also cover a setting that loads both.
How many repos use AGENTS.md and how many use CLAUDE.md?
Of 401 leaderboard repos, 197 have an AGENTS.md (49%) and 19 only a CLAUDE.md (5%). Empty files don't count.
Our AGENTS.md check passes either name; the choice only changes which agents find it. Read both kinds in popular repos.