Cursor Rules: The Complete Guide to .cursorrules and AI Coding Rules

Cursor rules are the single most impactful way to customize how Cursor's AI assistant writes code for your projects. A well-written .cursorrules file transforms Cursor from a generic coding assistant into one that understands your stack, follows your conventions, and produces code that looks like your team wrote it.

This guide covers everything about cursor rules -- syntax, framework-specific examples, and how to convert rules between AI editors like Claude Code, GitHub Copilot, and Windsurf.

What Are Cursor Rules?

Cursor rules are plain-text instructions that act as a system prompt for Cursor's AI. When you open a project containing a .cursorrules file, Cursor reads it and applies those instructions to every AI interaction -- code generation, chat, inline edits, and auto-completions.

Think of cursor rules as onboarding documentation for an AI pair programmer. They tell the AI:

• What your project does -- tech stack, architecture, key directories
• How you write code -- naming conventions, patterns, formatting preferences
• What to avoid -- deprecated APIs, anti-patterns, known pitfalls
• How to behave -- response style, level of detail, when to ask questions

How Cursor Rules Work: Global vs Project-Level

Cursor supports three layers of cursor AI rules, each with different scope:

1. Global rules (Settings)

Set via Cursor Settings > General > Rules for AI. These apply to every project on your machine -- personal preferences like "always use TypeScript strict mode" or "prefer functional components."

2. Project rules (.cursorrules file)

A .cursorrules file at the root of your repository. This is the most common approach. It is version-controlled and shared with your team.

3. Directory rules (.cursor/rules/)

A .cursor/rules/ directory containing multiple .mdc rule files. Each file can specify glob patterns to control when it activates -- different rules for frontend vs. backend, for example.

.cursor/
  rules/
    frontend.mdc     # Active for src/components/**
    backend.mdc      # Active for api/**
    testing.mdc      # Active for **/*.test.*
    general.mdc      # Always active

When rules conflict, project-level rules override global, and directory-specific rules override project-level. This layered approach keeps your .cursorrules file lean.

.cursorrules Syntax and Structure

The .cursorrules file uses plain text -- no special syntax, no YAML, no configuration format. Write clear, direct instructions in natural language:

# Project: TaskFlow API

## Tech Stack
- Node.js 20 with TypeScript 5.3
- Express.js for HTTP, Prisma ORM with PostgreSQL
- Zod for validation, Vitest for testing

## Architecture
- src/routes/ - Express route handlers
- src/services/ - Business logic layer
- src/models/ - Prisma schema and generated types
- src/middleware/ - Auth, validation, error handling

## Code Conventions
- Use named exports, never default exports
- All async route handlers wrapped with asyncHandler()
- API responses follow: { data, error, meta }
- Prefer early returns over nested conditionals

## Testing
- Colocate tests: feature.ts -> feature.test.ts
- Integration tests use a test database, never mock Prisma

## Avoid
- Never use `any` type -- use `unknown` and narrow
- Never raw SQL -- always use Prisma query builder
- Don't catch errors silently -- always log or rethrow

10+ Example Cursor Rules by Framework

Practical cursor rules for popular tech stacks. Use these as starting points, or find polished versions in our skills library.

React / Next.js

- Use functional components with TypeScript interfaces for props
- Prefer server components; add "use client" only when needed
- Use Next.js App Router conventions (layout.tsx, page.tsx, loading.tsx)
- Style with Tailwind CSS utility classes, avoid custom CSS
- Data fetching: server components + fetch, no useEffect for data
- Forms: react-hook-form with zod validation
- Keep components under 150 lines; extract into smaller pieces

See our Next.js Developer skill or browse Frontend skills.

Python / FastAPI

- Python 3.12+ with type hints on all function signatures
- Pydantic v2 models for request/response validation
- Async endpoints by default; sync only for CPU-bound work
- Dependency injection for database sessions and auth
- Testing: pytest with httpx AsyncClient for endpoint tests
- Use ruff for linting and formatting (not black/flake8)

Also see our Python Developer and API Developer skills.

Go

- Standard Go project layout: cmd/, internal/, pkg/
- Use stdlib net/http or chi router, avoid heavy frameworks
- Always check errors, wrap with fmt.Errorf("context: %w", err)
- Interfaces for dependency injection, defined at consumer site
- Table-driven tests with testify for assertions
- No globals -- pass dependencies explicitly via structs

TypeScript / Node.js Backend

- Strict TypeScript: strict, noUncheckedIndexedAccess enabled
- ESM imports (import/export), not CommonJS (require)
- Zod for runtime validation of external data
- Custom error classes extending base AppError
- Structured JSON logging with pino
- Never use `any` -- use `unknown`, generics, or type narrowing

Rust

- Result<T, E> with thiserror for libraries, anyhow for apps
- Use clippy: #![warn(clippy::all, clippy::pedantic)]
- Async with tokio, prefer async fn over manual Future impl
- Use ? operator, avoid .unwrap() outside tests
- Derive Debug, Clone, PartialEq on all public structs
- /// doc comments on all public items

Vue.js

- Composition API with <script setup lang="ts">
- Pinia for state management, Vue Router with lazy-loading
- defineProps<{}>() and defineEmits<{}>() for type safety
- Extract reusable logic into use*.ts composables
- Scoped styles, PascalCase components, camelCase composables

