Cursor Rules & Project Memory

One of the most underutilized features in Cursor is .cursorrules — a simple text file that acts as your project's memory. Without it, Cursor treats every conversation as fresh, requiring you to re-explain your stack and conventions repeatedly. With a well-written .cursorrules file, Cursor understands your project deeply from the first message.

What You'll Learn

• What .cursorrules is and how it works
• How to write rules that actually improve suggestions
• Global rules vs project-level rules
• Example .cursorrules for React/Next.js and Python projects
• The Notepads feature for persistent context

What Is .cursorrules?

.cursorrules is a plain text file you place at the root of your project. Cursor reads it automatically whenever you open the project. Its contents become part of the context for every Composer and Chat interaction in that project.

Think of it as a standing brief you give Cursor: "Here is what this project is, how it is structured, what conventions we follow, and what I want you to do (or not do)."

The file is read-only by Cursor — it does not modify it. You control it entirely. Commit it to your repository so everyone on your team gets consistent AI behavior.

Global Rules vs Project Rules

Global rules apply to all projects. Set them in Cursor Settings → Rules for AI. Use global rules for:

• Your personal coding style preferences
• Languages you always use
• Things you always want Cursor to do (e.g., "always add TypeScript types to generated code")

Project rules are in .cursorrules at the project root. Use project rules for:

• Stack-specific conventions
• Project architecture
• Business domain context
• Team agreements

Project rules override global rules when they conflict.

Writing Effective Rules

The key to effective rules is specificity. Vague rules like "write clean code" do nothing. Specific rules like "never use var, always use const or let, prefer const" change behavior.

Structure your .cursorrules in sections:

1. Project Overview (what is this, why does it exist)
2. Tech Stack (exact versions matter)
3. File Structure (where things live)
4. Coding Conventions (language-specific rules)
5. What NOT to Do (explicit prohibitions)
6. Examples (show a pattern you want followed)

🇮🇳 India Note: If your project includes INR formatting, GST calculations, or Indian phone number validation, put that in your .cursorrules. Cursor will then handle India-specific business logic correctly without being told each time.

Example: React/Next.js Project

# Project: E-commerce Platform
Indian fashion marketplace. Next.js 15 + TypeScript + Tailwind CSS 4 + PostgreSQL.

## Tech Stack
- Next.js 15 (App Router, NOT Pages Router)
- TypeScript 5 (strict: true)
- Tailwind CSS 4 (no CSS modules, no styled-components)
- PostgreSQL 16 via Prisma ORM
- NextAuth.js for authentication
- Razorpay for payments (Indian payment gateway)

## File Structure
- app/ — Next.js App Router pages
- components/ui/ — reusable UI primitives (Button, Input, Card, etc.)
- components/features/ — feature-specific components
- lib/ — utilities, API clients, database helpers
- hooks/ — custom React hooks
- types/ — TypeScript type definitions

## Component Rules
- Default: Server Components
- Use 'use client' only for: event handlers, useState/useEffect, browser APIs
- Props interfaces: always define explicitly, never use `any`
- Components: named exports only (not default export)
- File names: PascalCase for components, camelCase for utils

## Styling
- Tailwind only — no inline styles, no CSS modules
- Mobile-first responsive design
- India color scheme: saffron (#FF9933) as primary, navy (#000080) secondary

## India-Specific
- Currency: always display as ₹1,00,000 (Indian number format with lakhs/crores)
- Phone: +91 prefix, 10-digit validation
- GST: 18% for services, vary for products — always calculate server-side
- Addresses: include PIN code field (6 digits), not ZIP code

## DO NOT
- Never use `any` TypeScript type
- Never fetch data directly in client components (use Server Components or API routes)
- Never store sensitive data in localStorage
- Never use .then() chains (use async/await)
- Never import from relative paths that go up more than 2 levels (use @ aliases)

Example: Python FastAPI Project

# Project: Analytics API
REST API for analytics data processing. Python 3.12 + FastAPI + PostgreSQL.

## Tech Stack
- Python 3.12
- FastAPI 0.115+
- SQLAlchemy 2.0 (async)
- Alembic for migrations
- Pydantic v2 for validation
- PostgreSQL 16

## Code Style
- PEP8 strictly (black formatter)
- Type hints required on ALL functions — no bare `def func(x):`
- Async everywhere — all route handlers must be `async def`
- Use `|` for union types (Python 3.10+ style), not `Union[]`

## Structure
- api/routes/ — one file per resource (users.py, analytics.py)
- api/models/ — SQLAlchemy models
- api/schemas/ — Pydantic schemas
- api/services/ — business logic
- api/dependencies.py — FastAPI dependencies (auth, db session)

## Error Handling
- Always raise HTTPException with proper status codes
- 400: validation errors, 401: not authenticated, 403: forbidden, 404: not found, 500: server errors
- Never let exceptions propagate to the user without a proper HTTP response

## DO NOT
- Never use `print()` (use logging)
- Never put business logic in route handlers (use service layer)
- Never commit `.env` files or hardcode credentials
- Never use synchronous database calls in async routes

The Notepads Feature

Notepads are a newer Cursor feature that complements .cursorrules. While .cursorrules is always-on project context, Notepads are named text blocks you can selectively reference in conversations using #notepad-name.

Create a Notepad:

1. Click the Notepads section in the Cursor sidebar (or Cmd+Shift+P → "Open Notepads")
2. Create a new notepad, give it a name
3. Write any content — architecture diagrams in text form, API specifications, design decisions

Reference in Chat or Composer:

Implement the user authentication flow following #auth-spec

Notepads are useful for:

• Architecture decision records (ADRs) you want Cursor to reference
• API contracts or schemas for integration work
• Long examples you reference repeatedly (templates, complex patterns)

Tips for Writing Better Rules

Be prescriptive, not descriptive. "Uses React" is descriptive. "Always use React functional components with TypeScript interfaces for props" is prescriptive.

Add examples for patterns. Show one example of a correctly structured component — Cursor will match the pattern.

Review and update after mistakes. When Cursor generates something you have to correct multiple times, add a rule to prevent it.

Do not over-specify. Extremely long .cursorrules files can become noisy. Focus on the 10-15 rules that would change Cursor's behavior most meaningfully for your project.

Official Resources

• Cursor Documentation — Full Cursor features documentation
• Cursor Rules Guide — Official .cursorrules reference
• Cursor Notepads — Notepads feature guide
• awesome-cursorrules — Community collection of .cursorrules examples
• Cursor Forum — Community tips on effective rules