CLAUDE.md Says One Thing. AGENTS.md Says Another. Your Agents Noticed.

Every coding agent reads its own instruction file. Claude Code reads CLAUDE.md, Codex and a growing list of others read AGENTS.md, Cursor reads .cursorrules (or .cursor/rules/), Copilot reads .github/copilot-instructions.md, Gemini reads GEMINI.md. So the moment your team supports more than one agent, your repo grows a small pile of files that are all supposed to say the same thing about your project — and, left to hand-maintenance, they quietly stop agreeing.

Anthropic's own issue tracker names the failure mode directly. From claude-code#34235: keeping a separate CLAUDE.md "creates friction and risks instruction drift when the two files diverge." A developer put the mechanism plainly: "Then you update one and forget the other two. The agent you're using today reads the stale file. Bugs follow." Another watched it happen live: "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."

That's a weird, invisible class of bug: your agent is following your rules — just last week's rules, from whichever file you forgot to update. So we wrote a 200-line tool, agentdrift, that reads all of a repo's instruction files and checks whether they actually agree. Then we pointed it at real, famous repositories.

What's in the wild

agentdrift — corpus of real repos with agent-instruction files

  [DRIFT      ] browser-use/browser-use   2 files ·   1% similar
  [DRIFT      ] block/goose               3 files ·   3% similar
  [DUPLICATED ] langchain-ai/langchain    2 files · 100% similar
  [DUPLICATED ] prisma/prisma             3 files · 100% similar
  [REDIRECT   ] astral-sh/uv              2 files · canonical + stub
  [REDIRECT   ] payloadcms/payload        2 files · canonical + stub

Two genuinely different stories, both real:

Already drifted. In browser-use/browser-use, AGENTS.md and CLAUDE.md are 1% similar — two independent files that describe the same project differently (one leads with "an AI agent that autonomously interacts with the web," the other with "an async Python library"). agentdrift prints the lines that disagree. A Claude Code session and a Codex session in that repo are working from materially different briefings.

One commit from drifting. langchain-ai/langchain keeps AGENTS.md and CLAUDE.md byte-for-byte identical — today. There's no symlink and no import linking them; they're two regular files with the same content, kept in sync by hand. That's not safe, it's lucky: the next person who edits one and not the other starts the drift. Duplication is just drift with a delay.

Done right. astral-sh/uv keeps one canonical AGENTS.md and makes CLAUDE.md a one-line stub — literally @AGENTS.md, Claude Code's import syntax. payloadcms/payload does the same in reverse (its CLAUDE.md is canonical and AGENTS.md redirects to it — so a drift tool can't assume which file is the source). apache/airflow, vercel/next.js, and cal.com go further and make the second file a symlink. One source of truth; nothing to drift. (agentdrift knows a symlink can't drift, so it scores those clean instead of flagging them as duplicates.)

Across a broader sweep of repos that carry 2+ instruction files, the split held: the large, well-run projects have mostly adopted canonical-plus-redirect, but a long tail keeps independent copies — already diverged, or one edit away.

How agentdrift decides

It's deliberately simple and fully deterministic — no model in the loop, just file reading and text diffing:

1. Find the files. CLAUDE.md, AGENTS.md, GEMINI.md, CONVENTIONS.md, .cursorrules, .cursor/rules/*, .github/copilot-instructions.md, .windsurfrules, .clinerules.
2. Classify each. A symlink, or a short file whose content is "see/@/follow AGENTS.md", is a redirect stub — good, it can't drift. Everything else is a substantive file.
3. Compare the substantive ones pairwise (normalized similarity). Two real files that are <90% similar = DRIFT; ≥98% similar = DUPLICATED (sync-by-copy, drift pending); one real file (or all-stubs-but-one) = a clean single source.
4. Report the verdict, the similarity, and the actual divergent lines — and recommend the fix.

agentdrift --corpus <dir> runs it across many repos for a study; --json and a non-zero exit on drift make it a CI check: fail the build when your AGENTS.md and CLAUDE.md disagree, the same way you'd fail on a broken link.

A note on honesty: the similarity number is a heuristic and the file list is the cross-tool set as of mid-2026 (the conventions are moving). agentdrift flags structural drift — divergent or duplicated files — not "is this rule any good." And it's source-agnostic: it won't assume AGENTS.md is canonical, because payload proves it isn't always.

The fix is the pattern everyone's converging on

There's a clear winner emerging, and it's not "diff your files in a git hook every morning." It's: pick one canonical file and make the rest redirects. AGENTS.md is becoming the cross-tool standard (OpenAI, Google, Cursor, Windsurf, Zed, and GitHub Copilot all read it now); the idiom is to keep your real instructions there and reduce CLAUDE.md/GEMINI.md/.cursorrules to a symlink or a one-line @AGENTS.md import. Tools like rulesync will even generate the stubs for you.

agentdrift is the missing half of that workflow. The generators prevent drift going forward; nothing told you whether the repo you already have has already drifted. Now you can check — agentdrift . in any repo, and on your way to one canonical file you'll see exactly which agents were reading the stale one.

Single file, no dependencies. → Talk to us if your team runs more than one coding agent.

---

Corpus verified live via the GitHub API on 2026-06-20; every repo and file above is public and reproducible. Prior art credited: the canonical-AGENTS.md+redirect pattern and the generation tools (rulesync, agent-kit, agentlink) that implement it; AgentLinter does cross-file checks within a .claude/ workspace. agentdrift's contribution is the cross-tool divergence diff — detecting drift between existing files, classifying the redirect mechanism (symlink / @import / independent), and emitting a drift score you can run in CI. Similarity is heuristic; counts are exact.

---

Get the tool → agentdrift in agent-ops — open source (MIT), a single dependency-free script, part of our toolkit for running coding agents in production.