.cursorrules vs CLAUDE.md vs AGENTS.md: 2026 Full Comparison

Three configuration files. Three different philosophies. And in 2026, one of them is deprecated, one evolved significantly, and one became a genuine cross-tool standard.

This is the definitive breakdown of .cursorrules, CLAUDE.md, and AGENTS.md — their current state, what each one does well, and the decision logic for choosing the right file (or the right combination) for your workflow. Every claim here is verified against the official 2026 docs: Anthropic’s Claude Code documentation and Cursor’s current docs.

If you’ve landed here from a search for “should I use CLAUDE.md or AGENTS.md” — skip to the decision matrix or the migration checklists. If you want the full picture, read on.

The 2026 State of Play

Before comparing, the current status of each file:

.cursorrules — Still functional, but deprecated. Cursor’s own documentation now directs users to .cursor/rules/ (.mdc format) as the canonical system. The legacy single-file format works in 2026 but won’t receive new features.

CLAUDE.md — Significantly expanded in 2026. Claude Code now supports auto memory (MEMORY.md), path-scoped rules via .claude/rules/ with YAML frontmatter, managed policy deployment, and explicit AGENTS.md import syntax. The @import system now supports up to 5 hops. The file is more powerful than ever — and explicitly Claude-only.

AGENTS.md — Emerged as the multi-tool standard. Read natively by Claude Code (via @AGENTS.md import), Codex CLI, Gemini CLI, OpenCode, and Cursor (via discovery). Anthropic’s own docs now say: “If your repository already uses AGENTS.md for other coding agents, create a CLAUDE.md that imports it.” This is the cross-tool standard that the industry settled on.

What Each File Actually Does

.cursorrules (Legacy)

A single markdown file at the project root. No frontmatter, no activation modes, no scoping. Everything in the file applies to every Cursor session in that project.

# .cursorrules
You are an expert TypeScript developer.
Always use functional components in React.
Prefer `const` over `let`. Never use `var`.
Run `npm test` before suggesting you're done.

What happened to it: Cursor built a richer system (.cursor/rules/ with .mdc files) that supports four activation modes, glob-based file scoping, and alwaysApply control. .cursorrules predates all of that. It’s a flat file with no activation logic.

In 2026, .cursorrules still works. Cursor reads it. But there’s no new development on the format. Teams starting fresh should use .cursor/rules/.

.cursor/rules/ (The Modern Cursor System)

Rules live as .mdc files in .cursor/rules/. The YAML frontmatter controls when and how each rule fires:

---
description: "TypeScript API endpoint conventions"
alwaysApply: false
globs: "src/api/**/*.ts"
---

# API Endpoint Rules

- All handlers must validate input with Zod schemas
- Use the standard error response format from `src/lib/errors.ts`
- Add JSDoc comments to all exported functions
- Include integration tests in `tests/api/`

Four activation modes (determined by frontmatter):

Rules should stay under 500 lines. The .cursor/rules/ directory supports subdirectory organization. Team Rules take precedence over Project Rules, which take precedence over User Rules.

CLAUDE.md (Claude Code Native)

CLAUDE.md is Claude Code’s native persistent context system. It supports four scope levels, @imports, and companion path-scoped rules:

Four scopes (load order, broadest to most specific):

All files at the same scope level are concatenated — they don’t override each other.

@import syntax (up to 5 hops deep):

# CLAUDE.md
See @README for project overview and @package.json for npm commands.

# Architecture
@docs/architecture.md

# Git workflow  
@docs/git-workflow.md

Path-scoped rules via .claude/rules/:

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

Rules without paths frontmatter load at launch. Rules with paths load only when Claude reads files matching the pattern.

Auto memory (new in 2026):

~/.claude/projects/<project>/memory/
├── MEMORY.md          # Loaded at every session start (first 200 lines / 25KB)
├── debugging.md       # Topic file, loaded on demand
└── api-conventions.md # Topic file, loaded on demand

