AGENTS.md vs CLAUDE.md
Two files, almost the same job: tell AI agents how to work in your repo. The difference is reach — and what happens when your team uses more than one agent, or more than one repo.
If you've set up AI coding agents on a real project, you've hit the
question: do I write a CLAUDE.md, an AGENTS.md,
or both? They solve the same problem — giving an agent the project
context it should always know — and the right answer depends on how many
agents (and repos) your team runs.
What each one is
CLAUDE.md is Claude Code's
context file: Claude reads it automatically at the start of every session
in a repo. AGENTS.md is the
open, tool-agnostic equivalent — a shared convention, now stewarded under
the Linux Foundation, that agents across the ecosystem read. The body of
both is the same kind of thing: commands, conventions, repo layout, hard
rules.
Side by side
| CLAUDE.md | AGENTS.md | |
|---|---|---|
| Read by | Claude Code | Codex, Cursor, Gemini CLI & more (cross-tool) |
| Governance | Anthropic, vendor-specific | Open standard, Linux Foundation stewardship |
| Format | Plain Markdown, repo root | Plain Markdown, repo root |
| Best when | You only run Claude Code | You run more than one agent |
| Scales across repos? | No — one file per repo | No — one file per repo |
Which to use
Claude-only team? A tight CLAUDE.md is enough. Mixed toolchain — or you expect to add agents later? Make AGENTS.md the canonical file so every tool reads the same context, and have CLAUDE.md defer to it. The failure mode to avoid is two full files that slowly disagree; a wrong instruction is worse than none, so keep one source of truth and point the other at it.
Where both stop: more than one repo
Picking the right file solves the single-repo case. Neither file solves the next wall: a team across many repos. Both live inside a repository, so neither can carry a cross-service decision or keep a dozen repos in sync — you're back to copy-pasting conventions that drift, with no way to say why a choice was made or who owns it.
The fix isn't a third file — it's a shared layer above all of them.
First-Tree gives your team a context tree: cross-cutting decisions and ownership in one owned, reviewed Git repo that every agent, in every repo, reads — whether it's Claude Code reading CLAUDE.md or Codex reading AGENTS.md. The per-repo file stays thin; the durable knowledge lives once. It's the memory underneath running AI agent teams that stay coherent across a whole codebase.