For Those Who Use Claude Code Together with Codex

October 7, 2025

TL;DR. Put shared instructions in AGENTS.md. Reference it with @AGENTS.md in CLAUDE.md to keep one source of truth. Update once, both tools see the changes.

I've been working with Claude Code and Codex side by side for a few months now. Each has its strengths, and I've gotten into the habit of reaching for whichever feels right for the task at hand. Claude Code as main driver and for quick iterations, Codex for one-shot prompt development.

But there's this annoying thing that keeps happening. I'll update CLAUDE.md with some project-specific instruction—maybe a reminder about a tricky deployment step or a note about which files not to touch. Then I switch to Codex and watch it make exactly the mistake I just documented. Right, Codex reads AGENTS.md, not CLAUDE.md.

So I copy the instruction over to AGENTS.md. Now I've got the same instruction in two different files, and they're already starting to drift. One says "never deploy on Fridays," the other says "avoid Friday deployments." Same intent, different words, and when I need to update it, I'll probably forget one of the files.

The fix is straightforward once you see it. Pick one file as your source of truth and route everything else to it. I've seen three approaches that work well:

1. Use file includes. Most modern tools let you put @CLAUDE.md inside your AGENTS.md. The tool reads the referenced file inline. One source of truth, zero duplication.

2. Use symlinks. Run ln -sf CLAUDE.md AGENTS.md and now both files are literally the same file. Update one, you've updated both. Unix figured this out in 1973.

3. Use a pointer. This is the least elegant but perfectly functional: keep your canonical file with all the instructions, and make the other files just say READ CLAUDE.md FIRST!!! You won't accidentally update the wrong file because there's nothing else in it.

I went with the file include approach (@CLAUDE.md inside AGENTS.md). This gives me the best of both worlds: common instructions in AGENTS.md that all tools see, plus Claude-specific extras in CLAUDE.md.

It's a small thing, but it's nice when you can apply the same principles you use for code to the way you configure your tools. One source of truth, references everywhere else.