Keeping CLAUDE.md, AGENTS.md, and .cursorrules in Sync

A PR merges on a quiet Tuesday that changes how your team names feature flags. The author dutifully updates CLAUDE.md, then .cursorrules, and moves on. Nobody remembers the third file, the one Copilot reads. Two days later an agent opens a PR using the old naming scheme. It quotes the stale rule back to the reviewer as justification. Teams keep these files in sync one of two ways. They automate the copying with symlinks, imports, or a generator writing every file from one template. Or they eliminate the problem by serving every tool from one synthesized source. Most teams are converging the copies on AGENTS.md as the canonical file. The open instruction format is now used by over 60,000 open-source projects. That fixes duplication between files. It does not fix the gap between any file and the codebase it describes.

What Is Multi-File Rules Drift?#

Multi-file rules drift is the divergence that builds up when several AI coding tools each read their own instruction file. Every convention change has to be copied into each file by hand. One copy gets updated, the others keep confidently stating last month's rule. The condition is now the default, not the edge case. The Pragmatic Engineer's March 2026 tooling survey found that 70% of engineers use between two and four AI tools simultaneously. Another 15% use five or more (Pragmatic Engineer, 2026). Every tool in that stack historically shipped its own filename. Claude Code reads CLAUDE.md. Cursor keeps rules in .cursor/rules, plus the older single-file .cursorrules many repos still carry. Copilot has its instruction files, and Gemini CLI reads GEMINI.md. Even a single instruction file rots on its own. Multiplying it across tools multiplies the rot and adds a new failure mode: copies that disagree with each other.

Why Does Manual Syncing Break Down as Teams Grow?#

Manual syncing breaks down because the work scales with tools times conventions times contributors. Nothing fails when someone skips a file. GitHub's own documentation illustrates the sprawl inside a single product. Copilot reads .github/copilot-instructions.md, path-scoped .instructions.md files, and AGENTS.md anywhere in the tree, where the nearest one wins. It also honors CLAUDE.md or GEMINI.md at the repository root (GitHub Docs). That is five instruction filenames one vendor alone will honor. Now add Cursor, Claude Code, and a terminal agent. A convention changes in review. The person merging it must know every file that encodes the old rule. Then they open each one, phrase the change consistently, and commit. On a two-person project that loop mostly holds. On a twenty-person team with three tools, someone always misses one. The miss is invisible until an agent acts on the stale copy. Prose rules have no compiler, so drift between the copies accumulates silently.

What Does the AGENTS.md Standard Actually Cover in 2026?#

The standard has become the closest thing to a fix for duplication. The spec describes it as a simple, open format for guiding coding agents, "a README for agents" (spec site). It is now stewarded by the Agentic AI Foundation under the Linux Foundation. More than 60,000 open-source projects use it. The adopter list covers most of the 2026 tool stack. OpenAI Codex, Cursor, GitHub Copilot's coding agent, Google's Gemini CLI and Jules, Devin, Windsurf, Zed, Warp, Aider, Amp, and VS Code all read the file natively. Nesting is part of the format, with deeper files taking precedence for their subtree. OpenAI's main repository carries 88 of them. Codex goes furthest. Before doing any work, it merges files from your home directory and the repo root down to your working directory. The default budget for that merge is 32 KiB (OpenAI Codex docs). One canonical file, read by nearly everything, is a real consolidation win.

Where Do CLAUDE.md, Cursor Rules, and GEMINI.md Still Diverge?#

Convergence is real but incomplete, and the holdouts are exactly the tools most teams run. Anthropic's documentation is explicit that Claude Code reads only its own CLAUDE.md, not the shared file. The recommended bridge is a one-line CLAUDE.md that imports the shared file via @ syntax (Claude Code docs). A symlink works too where the filesystem allows it. On Windows, symlinks need administrator privileges, so the import is the safer default. Gemini CLI defaults to GEMINI.md. Teams can point its context.fileName setting at the standard file, but that is opt-in configuration, not default behavior (Gemini CLI docs). Cursor keeps its richer .mdc rules in .cursor/rules for glob-scoped and agent-requested rules. The standard file is positioned as a simpler alternative (Cursor docs). VS Code auto-detects the standard file at the workspace root and applies CLAUDE.md the same way. Nested-file support hides behind an experimental setting (VS Code docs). So a typical multi-tool repo in 2026 still carries two to four instruction files plus bridge glue.

