CLAUDE.md vs AGENTS.md
Quick answer
Both files are persistent, Markdown project instructions an AI agent reads automatically. The difference is the audience: CLAUDE.md is read by Claude Code, while AGENTS.md is the open, vendor-neutral convention read by OpenAI Codex and a growing set of other agents. If you use more than one agent, keep both and mirror the shared rules between them.
They are not competitors — they are the same idea aimed at different tools. Choosing one over the other is really a question of which agents touch your repo. The mistake to avoid is letting them drift apart, because two agents reading two different rule sets is how parallel work collides.
Side by side
| CLAUDE.md | AGENTS.md | |
|---|---|---|
| Primary reader | Claude Code | OpenAI Codex + several other agents |
| Standard | Anthropic / Claude Code convention | Open, cross-vendor convention (agents.md) |
| File location | Repo root, subdirs, ~/.claude/ | Repo root (and nested dirs) |
| Format | Plain Markdown | Plain Markdown |
| Auto-loaded each session | Yes | Yes (by supporting tools) |
| Best for | Claude-specific workflow + tooling notes | Tool-agnostic rules read by many agents |
How to run both without drift
Pick one file as the canonical source of shared rules and treat the other as its mirror. Whenever you change a structural rule — a deploy constraint, a naming convention, a hard "never do this" — update both in the same commit. The cost of a five-second copy is far lower than two agents fighting over the same files because one of them never got the memo.
For genuinely tool-specific notes (Claude Code slash commands, Codex-only behaviours), keep those in the file that owns them and leave a one-line pointer in the other.
FAQ
Do I need both CLAUDE.md and AGENTS.md?
If you only use Claude Code, a single CLAUDE.md is enough. If you also use OpenAI Codex or other agents — or want your repo to be portable across tools — keep both. The practical pattern is one canonical source of shared rules, mirrored into each file so every agent reads the same instructions.
Can AGENTS.md and CLAUDE.md just point to each other?
Yes, and many repos do exactly that to avoid drift: keep the full content in one file and have the other say "see CLAUDE.md / see AGENTS.md for the canonical rules". The trade-off is that some tools only read their own file, so critical rules are safest duplicated rather than referenced.
Which file wins if they disagree?
Each tool reads its own file, so there is no single winner — Claude Code follows CLAUDE.md and Codex follows AGENTS.md. That is exactly why you keep them in sync: divergence means two agents working the same repo follow different rules and collide.
Is AGENTS.md only for OpenAI?
No. AGENTS.md started as an open, vendor-neutral convention and is read by a growing set of agents and coding tools. Treat it as the portable, cross-tool instruction file and CLAUDE.md as the Claude Code-specific one.
Keep reading
One template, both files, kept in sync
SoloStack ships the CLAUDE.md master template and its AGENTS.md Codex mirror together — pre-aligned so your Claude and Codex agents read the same rules from day one.
Get SoloStack — £99