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, or make AGENTS.md the single source and import it from CLAUDE.md.
| 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.
Skills are the command layer on top of these files. To make yours load when they should, see how to write a SKILL.md that actually triggers.
Every kit is built this way. The free sampler shows the output for all five tools.
FAQ
Why does Cursor ignore my rules file?
Cursor reads project rules from .cursor/rules/*.mdc. A plain .md file in that folder is ignored.
How long should CLAUDE.md be?
Aim for under about 200 lines per CLAUDE.md. Very long files, such as a 600-line CLAUDE.md, hurt adherence. Put always-on essentials in the top file and move stack detail into scoped rules.
How do I scope rules to certain files?
In Cursor use globs, alwaysApply or a description in the .mdc frontmatter. In Claude Code use paths: frontmatter in .claude/rules. For AGENTS.md, the closest AGENTS.md in the directory tree applies.
How do I keep Cursor rules, CLAUDE.md and AGENTS.md in sync?
Keep one master rule set with metadata (always-on or scoped, plus globs) and generate each tool's native file from it, instead of hand-editing three copies that drift apart.