Cursor Rules let you configure how Claude behaves within your project. Without rules, Claude gives generic responses. With well-crafted rules, it responds like a developer who knows your codebase deeply. This guide shows you how to set them up effectively.

What Are Cursor Rules?

Cursor Rules are instructions you give to Claude about your project:

  • Tech stack and conventions
  • Code style preferences
  • File structure and naming
  • Patterns to follow or avoid
  • Testing requirements

They’re applied to every AI request in your project, so you don’t have to repeat yourself.

Types of Rules

1. Project Rules (.cursorrules file)

A .cursorrules file in your project root applies to all AI interactions in that project:

.
├── .cursorrules
├── src/
├── package.json
└── ...

2. Project Rules (Settings UI)

In Cursor Settings → Project → Rules, you can add rules without a file.

3. Global Rules

In Cursor Settings → General → Rules for AI, set rules that apply across all your projects.

Writing Effective .cursorrules

Basic Structure

# Project: [Name]
# Stack: [Technologies]

## Tech Stack
- Frontend: Next.js 14 with App Router
- Styling: Tailwind CSS
- State: Zustand
- Backend: Supabase (PostgreSQL + Auth)
- Testing: Vitest + React Testing Library

## Code Style
- Use TypeScript strict mode
- Prefer functional components
- Use async/await over .then()
- Always type function parameters and return values

## File Naming
- Components: PascalCase (UserProfile.tsx)
- Hooks: camelCase starting with 'use' (useAuthStore.ts)
- Utils: camelCase (formatDate.ts)
- Types: PascalCase with 'Type' suffix (UserType.ts)

## Patterns to Follow
- Use Zod for all form validation
- API calls go through services/ directory, not in components
- Error boundaries around all async components

## Testing
- Write tests for all utility functions
- Use React Testing Library, not Enzyme
- Test behavior, not implementation

Stack-Specific Rules

Next.js App Router

## Next.js Conventions
- Use server components by default
- Add 'use client' only when needed (event handlers, hooks, browser APIs)
- Put shared types in types/ directory
- API routes go in app/api/ directory
- Use Next.js Image component instead of <img>
- Use Link component instead of <a> for internal navigation

## Data Fetching
- Fetch data in server components when possible
- Use React Query for client-side data fetching
- No API calls directly in components — use custom hooks or server actions

## File Organization
- Group by feature, not by type
- app/(dashboard)/... for authenticated routes
- app/(marketing)/... for public routes

Python / FastAPI

## Python Conventions
- Python 3.12+ features allowed
- Use Pydantic v2 for all models
- Type hints required on all functions
- Docstrings on public functions (Google style)

## FastAPI Patterns
- Router files named [domain]_router.py
- Service files named [domain]_service.py
- All endpoints have response_model defined
- Use dependency injection for database sessions
- Background tasks for async operations

## Database (SQLAlchemy)
- Use async SQLAlchemy
- All queries through repository classes
- Migrations with Alembic

React Native / Expo

## React Native Conventions
- Expo SDK 52+
- NativeWind for styling (Tailwind in RN)
- React Navigation for navigation
- Zustand for state management

## Patterns
- Platform-specific files: Component.ios.tsx, Component.android.tsx
- No inline styles — use NativeWind classes
- SafeAreaView wrapping all screens
- KeyboardAvoidingView on forms

Rule Writing Best Practices

Be Specific, Not Vague

Bad:

Write clean code.

Good:

Functions should be under 30 lines. Extract logic into named helper functions.
Variables should describe their content (not 'data', 'temp', 'obj').

Include Examples When Helpful

## API Response Format
Always return: { success: boolean, data: T | null, error: string | null }

Example success: { success: true, data: { user: {...} }, error: null }
Example error: { success: false, data: null, error: "User not found" }

Specify What NOT to Do

## Avoid
- Don't use var — use const/let
- Don't use any TypeScript type without a comment explaining why
- Don't use console.log in production code — use the logger service
- Don't access process.env directly — use the config module

Rule Templates by Project Type

SaaS Product

You are an expert full-stack developer building a SaaS product.

Tech Stack: Next.js 14, TypeScript, Prisma, PostgreSQL, Stripe, Resend

Conventions:
- Multi-tenant architecture — always scope queries by organizationId
- Use Clerk for authentication
- Stripe customer created on signup
- All prices in cents (integer) not dollars
- Email through Resend service, never directly

Security:
- Validate all user inputs with Zod
- Check authorization before data access
- Never expose internal IDs in URLs — use slugs

Open Source Library

You are helping build an open-source JavaScript library.

Requirements:
- Zero runtime dependencies
- Support CommonJS and ESM dual builds
- TypeScript types exported from package
- 100% test coverage target
- All public API documented with JSDoc
- Backwards-compatible changes only (no breaking changes without major version)

Code Style:
- Functional, pure functions preferred
- No classes unless necessary for the API
- Explicit error messages (not generic "Error occurred")

Debugging Rules

If rules aren’t being applied:

  1. Check .cursorrules is in the project root (not in src/ or nested)
  2. Restart Cursor after adding the file
  3. In Settings → Project, verify rules are showing
  4. Test with a direct question: “What rules are you following for this project?”

Rule Sharing

Many developers share their .cursorrules files on GitHub. Search for:

  • “cursorrules nextjs”
  • “cursorrules fastapi”
  • “awesome-cursorrules” repository

Use community rules as a starting point and customize to your project’s specific needs.

Summary

Good Cursor Rules take 30 minutes to write and save hours of repeated explaining. Start with your tech stack, add your conventions, and iterate as you find yourself correcting Claude on the same points repeatedly. Each correction is a rule worth adding.