Cursor rules: how .cursor/rules works, with copyable examples

What are Cursor rules?

Cursor's rules documentation says rules provide system-level instructions to Agent. Language models do not keep memory between requests, so a rule is a way to put the same guidance in front of the model every time. When a rule applies, its contents are included at the start of the model context. Typical uses are your stack, your coding conventions, the commands that run your tests and the files the agent must never touch.

Cursor supports four kinds. Facts on this page come from Cursor's docs and help center, read on October 30, 2026.

If rules from several sources conflict, the docs give the order Team rules, then Project rules, then User rules, and say earlier sources win. One limit to know up front: rules apply to Agent (Chat). They do not affect Tab completion or Bugbot pull request reviews. The related guides what is Cursor AI and how to use Cursor cover the surrounding tool.

What does a .cursor/rules file look like?

Each project rule is a markdown file with frontmatter on top. The file must use the .mdc extension. A plain .md file inside .cursor/rules is ignored, because it has no frontmatter to say when it applies. You can name files anything and organize them in folders, though Cursor's help center says a flat folder is simpler to manage.

.cursor/rules/
  project-basics.mdc        # always applied
  react-components.mdc      # attached by file pattern
  api-conventions.mdc       # Agent decides from the description
  db-migrations.mdc         # only when you @-mention it
  frontend/
    forms.mdc               # folders are allowed
  notes.md                  # ignored: wrong extension

Three frontmatter fields control loading. Cursor documents exactly how they combine:

The dropdown in the Cursor UI writes these fields for you, so you rarely edit them by hand. The practical consequence: a description is what makes Apply Intelligently work. Without one, the agent has nothing to judge relevance by.

How do you create a rule?

1. From chat: type /create-rule in Agent and describe the rule. Agent writes the file with correct frontmatter into .cursor/rules.
2. From the command palette: press Cmd+Shift+P (Ctrl+Shift+P on Windows and Linux), choose New Cursor Rule, name it, write the instructions and pick the type from the dropdown.
3. From Customize: open Customize in the sidebar, go to Rules and click Add Rule. This also lists every rule and its status.
4. By hand: create a .mdc file in .cursor/rules and add frontmatter yourself.

Cursor's best-practice advice is to start simple. Add a rule only when you see the agent make the same mistake more than once, and check rules into git so the whole team gets them. When you notice a mistake, update the rule. Here is a prompt for turning a mistake into a rule:

/create-rule

The agent keeps adding default exports to React components in this repo. Create a rule that attaches only to files under src/components/ ending in .tsx. It should say: use named exports, keep components under 200 lines, and name the file after the component. Keep it under 15 lines and include one short good example.

What do good Cursor rules look like? Four copyable examples

These are examples to adapt, not rules Cursor ships. Replace the stack and commands with your own. Each one is short on purpose: Cursor's docs recommend focused, actionable rules under 500 lines, and say vague guidance is wasted. The first suits any project.

---
description: Stack, commands and boundaries for this project
alwaysApply: true
---

# Project basics

- Stack: Next.js (App Router), TypeScript in strict mode, Tailwind, Postgres.
- Use pnpm, never npm or yarn.
- Run `pnpm test` and `pnpm typecheck` after every change and fix failures before you say you are done.
- Never edit files in `dist/`, `.next/` or `supabase/migrations/` that already exist. Add a new migration instead.
- Do not add a dependency without telling me why and what it replaces.
- If you are unsure how something works, read the relevant source file before proposing a change.

The second attaches by file pattern, so it costs nothing in conversations that never touch a component.

---
globs: src/components/**/*.tsx
alwaysApply: false
---

- Use named exports, not default exports.
- One component per file, and the file name matches the component name.
- Keep components under 200 lines; extract subcomponents into the same folder.
- Props get an explicit TypeScript type. No `any`.
- Prefer composition (children, render props) over passing data through many layers.
- Every interactive element needs an accessible name.

The third is agent-selected. The description does the work: the agent reads it and loads the rule when you are doing something that matches. It points at a reference file with an @ path, which the agent reads only when it needs it.

