Cursor Rules

Rules are how you tell Cursor what conventions your project follows. Without rules, the AI invents a style on every prompt: sometimes Prettier formatting, sometimes Standard; sometimes async/await, sometimes promises. With rules, every Composer and Chat session starts with your conventions already loaded.

This page covers the three rule surfaces (.cursorrules, Project Rules, global Rules for AI), the four rule types introduced in 2025, and eight practical rule examples you can adapt today.

The three rule surfaces

Cursor has three places to put AI instructions:

1. .cursorrules file at the repo root. The original format, still supported. Plain markdown. Applies to the whole project.
2. Project Rules at Settings > Cursor Rules > Project Rules. A per-directory system added in 2025. Each rule is a file under .cursor/rules/*.mdc with a scope and a type.
3. Global Rules for AI at Settings > General > Rules for AI. Applies to every project on your machine.

All three surfaces are additive. Global rules apply first, then .cursorrules, then matching Project Rules. The AI sees them concatenated as system context.

Why .cursorrules is not going away

Cursor added Project Rules because .cursorrules did not scale. One file for a 500-file monorepo ended up either too vague or too long. Project Rules let you scope instructions to specific directories.

But .cursorrules still works, still ships with new Cursor versions, and is the right choice for small and medium repos. Start with .cursorrules; migrate to Project Rules when the file grows past 300 lines or when different parts of the repo need different conventions.

Writing .cursorrules

Create a file named .cursorrules at the repo root. Plain markdown, no frontmatter required. A short example:

# Project Rules

## Stack
- TypeScript strict mode, no `any`.
- Next.js 16 App Router.
- Tailwind CSS, no inline styles.
- Zod for all API input validation.

## Conventions
- Functional components, named exports only.
- Test file alongside every component: `Button.tsx` has `Button.test.tsx`.
- Commit style: conventional commits (feat, fix, chore, docs).

## Forbidden
- No `console.log` in production code.
- No barrel files (`index.ts` re-exports).
- No classes for React components.

## Commands
- Run tests: `pnpm test`
- Lint: `pnpm lint`
- Type-check: `pnpm typecheck`

This file is injected into every Composer and Chat session. The AI reads it as system context before answering any prompt.

Project Rules format

Project Rules live under .cursor/rules/ as .mdc files. Each rule has a frontmatter block and a markdown body:

---
description: Next.js App Router conventions
globs: app/**/*.tsx, app/**/*.ts
alwaysApply: false
---

# App Router

- Every route has `page.tsx`, `layout.tsx` optional.
- Server Components by default; add `'use client'` only when needed.
- Use `Metadata` type for `export const metadata`.

The globs field scopes the rule to matching paths. alwaysApply: true pins the rule regardless of the current file.

Rule types

Four rule types cover the lifecycle:

