AGENTS.md vs CLAUDE.md vs .cursorrules: When One File Isn't Enough

Most teams maintain more context files than they need, and the duplicates drift apart within weeks. Here is when a second file is actually justified.

How we got several files

Before the AGENTS.md specification was published in August 2025, every tool shipped its own convention. Cursor read .cursorrules. Claude Code read CLAUDE.md. Aider had its own config. A team using three tools maintained three files saying roughly the same thing, and they diverged within weeks because nothing forced them to agree.

The specification did not delete those files. Tools that had their own format kept reading it, and added AGENTS.md support alongside. That leaves a real question for a team standardising today: one file, or several?

The default answer: one file

Put everything in AGENTS.md. Most tools read it. The ones with a native format generally fall back to it. You maintain one file, review one file, and it cannot contradict itself.

The cost of the one-file approach is that you give up tool-specific instructions. In practice that cost is smaller than it sounds, because the overwhelming majority of what belongs in a context file — build commands, boundaries, frozen directories, traps — is a property of your repository, not of the tool reading it. A frozen directory is frozen regardless of which agent is looking at it.

When a second file earns its place

There are three legitimate cases.

Tool-specific mechanics

Instructions about how to operate a particular tool — which of its modes to use, how to invoke a capability it alone has — are genuinely tool-specific and genuinely useless to other tools reading the same file. Those belong in that tool's own file.

Different audiences with different permissions

If one tool runs in CI with write access to your deployment pipeline and another runs locally on a developer laptop, they are not the same actor and should not necessarily get the same instructions. This is a security boundary, and collapsing it into one file to save maintenance effort is a poor trade.

Migration

You are moving from .cursorrules to AGENTS.md and need both to work for a few weeks. Legitimate, and temporary. Put an expiry date in a comment and hold yourself to it.

The symlink approach, and why it usually disappoints

The obvious trick is to make the tool-specific files symlinks to AGENTS.md:

ln -s AGENTS.md CLAUDE.md
ln -s AGENTS.md .cursorrules

One source of truth, every tool satisfied. It works, and there are three practical reasons it disappoints.

• Windows. Symlinks in git repositories on Windows require developer mode or elevated permissions. A teammate on Windows will clone a plain text file containing the path AGENTS.md and nothing else.
• Format assumptions. .cursorrules was not designed as markdown with headings. Pointing it at a markdown file usually works, but you are relying on tolerance rather than a contract.
• It hides the question. If the answer really is "all these tools should get identical instructions", the cleaner statement of that is one file and no symlinks — and then finding out whether any tool actually fails to read it.

Symlinks are reasonable during a migration. As a permanent architecture they are a workaround for a decision nobody made.

Deciding, concretely

The cost of getting this wrong

It is worth being concrete about what duplicated context files actually cost, because the failure is gradual and nobody attributes it correctly.

Consider a team with AGENTS.md and CLAUDE.md, both created in the same week, both saying the test command is npm test. Six weeks later someone splits the suite and the command becomes npm run test:unit. They update AGENTS.md, because that is the one they had open. Nobody touches CLAUDE.md.

Now the repository contains two authoritative-looking statements that disagree. Which one wins depends on which tool is running, which is not a property anyone reasoned about. Half the team gets correct behaviour and half gets an agent that runs a command which no longer exists, sees a failure, and starts investigating. The people affected do not conclude "our context files have drifted" — they conclude "this tool is worse than the other one", which is both wrong and unfalsifiable.

This is why the maintenance argument is stronger than it first appears. It is not that two files are twice the work. It is that two files fail silently and asymmetrically, and the symptom presents as a tool quality problem rather than a configuration problem.

Detecting drift mechanically

If you do end up with more than one file, add a CI check that fails when they disagree on the things that matter. Even a crude one earns its place:

- name: Context files must agree on commands
  run: |
    for f in AGENTS.md CLAUDE.md; do
      grep -oE '`[a-z]+ (run )?[a-z:]+`' "$f" | sort -u > "/tmp/$(basename $f).cmds"
    done
    diff /tmp/AGENTS.md.cmds /tmp/CLAUDE.md.cmds || {
      echo "Context files disagree on commands. Reconcile before merging."
      exit 1
    }

It is not sophisticated and it will occasionally produce a false positive. It also catches the exact failure above, which would otherwise cost your team several confused afternoons spread across a quarter.

Check what is actually being read

Whatever you choose, verify it rather than assuming. The verification block from the monorepo case works here too: put a distinctive marker string in each file and ask each tool to echo it back. You will occasionally find that a tool you believed was reading your carefully maintained file has been ignoring it for months.

Run that check when you adopt a new tool and after any tool's major version update. Context file support is young enough that it changes between releases, and it changes silently — nothing errors when a file stops being read.