CLAUDE.md vs AGENTS.md vs Cursor rules
Teams hopping between Claude Code, Cursor, and Codex often ask whether to maintain
CLAUDE.md, AGENTS.md, and .cursor/rules in parallel. Maintaining three
divergent copies is how conflicts appear and tokens get paid twice. Prefer one canonical file plus thin adapters.
Summary table reflects public product docs: Claude Code memory, Cursor rules, and Codex AGENTS.md discovery.
Quick comparison
| File | Who reads it | Notes |
|---|---|---|
AGENTS.md |
Cursor, Codex, many other agents; Claude Code also reads it | Plain markdown. Best shared source of truth. Codex nests/overrides by directory and caps combined size (default 32 KiB). |
CLAUDE.md |
Claude Code (and Cursor, always applied when present) | Anthropic targets under ~200 lines per file. Can @import other files; imports still load with the parent. Advisory context, not enforced config. |
.cursor/rules/*.mdc |
Cursor | Frontmatter controls always / glob / intelligent / manual load. Keep each rule under 500 lines; split by concern. |
Recommended layout
- Canonical
AGENTS.md— short project map (see the example guide). - Thin
CLAUDE.md— e.g. a single@AGENTS.mdimport plus Claude-only notes (hooks, Claude-specific paths). Avoid pasting the whole AGENTS body again. - Cursor-specific activation — put glob-scoped or always-on triggers in
.mdcfiles that reference AGENTS.md patterns instead of forking them. Fix load issues with the Cursor rules checklist. - Must-never rules — enforce with hooks, permissions, or CI; markdown alone is advisory in Claude Code.
Token reality check
An import or symlink does not magically delete tokens if both tools still load the same text. The win is one edit surface and fewer contradictory always/never pairs. After consolidating, weigh the stack in Clogmeter and trim anything still duplicated. Size ceilings: How long should CLAUDE.md / AGENTS.md be?
Open Clogmeter and weigh your instruction files → Free, browser-only. Export a trimmed copy when you are done.