.cursorrules vs CLAUDE.md vs Copilot Instructions: 2026 Comparison

Every major AI coding assistant reads a different file to understand your project. The concept is identical — a Markdown document that tells the AI how your codebase works — but the file names, locations, formats, and advanced features differ significantly between tools.

This guide covers each format in depth so you can make an informed decision, with a clear decision framework at the end.

1. Cursor: .cursor/rules/

Cursor was one of the first AI-native editors to popularize persistent project rules. Its format became the de facto standard that other tools later followed.

The .cursorrules file (legacy format)

The original single-file format placed at the project root. While still supported, Cursor now recommends the .cursor/rules/ directory instead.

codeCopy
my-project/
└── .cursorrules    ← Legacy — still read automatically

The .cursor/rules/ directory (modern format)

Cursor's modern rules system uses multiple scoped rule files. Both .md and .mdc extensions are supported:

codeCopy
.cursor/
  rules/
    base.mdc        # alwaysApply: true — injected into every call
    react.mdc       # Applied only when editing .tsx/.jsx files
    api.mdc         # Applied only when editing files in /api/
    testing.mdc     # Applied only when editing *.test.ts files

Each file uses YAML frontmatter to control when it's injected:

markdownCopy
---
description: React component conventions
globs: "**/*.tsx"
alwaysApply: false
---

# React Component Rules
- Use functional components with hooks
- Named exports only — no default exports
- Props typed as {ComponentName}Props interfaces

Rule activation types

The frontmatter controls four activation modes:

• Always Apply (alwaysApply: true) — injected into every chat session
• Apply Intelligently — Cursor's agent decides relevance based on the description field
• Apply to Specific Files — activates when file matches globs pattern
• Apply Manually — only loaded when you @-mention the rule in chat

Rules should be kept under 500 lines. Reference files with @filename.ts rather than copying content.

Rule precedence

Cursor follows this priority: Team Rules > Project Rules > User Rules. User Rules apply globally across all projects but only in Agent/Chat mode, not inline autocomplete.

Cursor at a glance:

• Auto-loaded: always
• Multi-file scoping: yes, via .cursor/rules/
• User-level rules: yes (Agent/Chat only)
• Glob scoping: yes — via frontmatter
• Official docs: cursor.com/docs/rules

2. Claude Code: CLAUDE.md

Claude Code is Anthropic's terminal-based agentic coding tool. Its CLAUDE.md file is the project memory system Claude reads before every session.

File hierarchy

Claude Code reads rules from multiple locations and merges them, with more specific locations taking precedence:

Claude walks up the directory tree from your current working directory, loading CLAUDE.md files from each directory along the way. Sub-directory CLAUDE.md files load on demand when Claude reads files in those directories.

Path-scoped rules with .claude/rules/

For larger projects, the .claude/rules/ directory enables modular, file-scoped rules — similar to Cursor's MDC system:

codeCopy
.claude/
  rules/
    code-style.md    # Loaded always (no paths frontmatter)
    testing.md       # Loaded always
    api-design.md    # Scoped to API files

Rules can be scoped to specific files using paths YAML frontmatter:

markdownCopy
---
paths:
  - "src/api/**/*.ts"
---

# API Development Rules
- All API endpoints must include input validation
- Use the standard error response format

User-level rules in ~/.claude/rules/ apply to every project on your machine.

Import references

CLAUDE.md supports importing other files using @path syntax:

markdownCopy
# CLAUDE.md

See @docs/architecture.md for system overview.
API conventions: @docs/api-conventions.md

Both relative and absolute paths work. Imported files can recursively import others (up to five hops deep).

Memory system

Claude Code has two memory mechanisms:

• CLAUDE.md files — instructions you write manually
• Auto memory — notes Claude writes itself based on your corrections and preferences, stored in ~/.claude/projects/<project>/memory/

The /memory command lists all loaded CLAUDE.md and rules files, lets you toggle auto memory, and opens files for editing. When you ask Claude to "remember" something conversationally, it saves to auto memory automatically.

CLAUDE.md at a glance:

• Auto-loaded: always (CLI)
• Multi-file: yes — .claude/rules/, @path imports, sub-directory files
• Glob scoping: yes — paths frontmatter in .claude/rules/
• User-level rules: yes — ~/.claude/CLAUDE.md and ~/.claude/rules/
• Official docs: code.claude.com/docs/en/memory

3. GitHub Copilot: .github/copilot-instructions.md

GitHub Copilot is the most widely adopted AI coding assistant, with deep integration across VS Code, JetBrains, Visual Studio, Xcode, and GitHub.com.

File location

codeCopy
my-project/
└── .github/
    └── copilot-instructions.md

