Claude Code AGENTS.md Interop Handbook

AGENTS.md became native in Claude Code 2.1.277 — in a project with no CLAUDE.md. That one clause is the whole remaining problem, and it is why this handbook did not become obsolete on the day the feature shipped.

Issue #6235 was the most-reacted feature request in Claude Code's history — more than 6,600 reactions — closed as completed on 2026-08-17. Chapter 9 shows what actually shipped behind that closure on 2.1.246 — not a reader, and not what the closure implies. Chapter 11 then measures the real thing on 2.1.278 across three layers: the changelog (AGENTS.md went from zero mentions to two), the shipped binary, and the running behaviour.

The answer is most of the gap closed, not all of it. The file is read only where there is no CLAUDE.md, and not yet on Bedrock, Vertex or Foundry — so what remains is exactly what bites a repository that already has a CLAUDE.md, which is every repository this handbook was written for.

The rest of your stack never had the gap, and it does not have one shape. Codex, Amp, GitHub Copilot, Cursor, Windsurf and Cline read AGENTS.md with no setup at all. Aider and Gemini CLI read it only after one config line — and a config tool with no config is quietly running on a different rule set from everything else you use.

This handbook removes the duplication tax across all nine. It gives you a verified 9-tool matrix: which file each tool reads, whether it needs setup, and the one thing to watch — checked against every tool's official documentation on 2026-06-02 and re-checked row by row on 2026-09-20.

Chapter 12 records that re-check with the source URL for every row. Five of the eight rows came back different from the June text, and three of them change what you do. Codex does not read “the nearest AGENTS.md up the tree” — it concatenates from the repo root down, and stops adding files once the combined size hits 32 KiB, so the deepest and most specific file is the one that silently never arrives. Amp never dropped AGENT.md, and reads CLAUDE.md as a fallback. Windsurf's rules documentation now lives on another domain, where the URL you had bookmarked lands on a 404.

It ranks six sync paths by trade-off: the official @AGENTS.md import, symlink, pre-commit sync, SessionStart hook, direnv, and a CI drift check. And it hands you the parts: copy-paste templates for all nine tools plus a complete repo layout, a rollback-safe migration runbook to move CLAUDE.md to AGENTS.md without losing Claude-only behaviour, and a team drift guard that makes divergence fail loudly.

49 pages, dense and practical, with free updates as conventions change — the 2.1.277 chapter and the 2026-09-20 re-check were both free updates for everyone who had already bought. Read the free sample before you buy.

Try the free AGENTS.md Setup Generator and the field-guide Gist first; buy this for the full matrix, the runbook, and the templates in one place.

Also sold in two bundles. The four-book Claude Code Operator's Library — this handbook plus Safety Mastery, the Migration Playbook, and the token-cost guide — is from $29: https://leanpub.com/b/cc-operators-library . The seven-book Complete Edition adds Claude Code Safety, CLAUDE.md Under Test and the free Field Manual, from $39: https://leanpub.com/b/cc-operators-complete

Written by an independent operator who runs Claude Code unattended and maintains cc-safe-setup, a free MIT-licensed collection of more than 900 example safety hooks: https://github.com/yurukusa/cc-safe-setup . Independent handbook — not affiliated with Anthropic, OpenAI, GitHub, or Google.