<article> <p>A platform team adds Codex to one repo. A frontend team keeps using Cursor. A backend team standardizes on Claude Code. Within a month, the same rule exists in five places: <code>AGENTS.md</code>, <code>CLAUDE.md</code>, <code>.cursor/rules</code>, a Copilot instruction file, and somebody's local preferences.</p>

<p>That is where <strong>AGENTS.md vs CLAUDE.md vs Cursor rules</strong> stops being a file-format debate and becomes a governance problem. The question is not which file is the most elegant. The question is which instruction should be canonical, which files should adapt it for each tool, and which rules should be enforced outside the model entirely.</p>

<p>The practical answer for mixed-agent teams is clear: use <code>AGENTS.md</code> as the portable, version-controlled baseline; bridge it into Claude Code with a small <code>CLAUDE.md</code>; use Cursor <code>.cursor/rules/*.mdc</code> only where Cursor needs metadata-driven scoping; and put non-negotiable controls in settings, hooks, CI, repository protections, and security tooling.</p>

<p><a id="internal-link-anchor-agent-instructions-source-of-truth"></a></p>

<h2>AGENTS.md vs CLAUDE.md vs Cursor rules in one table</h2>

<table> <thead> <tr> <th>Instruction surface</th> <th>Best use</th> <th>Portability</th> <th>Risk if misused</th> </tr> </thead> <tbody> <tr> <td><code>AGENTS.md</code></td> <td>Shared team baseline for build, test, review, security, and repository conventions</td> <td>High. It is plain Markdown and supported by Codex and Cursor</td> <td>Can become too broad or stale if nested files are not owned</td> </tr> <tr> <td><code>CLAUDE.md</code></td> <td>Claude Code adapter, plus Claude-specific instructions when needed</td> <td>Medium. Native to Claude Code, not a general cross-agent file</td> <td>Duplicating <code>AGENTS.md</code> content creates drift</td> </tr> <tr> <td><code>.cursor/rules/*.mdc</code></td> <td>Cursor-specific activation rules, file globs, and scoped behavior</td> <td>Low outside Cursor</td> <td>Easy to turn shared policy into Cursor-only knowledge</td> </tr> </tbody> </table>

<p>If your team uses only Claude Code, <code>CLAUDE.md</code> can be enough. If your team uses only Cursor, project rules may be enough. But once more than one agent enters the repo, a single canonical baseline matters more than native ergonomics.</p>

<h2>What each file actually does</h2>

<p><code>AGENTS.md</code> is designed as a repo-native instruction file for coding agents. The official project describes it as a kind of agent-facing README: a plain Markdown place for setup steps, test commands, code conventions, pull request guidance, and security considerations. It has no required schema, which is part of its appeal. A team can read it in a normal code review without learning a product-specific format.</p>

<p>Codex gives <code>AGENTS.md</code> the most explicit loading contract among the tools in this comparison. It can read global guidance from <code>~/.codex</code>, then project guidance from the repository root down to the current working directory. In each directory, Codex checks for <code>AGENTS.override.md</code>, then <code>AGENTS.md</code>, then configured fallback names. It includes closer files after broader ones, so local guidance can override root guidance. Codex also has a default combined project-document cap of 32,768 bytes, which is a useful reminder that instruction files are not a place for an entire engineering handbook.</p>

<p><code>CLAUDE.md</code> is Claude Code's native memory file. Claude Code does not read <code>AGENTS.md</code> directly, so mixed teams need an adapter. Anthropic's documented pattern is simple: create a <code>CLAUDE.md</code> that imports <code>@AGENTS.md</code>, then add only Claude-specific notes below it. A symlink can also work, but the import pattern is safer across operating systems because Windows symlinks require Administrator privileges or Developer Mode.</p>

<p>Claude Code also has its own scoping model. It can load managed, user, project, and local memory files. Files above the working directory load at launch, while subdirectory <code>CLAUDE.md</code> files load when Claude works with files in those subdirectories. Claude concatenates discovered files rather than treating the nearest file as a total replacement. Anthropic also recommends keeping each <code>CLAUDE.md</code> under 200 lines and moving path-specific material into <code>.claude/rules/</code>.</p>

<p>Cursor rules are different again. Project rules live as <code>.mdc</code> files under <code>.cursor/rules</code>. They can use frontmatter such as <code>description</code>, <code>globs</code>, and <code>alwaysApply</code>. Cursor can apply rules always, apply them based on context, apply them to matching file globs, or require manual reference. Plain <code>.md</code> files in <code>.cursor/rules</code> are ignored by Cursor's rules system.</p>

<p>Cursor also supports <code>AGENTS.md</code> for straightforward repository instructions. That is useful. It means Cursor does not force every team into <code>.mdc</code> files. But Cursor's native rules are still valuable where metadata matters, especially in large repositories where a rule should activate only for a specific framework, package, or file pattern.</p>

<p><a id="internal-link-anchor-cursor-rules-vs-agents-md"></a></p>

<h2>The source-of-truth architecture that holds up</h2>

<p>For a mixed Codex, Claude Code, and Cursor team, the clean architecture looks like this:</p>

<pre><code>repo/ AGENTS.md CLAUDE.md .cursor/ rules/ react-components.mdc database-migrations.mdc services/ billing/ AGENTS.md auth/ AGENTS.md</code></pre>

<p>The root <code>AGENTS.md</code> is canonical. It contains shared repository facts: how to install dependencies, how to run tests, what not to touch without review, what generated files should be avoided, how pull requests should be prepared, and which checks must pass.</p>

<p>The root <code>CLAUDE.md</code> stays small:</p>

<pre><code>@AGENTS.md

Claude Code notes

Use the repository instructions above as the shared source of truth. Keep Claude-specific behavior here only when it cannot be expressed portably.</code></pre>

<p>That file is not a second policy document. It is a bridge. Its job is to make Claude Code read the same baseline as Codex and Cursor, then add any Claude-only details that genuinely belong there.</p>

<p>Cursor <code>.mdc</code> files should be narrower. A good Cursor rule might apply only to <code>apps/web/*/.tsx</code> or only to migration files. A weak Cursor rule repeats the root test command, security policy, or review process already written in <code>AGENTS.md</code>. Repetition feels harmless on day one. Six weeks later, one copy gets edited and the other does not.</p>

