Max Nardit
Dev

Claude Code now reads AGENTS.md, and the default is a fallback

Anthropic solved loading again and left precedence where it was. The default decides which project file loads by what happens to exist on disk, the file it loads stays out of the inventories you would audit it with, and the old one-line import is still the setup that behaves the same across providers and versions.

Claude Code v2.1.277 shipped on September 18 with the line the AGENTS.md feature request (#6235) had asked for:

text
Added AGENTS.md support: in a project with no CLAUDE.md, Claude Code reads
AGENTS.md instead; change it under "Project instructions" in /config
(not yet on Bedrock, Vertex or Foundry)

A repository set up for other coding agents now works in Claude Code without a CLAUDE.md, an import, or a hook. What the changelog line doesn't say is what happens when both files exist, and which sessions never get the feature at all.

What exactly did Anthropic ship?

A setting with four values, and a default that picks one file, not both. Under claude-md-or-agents-md (the default), Claude reads your CLAUDE.md files, or your AGENTS.md files if there is no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in the working directory or above it. claude-md-and-agents-md reads both, each directory's CLAUDE.md first. claude-md restores the old behavior, and managed-only loads only the organization's managed file and auto memory at launch.

Your ~/.claude/CLAUDE.md, the managed CLAUDE.md and .claude/rules/ don't count toward the check, so they keep loading alongside AGENTS.md. And the setting is ignored in project and local settings files; it lives in user settings, a --settings file or managed policy. A cloned repository cannot switch itself into the both-files mode.

Is the default a merge or a fallback?

A fallback. In August I argued that instruction files are addressing, not fragmentation: an import composes layers, a fallback reads one file and drops the other. The default does exactly that at the project layer. The operator layer survives, which is the right call, but between CLAUDE.md and AGENTS.md the rule is presence on disk.

That has a sharp edge the docs flag themselves. CLAUDE.local.md counts. A developer who adds one to keep personal, uncommitted notes in an AGENTS.md project stops Claude from reading the team's AGENTS.md, for them only, with no error. The project did not change; one developer's gitignored file did, and the team's instructions vanished for that one seat.

The both-files mode doesn't settle it either. It concatenates, CLAUDE.md before AGENTS.md, and the docs are candid about conflicts elsewhere: when two rules contradict, Claude may pick either. Order in a context window is not precedence. In August I granted a merged file one rule, document order. The docs say it does not even have that. The question my August piece left open, which file wins and why, is now open one layer down, between two project files instead of between a project and its operator.

Where does it quietly not work?

In any session that doesn't fetch feature flags from Anthropic, which covers Amazon Bedrock, other third-party providers and sessions with telemetry disabled. Also in the first session after installing or upgrading to the version that adds it, in setups with disableAllHooks or allowManagedHooksOnly, and any session where the built-in agents-md plugin is disabled. In all of those, Claude reads CLAUDE.md only and the setting doesn't even appear in /config.

So the same repository can hand two teammates different project instructions depending on their provider, their telemetry choice, or whether this is their first session on the new version. For a team, that is the more important sentence in the changelog, and it isn't in the changelog.

Does this open a new trust hole?

Barely. A repository could always ship a CLAUDE.md, so AGENTS.md reaching the model adds no new authority. External @path imports inside an AGENTS.md don't even raise the approval dialog; they load only if you already approved external imports for that project.

What changes is visibility. The default prints a one-line notice in an interactive session when it loads AGENTS.md, but the file doesn't show up in /memory or in the Memory files list in /context, and InstructionsLoaded hooks don't fire for it. If your instruction audit relies on that hook, this loading path never appears in the log. The hook only observes and can't block a load anyway, which is the difference between a log and a gate I drew when I wrote that a prompt is not an invariant. A repo written for another agent now reaches Claude through the one path your audit does not watch. One of my own repos is exactly that: an AGENTS.md headed "Codex Instructions" and no CLAUDE.md, which makes it eligible for the fallback in any supported session.

What should a mixed-tool team do?

Keep the one-line import. A CLAUDE.md that says

markdown
@AGENTS.md
 
## Claude Code
(Claude-specific lines go here)

loads AGENTS.md wherever project instructions load, including Bedrock and telemetry-off sessions, appears in /context, fires InstructionsLoaded when your hooks are on, and leaves room for lines that are only for Claude. The docs confirm that keeping the import never makes Claude read AGENTS.md twice, under any setting. One limit: an import pulls in only the file it names. Once a CLAUDE.md exists, the default stops discovering AGENTS.md files in subdirectories too, so a nested AGENTS.md needs its own CLAUDE.md import next to it, or the both-files setting. The native fallback is a good default for the stranger who opens your repo once. For the people who work in it every day, an explicit reference still beats a rule decided by which files happen to exist.

Discussion

No comment section here — all discussions happen on X.

Max Nardit

Max Nardit

@mnardit

More articles

A price you cannot compute

The bill went up by $96 a year, which is nothing. What changed underneath it is that the number is no longer derivable: the included allowance has no published size, the free credit allotment has no published size, and the annual credit costs more than the monthly one. A price you cannot compute from published figures is an estimate, and an estimate is a different kind of dependency.

The tool you install has your reach

An installed tool holds whatever authority you already have, and handing it over is the one security decision that gets no second look: taken once, in the least deliberate act of the whole install, and never revisited. You can contain what it can reach or read what its code actually touches; trusting the name does neither.

The compaction is an untrusted input

Input from outside gets a discipline and the agent's own output does not, so the summary it writes to survive a reset and the memory it recalls come back in as instructions with a standing nothing revoked. The author the harness records for them is the model itself, which is the exact reason the check lets them through.