.cursorrules vs CLAUDE.md vs AGENTS.md: Which AI Coding Rules Format Should You Use?

Three formats dominate AI coding rules in 2026: .cursorrules for Cursor, CLAUDE.md for Claude Code, and AGENTS.md for multi-agent systems. If you are setting up AI rules for your project, you need to pick one or more of them.

This guide compares all three based on real-world usage across thousands of repositories. We will cover what each format does, where it excels, where it falls short, and how to decide which one to use.

The Quick Answer

If you need a recommendation right now:

• You use Cursor exclusively → .cursorrules
• You use Claude Code exclusively → CLAUDE.md
• Your team uses multiple AI tools → AGENTS.md as the base, plus tool-specific files where needed
• You are an open-source maintainer → AGENTS.md for the broadest compatibility, plus CLAUDE.md if your contributors use Claude Code heavily

Now let us look at each format in detail.

.cursorrules

What It Is

.cursorrules is a file placed at the root of your repository that Cursor AI reads automatically. It defines how Cursor generates and modifies code in your project. The format has been around since early Cursor adoption and has the largest collection of community-contributed examples.

Format and Syntax

.cursorrules is plain text. There is no formal schema — you write natural language instructions, and Cursor interprets them. Most files start with a role definition and then list specific rules.

You are an expert in TypeScript, React, and Next.js.

Code Style:
- Use functional components with arrow functions
- Prefer named exports
- Use TypeScript strict mode

Architecture:
- Server Components by default
- Data fetching in server components only

The Next.js + TypeScript .cursorrules (1,240 stars) is one of the most popular examples and follows this pattern.

Strengths

Massive ecosystem. The awesome-cursorrules collection has thousands of rules covering nearly every framework and language combination.

Simple to write. There is no schema to learn. Write instructions in natural language and iterate.

IDE integration. Cursor reads the file seamlessly. No configuration needed — just drop the file in your repo.

Framework coverage. You can find .cursorrules files for Next.js, SvelteKit, Vue/Nuxt, Rails, Angular, Flutter, Django, Spring Boot, and dozens more.

Weaknesses

Cursor-only. Other AI tools ignore this file completely. If a contributor opens your project in Claude Code or Copilot, they get no guidance.

No hierarchy. You get one file at the root. There is no mechanism for subdirectory overrides or monorepo-specific configurations.

No formal spec. The format is not documented with a specification. What works well is learned through community experimentation.

