Where should I put the .cursorrules file?

Place .cursorrules in the root of your project repository, alongside package.json, pyproject.toml, or your main config file. Cursor reads it automatically when you open the project.

How long should a .cursorrules file be?

Most effective files are 30 to 150 lines. Long enough to cover the most important constraints, short enough that every rule is read and applied. If your rules are getting very long, consider splitting them by concern.

Is .cursorrules the same as .cursorignore?

No. .cursorrules contains instructions for how the AI should code. .cursorignore lists files and directories that Cursor should not index or use as context, similar to .gitignore.

Can I share .cursorrules publicly?

Yes. Before sharing, remove any internal hostnames, private paths, tokens, or client-specific details. Generic rules about language conventions and architecture travel well across projects.

Cursor Rules Examples — Best .cursorrules Templates for 2025

A .cursorrules file is a plain text instruction file that tells Cursor AI how your codebase should be changed. It is specific to the project, committed alongside your code, and read automatically when the project is open. The purpose is the same as a CLAUDE.md for Claude Code: replace repeated guidance with persistent, reliable context.

Good rules are specific enough to be actionable. Instead of saying "write maintainable code," say which TypeScript settings are enforced, how components are organized, what commands should verify work, and which patterns are banned. The AI reads these rules before making any edit, so vague rules produce inconsistent results and specific rules produce consistent ones.

TypeScript strict template

You are working in a strict TypeScript codebase.

Rules:
- Do not use any. If a type is unknown, use unknown and narrow it.
- Prefer discriminated unions for state with multiple modes.
- Keep all public functions explicitly typed, including return types.
- Run: npm run type-check && npm run build after type-sensitive changes.
- Do not suppress type errors with @ts-ignore without a comment explaining why.

React + Next.js template

This is a Next.js 16 App Router project.

Rules:
- Default to Server Components. Add "use client" only when needed for interactivity.
- Use existing components in src/components/ before creating new ones.
- Keep data fetching in Server Components or route handlers, not client components.
- Use accessible ARIA labels on interactive controls.
- Run: npm run build to verify there are no SSR or hydration errors.
- Do not store derived state. Compute it from props or server data instead.

Python backend template

Python 3.11+ backend service.

Rules:
- Add type hints to all new public functions and class methods.
- Keep IO at the boundaries of the application, not inside domain logic.
- Use pathlib instead of os.path for file operations.
- Write a focused unit test for every bug fix before merging.
- Run: pytest -x for fast local feedback.
- Avoid mutable default arguments in function signatures.

SQL and database migrations template

PostgreSQL database with Alembic migrations.

Rules:
- Every schema change must have a corresponding migration file.
- Make migrations reversible: include both upgrade and downgrade functions.
- Add a B-tree index for any new column used in WHERE or JOIN clauses.
- Avoid SELECT * in application queries. Name all columns explicitly.
- Add a comment for non-obvious constraints or default values.
- Test the migration on a copy of production data before applying it.

AI agent coding template

This repository is developed with AI coding agents (Cursor, Claude Code).

Rules:
- Read existing patterns before writing new ones. Do not introduce new abstractions unless clearly necessary.
- Keep changes scoped to the request. Do not refactor unrelated code.
- Verify with the smallest reliable command: unit test, type-check, or lint.
- Do not add error handling for scenarios that cannot happen in the current architecture.
- Add comments only when the WHY is not obvious from the code itself.
- Do not create new files without checking if an existing one fits.

General engineering template

General software engineering rules:

- Before editing, read the relevant existing code.
- Scope changes to the task. Do not improve unrelated code.
- Verify with the smallest reliable check: unit test, lint, or build.
- Do not add fallbacks or defaults for situations that cannot occur.
- Keep new dependencies minimal. Check if the standard library covers the need first.

What makes a rule effective

The best rules describe local truth: the exact commands your project uses, the architectural boundaries that matter in production, and the constraints that a generic AI would not know. Rules that say "write clean code" or "follow best practices" are too abstract to be applied consistently. Rules that say "run npm run type-check before finishing" or "do not import from lib/internal in api/ routes" are specific enough to enforce.

Include the verification step. If the AI does not know how to check its own work, it will guess or skip it. Specify the exact command, not just "run tests."

Review the file when the project changes. Stale rules are worse than missing ones — they produce confident mistakes. Update the file when commands change, new patterns become standard, or old restrictions are lifted.

FAQ

What is a .cursorrules file?

A project instruction file for Cursor AI. It tells the editor which coding patterns to use, which conventions to follow, and how to verify work. It is read automatically when the project is open.

What should I write in .cursorrules?

Specific, actionable rules. Name your TypeScript settings, your test commands, your component patterns, and your architectural constraints. Avoid generic advice that a thoughtful developer would already know.

How is .cursorrules different from CLAUDE.md?

They serve the same purpose for different tools. .cursorrules is read by Cursor. CLAUDE.md is read by Claude Code. The content is often very similar — coding conventions, verification commands, architectural context — and many teams maintain both files in the same repository.