AGENTS.md vs CLAUDE.md vs .cursor/rules: The Complete 2026 Three-Way Comparison (with Migration Paths)

When you set up AI coding rules for a 2026 project, three configuration systems compete for the slot: AGENTS.md (the multi-tool standard), CLAUDE.md (Claude Code’s native config), and .cursor/rules/ (Cursor’s structured rule system). They look superficially similar — all are some flavor of “markdown files telling the agent how to work” — but the underlying models diverge enough that picking the wrong one for your team costs setup time and consistency.

This article compares all three on the dimensions that matter — scope, file format, path scoping, imports, rule activation modes, multi-tool compatibility — and provides migration paths in both directions. Every claim here is verified against the Anthropic Claude Code docs (May 2026) and the Cursor official docs (May 2026), not community wikis.

If you’re standing up a new repo, considering a switch, or running multiple agents on the same codebase, this is the reference page.

TL;DR — The 30-Second Answer

• Your team uses multiple AI coding tools (Claude Code + Codex + Cursor + Gemini CLI): AGENTS.md is the lowest-common-denominator standard. All major agents read it.
• You’re Claude Code-only and want native features (@imports, .claude/rules/ with glob scoping, auto memory): CLAUDE.md plus .claude/rules/ is the most powerful option.
• You’re Cursor-only and want fine-grained rule activation (Always / Auto Attached / Agent Requested / Manual via @): .cursor/rules/ with .mdc frontmatter is built for this.
• You use multiple agents but want Claude-specific behavior: keep AGENTS.md as the shared file and create a CLAUDE.md that does @AGENTS.md (import). Both worlds, no duplication.

The rest of the article unpacks why.

What Each One Is

AGENTS.md (2026)

AGENTS.md is a plain-markdown configuration convention that emerged as the multi-tool standard. There is no frontmatter, no metadata, no rule-activation modes. Just a markdown file at the repo root (or nested in subdirectories) that tells any AI agent how to work in this codebase. As of 2026, AGENTS.md is read natively by Claude Code (via import), Codex CLI, Gemini CLI, OpenCode, and Cursor (via discovery) — and that compatibility list is its primary value.

Anthropic’s own Claude Code documentation explicitly recognizes the file: “If your repository already uses AGENTS.md for other coding agents, create a CLAUDE.md that imports it so both tools read the same instructions without duplicating them.”

Nesting is the AGENTS.md superpower: a repo can have AGENTS.md at the root, frontend/AGENTS.md, backend/AGENTS.md, and infra/AGENTS.md — and agents that walk the directory tree will compose instructions hierarchically.

CLAUDE.md (Anthropic, May 2026)

CLAUDE.md is Claude Code’s native instructions file. From the May 2026 official docs:

“Each Claude Code session begins with a fresh context window… CLAUDE.md files: instructions you write to give Claude persistent context.”

CLAUDE.md is loaded in full at session start (no lazy loading at the project root level), with four canonical scopes in load order from broadest to most specific:

1. Managed policy — IT/DevOps-controlled file at OS-managed paths (e.g., /Library/Application Support/ClaudeCode/CLAUDE.md on macOS). Cannot be excluded by individual settings.
2. User instructions — ~/.claude/CLAUDE.md, personal preferences across all projects.
3. Project instructions — ./CLAUDE.md or ./.claude/CLAUDE.md, team-shared via version control.
4. Local instructions — ./CLAUDE.local.md, personal project preferences (gitignored).

It supports @path/to/file imports up to 5 levels deep, nested CLAUDE.md files in subdirectories that lazy-load when Claude reads files there, and the companion .claude/rules/ directory for path-scoped rules with YAML frontmatter paths: globs.

The recommended size is under 200 lines per file — Anthropic’s docs are explicit that longer files reduce adherence.

.cursor/rules/ (Cursor, May 2026)

Cursor’s rule system is the most structured of the three. Rules live in .cursor/rules/ as .md or .mdc files. The .mdc format supports YAML frontmatter:

---
description: "Rule purpose"
alwaysApply: false
globs: src/**/*.tsx
---
Rule content here

The standout feature is four explicit rule application modes:

1. Always Apply (alwaysApply: true) — included in every chat session
2. Apply Intelligently — agent decides relevance using the description field
3. Apply to Specific Files — auto-attached when files match globs
4. Apply Manually — invoked via @rule-name mention

Rule precedence follows Team → Project → User, with earlier sources winning on conflict.

The legacy single-file .cursorrules still works in 2026, but Cursor’s docs now point users to .cursor/rules/ as the canonical form.

Three-Way Comparison Matrix

When to Use Which (Decision Tree)

Scenario 1: Solo dev, Claude Code only

