CLAUDE.md vs AGENTS.md vs .cursorrules: Which File Should You Write?
AGENTS.md, CLAUDE.md, or .cursorrules? A verified 2026 comparison of the three rules formats, which of six coding agents reads each one according to the vendors' own docs, and where all three run out.
Key Takeaways
• AGENTS.md is the cross-tool standard: stewarded by the Agentic AI Foundation under the Linux Foundation, used by more than 60,000 open-source projects, and read natively by Codex, Cursor, Copilot's coding agent, Windsurf, Zed, and over a dozen more.
• Claude Code reads CLAUDE.md, not AGENTS.md; the documented bridge is a one-line @AGENTS.md import, a symlink, or the /import command in v2.1.213 and later.
• .cursorrules is legacy per Cursor's own docs; new rules belong in .cursor/rules as .mdc files, which add glob scoping and four rule types.
• All three files are static snapshots of your conventions; picking the right filename does not stop the contents from going stale.
Write AGENTS.md, add a one-line CLAUDE.md bridge if you run Claude Code, and stop writing .cursorrules. That is the 2026 answer for most teams, and it comes down to reach. AGENTS.md is the open format stewarded by the Agentic AI Foundation under the Linux Foundation, and more than 60,000 open-source projects already use it. So do over 20 tools, including OpenAI Codex, Cursor, GitHub Copilot's coding agent, Gemini CLI, Windsurf, and Zed. The claude.md vs agents.md question has one real wrinkle, though: Claude Code does not read AGENTS.md natively, and Cursor has declared its original rules file legacy. This guide covers choosing a file; syncing, auditing, and conflict precedence each have their own pages, linked where they come up.
What Are CLAUDE.md, AGENTS.md, and .cursorrules?#
CLAUDE.md is Anthropic's memory file for Claude Code: plain markdown instructions loaded at the start of every session, treated as context rather than enforced configuration, per the Claude Code memory docs. It supports four scope levels, from an organization-wide managed policy file down to a personal, gitignored CLAUDE.local.md.
AGENTS.md is the cross-vendor open standard, described on the agents.md spec site as "a README for agents." It is standard markdown with no required fields, and agents "automatically read the nearest file in the directory tree, so the closest one takes precedence."
.cursorrules is Cursor's original single-file format, and Cursor's own docs are blunt about it: "The .cursorrules file in your project root is legacy and will be deprecated." Its successor is the .cursor/rules directory of .mdc files, so the honest three-way comparison in 2026 is CLAUDE.md vs AGENTS.md vs the .cursor/rules directory.
CLAUDE.md vs AGENTS.md vs Cursor Rules: How Do They Compare?#
The table below compares the three formats on the dimensions that actually change your day: where the file lives, who reads it, how it nests, and how much you can put in it. Every cell traces to the vendor docs cited throughout this post: Anthropic's memory docs, the agents.md spec, and Cursor's rules docs.
| Dimension | CLAUDE.md | AGENTS.md | Cursor rules |
|---|---|---|---|
| File name and location | CLAUDE.md at repo root or in .claude/, plus a user-level file, managed-policy paths, and CLAUDE.local.md | AGENTS.md at repo root, with nested files per subproject | .cursor/rules directory of .mdc files; legacy single .cursorrules at root |
| Owner or steward | Anthropic | Agentic AI Foundation under the Linux Foundation | Cursor |
| Agents that read it natively | Claude Code; Copilot agents also honor it at repo root | 20+ tools including Codex, Cursor, Copilot coding agent, Windsurf, Zed, Devin, Warp, Aider, and Amp | Cursor only |
| Format | Plain markdown; block-level HTML comments stripped before load | Plain markdown, no required fields | Markdown plus YAML frontmatter (description, globs, alwaysApply) |
| Nesting and hierarchy | Four scope levels; walks up the directory tree; subdirectory files load on demand | Nested files, nearest wins; Codex merges home, repo root, then working directory | Nested rules directories; Team, then Project, then User rules |
| Imports and composition | Imports via @path syntax, up to four hops deep | None in the spec; tool-dependent | Remote rules importable from GitHub repositories |
| Scoping | Path glob frontmatter on rules in .claude/rules/ | None; position in the tree only | Four rule types including file-pattern matching and description-based selection |
| Size guidance | Target under 200 lines per file | 32 KiB combined default budget in Codex | Keep rules under 500 lines |
| Team sharing | Version control plus managed-policy deployment via MDM | Version control | Version control plus dashboard-managed Team Rules on Team and Enterprise plans |
| Ecosystem momentum | Anthropic-specific, though honored at root by Copilot agents | 60,000+ open-source projects; the emerging standard | .cursorrules is legacy; the .mdc format is Cursor-proprietary |
The pattern: AGENTS.md wins on reach, Cursor rules win on scoping precision, and CLAUDE.md wins on hierarchy depth and imports for Claude-first teams. All three vendors publish size ceilings in the hundreds of lines; if you are over, here is how to audit a bloated CLAUDE.md.
Which Agents Read Which File in 2026?#
Only one mainstream agent holds out on the standard file, and it is Claude Code. Here is the support matrix as of August 2026, verified against vendor docs.
| Agent | CLAUDE.md | AGENTS.md | .cursor/rules or .cursorrules | Its own file |
|---|---|---|---|---|
| Claude Code | Yes | No; bridge with an import or symlink | No; the /init command can mine them into CLAUDE.md | CLAUDE.md is its own file |
| OpenAI Codex | No | Yes; merges home, repo root, then working directory under a 32 KiB default budget | No | AGENTS.override.md variants |
| Cursor | No | Yes, at root and in subdirectories | Yes; .cursorrules still read but legacy | .cursor/rules .mdc files |
| GitHub Copilot | Yes, at repo root | Yes, nearest file wins | No | .github/copilot-instructions.md plus path-scoped .instructions.md |
| Gemini CLI | No | Via the context.fileName setting | No | GEMINI.md by default |
| Windsurf | No | Yes, in any directory | No | .devin/rules preferred, .windsurf/rules as fallback, legacy .windsurfrules still read |
Three of these rows contradict most existing comparisons. First, Anthropic's docs are explicit: "Claude Code reads CLAUDE.md, not AGENTS.md." The documented bridge is a CLAUDE.md whose first line is @AGENTS.md, a symlink, or the /import command in v2.1.213 and later. We run that import in this very repo, and /context confirms the file loads under Memory files. Second, GitHub Copilot honors five instruction filenames: .github/copilot-instructions.md, path-scoped .instructions.md files with applyTo globs, AGENTS.md anywhere with nearest-wins precedence, and CLAUDE.md or GEMINI.md at repo root. Third, Gemini CLI defaults to GEMINI.md but reads AGENTS.md if you list it under context.fileName in settings.json. The Windsurf row traces to Windsurf's own docs, now under Cognition's Devin documentation: AGENTS.md files are read in any directory of the workspace, and the native rules home has moved to .devin/rules, with .windsurf/rules kept as a fallback. When these files disagree in one repo, see which file wins when they disagree.
How Do Hierarchy, Imports, and Scoping Differ?#
This is where the formats genuinely diverge in capability rather than filename. CLAUDE.md has the deepest machinery: a four-level load order from managed policy down to CLAUDE.local.md, subdirectory files that load on demand, @path imports that resolve up to four hops deep, and a .claude/rules/ directory where YAML paths: frontmatter scopes a rule to matching globs.
AGENTS.md is deliberately minimal: plain markdown, nested files with nearest-wins precedence, nothing else in the spec. Tools layer behavior on top; Codex concatenates files from your home directory, repo root, and working directory, stopping at a 32 KiB default budget (project_doc_max_bytes), and it honors AGENTS.override.md files for local overrides plus a config option that adds fallback filenames.
Cursor sits in between. Each .mdc rule declares one of four types: apply always, apply to specific files on a glob match, apply intelligently based on the rule's description, or apply manually. Rules nest in subdirectories; Team and Enterprise plans add dashboard Team Rules that outrank project rules. The ecosystem is converging on the same ideas (hierarchy, glob scoping, imports) and implementing them in incompatible ways.
Which File Should You Write in 2026?#
The CLAUDE.md vs AGENTS.md vs .cursorrules verdict from the top, restated as scenarios:
- Multi-tool team, the 2026 default: write AGENTS.md as the canonical file and add a one-line CLAUDE.md bridge. Already running all three? The mechanics live in keeping CLAUDE.md, AGENTS.md, and .cursorrules in sync.
- Claude Code-only team: write CLAUDE.md natively. You gain imports, path-scoped rules in .claude/rules/, and managed-policy distribution that no other format matches.
- Cursor-heavy team that needs glob-scoped rules: put scoped rules in .cursor/rules and the shared baseline in AGENTS.md; Cursor reads both.
- Anyone still on .cursorrules: migrate now. The vendor calls the format legacy, and the migration is a copy-paste into one always-apply rule.
Whichever row you land on, remember that you have chosen a container for conventions, and the contents still need someone to keep them true. Pick for reach today; Linux Foundation stewardship also makes AGENTS.md the safest bet for a file you will still be maintaining in two years. What no pick solves is the maintenance itself, which is where the last part of this post goes.
Frequently Asked Questions#
Should I use CLAUDE.md or AGENTS.md?#
In the CLAUDE.md vs AGENTS.md decision, reach settles it: use AGENTS.md if more than one tool touches the repo, and use CLAUDE.md if Claude Code is your only agent or you need its imports, path-scoped rules, or managed-policy deployment. The two coexist cleanly: a CLAUDE.md containing the single line @AGENTS.md gives both audiences the same instructions.
Does Claude Code read AGENTS.md?#
No. Anthropic's memory documentation states that Claude Code reads CLAUDE.md, not AGENTS.md, which contradicts several popular comparison posts. The documented bridges are a one-line @AGENTS.md import, a symlink from CLAUDE.md to AGENTS.md, or the /import command available since v2.1.213.
Is .cursorrules deprecated?#
Effectively, yes. Cursor's docs say the file "is legacy and will be deprecated." It is still read today for backward compatibility, but the migration path is official: move the content into a .cursor/rules .mdc file set to always apply, then delete .cursorrules.
Can one rules file work for all agents?#
Nearly. AGENTS.md plus a one-line CLAUDE.md bridge plus one Gemini CLI config line covers the mainstream 2026 stack: Codex, Cursor, Copilot, Windsurf, Claude Code, and Gemini CLI. What one file cannot do is stay current on its own, which is the real limit of this whole category.
Where Does the Rules-File Approach Run Out?#
Everything above answers which file to write. None of it fixes what the file is: a snapshot someone hand-edited, and it started going stale the moment it was saved. The 2026 evidence cuts both ways. A study of 124 pull requests across 10 repositories found AGENTS.md presence associated with a 28.64% lower median runtime and 16.58% lower output token consumption. But a second 2026 evaluation found repository context files raised inference cost by over 20% on average without improving task success. And a study of 2,853 GitHub repositories found context files are often the sole context mechanism a repository uses. The format war is about the filename; the failure mode is the file's freshness, and no filename fixes that. Why the contents decay is covered in why rules files rot, and whether to keep investing in files is the subject of rules files vs a context engine. Rules files tell agents what you remembered to write down; a context engine like Unblocked surfaces what you didn't, serving every agent the current answer over MCP instead of a per-tool snapshot.
Pick One File, Then Stop Writing Rules#
For most teams: AGENTS.md canonical, CLAUDE.md as a one-line bridge, .cursorrules deleted. The concrete steps:
- Create AGENTS.md at repo root, under 200 lines of stable, non-discoverable facts: build commands, conventions, the things an agent cannot infer from code.
- Bridge Claude Code with a CLAUDE.md whose first line is
@AGENTS.md. - Migrate .cursorrules into .cursor/rules, or delete it if AGENTS.md now covers it.
- Resist moving anything that changes weekly into any of these files. All three answer the same question, namely what was true the day someone last edited them; a context engine answers what is true now.
That last category of knowledge, the current and the undocumented, is what Unblocked synthesizes from your code, PRs, docs, and conversations and serves to every agent you run. If your rules files keep drifting from reality, try it alongside whichever file you picked.
