NAME
.cursor/rules/*.mdc — instruction file for Cursor
SYNOPSIS
.cursor/rules/
~/.cursor/rules/
METADATA
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.
Lower numbers load first. Higher-priority files override lower ones.
STRUCTURE
ANNOTATED EXAMPLE
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: patternYAML 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: trueYAML 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: stringYAML 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-nameChat 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
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.
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.
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.
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.
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.
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.