Pick CLAUDE.md + .claude/rules/. You get the most powerful native feature set — @imports, glob-scoped rules, lazy-loaded subdirectory files, auto memory.

your-project/
├── CLAUDE.md                 # Always loaded
└── .claude/
    └── rules/
        ├── testing.md        # No frontmatter → always loaded
        └── api.md            # paths: ["src/api/**/*.ts"] → conditional

Scenario 2: Team using multiple AI coding tools

Pick AGENTS.md as the source of truth. Add tool-specific wrappers when a tool needs unique behavior:

your-project/
├── AGENTS.md                 # Read by Codex, Gemini CLI, OpenCode, Cursor
├── CLAUDE.md                 # @AGENTS.md\n## Claude Code\n...
└── .cursor/
    └── rules/
        └── cursor-only.mdc   # Cursor-specific overrides

CLAUDE.md content:

@AGENTS.md

## Claude Code
- Use plan mode for changes under `src/billing/`
- Subagent dispatch pattern: see @docs/dispatch.md

Scenario 3: Cursor-only team that wants fine-grained activation

Pick .cursor/rules/. No other system has the four-mode activation. Use alwaysApply: false + description: "..." for rules that should only fire when relevant, saving context budget.

Scenario 4: Monorepo with per-package rules

All three handle this differently:

• AGENTS.md — place frontend/AGENTS.md, backend/AGENTS.md, services/auth/AGENTS.md etc. Compatible agents walk the tree.
• CLAUDE.md — root CLAUDE.md + .claude/rules/api.md with paths: ["src/api/**/*.ts"]. Or nested CLAUDE.md files in each package directory (lazy-loaded).
• .cursor/rules/ — single .cursor/rules/ directory at the root, with per-package .mdc files using globs: services/auth/**/* style scoping.

If your monorepo crosses ownership boundaries (each team owns its own rules), AGENTS.md nesting is the cleanest model: each team manages their AGENTS.md without touching the others.

Migration Paths

From CLAUDE.md to AGENTS.md (multi-tool standard)

1. Rename CLAUDE.md → AGENTS.md, scrub Claude-specific phrasing.
2. Create a thin CLAUDE.md with just @AGENTS.md and Claude-specific additions:

   @AGENTS.md
   
   ## Claude Code Specific
   - Use plan mode for refactors under `src/billing/`

3. Test that other agents (Codex / Cursor / Gemini CLI) pick up AGENTS.md correctly.

A symlink also works if you don’t need Claude-specific content:

ln -s AGENTS.md CLAUDE.md

(On Windows, prefer the @AGENTS.md import — symlinks require Developer Mode.)

From .cursorrules (legacy) to .cursor/rules/ (modern)

1. Move content from .cursorrules to .cursor/rules/main.md (or split by topic).
2. For rules that should be always-on, add alwaysApply: true frontmatter.
3. For rules tied to specific files, use globs: instead.
4. Delete .cursorrules (or keep it for backward compatibility with older Cursor versions).

From .cursor/rules/ to AGENTS.md (broaden tool support)

1. Strip frontmatter from .mdc files — AGENTS.md is plain markdown.
2. Merge “always apply” rules into the main AGENTS.md.
3. For file-scoped rules, move them to nested AGENTS.md in the corresponding directory (e.g., globs: src/api/**/* → src/api/AGENTS.md).
4. Keep .cursor/rules/ only for Cursor-specific behaviors not portable to other agents.

Running All Three in Parallel (most complex)

Some teams do this when migrating slowly or when tools diverge. The setup:

project/
├── AGENTS.md                 # Source of truth, shared across tools
├── CLAUDE.md                 # @AGENTS.md + Claude-specific
├── .claude/
│   ├── rules/
│   │   └── path-scoped.md    # Claude-only path-scoped rules
│   └── settings.json
└── .cursor/
    └── rules/
        └── cursor-specific.mdc  # Cursor activation modes

Beware duplication drift: when you update AGENTS.md, check whether any tool-specific file has stale copies. The @AGENTS.md import in CLAUDE.md prevents this on Claude’s side; Cursor doesn’t have an equivalent import, so manual sync is needed.

What These Files Do Not Solve

Three common misconceptions worth surfacing:

They are not enforcement layers

All three systems inject instructions into the model’s context. None of them block anything. If you need hard prohibitions, use:

• Claude Code: permissions.deny in .claude/settings.json (enforced client-side).
• Cursor: per-command settings (e.g., terminal commands require approval).
• Codex/Gemini CLI: tool-specific sandbox settings.

Anthropic’s docs are explicit: “Settings rules are enforced by the client regardless of what Claude decides to do. CLAUDE.md instructions shape Claude’s behavior but are not a hard enforcement layer.”

They do not survive /compact uniformly

