CURSORRULESMDC(5)CURSORRULESMDC(5)

NAME

.cursor/rules/*.mdc — instruction file for Cursor

SYNOPSIS

.cursor/rules/

~/.cursor/rules/

METADATA

FORMATMdc
FILENAME.cursor/rules/*.mdc
CASE SENSITIVENo
TOOLCursor
ENCODINGUTF-8
GIT COMMITTEDYes
MAX SIZE5KB per file
SINCECursor 0.45+ (late 2024)

DESCRIPTION

.cursor/rules/ is the modern rules system for Cursor, superseding the legacy .cursorrules file. Both .md and .mdc file extensions are supported. Each file combines optional YAML frontmatter metadata with Markdown rule content, enabling fine-grained, file-scoped AI instructions.

Cursor supports four rule activation modes: Always (included in every session via alwaysApply: true), Auto Attached (triggered when edited files match glob patterns), Agent Requested (the AI decides relevance based on the description field), and Manual (invoked explicitly via @rule-name in chat). Rules without frontmatter default to Always mode.

Rules follow a three-tier precedence: Team Rules (organizational, highest priority) > Project Rules (.cursor/rules/ in workspace) > User Rules (~/.cursor/rules/ global). Cursor also supports AGENTS.md as a simpler alternative for directory-scoped instructions, with root-level files applying globally and subdirectory files auto-scoping to their location.

Load Order
1~/.cursor/rules/(global)
2.cursor/rules/(project)

Lower numbers load first. Higher-priority files override lower ones.

STRUCTURE

├──YAML Frontmatter
Optional frontmatter block delimited by --- lines. Contains metadata fields: description (human-readable summary used for Agent Requested activation), globs (file patterns for Auto Attached activation), and alwaysApply (boolean for Always activation). Omitting frontmatter makes the rule an Always rule by default.
└──Rule BodyREQUIRED
The Markdown content after the frontmatter. Contains the actual instructions, coding conventions, or patterns for the AI to follow.

ANNOTATED EXAMPLE

.cursor/rules/*.mdc
mdc
1---
2description: React component conventions and patterns
3globs: "*.tsx"
4alwaysApply: false
5---
6
7# React Component Rules
8
9## Component Structure
10- Use functional components with explicit return types
11- Define props interface directly above the component
12- Export components as named exports, never default
13
14## Patterns
15- Use `useCallback` for event handlers passed to children
16- Prefer composition over prop drilling — use React context for
17  data needed by deeply nested components
18- Keep components under 150 lines; extract sub-components when larger
19
20## Styling
21- Use Tailwind CSS utility classes exclusively
22- No inline styles except for dynamic values (e.g., calculated widths)
23- Follow mobile-first responsive design: `base → sm → md → lg`
24
25---
26
27## Example: Agent Requested rule (.cursor/rules/security.mdc)
28
29```
30---
31description: Security review checklist for auth and data handling
32alwaysApply: false
33---
34
35# Security Conventions
36
37- Sanitize all user input before database queries
38- Use parameterized queries; never string concatenation for SQL
39- Validate JWT tokens on every protected route
40- Never log sensitive data (passwords, tokens, PII)
41```
42
43---
44
45## Example: Auto Attached rule (.cursor/rules/testing.mdc)
46
47```
48---
49description: Testing conventions for unit and integration tests
50globs: ["*.test.ts", "*.test.tsx", "*.spec.ts"]
51alwaysApply: false
52---
53
54# Testing Rules
55
56- Use Vitest as the test runner
57- Colocate test files next to source files
58- Use `describe` blocks organized by function/component name
59- Prefer `userEvent` over `fireEvent` in component tests
60- Mock external services; never hit real APIs in unit tests
61```

SPECIAL DIRECTIVES

globs: pattern
globs: pattern

YAML frontmatter field. A glob pattern (or array of patterns) specifying which files trigger this rule (Auto Attached mode). When Cursor operates on a file matching the pattern, this rule is automatically included in context. Examples: '*.tsx', 'src/api/**/*.ts', ['*.test.ts', '*.spec.ts'].

alwaysApply: true
alwaysApply: true

YAML frontmatter field. When set to true, this rule is included in every AI interaction regardless of which files are being edited (Always mode). Use sparingly for truly universal conventions.

description: string
description: string

YAML frontmatter field. A short human-readable description shown in Cursor's rule management UI. When no globs are set and alwaysApply is false, the AI uses the description to decide whether to include the rule (Agent Requested mode). Also serves as documentation.

@rule-name
@rule-name

Chat syntax. Reference a rule by name in chat to manually include it (Manual mode). Works for any rule file regardless of its frontmatter configuration.

COMMON MISTAKES

Gotchas
✗WRONG Putting all rules in a single large .mdc file
✓RIGHT Split rules into focused files: react.mdc, testing.mdc, api.mdc

The whole point of the new format is granular, file-scoped rules. A single monolithic file defeats the purpose. Create separate files so only relevant rules are loaded based on the files being edited.

✗WRONG Thinking only .mdc extension works
✓RIGHT Both .md and .mdc extensions are supported in .cursor/rules/

Cursor supports both .md and .mdc extensions in the rules directory. Use .mdc files with frontmatter to specify description and globs. Plain .md files work for simpler rules without scoping needs.

✗WRONG Using alwaysApply: true on every rule
✓RIGHT Use alwaysApply sparingly — prefer glob patterns for scoped inclusion

Rules with alwaysApply: true are injected into every request, consuming tokens even when irrelevant. Reserve this for truly universal conventions (formatting, git commit style). Use globs for everything else.

✗WRONG Ignoring the four activation modes
✓RIGHT Choose the right mode: Always, Auto Attached (globs), Agent Requested (description), or Manual (@mention)

Each rule should use the activation mode that best fits its purpose. Always for universal rules, Auto Attached for file-type-specific rules, Agent Requested for contextually relevant rules the AI can decide on, and Manual for rarely-used reference rules.

✗WRONG Assuming .cursorrules and .cursor/rules/ are merged
✓RIGHT If both exist, .cursor/rules/ takes precedence and .cursorrules is ignored

When migrating, you can keep both temporarily, but be aware that the new format completely replaces the legacy file. Remove .cursorrules once migration is complete to avoid confusion.

✗WRONG Not understanding rule precedence tiers
✓RIGHT Team Rules override Project Rules, which override User Rules

Cursor has three precedence tiers: Team Rules (highest, organizational standards), Project Rules (.cursor/rules/ in workspace, version-controlled), and User Rules (~/.cursor/rules/, personal preferences). Earlier sources override conflicts in later sources.

USED BY

SIMILAR FILES

.cursorrulesCursor Rules (Legacy)
CLAUDE.mdClaude Memory File
.windsurfrulesWindsurf Rules (Legacy)

COMPARISONS

agentconfig.ing2026-03-16CURSORRULESMDC(5)