Cursor AI Rules: Complete Guide to .cursorrules & Custom Instructions

Category: AI Coding Difficulty: Intermediate Updated: 2026-05-28

Master Cursor AI rules with this complete .cursorrules guide. Learn to write custom rules for consistent code style, framework best practices, and project-specific conventions.

What are .cursorrules?

.cursorrules files define how Cursor's AI behaves in your project. Think of them as a permanent set of instructions that tell Cursor about your coding style, framework conventions, project structure, and quality standards. Every time the AI generates code, it follows these rules.

Basic Setup

Create a .cursorrules file in your project root. Cursor automatically detects and applies it. You can also create .cursorrules in subdirectories for folder-specific rules.

Template: React/Next.js Project

You are an expert React/Next.js developer.

Code style:
- Use functional components with TypeScript
- Prefer React Server Components by default
- Add 'use client' only when using hooks or browser APIs
- Use Tailwind CSS for styling (no CSS modules)
- Use Zod for runtime validation

File structure:
- Components in /components/
- API routes in /app/api/
- Shared types in /types/
- Utility functions in /lib/

Testing:
- Write tests with Vitest + React Testing Library
- Test behavior, not implementation

Template: Python/FastAPI Project

You are a senior Python developer.

Code style:
- Type hints required for all functions
- Use Pydantic for data validation
- Follow PEP 8 strictly
- Use async/await for I/O operations

Error handling:
- Custom exception classes for domain errors
- Always log with proper context
- Return structured error responses from APIs

Project structure:
- Models in /models/
- Routes in /api/
- Services in /services/
- Tests mirror source structure

Pro Tips