AGENTS.md vs CLAUDE.md vs .cursorrules: Which File Each Tool Reads

You wrote a careful rules file, switched tools for an afternoon, and the new agent ignored half of it. That's usually not the model. It's that each tool looks for a different filename, and a few of them quietly stop reading one file when they find another.

I read each vendor's documentation on 2026-10-08 to pin down which file each coding agent reads, in what order, and what breaks. Then I wrote a small audit script, ran it against two sample repos, and pasted the real output below. I did not run the tools themselves, so every statement about tool behavior is from their docs, dated, and worth re-checking against your installed version.

If you only need to write a good CLAUDE.md, start with how to write a CLAUDE.md for any project. This post is about the part that goes wrong when more than one tool touches the same repo.

Which file does each coding agent read?

The open AGENTS.md format site describes itself as "a README for agents" and lists support from Codex, Cursor, Gemini CLI, Jules, Windsurf, Aider, Zed, VS Code, GitHub Copilot's coding agent, Devin and others. Claude Code was not on the list I fetched, but Anthropic's own docs now say it can read AGENTS.md, with the conditions above. Treat the vendor docs as the source of truth over any list.

Nesting works the same way almost everywhere: put a file in a subdirectory (say each package in a monorepo) and the closest one wins. The AGENTS.md site says "the closest one takes precedence" and "explicit user chat prompts override everything."

How do you keep one source of truth?

Make AGENTS.md the file you edit, and make every other tool point at it. Here is the arrangement for each tool.

Claude Code. Create a CLAUDE.md whose first line is an import:

@AGENTS.md

## Claude Code only

- Use plan mode for changes that touch more than three files.

Anthropic's docs say imports are expanded at launch, relative paths resolve from the file that contains them, and @AGENTS.md inside a CLAUDE.md does not make Claude read the file twice. Anything below the import is Claude-specific. If you would rather not keep a CLAUDE.md at all, delete it and let Claude read AGENTS.md directly. That needs v2.1.277 or later, and the docs warn that some sessions (for example older versions on Amazon Bedrock) could not read AGENTS.md until v2.1.281, so the import is the more robust choice.

Codex CLI. Nothing to do. If a teammate already uses another name, add it to ~/.codex/config.toml:

project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
project_doc_max_bytes = 65536

That snippet is copied from OpenAI's docs. The default project_doc_max_bytes is 32 KiB, and Codex stops adding files after that.

Gemini CLI. Add AGENTS.md to the list in settings.json:

{
  "context": {
    "fileName": ["AGENTS.md", "CONTEXT.md", "GEMINI.md"]
  }
}

Also from the vendor docs. They don't say whether the list replaces or adds to the default, so keep GEMINI.md in it. Antigravity CLI, the successor for individual users since 18 June 2026 per Google's announcement, reads both files without configuration. For that transition and what else changed, see Codex CLI vs Claude Code vs Gemini CLI.

