I run Codex and Claude Code side by side, and each wants its own instruction file at the root of a repository. Codex reads AGENTS.md, the shared format that Gemini CLI and two dozen other agents read as well. Claude Code reads CLAUDE.md. If I had the luxury of writing AI usage off as a business expense, I would have settled on one. Since I can’t, I keep both, and the two files drift as the projects progress. A rule would get corrected in one file and not the other, and the two agents would then follow different instructions for the same repository.

There are multiple ways to address this, but my go-to method is to consolidate into AGENTS.md and stop writing anything into CLAUDE.md at all.

1. (opt.) Move the contents of CLAUDE.md to AGENTS.md.
2. CLAUDE.md gets a one-liner:
   @AGENTS.md
   

Claude Code expands an @path import in CLAUDE.md at launch, resolving a relative path against the file that contains it, so CLAUDE.md holds the pointer and nothing else.

Claude Code’s documentation offers a symlink as an option as well. In my particular case, I avoided it as a practice, since I happen to test the same code on different environments as well. Claude Code now officially supports AGENTS.md natively, but only as a fallback. As far as I am aware, it does not treat AGENTS.md as default or write to it once it has located it.