Swift / iOS

- SwiftUI for all new views, UIKit only when required
- MVVM with ObservableObject view models
- async/await for all async work, not Combine for new code
- @MainActor for all UI-mutating code
- Add .accessibilityLabel on all interactive elements
- No force unwraps (!) outside tests and IBOutlets

DevOps / Terraform

- Terraform modules for reusable components
- Always include description on variables and outputs
- Docker: multi-stage builds, non-root user, .dockerignore
- Secrets: never hardcode; use environment variables or vault
- Naming: {project}-{environment}-{resource} convention
- Remote state in S3 with DynamoDB locking

Accessibility

- All images: meaningful alt text (not "image of...")
- Color contrast: WCAG AA minimum (4.5:1 text, 3:1 large)
- Every input needs a visible, associated label
- All functionality accessible via keyboard
- Semantic HTML first, ARIA only when HTML is insufficient
- Respect prefers-reduced-motion media query

Based on our Accessibility Expert skill. Find more in categories including Backend, DevOps, and Testing.

Cursor Rules vs Other AI Editor Formats

Every major AI coding tool has its own rules format. The good news: they are all plain-text system prompts under the hood.

Converting between formats

Since cursor rules, CLAUDE.md, and copilot-instructions.md are all plain-text system prompts, conversion is straightforward. The core instructions stay identical -- you only change the filename and remove tool-specific features.

Cursor rules to CLAUDE.md: Copy .cursorrules into CLAUDE.md. Add build commands and consider hooks for enforcement. CLAUDE.md to cursor rules: Copy content, remove Claude-specific features (hooks, slash commands). Keep all conventions as-is.

For a deeper comparison, see our Claude Code vs Cursor guide.

Advanced .cursor/rules/ Directory

For larger projects, .mdc files in .cursor/rules/ give fine-grained control:

---
description: Rules for React component development
globs: src/components/**/*.tsx, src/components/**/*.ts
alwaysApply: false
---

# React Component Rules
- Use functional components with TypeScript
- Props interface named {ComponentName}Props
- Keep components under 150 lines
- Use Suspense boundaries for async components

The frontmatter controls when rules activate: globs specifies file patterns, and alwaysApply: true makes rules active regardless of context. This is ideal for monorepos where different directories use different stacks.

Cursor Rules vs MCP Servers

Cursor rules and MCP servers solve different problems and work best together:

Most projects benefit from both. Explore available servers in our MCP directory, and read the Skills vs MCP Servers guide for details.

Best Practices for Writing Cursor Rules

After reviewing hundreds of cursor rules across open-source projects, these patterns produce the best results:

1. Be specific, not generic -- "Use early returns, max 40 lines per function" beats "write clean code."
2. Include concrete examples -- Code blocks in cursor rules are interpreted as templates.
3. State what to avoid explicitly -- An "Avoid" section catches common AI mistakes for your project.
4. Organize with headers -- Use ## headings: Tech Stack, Architecture, Conventions, Testing, Avoid.
5. Update when conventions change -- Treat your .cursorrules file like living documentation.
6. Combine multiple skills -- Pair a Next.js skill with an Accessibility skill and a Security skill.
7. Test your rules -- Use the Skills Playground to verify output before committing.

Migrating to Cursor Rules

From Claude Code: Copy CLAUDE.md into .cursorrules. Remove hooks, slash commands, and CLI flags. Conventions and architecture rules work as-is. See our Claude Code best practices guide.

From GitHub Copilot: Move .github/copilot-instructions.md content into .cursorrules. No changes needed.

From Windsurf: Rename .windsurfrules to .cursorrules. The formats are nearly identical.

For multi-editor teams, keep all formats in sync -- the content is identical, only the filename differs. Use a skill from Skills Playground as the canonical source:

# Quick sync script for multi-editor teams
cp .cursorrules CLAUDE.md
cp .cursorrules .windsurfrules
cp .cursorrules .github/copilot-instructions.md

Common Mistakes to Avoid

• Rules that are too long -- A 2,000-line .cursorrules file wastes tokens and degrades output. Keep it under 500 lines.
• Contradictory rules -- "Use Tailwind CSS" alongside "Style with CSS modules" creates confusion.
• Overly vague instructions -- "Write good code" teaches the AI nothing. Be specific.
• Forgetting version control -- Your .cursorrules belongs in git so the whole team benefits.
• Never updating -- Review and update quarterly as your stack evolves.
• Ignoring .cursor/rules/ -- For large projects, split rules by directory to keep each set focused.

Getting Started: Your First .cursorrules File

Create a .cursorrules file at your project root with three sections:

# Project: [Your Project Name]

## Tech Stack
- [Languages, frameworks, key libraries]

## Conventions
- [5-10 coding conventions your team follows]

## Avoid
- [3-5 common mistakes or anti-patterns]

This takes five minutes and immediately improves AI output quality. As you discover what the AI gets wrong, add more rules. Over time, your .cursorrules file becomes a living codex of your project's standards.

For a head start, browse our skills library, test them in the Playground, and paste the best ones directly into your .cursorrules file. Every skill on Skills Playground works as a cursor rule out of the box.