.cursorrules Guide

What are .cursorrules Files?

.cursorrules is a configuration file that provides custom instructions to Cursor AI, the popular AI-powered code editor built on VS Code. It helps Cursor understand your project's conventions, coding style, and specific requirements to generate more consistent and relevant code suggestions.

Cursor Rules provide a powerful way to give consistent, reusable instructions to Cursor's AI features, including the Agent, Cmd-K, Tab completion, and Chat. They help the AI adhere to your coding style and automate workflows.

Where to Place .cursorrules

Cursor supports multiple levels of rules:

• Project root — Place .cursorrules in your project root for project-wide rules
• Project Rules folder — Store .mdc files in .cursor/rules/ for advanced configurations
• User settings — Set global rules via Cursor Settings → General → Rules for AI

Rule Activation Modes

Cursor supports different modes for when rules are applied:

• Always Apply — Rules loaded into every conversation
• Manual — Activate via @mention in Cursor's input
• Model Decision — AI decides based on natural language description
• Glob — Applied to files matching patterns (e.g., *.tsx)

.cursorrules File Format

The .cursorrules file uses plain text or markdown format. Here's a recommended structure:

# Project: E-commerce Platform

## Tech Stack
- React 18 with TypeScript
- Next.js 14 App Router
- Tailwind CSS + shadcn/ui
- Zustand for state management
- React Query for data fetching

## Code Style
- Use functional components only
- Prefer named exports
- Use TypeScript strict mode
- No 'any' types allowed
- Use async/await over .then()

## Component Guidelines
- Keep components under 150 lines
- Extract hooks into /hooks folder
- Use composition over inheritance
- Colocate styles with components

## File Naming
- Components: PascalCase.tsx
- Hooks: use-kebab-case.ts
- Utils: kebab-case.ts
- Types: types.ts in each feature folder

## Testing
- Write tests for business logic
- Use React Testing Library
- Mock external dependencies
- Aim for 80% coverage on critical paths

## Do NOT
- Use class components
- Use inline styles (use Tailwind)
- Create files over 300 lines
- Use default exports for components

Writing Effective Cursor Rules

Keep Rules Concise

Write focused, composable rules under 500 lines. Reuse rule blocks instead of duplicating prompts. Give rules concrete names and descriptions.

Use a Direct Tone

Write rules in a short, direct, instructive style with no fluff. When rules run in Always Apply mode, they're loaded into every conversation, so clarity matters.

Include Real Examples

Be explicit about SDK versions to prevent outdated code. Include real-world examples that demonstrate complete implementations, not just isolated snippets.

Address Edge Cases

Include examples of handling edge cases like error handling, retries, and idempotency. This results in more robust generated code.

.cursorrules Examples by Framework

React/Next.js

# Next.js App Router Project

You are an expert in TypeScript, React 18, and Next.js 14 App Router.

## Key Principles
- Write concise, technical code with accurate TypeScript types
- Use functional and declarative programming patterns
- Prefer iteration and modularization over duplication
- Use descriptive variable names with auxiliary verbs

## Next.js Specifics
- Use Server Components by default
- Add "use client" only when client-side interactivity is needed
- Use Next.js Image component for all images
- Implement proper loading and error states

## Code Style
- Use Tailwind CSS for styling
- Use shadcn/ui for UI components
- Prefer const over let
- Use template literals for string interpolation

Python/FastAPI

# FastAPI Backend Rules

You are an expert in Python, FastAPI, and scalable API design.

## Code Style
- Use Python 3.11+ features
- Use type hints everywhere
- Use Pydantic v2 for validation
- Follow PEP 8 guidelines

## API Design
- Use RESTful conventions
- Return proper HTTP status codes
- Use dependency injection
- Implement proper error handling

## Database
- Use SQLAlchemy 2.0 with async
- Write migrations with Alembic
- Use repository pattern for data access

## Testing
- Use pytest with fixtures
- Mock external dependencies
- Test edge cases and error paths

.cursorrules vs Other AI Config Files

Each AI coding tool uses its own configuration format. See our complete comparison guide for detailed differences.

Related Guides

Frequently Asked Questions

Manage Your .cursorrules Files Visually

ClaudeMDEditor lets you browse, edit, and organize .cursorrules files across all your projects. Plus it handles CLAUDE.md, copilot-instructions.md, and more.

One-time purchase for macOS Tahoe (26+)