The Complete Guide to .cursorrules Files (2026)

A .cursorrules file is your secret weapon for getting better code out of Cursor AI. It tells the AI how to write code for your specific stack — frameworks, conventions, patterns, and preferences.

What is a .cursorrules File?

Placed in your project root, .cursorrules is a plain-text file that acts as a system prompt for Cursor's AI. It defines coding standards, framework conventions, and architectural patterns the AI should follow.

Without rules, Cursor writes generic code. With rules, it writes code that matches your project's exact style and conventions.

How .cursorrules Works

When you ask Cursor to generate or edit code, it reads your .cursorrules file and prepends it to the AI context. This guides every code suggestion toward your preferred patterns.

Writing Effective Rules

Follow these principles when writing .cursorrules:

• Be specific: Instead of "write good code," say "use async/await for all I/O operations" or "prerender React components with Next.js App Router."
• Cover your stack: Include rules for every framework and language in your project — React, TypeScript, Tailwind CSS, database ORM, testing library.
• Include constraints: Mention things like "never use any type," "prefer interfaces over types," or "use server components by default."
• Keep it concise: Cursor has limited context. Focus on the most impactful rules that define your coding style.

Framework-Specific Rules

The best .cursorrules are tailored to your framework. Here are examples for popular stacks:

React / Next.js

You are an expert React developer. Use functional components with hooks. Default to server components in Next.js App Router. Use 'use client' only when interactivity is needed. Co-locate styles and components.

Full React and Next.js rules available on our React rules page and Next.js rules page.

Python / Django

You are an expert Python developer. Write type-annotated code (Python 3.12+). Follow PEP 8. Use virtual environments. Write docstrings for public APIs. Use pytest for testing.

TypeScript / Node.js

You are an expert TypeScript developer. Enable strict mode. Prefer interfaces over types for object shapes. Avoid any — use unknown and type guards. Use discriminated unions for state.

Browse all 27 framework rule sets in our directory.

Advanced Techniques

Multi-Framework Rules

For full-stack projects, combine rules for all your frameworks. The AI understands context and applies the right rules for each file.

Project-Specific Conventions

Include your project's naming conventions, folder structure, and testing patterns. For example: "Components go in src/components/ui/, pages in src/app/[route]/."

Version-Specific Rules

Pin framework versions to avoid deprecated patterns. Example: "Use React 19 APIs and patterns. Avoid class components. Use the new hook APIs from React 19."

Pitfalls to Avoid

• Too vague: "Write good code" tells the AI nothing useful
• Too long: Keep rules under 500 characters per framework
• Contradictory rules: Don't say both "use hooks" and "use classes"
• Outdated patterns: Update rules when you upgrade frameworks