How to Make Claude Code Read AGENTS.md

The short answer

Use this sequence:

1. Run claude --version. You need v2.1.277 or later.
2. Update if needed. A native install accepts claude update; Homebrew and WinGet use their own package-manager upgrade commands.
3. Confirm the session can fetch Anthropic feature flags. Native AGENTS.md loading is unavailable on third-party provider sessions such as Amazon Bedrock, Google Cloud's Agent Platform, and Microsoft Foundry, and when telemetry or nonessential-traffic settings stop that flag fetch.
4. Put AGENTS.md or .claude/AGENTS.md in the project path. Under the default mode, make sure there is no project CLAUDE.md, .claude/CLAUDE.md, or CLAUDE.local.md in the working directory or above it.
5. If you need both file families, open /config and set Project instructions to claude-md-and-agents-md.
6. Test in a fresh session. The first session after installing or upgrading is an exception, so open the next one before judging the result.

That is the native path. If Project instructions is missing from /config, keep the documented @AGENTS.md import in CLAUDE.md.

What Claude Code actually chooses

The new behavior is a switchboard, not a blanket scan for every instruction file. Under the default claude-md-or-agents-md mode, Claude Code checks for project-level Claude instructions first. It falls back to AGENTS.md only when none of the qualifying Claude files exists in the working directory or above it.

The subtle part is scope. A CLAUDE.local.md in a parent directory suppresses the fallback. A personal ~/.claude/CLAUDE.md, an organization-managed CLAUDE.md, and .claude/rules/ do not. That distinction explains many reports where two developers open the same repository and see different behavior.

When the fallback applies, Claude Code reads AGENTS.md and .claude/AGENTS.md from the working directory and directories above it at session start. A subdirectory's AGENTS.md can load later when Claude reads a file there, provided that subdirectory does not have its own qualifying Claude file. It does not directly read AGENTS.local.md, AGENTS.override.md, or files under .agents/.

This is closer to a building's electrical selector than a folder search. The selector chooses the live instruction circuit first. Files on the other circuit can be perfectly valid and still remain disconnected.

Set the Project instructions mode deliberately

Open /config, find Project instructions, and choose based on the repository's intended source of truth:

• Fallback, claude-md-or-agents-md: best for a repository that already uses AGENTS.md and has no project Claude file. This is the default.
• Both, claude-md-and-agents-md: best when AGENTS.md holds shared rules and CLAUDE.md adds Claude-specific guidance.
• Claude only, claude-md: best when a team is not ready to expose shared agent instructions to Claude Code.
• Managed only, managed-only: best for a controlled launch context where organization policy and auto memory should load, but repository instructions should not load at startup.

In the both mode, Claude Code reads each directory's Claude content before its AGENTS content. It also avoids loading the same AGENTS.md twice when CLAUDE.md already imports or symlinks to it.

The choice takes effect from the next message and persists into new sessions. It can also live under the built-in agents-md@builtin plugin in user settings, a --settings file, or managed settings. Claude Code ignores this option in project and local settings files, so a repository cannot silently force every developer into the same selection. An administrator can make the choice centrally through managed settings.

Prove which file a fresh session loaded

Use a harmless fact, not a destructive instruction. Add this line to the file you want to test:

Project probe: BASALT-HERON.

Then close the session, start the next fresh session in the repository, and ask: What is the project probe? A correct BASALT-HERON response shows that the content reached the session context. Remove the line after the check.

Do not use /context as the only verdict. A directly loaded AGENTS.md does not appear in its Memory files list. Under the default fallback, an interactive session can show an AGENTS.md loaded startup line. Asking for the harmless probe works across the other selection modes too.

If the probe fails, check these in order:

1. Version: v2.1.277 or later.
2. Session count: not the first session after installation or upgrade.
3. Provider: not a session whose provider prevents Anthropic feature-flag fetching.
4. Environment: no telemetry or nonessential-traffic variable has disabled that fetch.
5. Plugin and policy: the built-in agents-md plugin is enabled, and neither disableAllHooks nor allowManagedHooksOnly blocks it.
6. File hierarchy: no qualifying CLAUDE.md, .claude/CLAUDE.md, or CLAUDE.local.md exists at the current level or above under the default mode.
7. Mode: /config points to the behavior you intend.

If Project instructions does not appear in /config, that is itself a diagnostic signal. The session is on an unsupported version or cannot use the feature.

Keep the import where native support cannot run

