Claude Code v2.1.277 and later reads a repository's AGENTS.md as project instructions whenever there is no CLAUDE.md at or above your working directory. It is the default, and AGENTS.md ships in more than 60,000 repositories.
The file loads on a different path than CLAUDE.md. It does not appear in /memory or in the Memory files list in /context, and InstructionsLoaded hooks do not fire for it.
The setting that controls this is ignored in project and local settings files. Only user settings, a --settings file, or managed settings can change it, so a repository cannot switch it on for you.
What actually shipped
The changelog line landed on 19 September and reads plainly enough: in a project with no CLAUDE.md, Claude Code reads AGENTS.md instead. The docs put the version floor at v2.1.277.
The precedence is simple. A CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in your working directory or any directory above it wins, and AGENTS.md is ignored. With none of those present, every AGENTS.md and .claude/AGENTS.md from your working directory upward loads at session start. As Claude opens files in subdirectories, a subdirectory's own AGENTS.md loads too, unless that subdirectory has one of the three CLAUDE.md files of its own.
Your ~/.claude/CLAUDE.md, your organization's managed CLAUDE.md, and .claude/rules/ files do not count for that check. They keep loading alongside.
A repository already set up for other agents now works without anyone adding a shim file. That is a sensible feature. The interesting part is the four places where the new path behaves differently from the old one.
The file you did not write is the normal one now
AGENTS.md is an open format stewarded by the Agentic AI Foundation under the Linux Foundation. It came out of work by OpenAI Codex, Amp, Jules, Cursor and Factory, and around 25 tools read it natively, including Codex, Cursor, Gemini CLI, the GitHub Copilot coding agent, Devin, Windsurf, Zed, Aider, goose, Junie and VS Code.
It is worth being precise about what changed, because the easy version of this story is wrong. CLAUDE.md is also a file that arrives with the repository. Cloning a hostile repo and running an agent in it was never safe. The trust boundary did not move.
What moved is coverage. Until this release, a repository could only steer Claude Code through a file named for Claude Code. That file is conspicuous. A reviewer glancing at a pull request notices a new CLAUDE.md the way they notice a new Makefile target. AGENTS.md is the opposite: it is the expected file, present in tens of thousands of projects, boring by design, and nobody flags it in review because it is supposed to be there.
The docs are honest about what these files are. They say Claude treats project instructions as context, not enforced configuration, and that to block an action regardless of what Claude decides you want a PreToolUse hook. That is the right framing, and it matters for what follows.
Four places the two paths diverge
An AGENTS.md read through the Project instructions setting differs from a CLAUDE.md in four documented ways.
It is not listed in /memory, and it is not in the Memory files list in /context. To confirm it loaded you look for an AGENTS.md loaded: line in the conversation, or you ask Claude what its project instructions say. The two places built for answering "what is in my context right now" do not answer it.
InstructionsLoaded hooks do not fire. If you wrote a hook to scan project instructions at load time, log them, diff them against an approved baseline, or refuse a session when something unexpected appears, that hook stays quiet on the new path. It still fires for an AGENTS.md that a CLAUDE.md imports or symlinks to, which is exactly the setup teams used before this feature existed. Upgrading and deleting the shim CLAUDE.md is what turns the hook off.
Directories you add with --add-dir do not contribute their AGENTS.md, even with CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD set. Their CLAUDE.md still loads.
And an @path import pointing outside your working directory behaves differently on consent. From a CLAUDE.md, Claude Code asks you to approve external imports. From an AGENTS.md, it loads with no prompt if you already approved external imports for that project. The approval is real and you granted it, so this is not a bypass. It is an approval given on one path being honored on another, a smaller thing than a prompt you never saw, and still worth knowing.
Enforcement is intact across all four. PreToolUse still fires, deny rules still apply, sandboxing still works. The gap is in review and visibility, not in the blocking layer. That is the less alarming read and the more useful one, because visibility is usually what people had actually built.
The local notes file that switches it off
The reversal that will bite someone is one file name.
CLAUDE.local.md counts as a CLAUDE.md for the precedence check. So on a team that standardized on AGENTS.md, the developer who keeps their own uncommitted instructions in a CLAUDE.local.md, which is the tidy thing to do, stops Claude from reading the team's AGENTS.md entirely. They get their personal notes and none of the shared project context, and the session looks completely normal.
The fix is to set Project instructions to claude-md-and-agents-md so both load. The point is that nothing tells you. The failure mode of losing your project instructions is an agent that is slightly worse at your codebase, which reads as a bad day rather than a misconfiguration.
Where the setting lives is the good news
Project instructions takes four values. claude-md-or-agents-md is the default. claude-md-and-agents-md loads both, CLAUDE.md first in each directory. claude-md reads CLAUDE.md only. managed-only drops everything except your organization's managed CLAUDE.md and auto memory at launch, including your .claude/rules/ files and every AGENTS.md.
You set it in /config, or under the built-in agents-md plugin's ID in pluginConfigs. It works in ~/.claude/settings.json, a --settings file, or managed settings, and Claude Code ignores it in project and local settings files.
That last clause is the part worth crediting. A repository cannot set this for you. It cannot turn itself on, and it cannot switch a locked-down fleet back to reading repo-supplied instructions. Central policy wins, and that is the correct shape for a setting that decides which untrusted file gets read into the prompt.
It is quietly off in more places than you think
Support is absent, and Project instructions does not even appear in /config, in several situations: on versions before v2.1.277, in sessions that do not fetch feature flags from Anthropic, which includes Amazon Bedrock and other third-party providers or a session with telemetry disabled, on your first session after installing or upgrading, and when you or your organization set disableAllHooks or allowManagedHooksOnly, or disabled the built-in agents-md plugin.
The reader is itself a built-in plugin riding the hook system, which is why turning hooks off turns it off. So a hardened enterprise on Bedrock with managed hooks gets the old behavior, and a developer on the same team running the CLI against the API gets the new one, from the same repository, on the same commit. Same code, different loaded context, no signal in either session that they differ.
The short list
Decide the value deliberately instead of inheriting the default. claude-md-and-agents-md for teams that use both, claude-md or managed-only if you run agents against code you did not write. Push it through managed settings, because that is the only layer a repo cannot argue with.
If you have InstructionsLoaded hooks doing governance work, check whether the repos they cover still have a CLAUDE.md. Keeping the @AGENTS.md import in a thin CLAUDE.md keeps the hook firing, and the docs confirm the content is not read twice.
Grep your own repos for CLAUDE.local.md before assuming everyone is getting the project instructions you wrote.
Add AGENTS.md to the paths your pull request review treats as sensitive. It is a configuration file for an agent that runs with your developer's access, and right now it probably sits in the same review bucket as the README.
Boring is the whole trick
The reason this one is worth twenty minutes is not that it is dangerous. It is that a file became load-bearing by becoming standard, and standard files stop getting looked at. That is the entire mechanism.
Sixty thousand repositories, a Linux Foundation project, twenty-five tools reading it natively, and a default that switches on with an upgrade. Every one of those facts is a reason to trust AGENTS.md, and together they are also the reason nobody will read one again.