Summary

From v2.1.277 (18 September 2026), Claude Code reads AGENTS.md as project instructions on its own. A repository with a good AGENTS.md doesn't need a CLAUDE.md, an import, or a setting. Write AGENTS.md for every coding agent and stop there unless Claude Code needs something no other tool should see.

Default: no CLAUDE.md. Claude Code reads AGENTS.md when there is no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in the working directory or above it
A CLAUDE.md hides AGENTS.md. If any of those three files exists, Claude Code reads it instead and skips AGENTS.md, unless the file imports it with @AGENTS.md
If you add one, start it with @AGENTS.md and put only Claude-only instructions below the import
Enforced rules go in settings. Tool allow and deny rules and the default permission mode belong in .claude/settings.json. Instruction files are context Claude weighs, not configuration it enforces
Old workarounds can go: a CLAUDE.md that only imports AGENTS.md, a CLAUDE.md symlink, or a SessionStart hook that prints AGENTS.md

Which files Claude Code reads

With the default setting:

In the repository	What Claude Code reads
`AGENTS.md` only	`AGENTS.md`
`AGENTS.md`, plus a `CLAUDE.md`, `.claude/CLAUDE.md` or `CLAUDE.local.md` on the path	The `CLAUDE.md` files only
`AGENTS.md`, plus a `CLAUDE.md` that imports it with `@AGENTS.md`	Both: `AGENTS.md` through the import, then the rest of `CLAUDE.md`
`CLAUDE.md` only	`CLAUDE.md`

The details that change outcomes:

What doesn't count. A user's ~/.claude/CLAUDE.md, an organization's managed CLAUDE.md, and .claude/rules/ files don't stop AGENTS.md loading. They load alongside it.
Nested files. Every AGENTS.md and .claude/AGENTS.md from the working directory upward loads at session start. A subdirectory's AGENTS.md loads when Claude reads a file in that directory, as long as the directory has no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md of its own. @path imports inside AGENTS.md are expanded.
What isn't read. AGENTS.local.md, AGENTS.override.md, and anything under .agents/.
CLAUDE.local.md counts. A developer who adds one for personal notes in an AGENTS.md-only repository stops Claude Code reading AGENTS.md for themselves, with no warning. Start the local file with @AGENTS.md, or set Project instructions to claude-md-and-agents-md.
The setting is per person. Project instructions (in /config) takes claude-md-or-agents-md (the default), claude-md-and-agents-md, claude-md, or managed-only. It can be set in user or managed settings, but Claude Code ignores it in a project's settings files, so a repository can't choose it for contributors. Write the repository for the default.
Checking what loaded. /memory lists the instruction files Claude read.

See Claude Code's memory docs for the full rules.

Sessions that still need a CLAUDE.md

In these sessions Claude Code reads CLAUDE.md files only:

Claude Code before v2.1.277
Before v2.1.281 (23 September 2026), some sessions such as Amazon Bedrock or with telemetry disabled
The built-in agents-md plugin disabled in /plugin
Sometimes, the first session after upgrading from v2.1.276 or earlier

If contributors or automation run in any of these, keep a CLAUDE.md that contains @AGENTS.md. On newer versions the import never loads AGENTS.md twice.

When to add a CLAUDE.md

Only when Claude Code needs instructions that other agents shouldn't get:

Claude Code skills, or slash commands this repository expects Claude to use
Hooks or servers the repository configures for Claude Code that change how Claude should work
Workflow notes that only make sense in Claude Code

Keep out of it:

Anything true for every agent. Commands, conventions, boundaries and layout belong in AGENTS.md.
Tool rules and permission mode. Put them in .claude/settings.json, where Claude Code enforces them (see below).
Hard stops. A rule that must hold whatever Claude decides needs a PreToolUse hook, not a sentence.
Model choice and memory configuration. Those are decisions about building agents, not context for working in this repository.

Writing one

Put the import on the first line and only Claude-only lines under it:

@AGENTS.md

## Claude Code

- Run /security-review on changes under src/auth/ and src/crypto/
- The PostToolUse hook in .claude/settings.json formats files after each edit; don't run the formatter by hand

In most repositories that need a CLAUDE.md, that's the whole file. Claude reads AGENTS.md first, then the lines below it.

A sentence such as "See " doesn't load the file. Claude only sees it if it decides to open it, so always use the @AGENTS.md import.

A symlink (ln -s AGENTS.md CLAUDE.md) also avoids duplication, but it leaves no room for Claude-only lines, Claude's edit tools refuse to write through it, and a Windows clone without core.symlinks checks it out as a one-line text file. Use the import.

Tool rules belong in settings

Instruction files are context. Claude Code doesn't enforce a sentence saying "never deploy". Permission rules in .claude/settings.json are enforced for everyone who works in the repository:

{
  "permissions": {
    "allow": ["Bash(pnpm test *)", "Bash(pnpm lint)"],
    "ask": ["Bash(pnpm db:migrate)"],
    "deny": ["Bash(vercel deploy *)", "Read(./.env)"],
    "defaultMode": "plan"
  }
}

deny and ask rules apply straight away; allow rules in a project file apply once each contributor trusts the folder. A project file can't set auto or bypassPermissions as the default mode. Those only take effect from user or managed settings. See Claude Code permissions for the rule syntax.

Moving off an older setup

What the repository has	What to do
A `CLAUDE.md` containing only `@AGENTS.md`	Delete it, unless some sessions can't read `AGENTS.md` (see above)
A `CLAUDE.md` that says "see AGENTS.md" in words	Delete it, or replace the sentence with `@AGENTS.md`
A `CLAUDE.md` that restates `AGENTS.md`	Move anything missing into `AGENTS.md`, then delete the file or cut it to Claude-only lines under the import
A `CLAUDE.md` symlinked to `AGENTS.md`	Harmless. Delete it when convenient
A `SessionStart` hook that prints `AGENTS.md`	Remove it. It now adds a second copy to the context
Tool rules or a permission mode written in `CLAUDE.md`	Move them to `permissions` in `.claude/settings.json`

Monorepos

Each package keeps its own AGENTS.md, and Claude Code picks it up when it reads a file in that package. A package-level CLAUDE.md hides that package's AGENTS.md just as a root one does, so if a package needs one, start it with @AGENTS.md. See Monorepos for how other tools resolve nested files.

Auto memory and rules

Claude Code also keeps auto memory, notes Claude writes itself from your corrections, and reads .claude/rules/, topic files that can be scoped to paths with paths frontmatter. Both load alongside AGENTS.md. Neither needs a mention in CLAUDE.md unless a contributor has to know the repository relies on one. See Claude Code's memory docs for how both work.

CLAUDE.md