Scope: Chat, code review, and coding agent

Copilot's custom instructions apply to Copilot Chat, code review, and the coding agent — but not inline autocomplete ghost text. Support varies by IDE:

• VS Code: Chat, code review, coding agent
• JetBrains: Chat, coding agent
• Visual Studio: Chat, code review
• GitHub.com: Chat, code review, coding agent

Path-specific instructions

Copilot supports scoped rules via .github/instructions/ with glob frontmatter:

codeCopy
.github/
  copilot-instructions.md           # Repository-wide
  instructions/
    react-components.instructions.md  # Scoped to .tsx files
    api-routes.instructions.md        # Scoped to API files

Each instruction file uses YAML frontmatter with glob patterns:

markdownCopy
---
applyTo: "**/*.tsx,**/*.jsx"
---
Use functional components with hooks. Named exports only.

When both repository-wide and path-specific files match, instructions from both are combined.

Instruction priority

Personal instructions > Repository instructions > Organization instructions. Personal instructions are set in your IDE settings and take highest priority.

Copilot at a glance:

• Auto-loaded: Chat, code review, coding agent (not autocomplete)
• Multi-file: yes — .github/instructions/ with glob scoping
• User-level rules: yes — personal instructions in IDE settings
• Official docs: docs.github.com/copilot/customizing-copilot

4. Windsurf: .windsurf/rules/

Windsurf (formerly Codeium Windsurf) is a Cursor competitor that has evolved to support a full rules directory system.

File structure

Windsurf discovers rules from .windsurf/rules/ directories in the current workspace and parent directories up to the git root:

codeCopy
my-project/
└── .windsurf/
    └── rules/
        ├── code-style.md
        ├── testing.md
        └── api-design.md

The legacy .windsurfrules single-file format is still supported for backward compatibility.

Global and workspace rules

• Workspace rules: stored in .windsurf/rules/, limited to 12,000 characters per file
• Global rules: apply to all projects, limited to 6,000 characters

Format rules using bullet points, numbered lists, and Markdown. XML tags can be used to group related rules.

Windsurf also has Cascade Memories — AI-generated session notes stored locally per user, not version-controlled.

Windsurf at a glance:

• Auto-loaded: always
• Multi-file: yes — .windsurf/rules/ directory
• User-level rules: yes — global rules
• Official docs: docs.windsurf.com

5. Cline: .clinerules/

Cline is an open-source autonomous coding agent that runs as a VS Code extension. It can create and edit files, run terminal commands, and browse the web.

File structure

Cline uses a .clinerules/ directory at the project root. It processes all .md and .txt files inside, combining them into a unified rule set:

codeCopy
my-project/
└── .clinerules/
    ├── coding.md         # Coding standards
    ├── testing.md        # Test requirements
    └── architecture.md   # Structural decisions

Numeric prefixes (like 01-coding.md) help organize files but are optional.

Conditional rules with path matching

Rules can be scoped to specific files using paths YAML frontmatter:

markdownCopy
---
paths:
  - "src/api/**/*.ts"
---
# API Rules
- Validate all request bodies with Zod
- Return standardized error responses

Global vs workspace rules

Global rules live in your system's Cline Rules directory and apply across all projects. Workspace rules take precedence when they conflict with global rules.

What makes Cline different

Cline is highly agentic — it operates in a loop, reading files, executing commands, and editing code until a task is complete. Your rules should include not just code conventions but also guidance on permitted commands and error handling.

Cline at a glance:

• Auto-loaded: always
• Multi-file: yes — .clinerules/ directory
• Path scoping: yes — paths frontmatter
• User-level rules: yes — global rules directory
• Official docs: docs.cline.bot/customization/cline-rules

6. OpenAI Codex: AGENTS.md

OpenAI Codex is OpenAI's coding agent that can write and run code and handle multi-step programming tasks. It reads AGENTS.md as its primary project context file.

File hierarchy

Codex builds an instruction chain with a strict precedence order:

1. Global scope (~/.codex/AGENTS.md or AGENTS.override.md) — personal defaults for all projects
2. Project scope — walks from git root toward working directory, taking one file per directory
3. Files concatenate root-downward, with closer files overriding earlier guidance

codeCopy
~/.codex/
  AGENTS.md              # Global defaults

my-project/
  AGENTS.md              # Project-level
  src/
    AGENTS.md            # Directory-level specialization

Override files

AGENTS.override.md temporarily replaces base guidance without deleting it — useful for experiments or temporary constraints.

Size and configuration

Keep AGENTS.md around 100 lines. Combined files are capped at 32 KiB by default (configurable via project_doc_max_bytes in ~/.codex/config.toml).

