CLAUDE.md, AGENTS.md, Cursor rules: one set of rules for every agent

Most teams don't use one coding agent. One person lives in Claude Code, another in Cursor, a third tries Codex on weekends, and GitHub Copilot reviews the pull requests. Each tool reads its instructions from a different file. Six months later the repo has four rule files that disagree with each other, and nobody knows which one is right.

Here is which file each agent reads, and a simple setup that keeps one source of truth.

Which file each agent reads

Claude Code reads CLAUDE.md. The file at the repo root loads at the start of every session; CLAUDE.md files in subfolders are picked up when Claude works in those folders; and ~/.claude/CLAUDE.md holds your personal preferences for every project. A CLAUDE.md can import another file with an @path/to/file line. Since version 2.1.277 (September 2026), Claude Code also falls back to AGENTS.md, but only where there is no CLAUDE.md: when both exist, only CLAUDE.md is read.
Codex reads AGENTS.md: a global one in ~/.codex/, then the files from the repo root down to the folder you are working in, with the closest file taking precedence.
Cursor reads project rules from .cursor/rules/, where each rule can apply always, by file glob, or when the agent decides it is relevant. It also reads AGENTS.md. The old single .cursorrules file still works but is legacy.
GitHub Copilot reads .github/copilot-instructions.md, plus path-specific files in .github/instructions/ with an applyTo glob. Copilot's coding agent also reads AGENTS.md.
Gemini CLI reads GEMINI.md by default, and can be configured to read AGENTS.md instead.

These conventions move quickly, so check your tool's documentation before you rely on a detail. The direction is clear though: AGENTS.md has become the shared, tool-neutral file that most agents understand.

Make AGENTS.md the source of truth

Put everything that applies to every agent in AGENTS.md at the repo root: how to install, build and test, the hard rules, the architecture in a few lines, and the known traps. Then point every other tool at it instead of copying it.

For Claude Code, a recent version will read AGENTS.md on its own when there is no CLAUDE.md. As soon as you want Claude-specific notes, or teammates are on older versions, keep CLAUDE.md as a thin wrapper that imports the shared file. Without the import line, adding a CLAUDE.md would quietly stop AGENTS.md from loading:

# CLAUDE.md
@AGENTS.md

## Claude Code only
- Use plan mode for any change that touches more than one package.
- Hooks in .claude/settings.json format files after each edit; don't run the formatter yourself.

Cursor and Copilot's coding agent read AGENTS.md directly, so you only need their own files for what they do better: glob-scoped rules in .cursor/rules/, or path-specific Copilot instructions. For tools that can't import or read AGENTS.md, generate their file from it (more on that below) rather than editing a copy by hand.

Scope rules to the folders they are about

A root file that tries to cover the whole monorepo becomes long, and long rule files get followed less. Rules that only apply to one package belong next to that package:

AGENTS.md                  # repo-wide: commands, hard rules, map
apps/api/AGENTS.md         # every route uses requireAuth; migrations are append-only
apps/web/AGENTS.md         # server components by default; no new state library
packages/billing/AGENTS.md # amounts are integers in cents, never floats

Codex merges these files from the root down. Claude Code picks up nested files as it works in each folder; if you keep CLAUDE.md wrappers, give each package a one-line one that imports its AGENTS.md. The agent working in apps/api gets the API rules, and the agent fixing CSS doesn't have to read them.

What belongs in the shared file

Commands that work. Install, dev, test, a single test, typecheck, lint. Agents will guess if you don't tell them, and they guess npm in a pnpm repo.
Hard rules, with the reason. “Never edit an applied migration; add a new one. Edited migrations broke staging in March.” The reason helps the agent apply the rule to cases you didn't list.
A short map. Where things live and which folder owns what.
Known traps. The surprising behavior that has already cost someone a day.

Leave out what the agent can read from the code itself, style rules that a formatter already enforces, and anything that changes every week. A rule file is loaded on every session, so every line costs attention.

Stop the copies drifting

If some files must be copies, make a script write them and let CI check them. The pattern is simple: generate, then fail the build if the result differs from what is committed.

# scripts/sync-rules.sh
cp AGENTS.md .github/copilot-instructions.md

# in CI
./scripts/sync-rules.sh
git diff --exit-code -- .github/copilot-instructions.md

A symlink works too on macOS and Linux, but symlinks behave badly on some Windows setups, so a generated copy is the safer default for a team.

The harder problem: keeping the content true

One source of truth fixes the drift between files. It doesn't fix the drift between the file and reality. Rule files go stale because updating them is nobody's job, and the lessons that matter most come from review comments and incidents, not from someone sitting down to write documentation.

That is the gap Memmo fills for us. Lessons are captured from sessions and reviews, a person approves them, and memmo sync writes the same budgeted block into CLAUDE.md, AGENTS.md and .cursor/rules, with a CI check that fails when the files drift. The details are in the rule files docs. But even without any tool, one shared file, scoped folders and a CI check will get most teams most of the way.