CLAUDE.md vs AGENTS.md: what goes where

Which tool reads which file

Both files do the same job for different tools. Codex and Cursor read AGENTS.md from the project root. Claude Code reads CLAUDE.md at the start of every session. The content is tool-neutral (the stack, the commands, the conventions, the do-not rules), so the real question is not what to write but which file to keep.

When Claude Code reads AGENTS.md

Claude Code reads AGENTS.md too, but on a condition worth knowing. By default it reads a repository’s AGENTS.md only when there is no CLAUDE.md or CLAUDE.local.md in your working directory or any directory above it. If one sits above, Claude Code reads that and skips the AGENTS.md. So AGENTS.md is a fallback, not a file loaded next to CLAUDE.md.

You change that under Project instructions in /config, which has four settings:

Setting	What Claude Code reads
claude-md-or-agents-md (default)	CLAUDE.md, or AGENTS.md when no CLAUDE.md or CLAUDE.local.md sits in or above the working directory
claude-md-and-agents-md	Both: in each directory the CLAUDE.md loads first, then the AGENTS.md
claude-md	CLAUDE.md only; AGENTS.md is ignored
managed-only	Only your organization’s managed CLAUDE.md and auto memory

Reading AGENTS.md directly needs Claude Code v2.1.277 or later. It arrived later on some providers: on Amazon Bedrock, Vertex and Foundry, and in sessions with telemetry turned off, you need v2.1.281 or later.

Which setup should I use?

Your setup	Keep
Only Claude Code	A CLAUDE.md.
Only Codex or Cursor	An AGENTS.md.
Several tools, one shared file	One AGENTS.md and no CLAUDE.md above it, so every tool reads the same file.
Several tools, but a CLAUDE.md already exists	Import it: a CLAUDE.md containing @AGENTS.md, or the claude-md-and-agents-md mode.
Monorepo with rules per package	The claude-md-and-agents-md mode, or import each package’s AGENTS.md from a CLAUDE.md; otherwise a root CLAUDE.md hides the nested AGENTS.md files.

What goes in the file, and what doesn’t

The content is tool-neutral, so it reads the same wherever it lives:

• The stack and the exact build, test and lint commands.
• The conventions to follow, written as short rules.
• The areas the agent must not touch.

What does not belong is live task state. It changes every session, and stuffing it into a file that loads every time makes the file long and the agent slower to follow. Keep the plan and the task list on a board or in a plan file the agent updates, and keep the rules file for what is stable. For the fuller case, see keeping Claude Code on track across sessions.

Share one file across all three

If you work with more than one tool, aim for one source of truth, not a pair you keep in sync. Two setups do that cleanly:

1. One AGENTS.md, no CLAUDE.md above it. Codex and Cursor read it, and Claude Code reads it too, because nothing higher up overrides it.
2. A CLAUDE.md that imports it. A one-line CLAUDE.md with @AGENTS.md pulls the shared file in. Use this when a CLAUDE.md has to exist anyway (a monorepo root, say), or when your Claude Code is older than v2.1.277.

Either way, generate a starting pair with the CLAUDE.md generator, or copy the AGENTS.md example. Keep whichever file you choose short: it loads on every run, so length is a cost you pay each session.