If you split your time between Claude Code and tools like Codex, Cursor, Amp, or Aider, you've hit this friction firsthand: four of those assistants read AGENTS.md, but Claude Code reads only CLAUDE.md. The result is two files with the same purpose living in your repo, demanding twice the maintenance for every rule, guardrail, or context injection you want to apply across your toolchain. The problem isn't setup—it's drift. You update one file and forget the other, and suddenly a "don't touch production" instruction silently stops applying to whichever tool is reading the stale version. The community has noticed: supporting AGENTS.md is the single most-reacted open issue on Claude Code's GitHub repo, with over 5,000 reactions—roughly four times the second-place request. Until Anthropic ships native support, developers are left patching this gap themselves.

Five Workarounds and Where Each One Falls Short

The first approach is a symlink: ln -s AGENTS.md CLAUDE.md. This takes about two minutes for a solo developer to implement, but it immediately breaks on Windows without Developer Mode or admin privileges—and cross-platform toolchains involving WSL can struggle with link resolution between filesystems. The second option, a pre-commit hook that auto-copies the file on commit, works well in isolation, but there's a critical catch: git clone doesn't reproduce hooks. Every teammate has to install it independently, making it unreliable as a team's only sync mechanism. A more robust alternative is the SessionStart hook, which instructs Claude Code to build CLAUDE.md from AGENTS.md at session startup. This survives git clone since it lives in the repo itself and requires no filesystem-level symlinks. Direnv offers another path through environment variable swapping for teams already invested in that ecosystem. The fifth option—infrastructure some developers overlook entirely—is a CI drift check that doesn't sync files at all, but instead fails your pipeline when AGENTS.md and CLAUDE.md diverge. This is the approach that converts silent staleness into an explicit error.

Picking the Right Fix for Your Setup

For solo developers on a single machine, a symlink handles the immediate problem—add the CI drift check if you already have continuous integration in place. Teams should gravitate toward either the SessionStart hook or the CI drift check, and avoid bare symlinks or pre-commit hooks as their only layer since neither survives clone reliably. If you're running multiple AI assistants in parallel against the same codebase, the SessionStart approach ensures every tool reads a freshly composed file each session rather than relying on yesterday's snapshot.

Key Takeaways

  • Symlinks break on Windows and WSL-to-Windows cross-platform setups—plan accordingly for mixed environments
  • Pre-commit hooks don't survive git clone; always layer in a second mechanism for team projects
  • SessionStart hooks are the most portable solution that survives cloning without filesystem tricks
  • CI drift checks don't sync files—they make divergence fail loudly, which is often what you actually need

The Bottom Line

The 5,000+ reactions on this issue aren't about convenience; they're about risk. A stale config file isn't a minor annoyance—it can silently disable guardrails you've built your workflow around. Native AGENTS.md support from Anthropic would settle this cleanly, but until then, the CI drift check is worth adding no matter which sync method you choose. It's the layer that turns a silent failure mode into something your pipeline catches before it reaches production.