Keep AGENTS.md and CLAUDE.md in sync: 5 user-side fixes (and where each quietly breaks)

#claude #ai #devtools #productivity

If you use more than one AI coding assistant, you've probably hit this: Codex, Cursor, Amp, and Aider all read AGENTS.md, but Claude Code reads only CLAUDE.md. So you end up maintaining the same instructions in two files.

The request to support AGENTS.md is the single most-reacted open issue on the Claude Code repo — over 5,000 reactions, roughly 4x the second-place request — and it's still open. Until native support lands, here's how the user-side options actually compare, because each one breaks in a different place.

The failure that actually costs you

The upfront setup isn't the real problem. Silent drift is.

You update AGENTS.md, forget CLAUDE.md (or the other way around), and an instruction you were relying on — say a "don't touch production" guardrail — quietly stops applying for the tool reading the stale file. The mild annoyance of two files quietly turns into an incident.

So the real goal isn't just "sync the files." It's "make a stale file fail loudly."

5 options, and where each one breaks

1. symlink — ln -s AGENTS.md CLAUDE.md

About 2 minutes for a solo dev.
Breaks on Windows (needs admin / Developer Mode), and a WSL → Windows toolchain may not resolve the link.

2. pre-commit hook — auto-copy on commit

Great solo.
The catch: it is not reproduced by git clone. Every teammate has to install it, so for a team you want a second layer.

3. SessionStart hook — compose at session start

Have Claude Code build CLAUDE.md from AGENTS.md when the session starts.
Survives clone (it lives in the repo) and needs no symlink.

4. direnv — swap via env vars

Nice if you already use direnv in the project.

5. CI drift check — don't sync at all

Just fail CI when AGENTS.md and CLAUDE.md diverge.
Safest for teams; it catches the "one got updated, the other didn't" bug directly — i.e. it's the one that makes a stale file fail loudly.

Pick by your setup

Solo, one machine: symlink, plus the CI drift check if you have CI.
Team: SessionStart hook or CI drift check. Avoid a bare symlink or pre-commit hook as your only layer — they don't survive clone the way you'd expect.
Several assistants in parallel: SessionStart hook, so every tool reads a freshly composed file each session.

Whatever you choose for syncing, add the CI drift check on top. That's the layer that converts a silent stale file into a loud, visible failure — which is the part that actually saves you.

This is a stopgap

Native AGENTS.md support is obviously the right fix — that's why the issue has thousands of reactions. But these user-side options work today, and the CI drift check in particular is worth adding no matter which sync method you pick.

I maintain cc-safe-setup (install with npx cc-safe-setup), a set of MIT-licensed safety hooks for Claude Code — the SessionStart sync approach above is one of them. Happy to compare notes if you're running multiple assistants on one repo.