Comparison / guide
Two project files, almost identical content, different audiences. Here's what each one is, which tools read it, how they differ, and which you should keep.
Short answer
Both are plain-Markdown files at your repo root that tell AI coding agents how your project works. CLAUDE.md is read by Claude Code. AGENTS.md is an open standard read by Codex, Jules, Amp, Zed, Devin and 20+ other agents. Same content, different readers - so if you use more than one tool, keep both.
Read by Claude Code
Anthropic's project-memory file for Claude Code. It loads automatically when you open a repo and gives Claude your stack, commands, conventions and any house rules. Supports nested files and imports, so a monorepo can layer instructions per package.
Read by 20+ agents
An open, vendor-neutral standard (agents.md) for one file that any agent can read. Codex, Jules, Amp, Zed, Devin, RooCode, Factory and others look for it - so a single AGENTS.md travels with your repo across tools.
| CLAUDE.md | AGENTS.md | |
|---|---|---|
| Read by | Claude Code | Codex, Jules, Amp, Zed, Devin, RooCode, Factory, +20 |
| Standard | Anthropic-specific | Open / cross-vendor |
| Format | Markdown, free-form | Markdown, free-form |
| Location | Repo root + nested | Repo root + nested |
| Precedence | Nearest file + imports | Nearest file wins |
| Best for | Claude Code users | Tool-agnostic / mixed teams |
The formats are interchangeable in practice: both are just Markdown describing the project. The real difference is reach - CLAUDE.md targets one excellent tool, AGENTS.md targets the whole field.
Use CLAUDE.md if your team is on Claude Code - it is the file Claude reads first and supports imports for layered, per-package context.
Use AGENTS.md if you want one file that works no matter which agent a teammate opens - or if you are unsure which tools people will use.
Use both if you mix tools, which most teams now do. The content overlaps almost entirely, so the only real cost is keeping the two in sync as your stack changes - and that part can be automated.
claude-init scans your repo once - stack, scripts, structure, env vars, conventions, git - and writes CLAUDE.md, AGENTS.md and a dozen other tools' context files together, so they never drift apart. No API key, no network, 100% local.
$ npx @horiastanxd/claude-initQ.What is the difference between CLAUDE.md and AGENTS.md?
CLAUDE.md is the project instructions file read by Claude Code. AGENTS.md is an open, cross-vendor standard read by many agents - Codex, Jules, Amp, Zed, Devin, RooCode, Factory and 20+ more. Both are plain Markdown describing your project; the difference is who reads them.
Q.What is AGENTS.md?
AGENTS.md is an emerging open standard (agents.md) for a single Markdown file at your repository root that tells AI coding agents how to work in your project - the stack, commands, conventions and structure. A growing list of agents read it, so one file works across many tools.
Q.Do I need both CLAUDE.md and AGENTS.md?
If your team uses Claude Code plus any other agent, yes - keeping both means every tool gets context. They share the same content, so the cost is keeping them in sync. Tools like claude-init generate both from a single repo scan, so there is no extra maintenance.
Q.Where do CLAUDE.md and AGENTS.md go?
Both live at the repository root. Both also support nested files in subdirectories or packages, where the file closest to the code being edited takes precedence - useful for monorepos.