File naming. The .cursorrules name is Cursor-specific and does not communicate intent to developers unfamiliar with the tool. Newer Cursor versions also support .cursor/rules/*.mdc files (see MDC Rules Guide) which adds flexibility but fragments the ecosystem.

Best For

Solo developers and small teams that use Cursor as their primary editor and do not need to support other AI tools.

CLAUDE.md

What It Is

CLAUDE.md is a Markdown file that Claude Code reads at the start of every session. Introduced by Anthropic as part of Claude Code’s agentic workflow, it has become the standard for configuring Claude’s behavior in a codebase.

Format and Syntax

CLAUDE.md uses standard Markdown. It supports headers, lists, code blocks, and all other Markdown features. This makes it easy to read for humans too.

# Project

A Next.js 14 application using the App Router.

## Code Style

- TypeScript strict mode, no `any`
- Functional components only
- Named exports preferred

## Commands

- `pnpm dev` — Start dev server
- `pnpm test` — Run tests with Vitest

The Anthropic Official CLAUDE.md Guide provides the canonical structure.

Strengths

Hierarchical configuration. You can place CLAUDE.md files at the repo root, in subdirectories, and at the user level (~/.claude/CLAUDE.md). Claude merges them intelligently. This makes it ideal for monorepos.

Rich formatting. Markdown means you can use headers for organization, code blocks for examples, and lists for rules. The structure is self-documenting.

Anthropic backing. CLAUDE.md is Anthropic’s official format. It receives first-class support in Claude Code, and updates to Claude Code improve how it interprets the file.

Growing adoption in major projects. Some of the world’s largest open-source projects now ship CLAUDE.md files: Next.js (138K stars), LangChain (128K stars), Excalidraw (118K stars), Deno (106K stars).

Compatible with AGENTS.md. Claude Code also reads AGENTS.md files, so you can use both if needed.

Weaknesses

Claude Code only (as primary consumer). While other tools could theoretically read it, CLAUDE.md is designed for and read by Claude Code specifically.

Can get too long. Because Markdown encourages detailed writing, CLAUDE.md files sometimes bloat beyond what is effective. The sweet spot is under 500 lines.

No programmatic access. There is no API to query or validate CLAUDE.md content. It is a text file that Claude reads conversationally.

Best For

Teams that use Claude Code heavily, especially for monorepo projects where the hierarchical file system is a significant advantage. Also excellent for open-source projects where contributors use Claude Code, because the Markdown format is readable by humans too.

AGENTS.md

What It Is

AGENTS.md is a more recent standard designed to be tool-agnostic. Originally popularized by projects like n8n and Grafana, it provides instructions that any AI coding agent can read — including Claude Code, OpenAI Codex, and others.

The AGENTS.md specification (60K stars) defines it as a universal format for multi-agent development environments.

Format and Syntax

Like CLAUDE.md, AGENTS.md uses standard Markdown. The key difference is in intent: AGENTS.md is written for any AI agent, not just one vendor’s tool.

# AGENTS.md

## Project Context
This is a Go microservice using the standard library's ServeMux.

## Coding Standards
- Follow Go idioms: short variable names, error wrapping
- Tests go in _test.go files alongside source
- Use table-driven tests

## Agent Instructions
- Run `go test ./...` before submitting any changes
- Do not modify files in vendor/

Strengths

Tool-agnostic. Read by Claude Code, OpenAI Codex CLI, and an increasing number of AI coding tools. One file works across ecosystems.

Designed for multi-agent workflows. If your project uses multiple AI agents for different tasks (code generation, testing, review), AGENTS.md can address each agent’s responsibilities.

Broad adoption in large projects. n8n (178K stars), awesome-go (167K stars), LangFlow (145K stars), llama.cpp (97K stars), and Bun (82K stars) all use AGENTS.md.

Hierarchical like CLAUDE.md. You can place AGENTS.md files in subdirectories for monorepo support.

Future-proof. As new AI coding tools emerge, they are more likely to support AGENTS.md than any vendor-specific format.

Weaknesses

Newer, less established. The ecosystem of examples is smaller than .cursorrules, though it is growing rapidly.

Generic by necessity. Because it targets multiple tools, you cannot use tool-specific features. Claude Code has capabilities (like sub-agent delegation) that AGENTS.md does not address.

No tool-specific optimizations. Each AI tool interprets Markdown differently. What works perfectly for Claude Code may be less effective for Codex, and vice versa.

Best For

Open-source projects with diverse contributors using different AI tools. Teams that want a single source of truth. Projects that use multiple AI coding agents.

Head-to-Head Comparison

Compatibility

Features

Adoption by Major Projects

The largest projects tend to use the format that matches their contributor base:

• JavaScript/TypeScript ecosystem: Split between CLAUDE.md and AGENTS.md. Next.js uses CLAUDE.md, n8n uses AGENTS.md.
• Go ecosystem: Strongly AGENTS.md. awesome-go, Grafana, and CockroachDB all use it.
• Rust ecosystem: Mixed. Deno uses CLAUDE.md, llama.cpp uses AGENTS.md.
• Python ecosystem: Leans CLAUDE.md. LangChain and Browser Use both chose it.

Using Multiple Formats

Many teams maintain more than one format. This is practical when:

1. Your team uses both Cursor and Claude Code. Maintain .cursorrules for Cursor users and CLAUDE.md for Claude Code users.
2. You are an OSS project. Ship AGENTS.md for broad compatibility and CLAUDE.md for Claude-specific optimization.
3. You want a migration path. Start with your current tool’s format and add AGENTS.md as a universal baseline.

The key is to keep the files in sync. If your .cursorrules says “use Vitest” but your CLAUDE.md says “use Jest,” contributors will get inconsistent results.

A practical approach: maintain one canonical document (AGENTS.md) and generate tool-specific files from it, or keep a shared section that all files reference.

Migration Guide

From .cursorrules to CLAUDE.md

1. Copy your .cursorrules content into a new CLAUDE.md file.
2. Add Markdown headers to organize sections (Code Style, Architecture, Commands, etc.).
3. Add a project overview paragraph at the top.
4. Convert any Cursor-specific instructions to general ones.
5. Add code examples using Markdown code blocks.
6. Consider splitting monorepo rules into subdirectory CLAUDE.md files.

From CLAUDE.md to AGENTS.md

1. Copy your CLAUDE.md content into a new AGENTS.md file.
2. Remove any Claude-specific language (references to “Claude Code,” “Claude sessions,” etc.).
3. Replace Claude-specific features with generic agent instructions.
4. Add explicit sections for different agent roles if your project uses multi-agent workflows.

From .cursorrules to AGENTS.md

1. Copy your .cursorrules content into a new AGENTS.md file.
2. Add Markdown structure (headers, code blocks, lists).
3. Add a project overview section.
4. Remove any Cursor-specific references.
5. Test with at least two different AI tools to verify compatibility.

Our Recommendation

For most developers in 2026, this is the pragmatic approach:

1. Start with one format that matches your primary tool.
2. Add AGENTS.md when your team or contributors use multiple tools.
3. Keep files short and specific. A 200-line file that is maintained is better than an 800-line file that is outdated.
4. Review quarterly. AI tools evolve fast. What you wrote 3 months ago may need updating.

Browse our collections to see how real projects implement each format:

• CLAUDE.md rules — all Claude Code configurations
• .cursorrules rules — all Cursor configurations
• AGENTS.md rules — all AGENTS.md configurations
• Full rules gallery — everything, all formats