Cursor. It reads AGENTS.md at the project root, so nothing to link. Keep Cursor-only behavior (glob-scoped rules, "attach when this file type is open") in .cursor/rules/*.mdc. The Cursor rules docs describe the four modes.

What goes in the shared file?

The AGENTS.md site's own example has sections for setup commands, code style, testing, and pull request conventions. That is about right. What matters is that every line is something an agent cannot infer from the code and would otherwise get wrong. Below is an illustrative template. It's an untested example I wrote, not output from any tool, and the commands are placeholders you should swap for yours.

# AGENTS.md

## Commands
- Install: `pnpm install`
- Test one file: `pnpm vitest run path/to/file.test.ts`
- Lint + typecheck before finishing: `pnpm lint && pnpm typecheck`

## Conventions
- TypeScript strict. No `any` without a comment saying why.
- API handlers live in `src/server/routes/`; one file per route.

## Do not
- Edit anything under `generated/`. Run `pnpm codegen` instead.
- Add a dependency without saying so in the PR description.
- Commit `.env*` files or print their contents.

## Done means
- Tests for the changed behavior exist and pass.
- The diff contains no unrelated formatting changes.

Two rules of thumb. First, put the exact commands in, because "run the tests" is the most common instruction an agent guesses wrong. Second, keep it short: Claude Code's docs recommend under about 200 lines per CLAUDE.md, and Codex's default cap is 32 KiB across all files it loads. For a longer treatment of what to include, see the CLAUDE.md guide and the Claude Code memory lesson.

One more thing to say plainly: a rules file is advice, not enforcement. Anthropic's permissions docs state that instructions in your prompt or CLAUDE.md shape what Claude tries to do but do not change what Claude Code allows. If a line like "never run git push" must hold, use a permission rule or a hook. The safety post in this series shows how.

Which traps catch people?

These come straight from the docs. The script below flags traps 1, 3 and 4, warns when AGENTS.md alone is over 32 KiB (part of 5), and reminds you about 6 when GEMINI.md and AGENTS.md coexist. It does not check trap 2.

1. Both files exist, no import. Claude Code reads only the CLAUDE.md files, so AGENTS.md edits never reach it.
2. A CLAUDE.local.md appears. It counts as a CLAUDE.md for the "do I read AGENTS.md" check, so adding one to keep personal notes stops Claude from reading your AGENTS.md. Either add @AGENTS.md to a CLAUDE.md, or set Project instructions to claude-md-and-agents-md.
3. A .md rule in .cursor/rules. Cursor ignores it. It must be .mdc.
4. .cursorrules in a new repo. Cursor's current rules page does not mention it. Don't build on it.
5. Silent truncation. Codex stops at 32 KiB combined by default, so a long root file can crowd out nested ones.
6. Gemini CLI without context.fileName. It will not see AGENTS.md.

How do you check your repo? A script you can run

Here is the audit script I wrote. It lists the context files in a repo and prints warnings for the traps above. It's about 80 lines of Python with no dependencies; I ran it on 2026-10-08 against two throwaway repos I made for this post. The repo names are demo and fixed.

The first repo has both an AGENTS.md and a CLAUDE.md with no import, plus a .cursor/rules/style.md. Real output:

Repo: .../p03/demo
  AGENTS.md            3 lines, 52 bytes
  CLAUDE.md            3 lines, 28 bytes
  .cursor/rules/style.md IGNORED (needs .mdc)
Warnings:
  - AGENTS.md and CLAUDE.md both exist and CLAUDE.md does not import or link AGENTS.md: Claude Code reads CLAUDE.md only, so the two can drift.

The second repo uses the arrangement from earlier, a CLAUDE.md that starts with @AGENTS.md:

Repo: .../p03/fixed
  AGENTS.md            3 lines, 52 bytes
  CLAUDE.md            5 lines, 95 bytes
No warnings.

The core of the check is small. This is the part that decides whether Claude will see your AGENTS.md:

claude_files = [n for n in ("CLAUDE.md", ".claude/CLAUDE.md", "CLAUDE.local.md") if n in found]
if "AGENTS.md" in found and claude_files:
    imports = False
    for n in claude_files:
        p = found[n]
        if os.path.islink(p) and os.path.realpath(p) == os.path.realpath(found["AGENTS.md"]):
            imports = True
        elif not os.path.islink(p):
            with open(p, encoding="utf-8", errors="replace") as f:
                if "@AGENTS.md" in f.read():
                    imports = True
    if not imports:
        warnings.append("AGENTS.md and CLAUDE.md both exist ...")

It is a text check, not a simulation of any tool. It can't tell you what your installed version of Claude Code, Codex or Cursor actually loads. In an interactive Claude Code session the docs say you see a line such as no CLAUDE.md found; AGENTS.md loaded: /home/you/repo/AGENTS.md, and /doctor prompt-audit audits instruction files. Trust those over my script.

A migration plan for an existing repo

1. Run the audit. Note which files you have.
2. Merge the shared content into AGENTS.md. Delete duplicated lines from CLAUDE.md and .cursor/rules.
3. Make CLAUDE.md start with @AGENTS.md. Keep only Claude-specific lines below it.
4. Rename any .cursor/rules/*.md to .mdc, or move their content into AGENTS.md if it isn't scoped.
5. If you use Gemini CLI, add the context.fileName list.
6. Start each tool in the repo and ask: "What rules do you have loaded for this project? Quote the first line of each file." A model's answer to that is a spot check, not proof, but a wrong answer is a useful alarm.
7. Add the audit to CI if more than one person edits these files.

What I could not verify

• I did not run Claude Code, Codex, Gemini CLI or Cursor for this post. Behavior is from docs read on 2026-10-08.
• Whether Cursor still honors .cursorrules. Its rules page doesn't say.
• Whether Gemini CLI's context.fileName list replaces or extends the default.
• The cross-tool template above is untested.
• The AGENTS.md site's tool list is the site's own claim, not a vendor confirmation.