Cursor Rules — The Complete Guide (2026)

What Are Cursor Rules?

Cursor rules are instruction files that tell Cursor’s Agent how to behave in your specific project. They’re the bridge between a generic coding assistant and one that understands your stack, conventions, and preferences.

Cursor supports four rule types per the official rules docs:

Rule type	Where it lives	Scope
Project Rules	.cursor/rules/*.mdc (version-controlled)	Per-repository
User Rules	Cursor settings	Global to your Cursor environment
Team Rules	Cursor dashboard (Team / Enterprise plans)	Org-wide, can be enforced
AGENTS.md	Project root (and nested subdirectories)	Plain-markdown alternative

Rules load at the start of the model context, so every Agent chat, edit, and inline command respects them.

Why Cursor Rules Matter

Without rules, Cursor generates code based on general patterns from its training data. This leads to:

• Wrong framework versions (React class components instead of hooks)
• Mismatched conventions (semicolons when you use none)
• Missing project patterns (not using your custom hooks, utilities, or types)
• Redundant imports or wrong libraries

With good rules, Cursor behaves like a team member who has read your entire codebase and style guide.

How to Create Cursor Rules

Method 1: Project Rules in .cursor/rules/*.mdc

Project rules are markdown files with frontmatter. The .mdc extension is required — a plain .md in .cursor/rules is ignored because it lacks the metadata Cursor needs to decide when to apply it. If you prefer plain markdown, use AGENTS.md instead.

.cursor/
  rules/
    react-patterns.mdc       # Recognized as a project rule
    api-guidelines.md        # Ignored — wrong extension
    frontend/                # Folders are fine
      components.mdc

Frontmatter fields

The three frontmatter fields interact to decide when each rule is included:

alwaysApply	description	globs	Behavior
true	—	—	Always included. Globs and description ignored.
false	—	provided	Auto-attached when a matching file is in context.
false	provided	omitted	Agent reads the description and pulls the rule in when relevant.
false	omitted	omitted	Included only when you @-mention the rule in chat.

Example: always applied

---
alwaysApply: true
---

- All source files must include the company copyright header
- When you are unsure about implementation details, read the relevant source files before proposing changes
- Never modify generated files in the `dist/` or `build/` directories

Example: auto-attached by file pattern

---
globs: src/components/**/*.tsx
alwaysApply: false
---

- Use named exports, not default exports
- Co-locate styles in a module CSS file next to the component
- Keep components under 200 lines. Extract subcomponents into the same directory when a file grows beyond that

Example: Agent-selected by description

---
description: RPC service conventions and patterns for the backend
alwaysApply: false
---

- Define each service in its own file under `src/services/`
- Always validate inputs at the service boundary before passing data to internal functions
- Return structured error objects with a `code` and `message` field, never throw raw strings

Method 2: AGENTS.md (Plain Markdown)

AGENTS.md is a simple markdown file in your project root. Unlike .mdc files, it has no frontmatter and no globs — just instructions. Cursor also picks up nested AGENTS.md files in subdirectories, with the most specific one taking precedence.

# Project Instructions

## Code Style
- Use TypeScript for all new files
- Prefer functional components in React
- Use snake_case for database columns

## Architecture
- Follow the repository pattern
- Keep business logic in service layers

Use AGENTS.md when you want readable, no-config instructions. Use .cursor/rules/*.mdc when you want scoped, auto-attached rules.

Method 3: User Rules (Global Preferences)

Define once in Customize → Rules. Used by Agent only — they do not affect Cursor Tab or inline edit.

Method 4: Team Rules

Team and Enterprise plans can publish rules from the Cursor dashboard that apply to every repo in the org. Admins can mark rules as enforced so members can’t disable them. Precedence: Team Rules → Project Rules → User Rules.

Glob Pattern Examples

Use globs to scope a rule to specific files. Separate multiple patterns with commas.

Pattern	Matches
*	Any single file name segment
**	Any number of directories (recursive)
*.ts	All .ts files in the root
src/**/*.tsx	All .tsx files anywhere under src/
docs/**/*.md, docs/**/*.mdx	Markdown files under docs/ (comma-separated)

Best Practices

Per the Cursor rules docs:

• Keep rules under 500 lines
• Split large rules into multiple composable rules
• Provide concrete examples or referenced files (use @filename.ts to include a file in a rule’s context)
• Avoid vague guidance. Write rules like clear internal docs
• Reference files instead of copying their contents — keeps rules short and prevents staleness
• Start simple. Add rules only when you notice Agent making the same mistake repeatedly

What to avoid

• Copying entire style guides: use a linter instead — Agent already knows common style conventions
• Documenting every possible command: Agent knows npm, git, pytest, etc.
• Adding edge-case instructions that rarely apply: keep rules focused on frequent patterns
• Duplicating what’s already in your codebase: point to canonical examples instead of copying code

Ready-to-Use Rule Files

Browse our library of framework-specific Cursor rules:

JavaScript / TypeScript

• React TypeScript Cursor Rules
• Next.js Cursor Rules
• Astro Cursor Rules
• Svelte Cursor Rules
• Vue Cursor Rules

Python

• Python Claude Rules
• CLAUDE.md for Python

Other Languages

• Go Cursor Rules
• Rust Cursor Rules

CLAUDE.md Files (for Claude Code)

• CLAUDE.md for TypeScript
• CLAUDE.md for Next.js
• CLAUDE.md for Python

Cursor Rules vs CLAUDE.md vs AGENTS.md

Feature	.cursor/rules/*.mdc	CLAUDE.md	AGENTS.md
Tool	Cursor	Claude Code	Cursor, Claude Code, and most agent harnesses
Format	Markdown with frontmatter	Plain Markdown	Plain Markdown
Scoping	globs / description / alwaysApply	Project root + nested directories	Project root + nested directories
Nesting	Folders under .cursor/rules/	Hierarchical	Hierarchical
Plain markdown?	No — .mdc extension required	Yes	Yes

If you maintain both a Cursor workflow and a Claude Code workflow, write rules in plain Markdown under AGENTS.md and reference them from each tool’s project files.

Related Resources

• Context Engineering Guide — The meta-skill behind good rules
• Cursor Tool Page — Full Cursor overview
• Vibe Coding Guide — The methodology these rules enable
• Cursor vs Copilot — Compare AI coding tools
• Official Cursor Rules docs — The source of truth