Convert CLAUDE.md to AGENTS.md without losing repository scope
Why a safe instruction-file conversion preserves hierarchy, commands, constraints, and tool-specific bridge behavior instead of merely renaming a file.
Practical takeaway
Convert the durable repository contract into AGENTS.md, keep a thin Claude bridge when needed, and validate scope before deleting any existing instruction file.
A rename is not a migration
CLAUDE.md files often mix durable repository facts with Claude-specific workflow hints. Renaming the file to AGENTS.md may preserve the words, but it does not prove that directory scope, import behavior, or other coding agents will interpret the result the same way.
A useful conversion first separates the repository contract from the client-specific bridge. Commands, architecture boundaries, validation steps, security rules, and the definition of done belong in the maintained repository instructions. Claude-only interaction tips can remain in a short bridge when they are still necessary.
Preserve operational detail
Weak conversions collapse real commands into advice such as “run tests” or “follow best practices.” Keep the exact package manager, focused test command, lint and build commands, files an agent should read first, and changes it must not make without explicit authorization.
Preserve hierarchy deliberately. A root file should describe repository-wide rules. Nested instruction files should contain only the narrower rules for that subtree. Repeating the entire root file in every directory creates the same drift problem the migration was meant to solve.
- Keep exact commands and observable completion checks.
- Separate repository-wide rules from subtree-specific rules.
- Retain tool-specific guidance only in the smallest necessary bridge.
Keep the bridge until the migration is proven
For Claude Code, a small root CLAUDE.md can import the canonical AGENTS.md instead of duplicating it. That gives existing Claude workflows a stable entry point while the repository moves toward one maintained source.
Before removing the older file, test the real entry points used by the team and inspect the generated plan for every selected coding agent. The migration is finished when the same commands, constraints, and scope reach those tools—not when the new filename exists.