Auto memory is Claude-written context — Claude saves notes based on what it learns in sessions. You can read, edit, and delete these files. The auto memory directory is machine-local and shared across worktrees of the same repo.

AGENTS.md import:

# CLAUDE.md
@AGENTS.md

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

Claude Code explicitly supports this pattern. /init in a repo with AGENTS.md reads it and incorporates relevant parts into the generated CLAUDE.md.

Key constraints:

• Target under 200 lines per file (longer files reduce adherence)
• Content delivered as user message after system prompt, not enforced configuration
• To hard-enforce behavior, use PreToolUse hooks instead

AGENTS.md (The Cross-Tool Standard)

Plain markdown. No frontmatter. No special syntax. Its power comes from breadth of support:

AGENTS.md nesting is its structural superpower:

monorepo/
├── AGENTS.md               # Root: applies to all tools, all packages
├── frontend/
│   └── AGENTS.md           # Frontend-specific: React conventions, build commands
├── backend/
│   └── AGENTS.md           # Backend-specific: API patterns, database access rules
└── services/
    └── auth/
        └── AGENTS.md       # Service-specific: security requirements, JWT handling

Compatible agents walk the directory tree and compose instructions hierarchically. Each AGENTS.md adds to the parent’s context, it doesn’t replace it.

Subagent definitions (Claude Code extension):

# AGENTS.md

## General Instructions
- Run tests before marking any task complete
- Use TypeScript strict mode

# agents

## security-reviewer
description: Reviews code for security vulnerabilities.
tools: read, bash
model: claude-sonnet-4-6

## test-writer
description: Writes comprehensive test suites for new features.
tools: read, write, bash
isolation: worktree
model: claude-sonnet-4-6

The # agents section is a Claude Code extension to AGENTS.md. Other tools ignore it (it’s just markdown with a heading they don’t parse).

Decision Matrix: Which File Wins

Tool Support Matrix (2026)

The .cursorrules Deprecation: What It Means in Practice

Cursor still reads .cursorrules in 2026. It hasn’t been removed. But:

1. No new features are being added to the single-file format
2. .cursor/rules/ supports everything .cursorrules does, plus activation modes and glob scoping
3. Cursor’s documentation now points to .cursor/rules/ as the canonical approach
4. The four-mode activation system is the main reason to migrate — it lets rules load selectively rather than dumping everything into every session

Migration from .cursorrules to .cursor/rules/:

The migration is mechanical. The main decision is how to split the monolithic file:

1. Create .cursor/rules/ directory
2. Split content by topic: code-style.md, testing.md, api-design.md
3. Add frontmatter to each file based on desired activation:
   • Rules for all sessions: alwaysApply: true
   • Rules for specific file types: globs: "src/**/*.ts"
   • Rules the agent should decide on: just add description:
4. Delete .cursorrules (or keep for backward compatibility with older Cursor)

# Quick check: what's in your .cursorrules?
wc -l .cursorrules

# If > 200 lines, definitely worth splitting into topic files

CLAUDE.md in 2026: What’s New

The 2026 CLAUDE.md documentation reveals several additions that weren’t present in earlier versions:

Auto memory system: Claude now maintains a MEMORY.md in ~/.claude/projects/<project>/memory/. This is Claude-written — it saves learnings from sessions automatically. The first 200 lines or 25KB of MEMORY.md load at every session start. Topic files in the same directory load on demand. You can edit or delete these files at any time.

HTML comment stripping: Block-level HTML comments in CLAUDE.md are stripped before injection into Claude’s context. Use them for maintainer notes without spending context tokens:

<!-- This section is for future maintainers. Claude won't see this. -->

## Build Commands
- `npm run dev` — start development server

claudeMdExcludes setting: For large monorepos where ancestor CLAUDE.md files from other teams are getting loaded, exclude them by path or glob:

{
  "claudeMdExcludes": [
    "**/other-team/CLAUDE.md",
    "/Users/me/monorepo/legacy/.claude/rules/**"
  ]
}

