AGENTS.md vs CLAUDE.md vs README.md: What's the Difference?
The short answer: README.md is for humans, AGENTS.md is the cross-tool standard for AI coding agents, and CLAUDE.md is Claude Code's own agent file. They look similar — all Markdown at your repo root — but they serve different readers, and using the right one for the right job keeps each clean and effective.
README.md Is for Humans
Your README is written for the people who contribute to your project: a quick start, what the project does, how to set it up, contribution guidelines. It is the front door for a new human. It is not the place for the exact, sometimes tedious operational detail an agent needs — that would clutter it and most of it is irrelevant to a human reader anyway.
AGENTS.md Is for Agents — Across Every Tool
AGENTS.md is the open standard that gives AI coding agents project context: build steps, test commands, conventions, and boundaries. It is read natively by most major agents — Codex, Cursor, Copilot, Gemini CLI and more — and is now stewarded by the Linux Foundation. Think of it as a README written for the agents that do the work rather than the humans who read about it.
CLAUDE.md Is Claude Code's Own File
CLAUDE.md is functionally parallel to AGENTS.md but read specifically by Claude Code, which does not yet read AGENTS.md natively. If you use Claude Code, you do not need to maintain two separate files: point CLAUDE.md at AGENTS.md with a symlink, and both names resolve to the same content.
$ ln -s AGENTS.md CLAUDE.mdHow They Work Together
Keep all three: README.md for humans, AGENTS.md as the single source of truth for agents, and CLAUDE.md as a symlink to AGENTS.md if you use Claude Code. The README can even link to AGENTS.md so contributors know where the agent conventions live. Each file stays focused on its own reader, and nothing has to compromise for anything else.
The One Rule That Prevents Trouble
Never keep two real files with the same content — a separate AGENTS.md and a separate CLAUDE.md will drift the first time you update one and forget the other. One real file, plus a symlink where another name is needed, is always the cleaner answer.