The existing import remains the safest compatibility layer for Bedrock, Vertex, Foundry, other third-party provider sessions, telemetry-restricted environments, and mixed-version teams. Put this in CLAUDE.md next to AGENTS.md:

@AGENTS.md

You can add Claude-specific instructions below it. Claude reads the imported shared file first and the Claude-specific additions after it. Keeping this bridge does not cause double-loading when a supported user selects the both mode.

A symlink from CLAUDE.md to AGENTS.md also works, but the import is the safer cross-platform choice. On Windows, symlink creation can require elevated privileges or Developer Mode, and Git needs the right symlink setting. A SessionStart hook that prints AGENTS.md should be removed once direct loading works because it can inject a duplicate copy.

The release changes the maintenance math. Before it, a team with one cross-agent policy often carried two files, an import shim, or a hook. On supported sessions, the default path can now be one committed instruction file. The Claude license line does not get cheaper: Anthropic lists Claude Code in the $20 monthly Pro plan. The saving is fewer synchronization points and fewer sessions working from stale rules.

For the rest of the setup, the broader Claude Code walkthrough explains installation, project context, and the daily command flow. If your repository defines specialist agents too, the subagent guide covers their separate startup context.

Seven situations where this pays

These are ranked by the size of the coordination problem the new selector removes.

The first three cases carry the biggest return because the failure is multiplied across people and repositories. For a solo repository with one agent, the convenience is real but small.

What you could build around this

1. A cross-agent instruction doctor

Build a local CLI and CI check that explains exactly which instruction files each coding agent will load. Platform teams and consultancies would pay for a reliable answer before a repository rollout.

Demand is already visible: claude code setup gets about 1,900 US searches a month, while claude md vs agents md gets 480 and has grown 1,500% year over year. The smallest sellable version scans the file tree, reads the Claude Code version and provider configuration, flags shadowing files, and prints a load-order plan. A paid team layer could enforce the same policy across repositories.

This is the strongest opportunity because it solves a diagnosis problem, not a template problem. The catch is platform risk. Anthropic could fold the checks into claude doctor, so the durable product needs coverage across several coding agents and a history of policy drift, not a single Claude command.

2. An AGENTS.md policy starter and linter

Build a guided editor that turns build commands, test rules, directory boundaries, and review requirements into a concise AGENTS.md, then checks it for conflicts and vague language. Small engineering teams adopting multiple agents are the buyer.

agents md gets about 2,900 US searches a month. The narrower agents md best practices query gets 210 and has grown 750% year over year. An MVP needs a repository scanner, a short interview, a generated draft, and lint rules for duplicated or contradictory instructions. It should stay under the provider's guidance for concise project files rather than producing a giant policy manual.

The catch is weak defensibility. Every coding agent can draft Markdown. The product earns its place only if its validation reflects real load order and can prove that each supported coding tool consumed the result.

3. A mixed-fleet migration audit

Offer a report that maps CLAUDE.md, AGENTS.md, imports, symlinks, hooks, nested rules, and provider exceptions, then produces a safe one-source migration plan. Agencies and larger teams with several agent tools are the likely buyers.

The 480 monthly searches for claude md vs agents md, up 1,500% year over year, are unusually direct evidence of the confusion. The MVP can be a read-only repository analyzer plus a pull-request plan. It should never delete a bridge automatically because unsupported sessions may still need it.

The catch is a short freshness window. Once teams converge on a stable shared-file convention, one-off migrations shrink. Recurring policy audits and provider compatibility checks need to become the core service.

Limits and the honest take

Native fallback removes a bridge. It does not turn project instructions into enforcement, make every provider compatible, or settle conflicting rules. Anthropic describes instruction files as context. If a command must always be blocked, use a permission rule or a PreToolUse hook.

It also does not make AGENTS.md visible in the same diagnostics as CLAUDE.md. A direct load is absent from /memory and the Memory files list in /context. That inconsistency makes the harmless probe worth keeping in your migration checklist.

Do not remove a working import across a mixed provider fleet just because one laptop passes the native test. Do not choose the both mode without reviewing contradictions. Claude content is read before AGENTS content within a directory, but context order is not a hard policy precedence system.

The release is still a meaningful operational improvement. A repository that already treats AGENTS.md as its shared source can now work with Claude Code without pretending the second filename is the source. That is a small feature with a large coordination effect.

If you want a reliable multi-agent instruction system built for your repositories, I can help with the agent architecture and rollout.