Cursor rules vs CLAUDE.md vs AGENTS.md: which file does what
In short: each tool reads its own file. Cursor reads .cursor/rules/*.mdc, Claude Code reads CLAUDE.md plus .claude/rules, and Codex (and others) read AGENTS.md. Write the rules once and generate all three.
| Cursor | Claude Code | Codex / AGENTS.md | |
|---|---|---|---|
| Location | .cursor/rules/*.mdc | CLAUDE.md, .claude/rules/*.md | AGENTS.md (nested files allowed) |
| Scoping | globs, alwaysApply, or description-based | paths: frontmatter in .claude/rules | The closest AGENTS.md in the directory tree |
| Size guidance | Under 500 lines per rule | Under ~200 lines per CLAUDE.md | 32 KiB default cap |
| Commands | Manual @rules | .claude/skills/*/SKILL.md | .agents/skills/*/SKILL.md |
The common mistake
People put a plain .md in .cursor/rules, which Cursor ignores, or a 600-line CLAUDE.md, which hurts adherence. A second mistake is keeping three hand-edited copies that drift apart.
A setup that works
- Keep one master rule set with metadata: always-on or scoped, plus globs.
- Generate each tool's native file from it.
- Put always-on essentials in the top file and move stack detail into scoped rules.
- Verify with each tool's context view, for example Claude Code's
/context.
Every kit is built this way. The free sampler shows the output for all five tools.