Cursor Project Rules

Project Rules vs. User Rules

Cursor distinguishes between two scopes of rules: Project Rules (stored in your repository at .cursor/rules/) and User Rules (stored in your Cursor settings). Project rules travel with your codebase — every team member gets the same AI behavior. User rules are personal preferences that only affect your local Cursor instance.

The .cursor/rules Directory Structure

Project rules live in .cursor/rules/ as .mdc files. Each file is a self-contained rule with frontmatter metadata:

• globs — File patterns the rule applies to (e.g., **/*.tsx)
• alwaysApply — Whether the rule is always active or opt-in
• description — Human-readable summary of what the rule does

Example rule file structure:

---
globs: "**/*.tsx"
alwaysApply: true
description: "React component conventions"
---
Always use functional components with TypeScript interfaces.
Prefer named exports over default exports.
Use the 'use client' directive only when necessary.

Recommended .cursor/rules Layout

A practical rules directory groups instructions by domain. This makes each file easier to review, update, and target with globs:

.cursor/rules/
  code-style.mdc
  frontend-components.mdc
  api-routes.mdc
  database-prisma.mdc
  testing-standards.mdc
  docs-and-readme.mdc

Keep global standards in one always-applied file, then use file-specific rules for frontend, backend, database, tests, and documentation.

Common Project Rule Patterns

Framework-Specific Rules

Target Next.js components with glob **/*.tsx and specify conventions: server components by default, proper metadata exports, and App Router patterns.

Testing Rules

Target test files with glob **/*.test.* and enforce testing patterns: describe/it blocks, AAA pattern, and specific assertion library preferences.

Documentation Rules

Target documentation files with glob **/*.md and enforce standards: required sections, heading hierarchy, and code example formatting.

Choosing the Right Application Mode

• Always Apply for repository-wide rules Cursor should always know.
• Intelligent when the rule should be available but not forced into every interaction.
• File Specific when globs define exactly where a rule belongs.
• Manual for specialized rules you invoke only when needed.

Migration from .cursorrules to Project Rules

If you're currently using the legacy .cursorrules file, migrating to the directory-based approach gives you per-file targeting and better organization. Split your single file into multiple .mdc files, each focused on a specific concern.

Our Cursor Rules Generator can help you create properly formatted project rules. Read What Are Cursor Rules for conceptual background, or browse templates for ready-to-use rule sets.

Frequently Asked Questions

Where do Cursor Project Rules go?

Cursor Project Rules live under the .cursor/rules/ directory as .mdc files that can include frontmatter metadata and markdown instructions.

How many Project Rules files should a repo have?

Use one file per concern, such as frontend components, backend services, testing, documentation, or security. Small projects may only need two or three.

When should alwaysApply be true?

Use alwaysApply for universal rules like security boundaries, response style, or repository-wide testing expectations. Use globs for domain-specific rules.