Explainer
Why your CLAUDE.md, AGENTS.md and Cursor rules drift apart
CLAUDE.md, AGENTS.md and Cursor rules drift because they're separate copies of the same rules, edited by hand in every repo. In one repo the fix is simple: keep shared rules in AGENTS.md and make CLAUDE.md a one-line @AGENTS.md import. Across many repos, tools and people, every workaround below still leaves copies.
Where the copies come from
One file per tool. Most coding agents now read AGENTS.md, including Codex, Cursor, Copilot, Windsurf and Zed. But when a repo has both, Claude Code reads only CLAUDE.md unless you change a setting. Cursor's scoped rules must be .mdc files in .cursor/rules, and Copilot's path-specific rules live in .github/. Which coding agent reads which file has the full table.
One copy per repo. Instruction files live in the repo, so every repo gets its own. A team with 20 repos and three agents can end up with dozens of files that say almost the same thing.
One version per person. Personal files such as ~/ and Cursor's User Rules hold rules teammates never see.
How they drift
In one public repo we looked at, CLAUDE.md says the project uses Spring Boot 4.0.7 while AGENTS.md still says 4.0.5, so Claude Code and Codex work from different versions. Nothing checks that copies agree, so nobody notices until an agent does the wrong thing.
It isn't rare. When we compared both files in 596 public repos, 4 in 10 of the repos that keep two copies had copies that already differ.
Six workarounds teams use today
| Workaround | How it works | What it fixes | What it doesn't |
|---|---|---|---|
| Symlink | ln -s AGENTS.md CLAUDE.md in each repo |
One file for Claude Code and the AGENTS.md agents | Windows clones need Git's core.symlinks (and admin rights or Developer Mode to create links); one repo at a time |
| Import | A one-line CLAUDE.md that says @AGENTS.md |
The same, without symlinks | One repo at a time |
| AGENTS.md only | Delete CLAUDE.md; Claude Code (v2.1.277 or later) then reads AGENTS.md | One file per repo for most agents | Tool-specific rules (Cursor globs, Copilot applyTo) still need their own files; a personal CLAUDE.local.md switches AGENTS.md off again |
| Rule-sync CLI | Keep rules in .ruler/ or .rulesync/; ruler or rulesync writes each tool's file |
One source, many tools | The outputs are copies someone has to regenerate (ruler keeps them out of git, so every clone runs it); one repo at a time |
| Shared rules repo | A git submodule, a template or a copy script | One source across repos | Changes arrive only when each repo pulls them |
| Vendor team rules | Cursor Team Rules (Team and Enterprise plans), Copilot organization instructions (Business and Enterprise, on github.com), Claude Code managed policy | One source across repos, for that vendor | One vendor each; lives in a dashboard or on each laptop, not in the repo |
Each workaround covers one or two of tools, repos and people, never all three. Vendor rules skip code review, personal rules never leave one laptop, and anyone outside git has to go through a pull request to change what the agents read.
What we're building
We're building Tape for this: one live document that's open in your editor, your agents, your phone and your team's doc, so you edit CLAUDE.md once instead of copying it. It's in early access: join the waitlist.
FAQ
Should I use CLAUDE.md or AGENTS.md? If your team uses more than one agent, put shared rules in AGENTS.md, because most agents read it. Claude Code (v2.1.277 or later) reads AGENTS.md when there's no CLAUDE.md; for older versions, keep a CLAUDE.md that imports it with @AGENTS.md.
Can I symlink CLAUDE.md to AGENTS.md? Yes: ln -s AGENTS.md CLAUDE.md works on macOS and Linux. On Windows, Git needs symlink support turned on, or the link arrives as a plain text file.
Does Cursor read AGENTS.md? Yes, as a plain-markdown alternative to its .cursor/ files.
How do I share agent rules across many repos? Vendor team rules work if everyone uses the same tool. Otherwise use a shared rules repo, or a sync CLI such as ruler or rulesync.
Sources
Checked on 24 October 2026: