AGENTS.md vs CLAUDE.md vs Cursor rules: which should you write?
Three files, mostly the same content, different readers. Here is what each one does, where they differ, and a setup that avoids maintaining three copies.
| AGENTS.md | CLAUDE.md | Cursor rules | |
|---|---|---|---|
| Read by | Many agents, including Codex, Cursor, Copilot's agents, Devin Desktop and Zed | Claude Code | Cursor |
| Location | Repo root, plus nested files per directory | CLAUDE.md or .claude/CLAUDE.md, nested files, .claude/rules/ | .cursor/rules/*.mdc (legacy: .cursorrules) |
| Format | Plain Markdown, no frontmatter | Markdown; .claude/rules files can have paths frontmatter | Markdown with description, globs, alwaysApply frontmatter |
| Scope to files | Only by directory (nested files) | Yes, via paths in .claude/rules | Yes, via globs |
| Agent decides when to use | No | Not for rules (skills cover this) | Yes, “Apply Intelligently” via description |
| Imports | No standard syntax | @path/to/file | Can reference files with @ |
| Maintained by | Agentic AI Foundation (Linux Foundation) | Anthropic | Anysphere (Cursor) |
AGENTS.md: the shared baseline
AGENTS.md is “a README for agents”: build commands, conventions and boundaries in plain Markdown. Its strength is reach. Because so many tools read it, it is the natural home for anything every agent on the project should know. Its weakness is precision: apart from nested files per directory, it cannot say “only for test files” or “only when working on migrations”.
CLAUDE.md: Claude Code's own file, with real scoping
Claude Code loads CLAUDE.md files from the working directory upwards at launch and from subdirectories on demand. The .claude/rules/
directory adds topic files, and a paths field turns any of them into a file-scoped rule. The catch for mixed teams: when a CLAUDE.md
exists, Claude Code does not read AGENTS.md unless CLAUDE.md imports it.
Cursor rules: the most activation options
Cursor's .mdc rules have four modes: always on, attached to file globs, chosen by the agent from a description, or applied manually with
an @-mention. No other format here has all four, which is why converting out of Cursor is where information gets lost. Cursor also reads
AGENTS.md, so you don't need to duplicate shared rules into .mdc files.
Which one should you write?
- Only Cursor:
.cursor/rulesgives you the most control. Start an AGENTS.md anyway if anyone else might open the repo with another agent. - Only Claude Code: CLAUDE.md plus
.claude/rulesfor scoped topics. - Several tools or open source: AGENTS.md for shared rules, a CLAUDE.md that imports it, and scoped rules in each tool's own format only where they earn their keep.
Whichever you choose, avoid keeping the same always-on rule in two formats a single tool reads. Cursor reads both AGENTS.md and
.cursor/rules; Devin Desktop reads both AGENTS.md and its own rules folder.