What loads with the default setting?

Files foundWhat Claude Code reads
AGENTS.md, with no project CLAUDE.md or CLAUDE.local.mdAGENTS.md directly, if the session supports it
AGENTS.md plus a project CLAUDE.md or CLAUDE.local.mdThe Claude files; AGENTS.md is skipped unless imported
Project AGENTS.md plus only ~/.claude/CLAUDE.mdBoth the user-level Claude file and project AGENTS.md
CLAUDE.md containing @AGENTS.mdCLAUDE.md and the imported AGENTS.md content
Decision diagram showing when Claude Code loads Claude instruction files or AGENTS.md by default
A project-path Claude file wins the default selection. Without one, a supporting Claude Code session can load AGENTS.md directly; a user-level Claude file does not block it. Credit: Original deterministic editorial diagram by Grow AI Skills. Open full-size image.

The file that changes the choice may be above your repository. Claude Code checks its current working directory and every parent directory for CLAUDE.md, .claude/CLAUDE.md, and CLAUDE.local.md. User-level ~/.claude/CLAUDE.md, managed instructions, and .claude/rules/ do not stop a project AGENTS.md from loading by default.

Consider a repository that uses AGENTS.md for the team. One developer adds a personal CLAUDE.local.md:

repo/
  AGENTS.md
  CLAUDE.local.md

With the default setting, that developer's session reads CLAUDE.local.md and skips AGENTS.md. A teammate without the local file reads AGENTS.md, assuming direct support is available. For the first developer, /context should list CLAUDE.local.md under Memory files; the teammate should see an AGENTS.md loaded line in the conversation. To keep the personal file and load the shared instructions too, select claude-md-and-agents-md under Project instructions. The setting takes effect from the next message.

Diagram comparing two developers when only one has CLAUDE.local.md beside a shared AGENTS.md
A personal CLAUDE.local.md can make two developers load different project instructions. Selecting claude-md-and-agents-md makes both files load from the next message. Credit: Original deterministic editorial diagram by Grow AI Skills. Open full-size image.

When AGENTS.md is selected, Claude Code reads AGENTS.md and .claude/AGENTS.md along the startup path. A nested AGENTS.md is loaded later when Claude opens a file in that subdirectory with its Read tool, provided that directory has no CLAUDE.md, .claude/CLAUDE.md, or CLAUDE.local.md of its own. Files named AGENTS.local.md or AGENTS.override.md, and files under .agents/, are not read through this mechanism.

How to check a session that seems to ignore AGENTS.md

  1. Run claude --version. Direct AGENTS.md loading requires v2.1.277 or later. If you just installed or upgraded to a supporting version, start another session; Anthropic says the first session after installation or upgrade may not load it.
  2. From the directory where you launched Claude Code, look for CLAUDE.md, .claude/CLAUDE.md, and CLAUDE.local.md there and in each parent directory. Any of these explains why the default chose Claude files. Do not count ~/.claude/CLAUDE.md as a project-path blocker.
  3. In Claude Code, open /config and inspect Project instructions. The default is claude-md-or-agents-md. If the setting is missing, that session cannot load AGENTS.md directly. Documented causes include unavailable Anthropic feature flags with some third-party providers or telemetry disabled, disableAllHooks or allowManagedHooksOnly, and a disabled built-in agents-md plugin.
  4. Under the default setting, check the conversation for a line such as AGENTS.md loaded: /path/to/repo/AGENTS.md. Directly loaded AGENTS.md does not appear in /memory or the Memory files list in /context. It also does not fire an InstructionsLoaded hook. An AGENTS.md imported through CLAUDE.md appears in that list; an import or symlink does fire the hook. A missing hook event alone cannot establish that direct loading failed.

An AGENTS.md loaded line confirms inclusion, not obedience. Claude Code treats instruction files as context, so check for conflicting files before diagnosing the loader. If a command must be blocked regardless of what Claude decides, Anthropic recommends a PreToolUse hook.

Keep AGENTS.md as the shared file

For a repository used by Claude Code and other coding agents, put the shared instructions in AGENTS.md. If the repo also needs Claude-specific instructions, place this import at the top of a CLAUDE.md in the same directory:

@AGENTS.md

## Claude Code

Use plan mode for changes under src/billing/.

The @AGENTS.md line imports the file; a sentence that merely asks Claude to read it does not guarantee it will open it. Anthropic says an imported or symlinked AGENTS.md is not loaded twice. The import also works in sessions where direct AGENTS.md loading is unavailable. If you only need the shared instructions, an AGENTS.md with no project Claude file is simpler where direct support works.

If you want both files read directly, set Project instructions in /config to claude-md-and-agents-md. Claude Code reads each directory's Claude files before its AGENTS.md. The same control offers claude-md, which reads only Claude files, and managed-only, which leaves project, local, and user instruction files out at launch. Under managed-only, a subdirectory's CLAUDE.md or a path-scoped rule can still load when Claude reads a file there. Anthropic also documents a pluginConfigs setting under agents-md@builtin for user or managed settings; Claude Code ignores that option in project and local settings files.

If /config has no Project instructions control, use the @AGENTS.md import. Start a new session after adding it, then run /context to confirm CLAUDE.md appears under Memory files.