AGENTS.md
AGENTS.md is a tool-neutral, plain Markdown convention supported by multiple coding agents. Root and nested files can express repository-wide and package-local context.
CLAUDE.md
CLAUDE.md is associated with Claude Code and may contain product-specific workflows or references. It is useful when instructions depend on Claude-specific behavior.
A practical split
Keep universal repository facts—setup, layout, tests, generated files, coding conventions, and handoff—in AGENTS.md. Keep only genuinely Claude-specific behavior in CLAUDE.md, and link to the shared source instead of duplicating it.
Migration checklist
- Inventory repeated sections and identify the authoritative copy.
- Move portable facts to AGENTS.md.
- Retain product-only behavior in its native file.
- Test the repository with each supported agent.
- Add a review rule so commands change in one source of truth.