In Claude Code, one CLAUDE.md silently kills your AGENTS.md

A dead AGENTS.md reads exactly like a live one, and nothing in the session tells you which you have. That is the practical upshot of the AGENTS.md support that Claude Code 2.1.277 shipped on 18 September 2026, as a guide published on GitHub works through it against Anthropic's memory docs.

At a glance

• The changelog line for Claude Code 2.1.277 added AGENTS.md support for projects with no CLAUDE.md, retiring the pile of symlink and @AGENTS.md include hacks teams used to keep one instruction file.
• It is a fallback, not a merge: a CLAUDE.md, a .claude/CLAUDE.md or a stray CLAUDE.local.md at or above your working directory switches AGENTS.md off completely.
• The file is invisible to tooling, since AGENTS.md never appears in /memory or /context and InstructionsLoaded hooks do not fire for it, and it is not read at all on Bedrock, Vertex or Foundry.

If you have not followed the instruction-file wars: AGENTS.md was formalized at agents.md in mid-2025 and, by Product at Work's account, co-promoted by OpenAI, Google, Cursor, JetBrains and Anthropic as an alternative to .cursorrules, copilot-instructions and CLAUDE.md. According to Kingy AI, OpenAI says more than 60,000 open-source projects have adopted it since the August 2025 release, and the specification was donated to the Agentic AI Foundation under the Linux Foundation in December 2025.

A stray CLAUDE.local.md is enough to switch AGENTS.md off

By default, Claude Code reads AGENTS.md only when there is no CLAUDE.md in your working directory or above it. If both files exist, AGENTS.md is ignored entirely. It is not appended, and it is not merged.

Three files trigger that: CLAUDE.md in the working directory or above, .claude/CLAUDE.md in the same places, and CLAUDE.local.md. Three others load alongside AGENTS.md instead of killing it: your user memory at ~/.claude/CLAUDE.md, your organization's managed CLAUDE.md, and files under .claude/rules/.

The advice that follows is blunt: pick one instruction file and delete the other, because keeping both leaves an AGENTS.md that is dead weight and reads as if it were live. And when a teammate reports that the agent ignores a rule everyone else sees, look for a stray CLAUDE.local.md.

AGENTS.md is not read on Bedrock, Vertex or Foundry

Teams on a cloud provider get CLAUDE.md behavior regardless of what their repo contains. The same goes for any session that skips feature-flag fetching, which covers sessions with DISABLE_TELEMETRY, DO_NOT_TRACK or CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC set, and the first session after an install or upgrade.

The gaps inside the repo are just as specific. There is no user-level AGENTS.md, so personal preferences stay Claude-specific. There is no managed or enterprise one either, and under a managed-only policy every AGENTS.md is left out.

Nothing under a .agents/ directory is read, and neither AGENTS.local.md nor AGENTS.override.md is a thing. Directories added with --add-dir do not contribute one. And the files never show up in /memory or /context, with no InstructionsLoaded hook firing for them.

Four values sit behind one setting called instructionFiles

The behavior ships as a built-in mod, agents-md@builtin, with a single option named instructionFiles. You reach it from /config under "Project instructions", or write it into settings under pluginConfigs by hand.

There are four values. claude-md-or-agents-md is the default fallback; claude-md-and-agents-md reads both files; claude-md ignores AGENTS.md; managed-only leaves every AGENTS.md out.

What matters is where the switch lives. It is a client preference, like a spell-check option that sits in your editor rather than in the document, so the repo cannot turn the merge on for the whole team. If you want both files read, every developer opts in individually.

agents.md carries no version number, and permissions reach 11 of 33 tools

The standard standardizes less than its adoption implies. agents.md is a website with an FAQ rather than a versioned specification: no version number, no date, no normative language, no required fields. It is plain Markdown, and the nearest file to the edited one wins. Of the 33 tools AgentsMesh generates for, 17 read a root AGENTS.md, and Claude Code now makes 18.

Agent Plugins 1.0.0, backed by maintainers from Amazon, Cursor, Microsoft, OpenAI and Vercel, defines exactly two component types, skills and MCP servers, and says why it stops there:

Other proposed component types — such as commands, hooks, agents, rules, and LSP servers — remain too client-specific for a stable portable contract and are outside the v1 format until their formats converge.

Permissions are deferred separately: v1.0.0 defines no trust model, permission system or sandboxing requirements. Counting native support across those 33 tools, rules land at 33, skills at 31, MCP servers at 27, subagents at 21, hooks at 18 and permissions at 11.

The guide comes from AgentsMesh, a project built for the rows marked None, and it says so, including that one AGENTS.md is now genuinely enough for many teams. In our view the odd part is placement: the file is checked into the repo, the setting deciding whether it is read is not. The guide also flags a soft spot of its own field — a shared .agents/skills/ location is often called settled and is still just a proposal.

Whether .agents/skills/ lands Agent Skills pins down the SKILL.md format but not where skills sit on disk, which is why Claude Code reads .claude/skills/ while the proposal for a shared directory stays open. No date is attached to it, and none is given for AGENTS.md support on Bedrock, Vertex or Foundry. The guide was verified against its sources on 19 September 2026 and notes that Claude Code ships often enough for any of this to move.