---
description: Conventions for creating or changing API route handlers under src/app/api
alwaysApply: false
---

- Validate every request body with a Zod schema at the top of the handler.
- Return `{ error: { code, message } }` with the right HTTP status. Never return a raw string or a stack trace.
- Keep handlers thin: business logic lives in `src/services/`, not in the route file.
- Add a test next to the route for the success case and one failure case.
- Read @src/app/api/example/route.ts for the standard layout before creating a new route.

The fourth is manual. It has no globs and no description, so it only loads when you type its name in chat. That suits a heavy checklist you want on rare, specific jobs.

---
alwaysApply: false
---

# Database migrations

- Every migration is a new file in `supabase/migrations/`, named with a timestamp prefix.
- Never change a column type in place. Add a new column, backfill it, then drop the old one in a later migration.
- Add the matching row level security policy in the same migration as the table.
- After writing the SQL, list the tables, columns and policies it touches so I can review them.
- Read @supabase/migrations/TEMPLATE.sql for the expected structure.

Does Cursor support AGENTS.md and CLAUDE.md?

Yes to both. Cursor's docs describe AGENTS.md as a simple markdown file for agent instructions, placed in the project root as an alternative to .cursor/rules for straightforward cases. It has no metadata and no frontmatter. Nested AGENTS.md files in subfolders are supported too: they apply when the agent works with files in that folder or its children, they combine with the files above them, and the more specific one takes precedence.

# Project instructions

## Commands
- Install: `pnpm install`
- Test: `pnpm test`
- Type check: `pnpm typecheck`

## Code style
- TypeScript everywhere; no `any`.
- Prefer small functions and early returns.

## Boundaries
- Do not edit generated files in `dist/` or `build/`.
- Ask before adding a dependency or changing the database schema.

## Definition of done
- Tests pass, the type check passes, and the diff contains only what was asked for.

Cursor's help center adds that it reads CLAUDE.md the same way it reads AGENTS.md, so a repository that already has one for Claude Code works in Cursor. A CLAUDE.md file is always applied to every conversation, whatever an alwaysApply setting says. If you need conditional rules, use .cursor/rules. For the format of those files, see how to write a CLAUDE.md and the AGENTS.md guide.

How do you migrate from .cursorrules, and what about user and team rules?

The single .cursorrules file in the project root is legacy and, per Cursor's help center, will be deprecated. To migrate:

1. Create a new rule with New Cursor Rule from the command palette.
2. Copy the content of .cursorrules into it.
3. Set the type to Always Apply, which matches the old behavior.
4. Delete .cursorrules from the project root.
5. Then split the new rule into focused files as it grows, so only the relevant ones load.

User rules are global preferences, set under Customize, then Rules, and they sync across your devices with your account. Cursor's example is a communication style, such as replying concisely. User rule files kept in ~/.cursor/rules stay on that machine and do not sync. Team rules are managed from the dashboard on Team and Enterprise plans: a team admin can enforce a rule so members cannot turn it off, or leave it optional, and a glob pattern can scope it to file types such as **/*.py.

Why is my Cursor rule not being applied?

• Check the file extension. Project rules must be .mdc. A .md file in .cursor/rules is ignored.
• Check the rule type. For Apply Intelligently, a description must be defined. For Apply to Specific Files, the glob must match a file that is actually in the conversation's context.
• Check where you are. Rules apply to Agent chat, not to Tab completion and not to Bugbot reviews.
• Look at the context ring. The ring next to the prompt box opens a breakdown of what fills the context window, with a category for rules. A giant rule uses space you need for the task.
• Reference files, do not paste them. An @file path in a rule tells Agent where to look, and Agent reads the file when it needs it; the contents are not inlined. If something must always be in context, put it in the rule body.
• Cut the length. Keep rules under 500 lines, and split large ones into composable files.

Rules are most useful when they encode what your project actually needs, and the quickest source of that is a build prompt that already states the stack, the screens and what is out of scope. If you want a project to practice on, take an idea from the ideas board; its generated build prompt gives you the raw material for a first AGENTS.md. For the agent that reads these rules, see the Cursor Agent guide.