The Complete Guide to .cursorrules

What Are Cursor Rules?

Cursor rules are persistent instructions that tell your AI coding assistant how to behave in your project. They act as guardrails — ensuring Cursor follows your coding conventions, uses your preferred libraries, and writes code that matches your team's style. Think of them as a "developer guide" that your AI actually follows.

Where Do Rules Live?

.cursor/rules/*.mdc

Project-level rules. The recommended approach in 2026. Files use Cursor's MDC format with frontmatter.

.cursorrules

Legacy root-level file. Still supported but .cursor/rules/ is preferred for better organization.

Cursor Settings → Rules

Global user rules that apply to every project. Good for personal coding preferences.

Best Practices for Writing Rules

Be specific and actionable

Say 'Use useState for local state, Zustand for global state' instead of 'Use appropriate state management'.

Focus on architecture, not syntax

Cursor already knows syntax. Tell it about YOUR project's patterns, folder structure, and naming conventions.

Keep rules concise

Each rule should be 1-3 sentences. Long paragraphs get diluted in the AI's context.

Include examples

Show a short code snippet of what good and bad code looks like in your project.

Organize by concern

Use separate rule files for different areas: architecture, testing, styling, API patterns.

Update regularly

Rules should evolve with your project. Review and update them quarterly.

Example: React + TypeScript Rules

---
description: React and TypeScript coding standards
globs: ["**/*.tsx", "**/*.ts"]
---

# React + TypeScript Rules

## Components
- Use functional components with TypeScript interfaces for props
- Name components with PascalCase, files with kebab-case
- Co-locate tests with components: Button.tsx → Button.test.tsx
- Use 'use client' only when the component needs interactivity

## State Management
- useState for local/component state
- Zustand for global client state
- Server components for server-fetched data
- Never use useEffect for data fetching — use server components or SWR

## Styling
- Use Tailwind CSS utility classes
- No inline styles
- Extract repeated patterns into cn() utility compositions
- Mobile-first responsive: sm: → md: → lg:

## TypeScript
- Define explicit return types on exported functions
- Use discriminated unions for complex state
- Never use 'any' — use 'unknown' plus type guards
- Prefer 'satisfies' over type assertions

Example: Python FastAPI Rules

---
description: Python FastAPI backend standards
globs: ["**/*.py"]
---

# Python FastAPI Rules

## API Design
- RESTful endpoints with plural nouns: /users, /orders
- Pydantic models for all request/response schemas
- Dependency injection for database sessions
- HTTPException for error responses with proper status codes

## Code Style
- Type hints on all function parameters and returns
- Async functions for I/O operations
- Use pathlib.Path instead of os.path
- f-strings for string formatting

## Testing
- Pytest with async fixtures
- Factory pattern for test data
- 80% minimum coverage target

Rules vs Skills: What's the Difference?

Feature	Cursor Rules	Agent Skills (SKILL.md)
When applied	Always active based on glob patterns	Agent decides when relevant
Format	.mdc files with frontmatter	SKILL.md with YAML frontmatter
Location	.cursor/rules/	.cursor/skills/
Purpose	Project conventions & standards	Specialized task expertise
Portability	Cursor-specific	Cross-tool (Cursor, Claude Code, etc.)