Cursor Rules Guide: .cursorrules Templates & Best Practices

What Is .cursorrules?

A .cursorrules file is a plain-text file in your project root that gives Cursor's AI context about your project: the tech stack, coding conventions, and project structure. Cursor is an AI-powered code editor built as a fork of VS Code, and the rules file lets you set expectations once instead of repeating them in every chat.

The idea is the same as CLAUDE.md for Claude Code or AGENTS.md for AI agents in general: a short, version-controlled set of instructions that travels with the repository. The content is usually written in Markdown-style plain text, so any text editor or Markdown viewer can open it.

Where to Put It

Place the file in the root of your project as .cursorrules. The leading dot makes it a hidden file on macOS and Linux, so press Cmd+Shift+. in Finder to see it. Cursor reads the file automatically when you open the project folder.

my-project/
├── .cursorrules
├── package.json
├── src/
└── tests/

Newer versions of Cursor also support a rules directory, .cursor/rules/, which can hold multiple separate rule files instead of one large file. This is useful for splitting rules by area (frontend, backend, testing). The file format and options in that directory have changed over time, so check the Cursor documentation for the latest syntax.

Basic Template

Start small. This starter template covers the three things that matter most: who the AI should act as, how the project is laid out, and which rules to follow.

You are an expert in TypeScript and React.

## Project Structure
- /src — source code
- /tests — test files

## Coding Conventions
- Use functional components
- Prefer const over let
- Use TypeScript strict mode

## Rules
- Always write tests for new features
- Use existing patterns from the codebase
- Don't add unnecessary dependencies

Replace the paths and conventions with your own. A short file with real details beats a long file with generic advice.

TypeScript / React Template

A fuller template for a React and TypeScript project. Adjust the stack (Vite, Zustand, Tailwind, Vitest) to match what your project actually uses.

You are an expert in TypeScript, React, and modern frontend tooling.

## Tech Stack
- TypeScript (strict mode), React 18, Vite
- State: Zustand for global state, React Query for server state
- Styling: Tailwind CSS
- Testing: Vitest and React Testing Library

## Project Structure
- /src/components — reusable UI components (one folder per component)
- /src/features — feature modules (components, hooks, and API calls together)
- /src/hooks — shared custom hooks
- /src/lib — utilities and API clients
- /tests — shared test helpers and fixtures

## Component Patterns
- Use functional components with hooks; no class components
- Define props with an explicit interface named ComponentNameProps
- Keep components small; extract logic into custom hooks
- Use named exports, not default exports

## State Management
- Local UI state: useState or useReducer
- Shared client state: Zustand stores in /src/lib/stores
- Server data: React Query; never copy fetched data into global state

## Styling
- Use Tailwind utility classes; avoid inline styles
- Reuse existing design tokens from tailwind.config.ts
- No new CSS files unless a component truly needs them

## Testing
- Write a test for every new component and hook
- Test behavior (what the user sees), not implementation details
- Name test files ComponentName.test.tsx next to the component

## Rules
- Never use the any type; use unknown and narrow it
- Follow patterns already used in the codebase
- Do not add new dependencies without asking

Python Template

A template for a Python backend. The example uses FastAPI, but the same structure works for Django or Flask — swap the framework line and the folder layout.

You are an expert in Python 3.12 and FastAPI.

## Tech Stack
- Python 3.12, FastAPI, SQLAlchemy 2.0, Pydantic v2
- Package management: uv (or pip with requirements.txt)
- Testing: pytest with pytest-asyncio
- Formatting and linting: black and ruff

## Project Structure
- /app/api — route handlers
- /app/models — SQLAlchemy models
- /app/schemas — Pydantic schemas
- /app/services — business logic
- /tests — pytest tests, mirroring the /app layout

## Typing
- Add type hints to all function signatures
- Use built-in generics (list[str], dict[str, int]) and the | union syntax
- Avoid Any; prefer Protocol or TypedDict where helpful

## Style
- Format with black; lint with ruff before finishing
- Follow PEP 8 naming: snake_case for functions, PascalCase for classes
- Write short docstrings for public functions
- Keep route handlers thin; put logic in /app/services

## Testing
- Write pytest tests for every new endpoint and service function
- Use fixtures for database sessions and test clients
- Prefer parametrized tests over copy-pasted cases

## Rules
- Raise HTTPException with clear messages for client errors
- Never hardcode secrets; read them from environment variables
- Do not add new dependencies without asking

What to Include (and What Not To)

Good rules files describe things the AI cannot reliably infer from a single file. Keep sensitive information out entirely, since the file is usually committed to version control.

Comparison with Other AI Context Files

Most AI coding tools have settled on a similar idea: a plain-text or Markdown file in the repository that tells the AI how to behave. The file names differ by tool.

Because these files are all plain text, content often transfers between them with little editing. If you use more than one tool, consider keeping one source of truth and copying or linking it. Support for each file name changes as tools evolve, so confirm the current behavior in each tool's documentation.

Best Practices

• Keep it short. Aim for under about 2,000 tokens. Long files crowd out the context the AI needs for your actual task.
• Be specific. “Use functional components and named exports” is useful. “Write good code” is not.
• Include real paths and patterns. Mention actual folders like /src/features and point to an existing file as an example.
• Update it when your stack changes. A rules file that describes last year's framework will produce last year's code.
• Version control it. Commit the file so the whole team (and every machine) gets the same behavior, and changes show up in review.

Common Mistakes

Too long or too vague

A multi-page file full of general advice dilutes the instructions that matter. Cut anything the AI would do correctly without being told, and replace vague lines with concrete ones.

Bad:  Write clean, high-quality code.
Good: Use named exports and keep components under 150 lines.

Including secrets

Rules files are committed to the repository. Never paste API keys, tokens, passwords, or internal URLs into them. Tell the AI where configuration lives instead, for example “read secrets from environment variables.”

Contradictory rules

If one line says “always add comments” and another says “avoid unnecessary comments,” the result is unpredictable. Review the file as a whole whenever you add a rule.

Not keeping it updated

Renamed folders, swapped libraries, and new conventions all make an old rules file misleading. Treat it like documentation: update it in the same pull request as the change.

FAQ

What is a .cursorrules file?

It is a plain-text file in your project root that tells Cursor's AI about your project: tech stack, coding conventions, and structure. Cursor uses it as context so its suggestions follow your standards without you repeating them in every prompt.

Where do I put .cursorrules in my project?

Put it in the project root as .cursorrules. Newer versions of Cursor also support a .cursor/rules/ directory for multiple rule files — check the Cursor documentation for the latest format.

How is .cursorrules different from CLAUDE.md?

They serve the same purpose for different tools. .cursorrules is read by Cursor, while CLAUDE.md is read by Claude Code. Both are plain-text or Markdown instruction files that live in your repository. See the Claude Code Markdown files guide for details.

Preview Your Markdown with MDViewer

MDViewer is a native macOS app for reading and previewing Markdown files. It can open and render .cursorrules files too, since they are plain text and Markdown. Open a file and read it with headings, lists, and code blocks formatted cleanly. Lite is free; Pro adds editing, Git history, and PDF export.

Requires macOS 13.0 or later. Intel and Apple Silicon.