Are AGENTS.md, CLAUDE.md, and .cursorrules mutually exclusive?

No. They target different agents and can coexist in the same repo. Most production projects ship AGENTS.md as the open-standard baseline plus tool-specific files where their team's primary assistant prefers them. Files at distinct paths don't conflict.

Should I ship AGENTS.md if I already have CLAUDE.md?

Yes. CLAUDE.md is only read by Claude Code; AGENTS.md is read by Codex, Cursor, Aider, and others. Keep CLAUDE.md for Claude-specific overrides (Anthropic recommends layered files). Add AGENTS.md so non-Claude agents get the same context.

Is .cursorrules deprecated?

Yes — Cursor moved to /.cursor/rules/ (a directory of Markdown files, one rule per file) in recent releases. The single .cursorrules file still works but is legacy. New projects should use the directory form.

Does Vercel recommend AGENTS.md or CLAUDE.md?

Vercel's Agent Readability Spec recommends a skill file at one of the canonical paths and accepts AGENTS.md, agents.md, /.well-known/agents.md, docs/AGENTS.md, CLAUDE.md, .cursor/rules, or .cursorrules. Their published research found that AGENTS.md outperformed Anthropic Skills format in evaluation benchmarks.

Where should I put each file?

AGENTS.md at the repo root (or docs/AGENTS.md, .well-known/agents.md). CLAUDE.md at the repo root, with optional ~/.claude/CLAUDE.md for global user-scoped rules and subdirectory CLAUDE.md files for module-scoped rules. .cursor/rules/ as a directory of .md files at the repo root (the legacy .cursorrules file also works at root).

AGENTS.md vs CLAUDE.md vs .cursorrules: which skill file should you ship?

At a glance

Criterion	AGENTS.md	CLAUDE.md	.cursorrules
Audience	Codex, Cursor, Aider, multi-agent IDEs	Anthropic Claude Code	Cursor IDE
Canonical path	/AGENTS.md (or /docs/AGENTS.md, /.well-known/agents.md)	/CLAUDE.md (project) + ~/.claude/CLAUDE.md (global)	/.cursor/rules/*.md (legacy: /.cursorrules)
Standardisation	Open convention with agents.md spec site	Anthropic-specific, documented in Claude Code docs	Cursor-specific, documented in Cursor docs
Hierarchy / overrides	Yes — AGENTS.override.md in subdirectories	Yes — global, project, subdirectory layered files	Directory form supports per-file rules; .cursorrules is single file
Format	Markdown, structured sections	Markdown, free-form prose welcome	Markdown (.cursor/rules) or plain text (.cursorrules)
Status	Emerging open standard; broadest adoption	Anthropic-maintained; active	Single file legacy; directory form is current

What is AGENTS.md?

AGENTS.md is an open, community-backed convention for a Markdown skill file at the root of a code repository. It tells coding agents how to install, configure, run, and test the project, along with any constraints (paths to avoid, conventions to follow). The canonical site is agents.md; readers include Codex, Cursor, Aider, and a growing list of IDE agents.

What is CLAUDE.md?

CLAUDE.md is Anthropic Claude Code’s project-memory file, read at session start. It supports a three-layer hierarchy: global at ~/.claude/CLAUDE.md, project at CLAUDE.md in the repo root, and scoped sub-directory files for module-specific rules. The format is intentionally loose — free-form Markdown is welcome.

What is .cursorrules?

.cursorrules is Cursor IDE’s original rules file— a single Markdown/text file at the repo root that constrains Cursor’s autocomplete and chat behaviour. Cursor has since moved to a directory form at /.cursor/rules/, where each rule lives in its own .md file with YAML frontmatter. Both forms still work; the directory form is recommended for new projects.

How do AGENTS.md, CLAUDE.md, and .cursorrules differ?

They’re solving the same problem from different vantage points: an open convention vs. two vendor-specific files.

Audience. AGENTS.md is read by multiple agents and is the safest single choice. CLAUDE.md is Claude-Code-specific. .cursorrules is Cursor-specific.
Standardisation. AGENTS.md has an open spec site; the other two are vendor documented and free to evolve.
Hierarchy. CLAUDE.md has the most explicit override model (global → project → subdirectory). AGENTS.md supports AGENTS.override.md per-subdirectory. Single-file .cursorrules has no hierarchy; .cursor/rules/ has per-file rules.
Tone.AGENTS.md tends toward structured sections (Install, Run, Test, Conventions). CLAUDE.md is freer-form. .cursorrules sits in between — rule-shaped statements that bias Cursor’s output.
Status. AGENTS.md is the emerging cross-tool standard; CLAUDE.md is actively maintained by Anthropic; the single-file .cursorrules is legacy and the .cursor/rules/ directory is current.

When should I use AGENTS.md?

Always — this is the recommended baseline. If your repo will be touched by any coding agent (including agents you don’t use directly, like contributors’ IDE assistants), AGENTS.md is the safest single file to ship. It also acts as the canonical source of truth that you can re-derive the vendor-specific files from.

When should I use CLAUDE.md?

When your team uses Claude Code as a primary IDE assistant. Anthropic’s docs recommend shipping CLAUDE.md for any project where Claude Code is in regular rotation, because Claude reads it at session start. Use the hierarchy: global for personal preferences, project root for repo-wide context, sub-directory files for module-specific overrides.

When should I use .cursorrules (or .cursor/rules)?

When your team uses Cursor. New projects should use the directory form (/.cursor/rules/*.md) because it supports per-rule frontmatter and per-file targeting (which paths each rule applies to). Keep the single-file .cursorrules only on projects that already ship it and don’t need per-file targeting.

Can I ship all three?

Yes, and many production repos do. AGENTS.md is the open-standard baseline that any agent can read. CLAUDE.md and .cursor/rules/ are tool-specific additions for teams whose primary assistant reads them. The three live at distinct paths and don’t conflict. A common pattern: write AGENTS.md as the source of truth, then derive CLAUDE.md and .cursor/rules/ as tool-specific subsets where needed.

Frequently asked questions

Are AGENTS.md, CLAUDE.md, and .cursorrules mutually exclusive?: No. They target different agents and can coexist in the same repo. Most production projects ship AGENTS.md as the open-standard baseline plus tool-specific files where their team's primary assistant prefers them. Files at distinct paths don't conflict.
Should I ship AGENTS.md if I already have CLAUDE.md?: Yes. CLAUDE.md is only read by Claude Code; AGENTS.md is read by Codex, Cursor, Aider, and others. Keep CLAUDE.md for Claude-specific overrides (Anthropic recommends layered files). Add AGENTS.md so non-Claude agents get the same context.
Is .cursorrules deprecated?: Yes — Cursor moved to /.cursor/rules/ (a directory of Markdown files, one rule per file) in recent releases. The single .cursorrules file still works but is legacy. New projects should use the directory form.
Does Vercel recommend AGENTS.md or CLAUDE.md?: Vercel's Agent Readability Spec recommends a skill file at one of the canonical paths and accepts AGENTS.md, agents.md, /.well-known/agents.md, docs/AGENTS.md, CLAUDE.md, .cursor/rules, or .cursorrules. Their published research found that AGENTS.md outperformed Anthropic Skills format in evaluation benchmarks.
Where should I put each file?: AGENTS.md at the repo root (or docs/AGENTS.md, .well-known/agents.md). CLAUDE.md at the repo root, with optional ~/.claude/CLAUDE.md for global user-scoped rules and subdirectory CLAUDE.md files for module-scoped rules. .cursor/rules/ as a directory of .md files at the repo root (the legacy .cursorrules file also works at root).