Home › Rules › AGENTS.md vs CLAUDE.md
AGENTS.md vs CLAUDE.md: which one do you need?
Short answer: write one AGENTS.md. If you use Claude Code too, either let it read AGENTS.md directly or add a one-line CLAUDE.md that imports it. Don't maintain two copies.
The difference
| AGENTS.md | CLAUDE.md | |
|---|---|---|
| Who reads it | Many tools: OpenAI Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Zed, Aider and others listed on agents.md. Claude Code too, in some cases (below). | Claude Code. GitHub Copilot also reads it in some surfaces. |
| Format | Plain Markdown, no required fields | Plain Markdown, plus @path imports |
| Locations | Repo root, plus optional nested files in subfolders | ./CLAUDE.md or ./.claude/CLAUDE.md, personal ~/.claude/CLAUDE.md, private CLAUDE.local.md |
| Who maintains it | An open format, stewarded by the Agentic AI Foundation (Linux Foundation) | Anthropic |
How Claude Code handles AGENTS.md
Per Anthropic's docs (Claude Code v2.1.277 or later):
- Only AGENTS.md in the project: Claude reads it.
- Both AGENTS.md and CLAUDE.md (or CLAUDE.local.md): by default Claude reads only the CLAUDE.md files. You can change this with the Project instructions setting in
/config. - CLAUDE.md that imports AGENTS.md: Claude reads both, with no double-loading.
That middle case catches people: adding a personal CLAUDE.local.md quietly stops Claude from reading your shared AGENTS.md. The import avoids it.
The setup we recommend
# AGENTS.md
(your shared rules: project, commands, rules, how to work)
@AGENTS.md
## Claude Code
- Use plan mode before any change that touches more than 3 files.
A symlink (ln -s AGENTS.md CLAUDE.md) also works, but Anthropic's docs recommend the import if anyone on the project uses Windows, where Git may check symlinks out as plain text files.
When CLAUDE.md alone is fine
You only ever use Claude Code, and you want Claude features like @ imports of other docs. Even then, naming the file AGENTS.md costs nothing and keeps your options open if you try Codex or Cursor later.
Get a ready-made file
Every file in the rules library comes as AGENTS.md with the CLAUDE.md import ready to copy. Or generate a CLAUDE.md for your project.