The short version
| AGENTS.md | CLAUDE.md | |
|---|---|---|
| Read by | Most major agents (Cursor, Codex, Copilot, Gemini…) | Claude Code |
| Scope | Tool-neutral convention | Claude-specific filename |
| Content | Effectively identical — setup, code style, structure, guardrails | |
| Best as | Single source of truth | A generated copy / symlink |
They’re not really rivals
The content of a good CLAUDE.md and a good AGENTS.md is the same. The only real difference is the filename a given tool looks for. So the question isn’t “which one” — it’s “how do I avoid maintaining the same instructions twice.”
Recommended setup
Keep AGENTS.md as canonical and point CLAUDE.md at it with a symlink (ln -sf AGENTS.md CLAUDE.md), or generate both from one source. Now Claude Code and every other agent read identical rules, and you edit in one place.
Do it automatically
The generator emits AGENTS.md and CLAUDE.md together, plus a symlink script, so they can never disagree.
Frequently asked
Should I use AGENTS.md or CLAUDE.md?
Use AGENTS.md as the source and keep CLAUDE.md as a symlink or generated copy, so Claude Code and other agents stay in sync.
Does Claude Code read AGENTS.md?
Claude Code looks for CLAUDE.md; point it at AGENTS.md via symlink so there’s a single source of truth.
Is the content different between them?
No — same sections and rules. Only the filename differs.