In Claude Code, project-root CLAUDE.md is re-injected after /compact (it’s re-read from disk). Nested CLAUDE.md files in subdirectories are not re-injected automatically — they reload only the next time Claude reads a file in that subdirectory. Cursor and Codex have different compaction semantics; check tool-specific docs.

They are not skills, hooks, or commands

If something needs to run at a fixed lifecycle event (pre-commit, post-edit), use hooks. If something is a multi-step workflow you invoke on demand, use skills (Claude Code) or @rule Manual mode (Cursor). Configuration files are for always-loaded context, not workflows.

A Note on claude.md vs claude-md Searches

Search-console data from 2026 shows persistent typo variations: claude.md, claude md, agents md (without dot), agent.md, caveman md (likely OCR/auto-correct). The canonical spelling is CLAUDE.md (all caps with dot, no space) and AGENTS.md (all caps with dot, plural). Cursor uses .cursor/rules/ as the directory, with individual files named freely (testing.md, api.mdc, etc.); the legacy single-file form is .cursorrules (lowercase, no dot).

FAQ

Does Claude Code read AGENTS.md natively?

No. Claude Code reads CLAUDE.md, not AGENTS.md. The official workaround is to create a CLAUDE.md that imports AGENTS.md with @AGENTS.md syntax, or a symlink (ln -s AGENTS.md CLAUDE.md). Anthropic’s docs explicitly recommend this pattern for multi-tool repositories.

Can I use CLAUDE.md and .cursor/rules/ in the same project?

Yes, and many teams do. Claude Code reads CLAUDE.md; Cursor reads .cursor/rules/. They do not conflict because each tool only reads its own files. The risk is drift: if both files describe the same convention and diverge, the two agents behave differently. The cleanest solution is to make AGENTS.md the source of truth and import it into CLAUDE.md.

What is the difference between .cursorrules and .cursor/rules/?

.cursorrules is the legacy single-file form. .cursor/rules/ is the modern directory-based system that supports .mdc frontmatter, four rule activation modes (Always / Auto Attached / Agent Requested / Manual), and per-file glob scoping. Both still work in Cursor 2026, but the docs point new users to .cursor/rules/.

Does AGENTS.md support glob scoping like .cursor/rules/?

Not via frontmatter — AGENTS.md has no frontmatter. The equivalent pattern is nested AGENTS.md files: place frontend/AGENTS.md, backend/AGENTS.md, etc., and agents that walk the directory tree compose instructions hierarchically. This works in Claude Code (via subdirectory CLAUDE.md lazy-loading), Codex CLI, and other multi-tool agents.

How many lines should a CLAUDE.md be?

Anthropic’s official guidance is under 200 lines per file. Longer files consume more context and reduce adherence. If your instructions are growing, split them into .claude/rules/ with paths: glob scoping so rules only load when Claude works with matching files.

Which file does /init create?

In Claude Code, /init creates a CLAUDE.md. If AGENTS.md already exists, /init reads it and incorporates relevant parts into the generated CLAUDE.md. It also reads .cursorrules and .windsurfrules to seed conventions when migrating from those tools.

Can I write rules that apply only to TypeScript files?

Yes, in all three systems — but the syntax differs:

• CLAUDE.md: create .claude/rules/typescript.md with frontmatter paths: ["**/*.ts", "**/*.tsx"].
• .cursor/rules/: create typescript.mdc with frontmatter globs: **/*.{ts,tsx}.
• AGENTS.md: place rules in nested AGENTS.md (e.g., src/AGENTS.md) and rely on directory-tree walking.

Are there managed/enterprise versions?

CLAUDE.md has explicit support: managed policy CLAUDE.md at OS-managed paths (e.g., /Library/Application Support/ClaudeCode/CLAUDE.md) cannot be excluded by individual settings. Cursor supports Team Rules. AGENTS.md is a community convention without standardized enterprise tooling.

What happens to my instructions after /compact?

For Claude Code: project-root CLAUDE.md is re-injected from disk after /compact. Nested CLAUDE.md files do not re-inject automatically — they reload the next time Claude reads a file in that subdirectory. Conversation-only instructions are lost; move them to CLAUDE.md to persist.

Related Articles

• AGENTS.md vs CLAUDE.md: 60,000+ Real Repos Tell You Which to Use
• .cursorrules vs CLAUDE.md vs AGENTS.md
• Inside Career-Ops: 14-Mode Skills Architecture Lessons
• Career-Ops on Claude Code: The Complete 2026 Reference
• How to Write a CLAUDE.md File
• Browse 165+ Real AI Coding Rules

External References

• Claude Code Memory Documentation (Anthropic, May 2026)
• Cursor Rules Documentation (May 2026)
• AGENTS.md Specification Reference