<h2>Why drift is the real failure mode</h2>

<p>Instruction drift usually starts with good intent. One team adds a local <code>AGENTS.md</code> for a package. Another adds a <code>CLAUDE.md</code> because Claude did not pick up the first file. A Cursor user creates a project rule to make the editor behave better. A developer adds a personal user rule to stop seeing the same mistake.</p>

<p>None of those moves is wrong by itself. The problem appears when nobody can answer three basic questions:</p>

<ul> <li>Which instruction is canonical?</li> <li>Which instructions load for this directory?</li> <li>Which rules are only suggestions, and which are enforced?</li> </ul>

<p>The loading models make this harder than it looks. Codex walks from root to current directory and includes one project instruction file per directory. Claude Code concatenates multiple memory sources and lazy-loads subdirectory files. Cursor can combine nested <code>AGENTS.md</code> files and also apply separate rule tiers and rule types. The same repository layout can produce different context in different tools.</p>

<p>This does not mean you should avoid local files. In a monorepo, local files are often the right answer. The billing service may have a special test command. The auth package may require security review for policy changes. A generated-code directory may need a strict "do not edit by hand" instruction. Those facts belong close to the code.</p>

<p>The rule is ownership. Root instructions should be owned by the platform or developer-experience team. Service-level instructions should be owned by service teams. Security-sensitive sections should have security review. If no one owns a nested file, it will eventually become an archaeological artifact that agents continue to read.</p>

<p><a id="internal-link-anchor-ai-coding-agent-governance"></a></p>

<h2>Prompts are not policy</h2>

<p>This is the most important distinction in the whole comparison: <code>AGENTS.md</code>, <code>CLAUDE.md</code>, and Cursor rules are prompt context. They guide model behavior. They do not guarantee enforcement.</p>

<p>Anthropic states this directly for Claude Code memory: use hooks or managed settings for actions that must be blocked regardless of model behavior. Cursor describes rules as persistent prompt-level context. Codex guidance also points teams toward pairing instructions with hooks, linters, type checks, and other deterministic controls.</p>

<p>So keep hard rules in two places. Put them in instruction files so the agent knows what the team expects. Then enforce them outside the prompt.</p>

