AGENTS.md vs CLAUDE.md vs README.md: what's the difference?

Same shape, different readers

All three are Markdown at your repo root, which is why they get confused. But:

• README.md → for humans: quick start, what the project does, how to contribute.
• AGENTS.md → for agents, cross-tool: build/test commands, conventions, boundaries. Read by Codex, Cursor, Copilot, Gemini CLI and more.
• CLAUDE.md → for Claude Code specifically (it doesn't read AGENTS.md natively yet).

You don't need two agent files

If you use Claude Code, don't maintain a separate CLAUDE.md. Symlink it:

$ ln -s AGENTS.md CLAUDE.md

One real file, two names, zero drift.

How they fit together

repo/
  README.md     # humans
  AGENTS.md     # agents (source of truth)
  CLAUDE.md ->  AGENTS.md   # symlink, for Claude Code

Keep all three. Each stays focused on its reader; the README can even link to AGENTS.md so contributors know where the agent conventions live.

The one rule

Never keep two real files with the same content — they drift the first time you edit one and forget the other. One file + a symlink, always.

---

Free cheat sheet: the format, an annotated example, and the one-line test — AGENTS.md Cheat Sheet.

Go deeper: the full reference — cross-tool setup, the monorepo hierarchy, and a 30-day plan — AGENTS.md: The Complete Guide to the Cross-Tool Agent Standard.

Do you keep a separate CLAUDE.md, or symlink it to AGENTS.md? 👇