Should You Automate the Sync or Eliminate the Problem?#

Automating the sync means you still have N files, just scripted. That might be a symlink from CLAUDE.md to the canonical file, an import line, or a CI generator writing per-tool copies. Do this; it is cheap and it removes the "someone forgot the third file" failure mode. But be clear about what it buys. Every copy is still a static snapshot, hand-edited by whoever last remembered. A perfectly synchronized set of files can be perfectly, uniformly wrong about the codebase as it exists today. Synchronization fixes file-to-file drift and does nothing for file-to-reality drift. Eliminating the problem means moving what changes out of static files entirely. Keep a short canonical file for hard, stable constraints. Serve everything that moves (conventions, architecture decisions, the reasoning behind them) from a context engine reading live sources at request time. Which content belongs at which layer is its own decision. If your current file has bloated past usefulness, audit it down before you replicate it anywhere.

What Does One Synthesized Source Look Like in Practice?#

A synthesized source inverts the model. Instead of pushing hand-written snapshots into every tool, each tool pulls current context when it needs it. Unblocked provides institutional context for coding agents over MCP, so Claude Code, Cursor, and Copilot query the same source. Answers are synthesized from where conventions actually live: merged PRs, design docs, review comments, and threads where your team decided things. Access isn't the same as understanding. An agent with your repo cloned still can't see the approach rejected in review or the naming decision made in a thread. No rules file keeps that current by hand. Nothing to copy means nothing to miss, and the answer reflects last week's decisions without anyone editing a file. Instead of distributing snapshots to N tools, you give every agent institutional memory it can query.

My agents know to use Unblocked first because it's faster than having them figure it out from the code alone. When I'm working on a Java service, I ask Unblocked what documentation exists, what the code says, what the service does — and it comes back with a succinct, clear answer. Individual MCPs are great when you already know what you're looking for. Unblocked is what you use when you need the full picture.

— Zachary Goldberg, Engineering Manager, Lilt

N Static Rules Files vs One Synthesized Source#

The comparison comes down to who does the updating and how you find out when something is wrong.

Frequently Asked Questions#

Does Claude Code read AGENTS.md? Not natively. Anthropic's docs state that Claude Code reads CLAUDE.md. The recommended bridge is a CLAUDE.md that imports the shared file with @ syntax, or a symlink where supported. Either bridge lets both file names carry identical instructions. The import version also lets you append Claude-specific lines below it.

Should I delete .cursorrules? Migrate it. Cursor's current documentation centers on .cursor/rules (.mdc files with glob scoping) and the shared standard file. The legacy single file is one more copy to keep in sync. Fold its contents into whichever canonical file the rest of your tools read. Then remove it once nothing references it.

Do symlinks solve multi-file rules drift? They solve half of it. A symlink guarantees two filenames serve identical bytes, which ends file-to-file divergence for that pair. It does nothing about the content going stale against the codebase. Windows checkouts also need special handling, which is why import syntax is often the sturdier bridge.

Is one big shared rules file better than per-tool files? For stable, hard constraints, yes: one canonical file bridged into each tool beats N hand-maintained copies. But a longer shared file is not a better one. Oversized instructions crowd the context window and degrade what agents actually follow. Keep the shared file short and serve changing conventions dynamically.

How Many Rules Files Should You Be Maintaining?#

One canonical file, bridged into every tool that needs a different name. Keep it short enough that a human reads all of it in a minute. The 2026 consolidation makes that genuinely achievable. Most agents now read the same standard natively, and the holdouts bridge with one line of glue. What no amount of file plumbing achieves is currency. A rules file is a snapshot of decisions your team made. The decisions keep happening, in reviews, in threads, in merged PRs. Sync the snapshot, by all means. Then stop trying to make static files do a live job. Let a context engine that connects code, discussions, tickets, and docs in one query serve the part that changes. Your agents get this week's conventions, from every tool, without anyone remembering to edit anything.