How to Write Cursor Rules (.cursorrules) That Actually Work

If you use Cursor and you haven't written a .cursorrules file, you're leaving the biggest improvement on the table. Cursor Rules are persistent project context that shapes every AI interaction — completions, chat, Agent mode. A good rules file is the difference between generic suggestions and code that fits your project.

What Are Cursor Rules?

A .cursorrules file in your project root tells Cursor's AI about your stack, conventions, and patterns. Think of it as a system prompt that runs on every interaction. Every tab completion, every chat message, every Agent mode session reads this file and adjusts output accordingly.

Without rules, Cursor guesses. It might use class components when you use hooks, suggest CSS modules when you use Tailwind, or import from paths that don't exist. With rules, it knows. See: Cursor Rules glossary.

Where to Put Them

Single project: .cursorrules in your project root.

Monorepos: One at the repo root for shared conventions, plus one per package. Cursor merges them — specific rules override general ones.

Directory-scoped rules: Cursor also supports .cursor/rules/ with individual rule files (e.g., testing.md, api-patterns.md). Each file gets included as context.

Anatomy of Great Rules

Stack declaration — Framework versions, key libraries, runtime. Be specific.

Code conventions — Naming, file structure, import style. What a new team member needs on day one.

Patterns to follow — Short code examples showing the right way. Worth more than paragraphs of description.

Anti-patterns — Explicitly ban things the AI tends to suggest that don't fit your codebase.

Testing approach — Framework, test style, file locations.

You don't need all five. But stack declaration and conventions are non-negotiable.

3 Real-World Examples

Next.js + TypeScript + Tailwind

# Stack: Next.js 16 (App Router), TypeScript, Tailwind CSS 4, shadcn/ui
# Database: Supabase (Postgres)
# Conventions:
- Default to Server Components; add "use client" only when needed
- Absolute imports with @/ prefix
- Tailwind for all styling — never CSS modules or inline styles
- Use shadcn/ui; don't build custom UI primitives
# Anti-patterns:
- No class components or default exports (except pages/layouts)
- Never use getServerSideProps (App Router only)

Python FastAPI

# Stack: Python 3.12, FastAPI, SQLAlchemy 2.0, Pydantic v2
# Database: PostgreSQL via asyncpg | Testing: pytest + httpx
# Conventions:
# - All route handlers must be async
# - Pydantic BaseModel for all request/response schemas
# - Repository pattern for DB access (no raw SQL in routes)
# - Dependency injection via Depends() for auth, db sessions
# Anti-patterns:
# - No sync database calls
# - Never commit sessions inside route handlers
# - Don't use dict responses — always define a schema

React Native + Expo

# Stack: React Native 0.76, Expo SDK 52, TypeScript
# Navigation: Expo Router (file-based) | State: Zustand + React Query
# Conventions:
- Functional components only, hooks for all state
- Platform-specific code via .ios.tsx / .android.tsx suffixes
- Use expo-image instead of React Native Image
# Anti-patterns:
- No inline styles — use StyleSheet.create or NativeWind
- Never use AsyncStorage directly (use MMKV)
- Use router.push() from Expo Router, not navigation.navigate()

Advanced: Rules for Monorepos

Layered rules prevent repetition. Root .cursorrules covers shared conventions — TypeScript config, commit format, linting. Package-level rules cover stack-specific patterns — React conventions for the frontend, API patterns for the backend.

Cursor reads the nearest rules file first and merges upward. Package rules win over root rules when they conflict. Global defaults, local overrides.

Cursor Rules vs CLAUDE.md vs Kiro Steering Files

All three solve the same problem — giving AI tools project context — but for different tools.

If you use multiple tools, maintain both. The content overlaps — your stack and conventions don't change between tools. Some teams generate both from a single source of truth. See: CLAUDE.md glossary, Kiro glossary.

Tips

• Be specific about versions. "Next.js 16" prevents the AI from suggesting deprecated APIs. "Next.js" does not.
• Include short code examples. A 3-line snippet beats a paragraph. The AI learns from examples faster than instructions.
• Update rules when your stack changes. Stale rules actively push the AI toward wrong patterns.
• Keep it under 50 lines. If you need more, use .cursor/rules/ with separate files.
• Test your rules. Generate a new component after writing them. If output doesn't match conventions, iterate.

Related: Cursor IDE Complete Guide | Context Engineering | What Is Vibe Coding?

Browse: AI Coding Tools | Glossary