• Always: attached to every prompt, regardless of file context. Good for language-level rules like "no any".
• Auto Attached: matched by glob. Fires only when the current file or edited file matches. Good for framework rules like "Next.js App Router conventions" scoped to app/**.
• Agent Requested: available to agent mode but not auto-attached. The agent picks it up if the description matches the task. Good for niche rules like "database migration safety".
• Manual: attached only when you add it via @Rule in the context bar. Good for infrequent rules like "release checklist".

Eight practical rule examples

Copy-paste patterns you can adapt to your stack.

1. TypeScript strict mode

- TypeScript strict mode is on. Never use `any`; use `unknown` plus a type guard.
- Prefer `type` over `interface` for data shapes. Use `interface` only for class contracts.
- Return types are required on exported functions.

2. Next.js App Router conventions

- Default to Server Components. Add `'use client'` only for interactivity or hooks.
- Await `params` and `searchParams`; they are Promises in Next.js 15+.
- Use `generateMetadata` for dynamic metadata; avoid `document.title` manipulation.
- Images go through `next/image`, never `<img>`.

3. Conventional commits

- Commit messages follow conventional commits: `type(scope): description`.
- Types allowed: feat, fix, chore, docs, test, refactor, perf, ci.
- Body wraps at 72 chars. Breaking changes use `BREAKING CHANGE:` footer.

4. No console.log in production

- No `console.log` in `src/**` code. Use the `logger` module from `src/lib/logger.ts`.
- `console.error` is allowed in error boundaries.
- Tests may use `console.log` freely.

5. Test file alongside every component

- Every component in `src/components/**` has a matching `*.test.tsx` in the same folder.
- Tests cover the default render, one user interaction, and one edge case minimum.
- Use Vitest and Testing Library. Never use Enzyme.

6. Python type hints

- All Python functions have type hints on parameters and return values.
- Use `from __future__ import annotations` for forward references.
- Prefer `list[str]` over `List[str]` (Python 3.9+ syntax).
- `mypy --strict` must pass before commit.

7. Database migration safety

- Never drop columns in a single migration. Two-step: deprecate in code, drop in follow-up.
- New columns are nullable or have defaults. Never add NOT NULL without a default.
- Migrations are reviewed separately from code changes. Split into its own PR.
- Run `pnpm prisma migrate dev --name <desc>` locally before committing.

8. Security - never log sensitive data

- Never log request bodies or response bodies that may contain PII.
- Never log API keys, tokens, or passwords, even in development.
- Use the `redact` helper from `src/lib/redact.ts` when logging user objects.
- Sentry breadcrumbs strip headers by default; do not override.

Importing rule files

Project Rules support @file references to import shared content:

---
description: API conventions
alwaysApply: true
---

@file:.cursor/shared/typescript-strict.md
@file:.cursor/shared/error-handling.md

The imported files are inlined when the rule fires. Useful for rules shared across many scoped rules.

Global vs project rules precedence

If global rules and project rules conflict, project rules win. The AI sees both in the system context and the later instruction overrides the earlier. Ordering from weakest to strongest:

1. Global Rules for AI (weakest)
2. .cursorrules
3. Project Rule with Always type
4. Project Rule with Auto Attached type and matching glob (strongest)

This means a project-specific "use Yarn" rule beats a global "use npm" preference, which is what you want.

Migrating from .cursorrules to Project Rules

You do not have to migrate. Both formats are supported and work together. Signals that it is time to migrate:

• Your .cursorrules has grown past 300 lines
• You have a monorepo with different conventions per package
• You want to scope rules to specific file types
• The AI is ignoring rules at the bottom of a long .cursorrules file

To migrate, break .cursorrules by topic into 5-10 Project Rule files. Put language-level rules as Always. Put framework-level rules as Auto Attached with the right glob. Keep .cursorrules for the top-level overview or delete it.

Testing your rules

After writing rules, verify they fire. Open a fresh Composer session and ask:

What conventions should I follow when editing this codebase?

The AI should recite your rules back. If it misses something important, the rule is either too vague, too long, or too far down the instruction list. Tighten the wording or split into a scoped Project Rule.

Common rule mistakes

Four patterns that waste tokens and get ignored by the model. Watch for these when you audit your rule set.

First, rules written as aspirations rather than instructions. "We try to write clean code" means nothing to the AI. "Functions have at most 40 lines; extract helpers past that" is a rule the AI can follow. Phrase every rule as a concrete directive.

Second, duplicate rules across .cursorrules and Project Rules. The AI reads both and the instruction gets repeated in context, which wastes tokens and sometimes confuses the model when the wording differs slightly. Pick one surface per rule and delete from the other.

Third, overly broad globs on Project Rules. A rule with globs: */ is effectively Always. Scope rules tightly so they fire only when relevant. Broad globs defeat the point of scoped rules.

Fourth, rules that contradict the codebase. If your rule says "use type over interface" but the codebase is full of interfaces, the AI will compromise by alternating, and neither style wins. Either update the rule or run a codemod to align the codebase first.

Rule length guidance

Short rules fire more reliably than long ones. A rule with 8 bullets beats a rule with 40 bullets because the model can hold the 8 in active context and apply them consistently. If a rule has more than 15 items, split it by topic.

For reference, typical mature projects land at 150-300 lines of rules total across all surfaces. Anything under 50 lines is too thin to materially change AI output. Anything over 500 lines starts to see diminishing returns as the later rules get ignored.

Updating rules over time

Rules are living documents. Every time you catch yourself correcting the AI on a convention, write a rule for it. Every time a rule no longer matches the codebase, update or delete it. A monthly rules review during a retrospective keeps the file aligned with how the team actually writes code.

Treat the rule set like test coverage: the goal is not to cover everything, the goal is to cover the conventions that matter and that the AI gets wrong without a rule. Start small, add rules as pain points appear, prune rules that no longer apply.

A tour of real rule files

Looking at open-source repos that have published their Cursor rules gives a feel for what good looks like. A few patterns repeat across well-tuned rule sets regardless of stack.

The first pattern is a stack declaration block at the top. Two to five bullets listing the major tools: language and version, framework, database, test runner, package manager. This gives the AI enough context to pick the right library functions without reading a dozen files. A Node project declares Node 20, TypeScript 5.4, Next.js 16, Postgres via Prisma, Vitest for tests, pnpm for package management, and every Composer session starts with that baseline.

The second pattern is a short conventions block covering the five or six decisions that are easy to get wrong. Where components live, how files are named, how imports are ordered, which error-handling pattern to follow, how async work is structured. These are the decisions that differ across codebases and that the AI cannot infer from a single file read.

The third pattern is a forbidden list. Three to ten items that the AI should never do. This is more effective than positive rules because it catches failure modes the model would otherwise drift toward: inline styles, magic strings, classes where functions suffice, deep inheritance, global state. A short forbidden list is worth more than a long style guide.

The fourth pattern is a commands block at the bottom. The exact command strings for running tests, linting, type-checking, building. The AI will run these when you ask it to verify its own work, and having them spelled out prevents the model from guessing at the wrong package manager or script name.

Finally, the best rule files are boring. No rhetorical flourishes, no explanations, no justifications. Rules are reference material the model reads on every prompt; every extra word competes for context budget with the actual task. If you catch yourself writing a paragraph to explain why a rule exists, move that explanation to a separate DESIGN.md and keep the rule itself to a single line.