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

Claude Code 2.1.277, released September 18, reads AGENTS.md only in a project that has no CLAUDE.md. If a repo has both files, AGENTS.md is ignored entirely: it isn’t appended to CLAUDE.md and it isn’t merged with it.

That is the starting point of a guide from the AgentsMesh project, published on GitHub, which was checked against Anthropic’s memory documentation on September 19 and maps where the fallback stops. The guide notes that most repos that care about this already have both files.

Three files switch AGENTS.md off: CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md, in the working directory or any directory above it. Three others load alongside it: your user memory at ~/.claude/CLAUDE.md, your organization’s managed CLAUDE.md, and files under .claude/rules/. If a single teammate says the agent is ignoring a rule everyone else sees, the guide’s advice is to look for a stray CLAUDE.local.md.

The guide lists five things the fallback doesn’t do:

• There is no user-level AGENTS.md. Nothing cross-tool replaces ~/.claude/CLAUDE.md, so personal preferences stay Claude-specific.
• There is no managed or enterprise AGENTS.md. Under a managed-only policy, every AGENTS.md is left out.
• Nothing under .agents/ is read, and neither are AGENTS.local.md or AGENTS.override.md.
• Directories added with --add-dir don’t contribute their AGENTS.md.
• The file is invisible to your tooling. It isn’t listed in /memory or /context, and InstructionsLoaded hooks don’t fire for it.

Shopify’s Tobi Lutke had floated banning Claude Code until it read AGENTS.md and .agents/skills, in a post that hasn’t been independently verified. Version 2.1.277 covers the first of those two.

Availability is narrower than the changelog’s one-line caveat suggests. The fallback doesn’t work on Amazon Bedrock, Google Vertex AI or Microsoft Foundry. Nor does it work in any session that skips feature-flag fetching, which includes sessions with DISABLE_TELEMETRY, DO_NOT_TRACK or CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC set, and the first session after an install or upgrade. Teams on a cloud provider get CLAUDE.md behaviour whatever their repo contains.

Reading both files is opt-in. The behaviour is a built-in mod, agents-md@builtin, with an instructionFiles option you can set under “Project instructions” in /config or in settings under pluginConfigs. It takes four values: claude-md-or-agents-md (the default fallback), claude-md-and-agents-md (read both), claude-md (ignore AGENTS.md) and managed-only. Each developer has to make the switch individually, which is why the guide’s first step is to pick one instruction file and delete the other: with the default in place, a kept AGENTS.md “is dead weight that reads as if it were live.”

What agents.md standardizes

The standard Claude Code now honours is a website and an FAQ rather than a versioned specification. It has no version number, no date and no normative language, the “must” and “should” wording a spec uses to define what’s required. It describes itself this way:

Think of AGENTS.md as a README for agents: a dedicated, predictable place to provide the context and instructions to help AI coding agents work on your project.

It has no required fields. It’s plain Markdown, and the file nearest to the one being edited wins. That informal contract has spread anyway: the agents.md site says more than 60k open-source projects use the format. AgentsMesh counts 17 root-AGENTS.md readers among the 33 tools it generates config for, and Claude Code makes 18.

The rows marked “None”

Beyond instruction files, the most serious attempt at a portable format is Agent Plugins 1.0.0, backed by maintainers from Amazon, Cursor, Microsoft, OpenAI and Vercel. It defines exactly two component types, skills and MCP servers, and explains 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 excluded separately: v1.0.0 “does not define a trust model, permission system, or sandboxing requirements for plugins.” Slash commands, subagents and hooks have no cross-tool standard, and neither do ignore files. Even skills are only partly covered. Agent Skills defines the SKILL.md format but not where skills live on disk. Claude Code reads .claude/skills/, and the proposal for a shared .agents/skills/ location is still open, although it’s often described as settled.

AgentsMesh’s own count across its 33 tools shows how uneven native support is. All 33 support rules, 31 support skills, 27 support MCP servers, 21 support subagents, 18 support hooks and only 11 support permissions. Claude Code has a real allow-and-deny model, the guide says, while most tools have something weaker, something shaped differently, or nothing. There is no portable way to say “never run terraform apply” and have every assistant on a team honour it.

AgentsMesh’s answer is a single .agentsmesh directory from which agentsmesh generate writes each tool’s native files, including a root AGENTS.md and a CLAUDE.md built from the same source so the two can’t drift apart. Where a tool has no native slot for a feature, AgentsMesh embeds it with round-trip metadata so that a re-import rebuilds the original. For teams whose fragmentation stops at instructions, the guide says the tool may not be needed: “one AGENTS.md is now genuinely enough for a lot of teams.”