Codex at a glance:

• Auto-loaded: always
• Multi-file: yes — directory hierarchy from root to CWD
• User-level rules: yes — ~/.codex/AGENTS.md
• Override support: yes — AGENTS.override.md
• Official docs: developers.openai.com/codex/guides/agents-md

7. Google Antigravity: .agent/rules/rules.md

Google Antigravity is Google's AI coding agent. Its rules file lives in a dedicated .agent/rules/ directory, making it straightforward to keep separate from other configuration.

File location

codeCopy
my-project/
└── .agent/
    └── rules/
        └── rules.md

The file is standard Markdown and follows the same conventions as other rules files — tech stack, coding conventions, and project-specific constraints.

Antigravity at a glance:

• Auto-loaded: always
• Multi-file: no (single file in .agent/rules/)
• User-level rules: no
• Official docs: —

8. Gemini CLI: GEMINI.md

Gemini CLI is Google's open-source command-line coding agent powered by the Gemini model family. It uses a hierarchical context system similar to Claude Code.

File hierarchy

Gemini CLI loads context from three tiers:

1. Global: ~/.gemini/GEMINI.md — personal preferences for all projects
2. Workspace: GEMINI.md in the project root and parent directories
3. Just-in-time: when tools access files, the CLI auto-discovers GEMINI.md files in those directories and ancestors

All discovered files are concatenated and sent with every prompt.

Import support

Large context files can be modularized using @file.md import syntax, supporting both relative and absolute paths:

markdownCopy
# GEMINI.md
Project overview: @docs/architecture.md
API conventions: @docs/api-conventions.md

Memory commands

The /memory command provides: show (displays concatenated context), reload (rescans all locations), and add (appends to ~/.gemini/GEMINI.md).

The default filename can be customized via settings.json using the context.fileName property.

Gemini CLI at a glance:

• Auto-loaded: always
• Multi-file: yes — @file.md imports and directory hierarchy
• User-level rules: yes — ~/.gemini/GEMINI.md
• Official docs: github.com/google-gemini/gemini-cli

Feature Comparison

Decision Framework

Choose Cursor (.cursor/rules/) if:

• Cursor is your primary editor
• You need glob-scoped rules with intelligent activation modes
• You're on a large project where rule file organization matters

Choose Claude Code (CLAUDE.md) if:

• Claude Code CLI is your primary AI tool
• You want the richest hierarchy: org, project, user, and local scopes
• You need file imports and path-scoped rules via .claude/rules/

Choose Copilot (copilot-instructions.md) if:

• Your team standardizes on GitHub Copilot
• You need rules for Chat, code review, and the coding agent
• You want path-specific instructions via .github/instructions/

Choose Windsurf (.windsurf/rules/) if:

• Windsurf is your primary editor
• You want a multi-file rules directory with global support

Choose Cline (.clinerules/) if:

• You use Cline as your primary agentic VS Code extension
• You need path-scoped conditional rules with global defaults

Choose Codex (AGENTS.md) if:

• OpenAI Codex is your primary coding agent
• You need a directory hierarchy with override files

Choose Gemini CLI (GEMINI.md) if:

• Gemini CLI is your primary terminal-based coding agent
• You want import support and a three-tier context hierarchy

Maintain all formats if:

• Your team uses multiple AI tools (increasingly common in 2026)
• Use the Agent Rules Builder to generate once, export to all formats instantly

Keeping Multiple Formats in Sync

For teams using two or more AI tools, the key is a single source of truth. Options:

Option A — Use the Agent Rules Builder: Author your rules in the builder, then export to each format at once. Regenerate whenever conventions change.

Option B — Pre-commit hook:

bashCopy
#!/bin/sh
# .git/hooks/pre-commit — sync rules to all formats
SOURCE="docs/ai-rules-base.md"
cp "$SOURCE" .cursorrules
cp "$SOURCE" CLAUDE.md
cp "$SOURCE" .windsurfrules
cp "$SOURCE" .github/copilot-instructions.md
mkdir -p .clinerules && cp "$SOURCE" .clinerules/base.md
cp "$SOURCE" AGENTS.md
cp "$SOURCE" GEMINI.md
mkdir -p .agent/rules && cp "$SOURCE" .agent/rules/rules.md
git add .cursorrules CLAUDE.md .windsurfrules .github/copilot-instructions.md \
  .clinerules/base.md AGENTS.md GEMINI.md .agent/rules/rules.md

Option C — Accept controlled divergence: In practice, 90%+ of the content is identical across formats. Tool-specific additions (like Cursor's MDC frontmatter, CLAUDE.md's @path imports, or Codex override files) can live only in the relevant file.