AGENTS.md vs CLAUDE.md: which one Claude Code reads and how to share one file

When to use

• Your repository already has an AGENTS.md and you want to know whether Claude Code reads it.[1]
• Your team uses Claude Code plus other coding agents and wants to maintain a single set of project instructions.[1][2]
• You want to separate the instruction files you write from the notes Claude keeps for itself, and know where each lives.[1]

When not to use

• You expect other tools to follow the same loading rules as Claude Code: rules differ per tool, so read each tool's own docs.[1][3]
• You want CLAUDE.md to act as a hard constraint: the docs say Claude treats it as context, not enforced configuration.[1]

Three combinations and what Claude Code reads by default

The official docs give a table of what Claude Code reads by default for each combination of instruction files. It is reorganized below without changing the meaning.[1]

[1]

These count as having a CLAUDE.md: a CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in the working directory or any directory above it. These do not count and keep loading alongside AGENTS.md: ~/.claude/CLAUDE.md, the organization's managed CLAUDE.md, and files in .claude/rules/.[1]

Note that CLAUDE.local.md counts too: adding one for your own uncommitted instructions stops Claude Code from reading your AGENTS.md. The docs' fix is to set Project instructions to claude-md-and-agents-md in /config so both file types are read.[1]

• claude-md-or-agents-md: the default; reads CLAUDE.md, or AGENTS.md only when there is no CLAUDE.md.
• claude-md-and-agents-md: reads both, with each directory's CLAUDE.md first; an AGENTS.md already loaded is not read twice.
• claude-md: reads CLAUDE.md files only.
• managed-only: at launch, loads only the organization's managed CLAUDE.md and auto memory; your project, local and user CLAUDE.md files, your .claude/rules/ files and every AGENTS.md are left out. A subdirectory's CLAUDE.md and .claude/rules/ files, and path-scoped rules, still load on demand.

[1]

The docs also list sessions where Claude Code cannot read AGENTS.md: these read CLAUDE.md files only, and Project instructions does not appear in the /config panel. They include: a Claude Code version before v2.1.277; having disabled the built-in plugin that reads AGENTS.md through /plugin; and, in some cases, the first session after upgrading from v2.1.276 or earlier (AGENTS.md is read from the next session on). Before v2.1.281, some sessions, such as those on Amazon Bedrock or with telemetry disabled, also read CLAUDE.md files only, and the docs advise updating. To give Claude your AGENTS.md in these sessions, import it from a CLAUDE.md.[1]

Share one file with an import

To keep AGENTS.md as the one file every tool shares, the docs put a CLAUDE.md next to it containing @AGENTS.md, with Claude-specific instructions below that line. Claude reads the imported file first, then the rest.[1]

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

[1]

The docs say an existing @AGENTS.md can stay: whichever Project instructions value you use, it never makes Claude read AGENTS.md twice. If you need no Claude-specific content, a symlink also works.[1]

ln -s AGENTS.md CLAUDE.md

[1]

• Editing: Claude reads CLAUDE.md through the link, but the Edit and Write tools refuse to write through a symlink and point Claude to AGENTS.md instead.
• Windows: the docs recommend the @AGENTS.md import, because creating a symlink there needs Administrator privileges or Developer Mode, and Git may check a committed symlink out as plain text.
• After setting up, the docs suggest running /context in your next session to confirm CLAUDE.md appears under Memory files.

[1]

Import details: @path accepts relative and absolute paths, relative paths resolve from the file that contains the import, and imported files can import others up to four hops deep. Imported files load into context together with the CLAUDE.md, so imports help organization but do not reduce context use.[1]

Where files live and what they apply to

[1]

AGENTS-style files Claude Code does not read: AGENTS.local.md, AGENTS.override.md, and anything under a .agents/ directory.[1]

The agents.md site suggests creating AGENTS.md at the repository root; large monorepos can add another one in each subproject.[2]

How it differs from auto memory

The docs describe two complementary memory systems: CLAUDE.md (or AGENTS.md in its place) holds instructions you write, while auto memory holds notes Claude writes itself from your corrections and preferences. The docs also note that Claude treats both as context, not enforced configuration.[1]

[1]

Auto memory lives under ~/.claude/projects/<project>/memory/ and is machine-local; it is not shared across machines. Any special relationship between AGENTS.md and auto memory is not stated officially; use the table above to tell them apart. The "first 200 lines or 25KB" in the table applies to MEMORY.md only: whichever limit comes first, and content beyond it is not loaded at session start; other topic files in the directory are not loaded at start and Claude reads them on demand.[1]

Other tools (only what official pages state)

Only statements that each official page makes are listed below. Rules differ between tools and must not be read as Claude Code behavior. Neither the agents.md site nor the Cursor docs state a version, so the content above is accurate as of the verification date, 2026-10-28; the version threshold stated by the Claude Code docs page is given at the start of this article.[1][2][3]

• agents.md site: AGENTS.md is an open format for guiding coding agents; the site lists Codex, Cursor, Gemini CLI, Zed and others as compatible; there are no required fields, just standard Markdown.
• agents.md site: large monorepos can place an AGENTS.md in each subproject; agents read the nearest file in the directory tree and the closest one takes precedence; explicit user chat prompts override everything.
• Cursor docs: AGENTS.md is supported in the project root and subdirectories; a nested AGENTS.md applies automatically when working on files in that directory or its children, is combined with parent directories, and the more specific instructions take precedence.
• Claude Code docs: the rules for reading AGENTS.md are above, and the docs list differences between an AGENTS.md read through the setting and a CLAUDE.md, for example InstructionsLoaded hooks do not fire.

[1][2][3]

For exact AGENTS.md behavior and version requirements in any tool, rely on that tool's current official docs.[2]