Claude Code 2.1.277 reads AGENTS.md, but only when your repository has no CLAUDE.md

Claude Code 2.1.277, published to npm on September 18, 2026, reads AGENTS.md, the cross-vendor instructions file that other coding agents already use. The changelog entry is one line:

"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)"

The documentation behind that line is longer, and the details decide whether your repository's file is actually read.

The default is either/or, not both

Anthropic's memory documentation puts the default in a table. With an AGENTS.md and no CLAUDE.md or CLAUDE.local.md in your working directory or above it, Claude reads the AGENTS.md. With both present, Claude reads "Your CLAUDE.md files only."

What counts for that check is specific. A CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in the working directory or any parent suppresses AGENTS.md. Your personal ~/.claude/CLAUDE.md, the organization's managed CLAUDE.md and .claude/rules/ files do not, and keep loading alongside it.

The trap is CLAUDE.local.md, the file for personal, uncommitted notes. The docs spell it out: "Because CLAUDE.local.md counts, adding one to keep your own uncommitted instructions in a project that relies on AGENTS.md stops Claude from reading AGENTS.md for you."

Four settings, one of them for lockdown

The Project instructions setting in /config takes four values: claude-md-or-agents-md (the default), claude-md-and-agents-md, claude-md, and managed-only. The "and" mode reads each directory's CLAUDE.md files first and its AGENTS.md after them, and "skips an AGENTS.md it has already loaded," so an existing import or symlink is not read twice.

The setting lives under a built-in plugin's ID in pluginConfigs:

{
  "pluginConfigs": {
    "agents-md@builtin": {
      "options": { "instructionFiles": "claude-md-and-agents-md" }
    }
  }
}

It is honored in ~/.claude/settings.json, a --settings file or managed settings. "Claude Code ignores it in project and local settings files," so a cloned repository cannot change which instruction files load for you.

When it silently does nothing

The docs list the sessions where Claude "reads CLAUDE.md files only" and the setting does not even appear:

• versions before 2.1.277;
• sessions that don't fetch feature flags from Anthropic, "for example because you use Amazon Bedrock or another third-party provider, or you disabled telemetry";
• the first session after installing or upgrading to a version with support ("Claude reads AGENTS.md from your next session on");
• sessions where disableAllHooks or allowManagedHooksOnly is set, or the built-in agents-md plugin is disabled.

The telemetry item is the one most likely to surprise. A privacy-minded setup that turns telemetry off loses the feature without an error. The documented workaround works everywhere: a CLAUDE.md whose first line is @AGENTS.md.

Some differences survive even when it works. An AGENTS.md loaded through the setting is not listed in /memory or in /context's Memory files list, and InstructionsLoaded hooks "Don't fire" for it. The confirmation to look for is a conversation line such as no CLAUDE.md found; AGENTS.md loaded: /home/you/repo/AGENTS.md. Claude also does not read AGENTS.local.md, AGENTS.override.md or anything under .agents/.

Why it matters

The agents.md site describes the format as "A simple, open format for guiding coding agents, used by over 60k open-source projects," and lists Codex, Jules, Cursor, Gemini CLI and GitHub's Copilot coding agent among the tools that read it. Until this release, Claude Code users working in those repositories needed a CLAUDE.md shim to pick the file up.

Anthropic's docs also address the shims. A CLAUDE.md containing only @AGENTS.md can stay ("Keeping the import never makes Claude read AGENTS.md twice"). A SessionStart hook that prints AGENTS.md should go, because "the hook adds a second copy to the context." And a CLAUDE.md that merely tells Claude in prose to read the file never guaranteed anything: "Claude sees AGENTS.md only if it decides to open the file."

For mixed teams the safe pattern is the import, since it behaves the same on every provider and with telemetry off.

Primary sources: Claude Code CHANGELOG, Claude Code docs: How Claude remembers your project, npm registry: @anthropic-ai/claude-code, agents.md, read 2026-09-22.