Short answer: they're the same kind of file for different tools. Both AGENTS.md and CLAUDE.md are plain-Markdown instructions that tell an AI coding agent how to work in your repo. The only real difference is which agent goes looking for which filename.
Which tool reads which file
| File | Read by |
|---|---|
AGENTS.md | Cross-agent standard — most coding agents now read it natively |
CLAUDE.md | Claude Code and Claude |
GEMINI.md | Google Gemini / Gemini CLI |
.cursor/rules/*.mdc | Cursor |
.github/copilot-instructions.md | GitHub Copilot |
CLAUDE.md, GEMINI.md, and the Cursor/Copilot files came first, each tool inventing its own. AGENTS.mdis the later attempt at a shared, vendor-neutral name so you don't need one file per tool.
Do you need both?
It depends on how many tools touch the repo:
- One tool only. If everyone on the project uses Claude Code, a single
CLAUDE.mdis enough — you don't need AGENTS.md too. Same logic if you're all on Cursor, or all on Gemini. - A mix of tools.The moment teammates use different agents, you want each tool's file present so nobody gets un-briefed. Most agents now read
AGENTS.mdnatively, which makes it the safest single file to start with — but a few, Claude Code among them, only look for their own file, so the dedicated files still earn their place.
What happens if both exist
A tool reads its own file first: Claude Code uses CLAUDE.md even if an AGENTS.mdsits right next to it. Where directory nesting is supported, the file nearest the code being edited wins, so a subdirectory's instructions override the root for that folder. Precedence, though, is rarely the real problem. The real problem is drift: two files that started identical and slowly disagreed, so the answer you get depends on which tool a teammate happened to open.
Keeping them in sync
The whole point is that the instructions are the same everywhere, so maintain one source of truth and generate the rest. Three ways to avoid drift:
- Write the content once and copy it into each file verbatim — fine until someone edits one and forgets the others.
- Point one file at the other. Claude Code supports imports: a
CLAUDE.mdwhose first line is@AGENTS.mdpulls the shared file in, so the content lives in one place and Claude reads the same brief as everyone else. - Generate all of them from a single pass. ContextPruner produces AGENTS.md, CLAUDE.md, GEMINI.md, Cursor rules, and Copilot instructions — plus the four enforced ignore files, all nine from one triage of your file tree — and writes them inside a managed block so your own hand-written notes and exceptions survive every regeneration.
And if the files are already committed, you can check for drift instead of guessing: the lint check compares your existing configs against your current tree and flags where they disagree.
Common questions about AGENTS.md vs CLAUDE.md
Quick answers to the exact AGENTS.md vs CLAUDE.md questions people search for:
What's the difference between AGENTS.md and CLAUDE.md?
None in purpose — both are plain-Markdown instructions that tell an AI coding agent how to work in your repo. The only difference is the filename each tool looks for: Claude Code reads CLAUDE.md, while AGENTS.md is the vendor-neutral name a growing number of agents read natively.
Do I need both AGENTS.md and CLAUDE.md?
Only if more than one tool touches the repo. If everyone uses Claude Code, a single CLAUDE.mdis enough. Once teammates use different agents, add each tool's file — most agents read AGENTS.md natively, but a few, Claude Code among them, only look for their own filename.
Does Claude Code read AGENTS.md?
Not by default — Claude Code looks for CLAUDE.md. But you can keep one source of truth: make the first line of CLAUDE.md read @AGENTS.md and it imports the shared file, so Claude reads the same brief as every other tool.
If both AGENTS.md and CLAUDE.md exist, which one wins?
Each tool reads its own file first, so Claude Code uses CLAUDE.md even with an AGENTS.mdbeside it. Where nested files are supported, the file nearest the edited code wins. The real risk isn't precedence but drift, so keep both generated from one source.
New to the format itself? Start with What is AGENTS.md? for the structure and a worked example.