Cursor Rules Guide 2025: .cursorrules & Project Rules Setup

What Are Cursor Rules?

Cursor rules are persistent context injected into every AI interaction in your project. Without rules, Cursor's AI starts fresh each conversation — it doesn't know your tech stack, your coding conventions, or what patterns you prefer. Rules fix this by giving the AI a stable base of project-specific knowledge.

Good rules dramatically reduce the back-and-forth needed to get useful suggestions. Instead of telling the AI "we use TypeScript with strict mode and zod for validation" in every chat, you write it once in a rule and it's always there.

See the full Cursor guide for a complete overview of the IDE. This guide focuses specifically on the rules system.

Legacy: The .cursorrules File

The original format is a single .cursorrules file at the root of your project. It's plain markdown and applies to all AI interactions:

# Project: My SaaS App

## Tech Stack
- Framework: Next.js 15 (App Router)
- Language: TypeScript (strict mode)
- Styling: Tailwind CSS
- DB: PostgreSQL via Drizzle ORM
- Auth: Clerk
- Validation: Zod

## Coding Standards
- Always use TypeScript — no plain JS files
- Prefer server components; use 'use client' only when needed
- Use Zod for all API input validation
- Named exports only — no default exports
- Use early returns instead of nested if/else

## Anti-patterns
- Do NOT use any (use unknown and narrow)
- Do NOT use useEffect for data fetching (use server components)
- Do NOT commit secrets or .env values

The .cursorrules format still works in 2025 but Cursor now recommends migrating to Project Rules for more control.

New Format: Project Rules (.cursor/rules/*.mdc)

Project Rules (introduced in Cursor 0.43) use .mdc files in a .cursor/rules/ directory. Each file is a separate rule with a YAML frontmatter header that controls when it applies.

---
description: React component conventions for this project
globs: ["src/components/**/*.tsx", "src/app/**/*.tsx"]
alwaysApply: false
---

# React Component Rules

- Use functional components with TypeScript interfaces for props
- Place prop interface directly above the component function
- Use 'use client' directive only for interactive components
- Extract complex logic into custom hooks in src/hooks/
- Component files: PascalCase (UserCard.tsx, not user-card.tsx)

Create rules via Cursor Settings > Rules > New Rule, or manually create files in .cursor/rules/.

The Four Rule Types

Writing Effective Rules

The best Cursor rules are specific, actionable, and avoid vague adjectives. Compare:

Write clean, readable code
following best practices.

Functions must be under 40 lines.
Extract helper functions rather
than nesting more than 2 levels.
Use descriptive names — no
single-letter variables except
loop indices.

Key principles:

• State your tech stack explicitly (framework, version, key libraries)
• List anti-patterns explicitly — "do NOT use X" is more effective than "prefer Y"
• Include example code snippets for complex conventions
• Keep each rule file focused on one concern (don't put everything in one file)

Example Rules for Common Stacks

---
globs: ["**/*.py"]
alwaysApply: false
---

# Python / FastAPI Conventions

- Python 3.11+ type hints everywhere
- Use Pydantic v2 for request/response models
- Async functions for all route handlers
- HTTPException with status codes (not plain ValueError)
- Dependency injection via Depends() for DB sessions and auth
- No print() — use logging.getLogger(__name__)
- Tests: pytest + pytest-asyncio, fixtures in conftest.py

Find more examples at cursor.directory — a community-maintained collection of rules organized by framework and language.

Global User Rules

Global rules (Cursor > Settings > Rules) apply across every project. Use them for preferences that transcend individual codebases: your preferred explanation style, language for comments, preferred test framework, or accessibility requirements.

- Explain changes before making them
- Use concise, direct language — skip filler phrases
- Default test framework: Vitest for JS/TS, pytest for Python
- Always add JSDoc to exported functions
- Prefer immutable patterns (const, Object.freeze, readonly)

Project rules combine with global rules — the AI sees both. Project rules take precedence when there's a conflict.

Cursor Rules vs Copilot Custom Instructions vs CLAUDE.md

Also see: Cursor vs GitHub Copilot · Cursor vs Windsurf · Claude Code guide