AGENTS.md vs CLAUDE.md vs Cursor rules: what goes where

Checked against each tool’s documentation on October 21, 2026. These files change often; the links below go to the current docs.

The short answer

If you use more than one of these agents, AGENTS.md is the common ground. The rest of this guide is the detail behind that table.

Claude Code and AGENTS.md

Claude Code’s own file is CLAUDE.md, at the project root or in .claude/, plus a personal, gitignored CLAUDE.local.md. Files above your working directory load at launch; files in subfolders load when Claude starts working in them. A CLAUDE.md can pull in other files with @path/to/file.

Since version 2.1.277, Claude Code also reads AGENTS.md, with one rule that trips people up: by default it reads AGENTS.md only when there is no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in your working directory or above it. Add a CLAUDE.local.md for your own notes and Claude Code stops reading the team’s AGENTS.md. A ~/.claude/CLAUDE.md in your home folder doesn’t count, and keeps loading alongside.

To get both, either import AGENTS.md from CLAUDE.md, or set Project instructions to claude-md-and-agents-md in /config. Anthropic’s memory docs have the full table.

Claude Code also keeps auto memory: notes it writes itself in ~/.claude/projects/<project>/memory/, on by default. That’s separate from your instruction files; see how the three agents’ memory compares.

Codex

Codex reads AGENTS.md. It starts with a global file in ~/.codex/, then walks from the repository root down to the folder you’re working in, taking at most one file per folder: AGENTS.override.md if present, otherwise AGENTS.md, otherwise any fallback names you list in project_doc_fallback_filenames. Files closer to your folder come later, so they win.

Codex stops adding files at project_doc_max_bytes, 32 KiB by default, so a long root file can crowd out a nested one. See OpenAI’s AGENTS.md guide.

Cursor

Cursor’s native format is project rules: .mdc files in .cursor/rules/ with frontmatter that says when each applies (always, for files matching a glob, when the agent judges it relevant, or only when you @-mention it). A plain .md in that folder is ignored.

Cursor also reads AGENTS.md at the root and in subfolders, combined with parent folders, more specific ones taking precedence. It has no frontmatter, so it always applies. See Cursor’s rules docs.

One file for every agent

Three ways to keep a single source of truth:

1. AGENTS.md only. No CLAUDE.md anywhere in the repo. Codex, Cursor and Claude Code all read it. Simplest, until someone adds a CLAUDE.local.md and Claude Code quietly switches files.
2. AGENTS.md plus a one-line CLAUDE.md. CLAUDE.md contains @AGENTS.md and anything Claude-specific below it. Robust to CLAUDE.local.md, and it’s the setup we use.
3. A symlink. ln -s AGENTS.md CLAUDE.md. Works, but Claude-only additions have nowhere to go, and symlinks don’t survive every checkout on Windows.

Use .cursor/rules/ on top for rules that should only attach to some files, like a migration style that only matters in db/.

What goes in it

Things that are true for months:

• How to build, test, lint and run the project, as exact commands.
• Where things live: which folder holds what, which files are generated.
• Conventions an agent can’t infer: error handling, naming, what “done” means.
• What not to touch, and what needs a human: migrations, releases, anything that costs money.

Keep it short. Claude Code’s docs suggest under 200 lines per file; Codex truncates at 32 KiB. Every line is read on every session, so each one should change what the agent does.

What doesn’t

The state of the work: what’s half done, what was decided on Tuesday’s call, which customer asked for what, which test is failing and why. People put this in instruction files because it’s the one place every agent reads. Then nobody updates it, and the agent follows last month’s plan with confidence.

That context changes daily and belongs somewhere that changes with it. A few options:

• A progress file the agent rewrites at the end of each session (cheap, but only covers that one agent’s work).
• The agent’s own memory (Claude Code’s auto memory, Codex memories), which covers its own sessions in one repo.
• An MCP memory server every agent can read. Cachejay is one: it captures your screen, calls and Claude Code and Codex sessions on your Mac, so a new session in Codex can ask what you decided in Claude Code yesterday, or on a call. Agents report back what they finished, which keeps project status and to-dos current.

Whatever you use, keep the split: rules in AGENTS.md, state somewhere that updates itself. More on why in why AI memory goes stale.

A starter AGENTS.md

# AGENTS.md

## Commands
- Install: npm ci
- Test: npm test (must pass before you finish)
- Lint and format: npm run lint -- --fix

## Layout
- src/api: HTTP handlers, one file per resource
- src/core: business logic, no I/O
- src/generated: generated by npm run codegen; never edit by hand

## Conventions
- Functions that can fail return a Result; don't throw across modules.
- New behavior needs a test in the same change.

## Ask first
- Database migrations, dependency upgrades, anything that deploys.

## Recent work
- Not kept here. Ask the project's memory (MCP) what changed and what's open.

Then add a CLAUDE.md that says @AGENTS.md. For connecting each agent to a shared memory, see Claude, Codex and Cursor, or share context between agents.