.png)
1 month ago
2
TL;DR. Put shared instructions in AGENTS.md. Symlink CLAUDE.md to it with ln -s AGENTS.md CLAUDE.md to keep one source of truth. Update once, both files point to the same data. Unix figured this out 43 years ago.[1]
I've been working with Claude Code, Codex, and Cursor side by side for a few months now. Each has its strengths, and I've developed some intuition on what seems right for solving the task.
But there's this annoying thing that keeps happening. I'll update CLAUDE.md with some project-specific instruction. Then I switch to Codex or Cursor and watch them make exactly the mistake I just documented. Right, they read 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 don't commit to main, create a dedicated feature branch, the other says avoid committing directly to main. Same intent, different words, and when I need to update it, I'll probably forget one of the files.
The fix is straightforward. Pick one file as your source of truth and route everything else to it. I've seen three approaches that work well:
1. Use @ to reference a file. Put @AGENTS.md inside your CLAUDE.md. Claude Code reads the referenced file inline.
2. Use symlinks. Run ln -sf AGENTS.md CLAUDE.md and CLAUDE.md becomes a link pointing to AGENTS.md.
3. Use a pointer. Keep your canonical file with all the instructions, and make the other files just say READ AGENTS.md FIRST!!!
Approaches 1 and 3 have a nice advantage: you can keep Claude-specific instructions in CLAUDE.md alongside the shared content from AGENTS.md. With symlinks, everything is shared since both names point to the same content.
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.[2]