--add-dir + CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD: Load CLAUDE.md from additional directories outside the main working directory. Useful for shared config repos.

Managed policy via claudeMd key: Organizations can embed CLAUDE.md content directly in managed-settings.json instead of deploying a separate file:

{
  "claudeMd": "Always run `make lint` before committing.\nNever push directly to main."
}

Subagent auto memory: Individual subagents can now maintain their own auto memory (separate from the main session’s memory), configured via the subagent definition frontmatter.

AGENTS.md in 2026: Where the Standard Landed

AGENTS.md started as an informal convention and became explicit support across all major AI coding tools in 2025–2026. The significant 2026 development: Anthropic officially documented the @AGENTS.md import pattern and made /init AGENTS.md-aware.

What /init does with AGENTS.md:

• Reads existing AGENTS.md when present
• Incorporates relevant parts into generated CLAUDE.md
• Also reads .cursorrules and .windsurfrules for context

This makes AGENTS.md the natural starting point for new projects that might use multiple AI tools: write it once, have Claude Code import it, and other tools read it natively.

The # agents section as Claude Code extension:

The AGENTS.md spec doesn’t define a # agents section. But Claude Code reads it as subagent definitions (the description, tools, model, isolation fields). Other tools see it as a markdown section with headings — harmless to them, powerful for Claude Code.

This means a single AGENTS.md file can contain:

1. General instructions (all tools)
2. Subagent role definitions (Claude Code only)
3. Per-package nesting for monorepos (all tools)

Coexistence Patterns

Most production setups combine files rather than picking one exclusively. The most common patterns:

Pattern 1: AGENTS.md + Thin CLAUDE.md Wrapper

# CLAUDE.md
@AGENTS.md

## Claude Code

- Use plan mode for changes under `src/billing/`
- Subagent dispatch: @docs/agent-dispatch.md
- Use isolation: worktree for all file-writing subagents

The @AGENTS.md import brings in all shared instructions. The Claude Code section adds Claude-specific behavior without duplicating content.

Pattern 2: AGENTS.md + .cursor/rules/ for Cursor Teams

your-project/
├── AGENTS.md                 # Source of truth for all AI tools
├── CLAUDE.md                 # @AGENTS.md + Claude-specific additions
└── .cursor/
    └── rules/
        └── cursor-only.mdc   # Cursor-specific activation logic

Shared instructions in AGENTS.md. Cursor-specific rules (with activation modes) in .cursor/rules/. Claude-specific additions in CLAUDE.md.

Pattern 3: Monorepo with Hierarchical AGENTS.md

monorepo/
├── AGENTS.md               # Root: shared conventions, CI commands
├── CLAUDE.md               # @AGENTS.md + Claude subagent definitions
├── frontend/
│   ├── AGENTS.md           # React conventions, frontend build commands
│   └── CLAUDE.md           # @AGENTS.md + frontend-specific Claude behavior
└── backend/
    ├── AGENTS.md           # API patterns, database rules
    └── .claude/
        └── rules/
            └── api.md      # paths: ["**/*.ts"] — Claude-specific API rules

Each package team owns their AGENTS.md. CLAUDE.md wrappers import the local AGENTS.md. Path-scoped rules in .claude/rules/ handle Claude-specific conditionals.

Migration Checklists

Migrating from .cursorrules to .cursor/rules/

• Create .cursor/rules/ directory
• Split .cursorrules content by topic (code style, testing, API patterns, etc.)
• Create one .mdc file per topic in .cursor/rules/
• Add appropriate frontmatter to each file:
  • alwaysApply: true for rules that should always be active
  • globs: "src/**/*.ts" for file-type-specific rules
  • description: "..." for agent-decided rules
• Test by opening relevant file types and checking rule activation in Cursor
• Delete .cursorrules (or keep for backward compatibility with older Cursor versions)

Migrating from CLAUDE.md to AGENTS.md (Broadening Tool Support)

