CLAUDE.md vs AGENTS.md vs Cursor Rules: Which File Does What?
Every AI coding tool wants a file that explains your project: your stack, your conventions, the commands to run. The trouble is they all use different names — CLAUDE.md, AGENTS.md, Cursor rules, GEMINI.md, .clinerules.
This page explains which tool reads which file, what to put in them, and how to keep one source of truth so you don't maintain five copies.
Quick verdict
Claude Code reads CLAUDE.md — and, in recent versions, AGENTS.md when a project has no CLAUDE.md. Codex reads AGENTS.md, while Cursor, Gemini CLI and Cline use their own formats. To avoid duplication, keep shared content in AGENTS.md and import it into CLAUDE.md with an @AGENTS.md line.
Put in every instructions file…
- Your stack and key libraries
- How to install, run, test and lint
- Coding conventions and folder structure
- Things the agent must never do
Keep out of them…
- Secrets, API keys and passwords
- Long procedures (make them skills instead)
- Specialist roles (make them subagents)
- Anything that changes every week
Side-by-side comparison
| File | Read by | |
|---|---|---|
| CLAUDE.md | ./CLAUDE.md or ./.claude/CLAUDE.md, subfolders, ~/.claude/CLAUDE.md (plus CLAUDE.local.md for personal notes) | Claude Code |
| .claude/rules/ | Topic files, optionally scoped to file paths | Claude Code |
| AGENTS.md | Project root (and subfolders) | OpenAI Codex, Claude Code (when there's no CLAUDE.md) and other tools that support the format |
| Cursor rules | Rule files such as .cursor/rules/ (legacy: .cursorrules) | Cursor |
| GEMINI.md | Project root | Gemini CLI |
| .clinerules | Project root | Cline |
What CLAUDE.md does
Claude Code reads CLAUDE.md at the start of every session. A file in your project root (or .claude/CLAUDE.md) applies to the project, files in subfolders load when Claude works in that part of the code, ~/.claude/CLAUDE.md holds personal preferences for every project, and a gitignored CLAUDE.local.md holds your private notes for one project.
Anthropic's documentation recommends keeping each CLAUDE.md under about 200 lines, because longer files use more context and are followed less reliably. Run /init to generate a first draft from your codebase. For bigger projects, split instructions into topic files in .claude/rules/, which can be scoped so they only load for matching file paths.
What AGENTS.md does
AGENTS.md plays the same role for OpenAI's Codex and for other tools that have adopted the format. The content is usually interchangeable with CLAUDE.md: a plain markdown description of your project and how to work in it.
Recent versions of Claude Code (v2.1.277 and later) also read AGENTS.md directly — but only when the project has no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md. If you have both, Claude Code reads your CLAUDE.md files only, unless CLAUDE.md imports AGENTS.md.
Keeping one source of truth
If your team uses more than one tool, don't maintain separate copies. A simple pattern is to keep shared instructions in AGENTS.md and make CLAUDE.md import it with a line like @AGENTS.md, adding only Claude-specific notes below. This very website uses that setup: its CLAUDE.md contains a single @AGENTS.md line.
- AGENTS.md — the shared project description
- CLAUDE.md — @AGENTS.md plus anything Claude Code-specific
- Editor rules — point to the same conventions, or keep them short
When an instructions file isn't enough
Instruction files are read every session, so they should stay short. When you find yourself writing a long procedure or a specialist role into CLAUDE.md, move it out: rules for one part of the code become path-scoped files in .claude/rules/, procedures become skills that load only when needed, and specialist roles become subagents with their own context.
Where claudeagents fits
claudeagents is built around one CLAUDE.md system: describe your stack and goals once, and all 120+ agents, 54 skills and 54 slash commands follow it. You can try the free CLAUDE.md generator to draft your first file.
Frequently asked questions
Does Claude Code read AGENTS.md?
Yes, in recent versions — but only when your project has no CLAUDE.md. If you have both files, add an @AGENTS.md line to CLAUDE.md so Claude Code reads the shared instructions too.
Where should CLAUDE.md go?
In your project root (or .claude/CLAUDE.md) for project-wide instructions. You can add more in subfolders, a personal one at ~/.claude/CLAUDE.md for every project, and a gitignored CLAUDE.local.md for private notes.
What is .cursorrules?
It's Cursor's older single-file rules format. Cursor now uses rule files in a rules folder, such as .cursor/rules/.
Should I put API keys in CLAUDE.md?
No. Instruction files are often committed to git and read by AI tools. Keep secrets in environment variables or a secrets manager.
Get 120+ agents for Claude Code
Coding, SEO and marketing kits, 54 skills and 54 slash commands. $49 one-time, lifetime updates.
See what's included →