<table> <thead> <tr> <th>Rule type</th> <th>Instruction file role</th> <th>Enforcement layer</th> </tr> </thead> <tbody> <tr> <td>Do not commit secrets</td> <td>Tell the agent to avoid secrets and run checks</td> <td>Secret scanning, pre-commit hooks, CI</td> </tr> <tr> <td>Do not edit generated files</td> <td>List generated paths and regeneration commands</td> <td>CI diff checks, CODEOWNERS, build validation</td> </tr> <tr> <td>Do not change auth policy without review</td> <td>Name the sensitive paths and required reviewers</td> <td>CODEOWNERS, branch protections, required reviews</td> </tr> <tr> <td>Do not run destructive database commands</td> <td>Warn the agent and document safe alternatives</td> <td>Sandboxing, blocked commands, environment permissions</td> </tr> </tbody> </table>

<p>If the cost of a mistake is high, prose is not enough. Treat the instruction file as the readable contract and the tooling as the control plane.</p>

<h2>A practical comparison for teams</h2>

<table> <thead> <tr> <th>Question</th> <th><code>AGENTS.md</code></th> <th><code>CLAUDE.md</code></th> <th>Cursor rules</th> </tr> </thead> <tbody> <tr> <td>Which tool reads it natively?</td> <td>Codex and Cursor</td> <td>Claude Code</td> <td>Cursor</td> </tr> <tr> <td>Should it be version-controlled?</td> <td>Yes, for project instructions</td> <td>Yes, for project adapter files</td> <td>Yes, for project rules</td> </tr> <tr> <td>Good home for shared policy?</td> <td>Yes</td> <td>Only if the team is Claude-only</td> <td>Only if the team is Cursor-only</td> </tr> <tr> <td>Good home for path-scoped behavior?</td> <td>Yes, through nested files</td> <td>Yes, through subdirectory files or <code>.claude/rules/</code></td> <td>Yes, through <code>globs</code> and activation metadata</td> </tr> <tr> <td>Main governance risk</td> <td>Stale local instructions</td> <td>Duplicated source-of-truth content</td> <td>Cursor-only policy hidden from other agents</td> </tr> </tbody> </table>

<p>The strongest default is not the most feature-rich option. It is the option your whole team can inspect, review, and reuse across tools. That points to <code>AGENTS.md</code> as the baseline for mixed environments.</p>

<h2>What to put in the canonical AGENTS.md</h2>

<p>A useful root <code>AGENTS.md</code> is short, specific, and operational. It should answer questions an agent would otherwise infer badly.</p>

<ul> <li>Repository purpose and major package boundaries</li> <li>Install, build, test, lint, and type-check commands</li> <li>Generated files and regeneration commands</li> <li>Security-sensitive paths and required review expectations</li> <li>Database migration rules</li> <li>Pull request expectations and validation steps</li> <li>Known tool limitations or environment constraints</li> </ul>

<p>It should not contain the full style guide, a duplicate README, stale project tickets, or every command in the repository. Cursor's own guidance recommends focused, actionable, scoped rules and warns against copying whole style guides or documenting every common command. Claude's guidance similarly pushes teams toward concise memory files. Codex's byte limit creates a practical ceiling even before readability becomes a problem.</p>

<p>A good instruction file removes ambiguity. A bad one adds more context for the model to misunderstand.</p>

<h2>When to use nested files</h2>

<p>Nested files are useful when local facts differ from the root. They are risky when they become a dumping ground for tribal knowledge.</p>

<p>Use nested <code>AGENTS.md</code> files for stable service-level facts:</p>

<ul> <li>This package uses <code>pnpm test:billing</code>, not the root test command.</li> <li>Files under <code>src/generated</code> must be regenerated from schema files.</li> <li>Changes under <code>auth/policies</code> require security review.</li> <li>This service cannot import from a neighboring bounded context.</li> </ul>

<p>Avoid nested files for temporary task context, copied README content, or rules already enforced by the linter. If a rule changes often, it probably belongs in code, tests, or a tracked configuration file rather than a prose instruction that every agent carries around as context.</p>

<h2>Migration recipes</h2>

<h3>From Claude-only to mixed tools</h3>

<p>Start by splitting shared instructions from Claude-specific instructions. Move the shared material into <code>AGENTS.md</code>. Replace the top of <code>CLAUDE.md</code> with <code>@AGENTS.md</code>, then keep only Claude-specific notes below it. Add a short warning in <code>CLAUDE.md</code> that shared build, test, review, and security rules belong in <code>AGENTS.md</code>.</p>

<h3>From Cursor-only to mixed tools</h3>