• Rename CLAUDE.md → AGENTS.md
• Strip any Claude-specific syntax (subagent definitions, @imports) from AGENTS.md
• Create a new thin CLAUDE.md that imports AGENTS.md: @AGENTS.md
• Add Claude-specific content below the import in CLAUDE.md
• Move subagent definitions to .claude/agents/ (project scope) or keep in the # agents section of AGENTS.md
• Verify other tools (Codex, Gemini CLI) pick up AGENTS.md correctly

Migrating from AGENTS.md to CLAUDE.md (Claude-Only Setup)

• Rename AGENTS.md → CLAUDE.md (or keep AGENTS.md and create CLAUDE.md with @AGENTS.md)
• Break large CLAUDE.md into path-scoped rules in .claude/rules/
• Add YAML frontmatter paths: to rules that should only apply to specific files
• Enable auto memory if desired (/memory toggle or autoMemoryEnabled: true)
• Set up user-level rules in ~/.claude/rules/ for personal preferences

The Honest Answer for New Projects

For most teams starting a new project in 2026:

If you’re Claude Code-only: Start with CLAUDE.md. Use .claude/rules/ for path-scoped instructions. Let auto memory accumulate learnings. You’ll have the richest feature set.

If you might use multiple AI tools: Write AGENTS.md first. Create CLAUDE.md that does @AGENTS.md plus Claude-specific additions. When you add Cursor, add .cursor/rules/ for Cursor-specific activation logic. Each tool reads what it understands; nothing is duplicated.

If you’re Cursor-first: Start with .cursor/rules/. If you add Claude Code later, add an AGENTS.md with your shared conventions and a CLAUDE.md that imports it.

The important thing: these files are not mutually exclusive. The most common production setup uses all three — AGENTS.md as the shared foundation, CLAUDE.md as the Claude-specific layer, and .cursor/rules/ for Cursor’s activation system.

Related Articles

• AGENTS.md vs CLAUDE.md: When to Use Which (2026) — Use-case-driven decision guide
• Migrating .cursorrules to AGENTS.md (2026) — Step-by-step migration guide
• AGENTS.md vs Cursor Project Rules (2026) — Detailed comparison of AGENTS.md nesting vs. Cursor’s glob system
• CLAUDE.md Best Practices (2026) — Writing effective CLAUDE.md for Claude Code
• Writing Effective AGENTS.md Files — Practical guide to AGENTS.md structure and subagent definitions

Frequently Asked Questions

Q: Is .cursorrules still supported in 2026?

Yes, Cursor still reads .cursorrules. But Cursor’s documentation now points to .cursor/rules/ as the canonical system. The legacy format works but won’t receive new features. Teams starting fresh should use .cursor/rules/ for the four-mode activation system.

Q: Does Claude Code read AGENTS.md directly?

No. Claude Code reads AGENTS.md when you import it from CLAUDE.md using @AGENTS.md. Without that import, Claude Code doesn’t see AGENTS.md. Anthropic’s docs say explicitly: “create a CLAUDE.md that imports it so both tools read the same instructions without duplicating them.”

Q: What is the difference between CLAUDE.md and auto memory?

CLAUDE.md is written by you — explicit instructions. Auto memory (MEMORY.md) is written by Claude based on what it learns in sessions. Both load at session start. Auto memory is Claude’s notes to itself; CLAUDE.md is your instructions to Claude.

Q: Can AGENTS.md and CLAUDE.md coexist in the same project?

Yes — this is the recommended pattern for multi-tool teams. Keep shared instructions in AGENTS.md. Create a CLAUDE.md that starts with @AGENTS.md and adds Claude-specific content below. Both tools read the same base instructions without duplication.

Q: How do CLAUDE.md path-scoped rules differ from Cursor’s globs?

Both scope rules to file patterns, but differently. Claude Code’s .claude/rules/ uses paths: frontmatter — rules load when Claude reads matching files. Cursor’s .cursor/rules/ uses globs: — rules auto-attach when matching files are open. Cursor also has four activation modes; Claude Code rules are either always-loaded or path-triggered.