AGENTS.md vs CLAUDE.md vs Cursor/Windsurf/Copilot: where repo instructions belong

verdict: for multi-agent repos, make AGENTS.md the source-of-truth policy file. CLAUDE.md, Cursor rules, Windsurf rules, and Copilot instructions should be adapters, not competing rulebooks.

updated 2026-05-17: refreshed after the SEO repair pass. this is a policy-placement guide, not a filename war: one shared rulebook first, vendor adapters second.

this is repo policy, not a claim that every tool natively loads AGENTS.md. the point is simpler: one file should own the shared rules.

if you are coming from Claude Code setup , this is the next decision. if you want the terminal-first rationale, read why Claude Code wins the terminal .

verdict: one policy file

policy lives once.

if a repo is truly Claude-only, CLAUDE.md is fine. once a second tool enters the repo, stop hand-editing multiple instruction files. make AGENTS.md the shared policy file and treat vendor files as adapters.

the reason is drift. when instructions live in more than one hand-edited file, they diverge. the code changes, the filenames stay, and agents start following different realities.

decision tree

do repo instructions need to live somewhere?
├─ no
│  └─ do nothing
├─ yes, and only Claude Code touches the repo
│  └─ CLAUDE.md can be the primary file
└─ yes, and more than one agent or tool touches the repo
   ├─ make AGENTS.md the shared policy file
   └─ derive vendor files from it

use the simplest path that will still work after the next tool is added. if you expect Cursor, Windsurf, Copilot, Codex, or another agent to touch the repo later, start with AGENTS.md now.

placement matrix

commands belong in the policy file when they are part of the working contract: build, test, lint, migration, review. if the explanation is long, put the long version in docs and keep the command in the instruction file.

for the repo-shape side of this rule, see agent-first design .

file comparison

this is a repo-policy page; keep vendor path details thin and current. if your setup uses a slightly different adapter path, change the wrapper and keep the rule.

if your current CLAUDE.md is just a better-written README, it is not doing the job. fix that with the structure in CLAUDE.md guide and the anti-patterns in why your CLAUDE.md sucks .

memory guardrail

agent memory and scratch notes are not repo policy.

do not put these in memory:

• durable repo rules that should survive a fresh checkout;
• commands every agent needs to run;
• architecture decisions other agents need to see;
• vendor-specific instruction copies;
• secrets, tokens, private keys, or private environment values;
• long explanations that belong in docs.

use this test: if deleting the memory note would break a fresh checkout, it belongs in git.

when instructions disagree, agents drift toward the nearest file. if the repo policy changes, update the policy file and remove stale copies. don’t leave three versions of the same rule behind.

source-of-truth layout

repo/
  AGENTS.md                       # shared policy
  CLAUDE.md                       # optional Claude adapter
  .cursor/rules/                  # optional Cursor adapter
  .windsurfrules                  # optional Windsurf adapter
  .github/copilot-instructions.md # optional Copilot adapter
  docs/                           # reference only
  memory/                         # temporary notes only

the layout is intentionally boring. one policy file. thin adapters where needed. reference docs for the long version. temporary memory for the current task.

this is the same repo-design logic behind agent-first design : make the structure legible to agents, then keep the rules close to the code that needs them.

adapter strategy

if symlinks are not viable, generate the adapter file from AGENTS.md instead. don’t hand-edit both.

example:

# simple local adapter when symlinks are acceptable
ln -s AGENTS.md CLAUDE.md

# if symlinks are not acceptable, generate instead
cp AGENTS.md CLAUDE.md

if you use cp, treat it as a generated artifact and refresh it whenever the policy file changes.

migration runbook

1. pick the policy file.
   • multi-agent repo: AGENTS.md.
   • Claude-only repo: CLAUDE.md is acceptable until a second agent joins.
2. move shared instructions into that file.
   • keep commands, conventions, path rules, exceptions, and architecture notes that affect behavior.
3. remove duplicate policy from vendor files.
   • do not keep the same rule in two hand-edited places.
4. create adapters only when a tool needs them.
   • symlink when it works, generate when it does not.
5. verify a clean checkout.
   • a new agent should know how to build, test, and avoid obvious mistakes without opening half the repo.
6. review after repo changes.
   • when commands, layout, or tool mix changes, update the policy file first and regenerate adapters after.

this pattern fits the same reason Claude Code wins the terminal : the repo should be driven by small files and repeatable commands, not hidden memory.

next

if you need the adjacent Claude-specific ruleset, read CLAUDE.md guide . if your current file is too long, too vague, or too self-congratulatory, read why your CLAUDE.md sucks .

if you are building the broader stack around this policy layer, continue with best Claude Code plugins . that page belongs after this one: instructions first, tools second.

21 days after publish, check recrawl, impressions, clicks, CTR, and whether internal clicks move from this page to the next page in the cluster.

45 days after publish, if this page still is not the answer for instruction placement, merge overlapping sections into the sharper CLAUDE.md guide / why your CLAUDE.md sucks cluster instead of keeping duplicate intent around.