AGENTS.md in Claude Code: pick-vs matrix for mixed-agent repos

What it is

Claude Code 2.1.277+ can treat root AGENTS.md as project instructions when no project CLAUDE.md / CLAUDE.local.md is present. Docs: memory. Format overview: agents.md.

Pick vs

Situation	Do this
Repo already has AGENTS.md only; first-party Anthropic API / claude.ai login	Upgrade to ≥2.1.277; rely on default claude-md-or-agents-md
Need Claude-specific rules plus shared AGENTS.md	Set Project instructions to claude-md-and-agents-md, or put @AGENTS.md at the top of CLAUDE.md
Team uses Bedrock, Vertex, Foundry, or disables telemetry	Keep @AGENTS.md import inside CLAUDE.md; do not depend on direct load
Personal notes in CLAUDE.local.md inside an AGENTS.md repo	Switch to claude-md-and-agents-md or move personal notes elsewhere
Migrating from Cursor/Copilot	/init (and /import on newer builds) can fold other rule files into CLAUDE.md

Failure modes

• Silent suppression: a leftover CLAUDE.local.md counts as a CLAUDE.md for the default check and blocks AGENTS.md.
• Wrong override file: Claude Code does not read AGENTS.override.md, AGENTS.local.md, or .agents/ trees. Codex may. Mixed-agent repos can diverge.
• Hook/plugin disable: disableAllHooks, allowManagedHooksOnly, or disabling built-in agents-md removes the feature.
• Confirmation gap: direct AGENTS.md loads are omitted from /memory / /context Memory files lists. Look for the loaded line or ask the model.

Minimal checklist

1. claude --version ≥ 2.1.277
2. Decide Project instructions value in /config
3. Put shared instructions in AGENTS.md
4. Add CLAUDE.md only for Claude-only policy or cloud-provider sessions
5. Verify on a fresh session before deleting any @AGENTS.md workaround