<p>Audit <code>.cursor/rules/*.mdc</code>. Move portable team policy into <code>AGENTS.md</code>. Keep Cursor rules where the frontmatter matters: <code>globs</code>, <code>alwaysApply</code>, descriptions, and manual activation. If the repository still has legacy <code>.cursorrules</code>, migrate it deliberately rather than letting it sit beside newer rules.</p>

<h3>From duplicated files to one baseline</h3>

<p>Pick <code>AGENTS.md</code> as the source of truth. Then reduce each adapter until it has a clear job. <code>CLAUDE.md</code> imports the canonical file. Cursor rules handle Cursor-specific scoping. Local files contain local facts. Personal user rules stay personal and must not define production workflow behavior.</p>

<p><a id="internal-link-anchor-agent-instruction-drift"></a></p>

<h2>CI checks that prevent instruction drift</h2>

<p>The governance pattern is only durable if it is checked. A lightweight CI job can catch most failures before they become cultural debt.</p>

<ul> <li>Verify that root <code>CLAUDE.md</code> starts with <code>@AGENTS.md</code>.</li> <li>Fail if large copied sections from <code>AGENTS.md</code> appear in adapters.</li> <li>List every <code>AGENTS.md</code>, <code>CLAUDE.md</code>, <code>.claude/rules/.md</code>, <code>.cursor/rules/.mdc</code>, <code>.github/copilot-instructions.md</code>, and legacy <code>.cursorrules</code> file.</li> <li>Report owner, byte size, line count, and last-modified commit for each instruction file.</li> <li>Fail when instruction files exceed agreed size limits.</li> <li>Require CODEOWNERS review for root instructions, service-level instructions, and security-sensitive rule files.</li> </ul>

<p>For monorepos, add one more check: from important package directories, ask the active agent to summarize the instructions it loaded, then compare the answer against expected root and local rules. Claude Code documents <code>/context</code> and an <code>InstructionsLoaded</code> hook for debugging loaded instructions. Codex's documented discovery order also makes expected loading easier to reason about.</p>

<h2>What the evidence does and does not prove</h2>

<p>The official docs are strong enough to support the operational recommendation: use portable shared instructions, keep native adapters thin, and enforce hard controls outside prompt files.</p>

<p>The evidence is weaker on performance claims. A 2026 arXiv factorial study tested coding-agent configuration variables across 1,650 Claude Code CLI sessions and 16,050 function-level observations. In that study, file size, instruction position, file architecture, and contradictions did not produce detectable contrasts after multiple-testing correction. Compliance varied by task and session sequence.</p>

<p>That finding does not mean instruction architecture is irrelevant. It means teams should be cautious about claiming that one file layout automatically improves agent obedience. The stronger case for a source-of-truth architecture is governance: fewer duplicated rules, clearer ownership, easier audit, and less hidden drift.</p>

<h2>Recommended default</h2>

<p>If you are choosing today, use this default:</p>

<ul> <li><strong>Canonical shared policy:</strong> root <code>AGENTS.md</code>.</li> <li><strong>Claude Code bridge:</strong> root <code>CLAUDE.md</code> with <code>@AGENTS.md</code> and only Claude-specific additions.</li> <li><strong>Cursor-specific behavior:</strong> <code>.cursor/rules/*.mdc</code> for scoped rules that need Cursor metadata.</li> <li><strong>Monorepo local facts:</strong> nested <code>AGENTS.md</code> files owned by the relevant service teams.</li> <li><strong>Non-negotiable controls:</strong> hooks, managed settings, CI, CODEOWNERS, branch protections, sandboxing, and security tooling.</li> </ul>

<p>The best instruction system is not the one with the most places to write prompts. It is the one where every engineer can tell which rule is canonical, every agent gets the right context, and the dangerous actions are blocked by systems that do not rely on the model remembering a sentence.</p>

<h2>Sources</h2>

<ul> <li><a href="https://agents.md/">AGENTS.md project site</a></li> <li><a href="https://developers.openai.com/codex/codex-manual.md">OpenAI Codex manual</a></li> <li><a href="https://learn.chatgpt.com/docs/agent-configuration/agents-md.md">OpenAI AGENTS.md configuration guidance</a></li> <li><a href="https://docs.anthropic.com/en/docs/claude-code/memory">Anthropic Claude Code memory documentation</a></li> <li><a href="https://cursor.com/docs/rules">Cursor rules documentation</a></li> <li><a href="https://arxiv.org/abs/2605.10039">Instruction Adherence in Coding Agent Configuration Files</a></li> </ul> </article>