Quick answer
They're the same idea with different labels. Use CLAUDE.md for Claude Code, .cursor/rules for Cursor (the old single-file.cursorrules is legacy), and AGENTS.md if you want one file most agents can read. If you only use one tool, you only need one file. The real work isn't choosing — it's keeping them consistent once you use more than one tool.
The three files at a glance
| CLAUDE.md | AGENTS.md | .cursorrules | |
|---|---|---|---|
| Read by | Claude Code | Many agents (open format) | Cursor |
| Location | Repo root & ~/.claude/ | Repo root | .cursor/rules/ (new) |
| Format | Markdown | Markdown | Plain text / .mdc |
| Path scoping | Nested CLAUDE.md files | Nested AGENTS.md files | Yes (globs in .mdc) |
| Status | Active | Emerging standard | Legacy → .cursor/rules |
What each file actually is
CLAUDE.md
The context file Claude Code reads automatically at the start of a session. It can live in your repo root (project rules) and in ~/.claude/ (global rules that apply everywhere). You can nest a CLAUDE.md in subdirectories to scope rules to part of the codebase. It holds your conventions, architecture decisions, commands, and anything the agent should treat as standing instructions.
AGENTS.md
An open, tool-agnostic format created to stop the proliferation of one proprietary file per tool. The pitch is simple: write your agent instructions once in AGENTS.md and any compatible agent can read it. Adoption is growing across the ecosystem, which makes it the most portable option if you switch tools often or want to future-proof.
.cursorrules (and .cursor/rules)
Cursor's instruction format. The original single .cursorrules file in the repo root still works but is considered legacy. Cursor now recommends a .cursor/rules/ directory of .mdc files, each of which can be scoped to specific file globs and toggled on or off. If you're starting fresh in Cursor, use the directory format.
And the rest
Windsurf has its own rules files, GitHub Copilot reads .github/copilot-instructions.md, and more tools add their own variants regularly. The names change; the concept doesn't. Every one of them is a place to write down what the agent should know before it touches your code.
The real problem: keeping them in sync
Choosing a file is easy. The problem shows up the moment you use more than one tool — or work on a team where different people use different tools. Now the same conventions live in two or three files, and they drift. You update CLAUDE.md with a new rule, forget the .cursor/rules copy, and your teammate's Cursor happily ignores it. The agent files quietly disagree, and the "single source of truth" becomes three sources of slightly different truth.
Maintaining them by hand
- Same rules copied into 2-3 files
- Updates applied to one, forgotten in the others
- Files silently diverge over time
- Each tool behaves differently on the same repo
One source of truth
- Write the rules once
- Generate each tool file from the same spec
- Point lightweight files at the canonical one
- Every agent reads the same decisions
Which should you use?
You only use Claude Code
Use CLAUDE.md and nothing else. Put global rules in ~/.claude/CLAUDE.md and project-specific rules in the repo root. Done.
You only use Cursor
Use .cursor/rules/ with scoped .mdc files. Skip the legacy single-file .cursorrules for new projects.
You switch tools or want to future-proof
Lead with AGENTS.md as your portable canonical file, then generate tool-specific files (CLAUDE.md, .cursor/rules) from it so each agent gets the format it expects.
Your team uses a mix of tools
Pick one canonical source and automate the rest. Hand-maintaining three files across a team is where rules drift fastest — generate them from a shared spec instead.
Generate a CLAUDE.md free
Describe your project and get a structured CLAUDE.md in seconds — the same context your agent needs, without writing it from scratch.
Try the free generatorStop maintaining three files
The Keeborg dev system gives you one opinionated CLAUDE.md as the source of truth — plus the skills, quality gates, and continuity that keep every agent working the same way. Personalised to your stack.
Get the dev system