Cursor Rules: Types, File Format and 10 Examples

Every time you type "we use pnpm, not npm" into a chat, you are writing a rule by hand. Cursor's own advice is to add one when you notice Agent making the same mistake repeatedly, and not before. That's the spirit of this guide: fewer, sharper rules, each with a clear trigger.

What Cursor rules are

Language models don't remember anything between requests. Cursor's rules docs describe rules as persistent, reusable context: when a rule applies, its text is placed at the start of the model context, so Agent sees it before your prompt. Rules shape Agent (Chat). They do not change Tab completions, and Cursor's help center says they don't apply to Bugbot pull request reviews either.

A rule is not a prompt. A prompt describes today's task; a rule describes how your project always works. If you want task prompts, our Cursor prompts collection has 20 of them, including a few that turn repeated corrections into rules.

The four types of rules and where they live

When guidance conflicts, Cursor applies Team Rules first, then Project Rules, then User Rules, and earlier sources win. Two more files are worth knowing. Cursor reads CLAUDE.md the same way it reads AGENTS.md and always applies it, which keeps one instruction file working in both Cursor and Claude Code (our Cursor vs Claude Code comparison covers the rest of that choice). And because AGENTS.md is also what OpenAI's Codex reads, a shared AGENTS.md is the easiest way to keep several agents on the same page; see Codex vs Claude Code for how the instruction files compare.

To migrate an old .cursorrules file, Cursor's help center lists four steps: create a new rule from the command palette ("New Cursor Rule"), paste in the old contents, set the type to Always Apply to match the old behavior, then delete .cursorrules.

How a project rule is applied

Each project rule has a type, picked from a dropdown that sets three frontmatter fields behind the scenes: description, globs and alwaysApply. The combination decides when the rule is loaded.

Pick the narrowest type that works. Always Apply costs context in every chat, so keep it for facts that are true everywhere. File patterns suit framework or folder conventions. Apply Intelligently suits topics that cut across folders, such as error handling. Apply Manually suits checklists you only want on demand.

Rule file format and globs

A project rule is a markdown file with frontmatter at the top and the instructions underneath. It must use the .mdc extension: Cursor ignores a plain .md file in .cursor/rules because it has no frontmatter. You can name the file anything and organize rules in subfolders, though the help center suggests a flat folder is simpler. Cursor identifies rules by their full path, so two files with the same name in different folders both apply.

• Globs use ** for any number of folders and * for one name segment. Separate several patterns with commas, as in src/**/*.tsx, docs/**/*.md.
• File references such as @src/server/routes/invoices.ts tell Agent where to look. The file is read with Agent's tools when needed, not pasted into the prompt, so put anything that must always be in context in the rule body.
• Three ways to create a rule: type /create-rule in Agent and describe it, use Add Rule under Customize, Rules, or run "New Cursor Rule" from the command palette.
• Length: Cursor recommends keeping each rule under 500 lines and splitting large ones into smaller rules.

10 example Cursor rules

These are starting points. Swap the bracketed paths and commands for your own, delete lines that don't fit, and commit them so the whole team gets the same behavior. Rules 1 to 8 are .mdc project rules covering all four types; 9 is AGENTS.md and 10 is a user rule.

1. Project basics (Always Apply)

Save as .cursor/rules/project-basics.mdc. The few facts Agent needs in every chat. Keep it short, because it is loaded every time.

---
alwaysApply: true
---
- Package manager is [pnpm]. Never use npm or yarn in commands or docs.
- Before saying a task is done, run [pnpm typecheck] and [pnpm test] and report the result.
- App code is in [src/], shared UI in [src/ui/], server code in [src/server/].
- Ask before adding a new dependency. Say what it does and why the existing code can't do it.
- Keep changes to the files the task needs. List any other file you think should change instead of editing it.

2. UI components (Apply to Specific Files)

Save as .cursor/rules/ui-components.mdc. Attaches only when a matching file is in context, so the backend never sees it.

---
globs: src/ui/**/*.tsx, src/app/**/*.tsx
alwaysApply: false
---
- Clickable things are <button> or <a>, never a div with an onClick.
- Every <img> has alt text. Decorative images use alt="".
- Use the color and spacing tokens from src/ui/tokens.ts. No raw hex values or pixel sizes.
- Every form input has a visible <label>. Placeholder text is not a label.
- Loading, empty and error states are part of the component, not a follow-up task.

3. Tests (Apply to Specific Files)

Save as .cursor/rules/tests.mdc. Keeps generated tests from drifting into a style nobody on the team uses.

---
globs: **/*.test.ts, **/*.test.tsx
alwaysApply: false
---
- Test runner is [Vitest]. Import from "vitest", not from jest.
- One behavior per test. Name tests as sentences: "returns 404 when the invoice does not exist".
- Use the factories in [tests/factories/] for data. Do not hand-write large fixtures.
- Do not mock the module under test. Mock only network calls and the clock.
- A bug fix comes with a test that fails before the fix and passes after it.

4. API route handlers (Apply Intelligently)

Save as .cursor/rules/api-routes.mdc. No globs, so Agent reads the description and decides when it is relevant.

---
description: Conventions for HTTP API route handlers, request validation and error responses
alwaysApply: false
---
- Validate the request body with the schema in the same folder before using any field.
- Check the user's permission for the specific record, not just that they are signed in.
- Errors return JSON shaped as { "error": { "code": "...", "message": "..." } } with the right status code.
- Never return stack traces or raw database errors to the client.
- Look at @src/server/routes/invoices.ts as the reference handler before writing a new one.

5. Error handling and logging (Apply Intelligently)

Save as .cursor/rules/errors-logging.mdc. Pulled in when Agent is writing code that can fail.

---
description: How to handle errors and write logs anywhere in the codebase
alwaysApply: false
---
- Use the logger from [src/lib/log.ts]. No console.log in committed code.
- Log one line per failure with an event name and ids, never with emails, tokens or full request bodies.
- Catch an error only where you can do something useful with it. Otherwise let it reach the request handler.
- Retries need a limit and a delay. No infinite loops around network calls.

6. Database schema changes (Apply to Specific Files)

Save as .cursor/rules/db-schema.mdc. Schema edits are where a confident wrong answer costs the most.

---
globs: prisma/schema.prisma, db/migrations/**
alwaysApply: false
---
- Every schema change ships with a migration. Never edit a migration that has already been merged.
- New columns on existing tables are nullable or have a default, so the migration runs on a full table.
- Renames happen in two steps: add the new column and backfill, then remove the old one in a later change.
- Add an index for any new column used in a WHERE clause on a large table, and say which query needs it.

7. Pull request description (Apply Manually)

Save as .cursor/rules/pr-description.mdc. No description, no globs: it applies only when you type @pr-description in chat.

---
alwaysApply: false
---
Write the pull request description from the current diff.
Sections: What changed (3 bullets max), Why, How to test (exact steps or commands), Risks, Screenshots needed (yes or no).
Mention any migration, new environment variable or feature flag at the top.
Do not describe files line by line. Do not claim tests pass unless you ran them in this chat.

8. Unfamiliar or legacy code (Apply Manually)

Save as .cursor/rules/careful-mode.mdc. Mention @careful-mode when you are working in code nobody fully understands.

---
alwaysApply: false
---
Before editing anything, explain how the code you are about to change works and list every caller you found.
Propose the smallest change that solves the task and wait for my approval.
Do not rename, reformat or reorganize anything that the task does not require.
If you are unsure what a function does, say so instead of guessing.

9. AGENTS.md for a subfolder

Save as [packages/mobile]/AGENTS.md. Plain markdown, no frontmatter. Cursor combines it with any parent AGENTS.md, and the more specific file wins.

# Mobile app instructions

## Stack
- React Native with Expo. Do not add native modules without asking.
- Navigation lives in src/navigation. Add new screens there, not inline.

## Rules
- Test layouts at small phone widths first.
- Strings go in src/i18n/en.json. No hard-coded user-facing text.
- Run [pnpm --filter mobile test] after changes in this folder.

10. A user rule for how Agent talks to you

Paste into Customize, Rules, under User Rules. It applies across all your projects and syncs with your account.

Reply in short paragraphs. Lead with the answer, then the reasoning.
When you change code, end with a list of the files you touched and anything I should test by hand.
If my request is ambiguous, ask one clarifying question before writing code.
Use British spelling in comments and docs.

How to test and debug a rule

Don't trust a rule until you've watched it change Agent's behavior. A quick routine:

1. Check the file. Is it in .cursor/rules, and does it end in .mdc? A .md file there is silently ignored.
2. Check its status. Open Customize, Rules. Cursor shows every rule and its status there, and team rules appear alongside your own.
3. Force it once. @-mention the rule in a new chat and give a task it should affect. If the output follows the rule, the content works and any problem is the trigger.
4. Test the trigger. For a file-pattern rule, open or tag a file that matches the glob and repeat the task. For an Apply Intelligently rule, make the description say plainly when it applies; Cursor's docs say this type needs one.
5. Watch for conflicts. A team rule or another project rule may say the opposite. Team rules take precedence, and an enforced one can't be switched off.

Rules don't make output correct, they make it consistent. Keep reviewing diffs the way our AI coding best practices describe, and when a rule keeps getting ignored, rewrite it as a concrete instruction rather than a value ("Use the logger in src/lib/log.ts" beats "write clean logs").

Rules or skills?

Cursor also has skills: SKILL.md files in folders such as .cursor/skills/your-skill-name/ that hold multi-step workflows. The help center draws the line clearly. Rules are short guidelines included as context in every chat or every matching chat; skills are longer procedures invoked on demand with /skill-name or @skill-name. "Use TypeScript for new files" is a rule. "Run the tests, build, deploy to staging and check health" is a skill. You can convert a rule into a skill with /create-skill, and Cursor 2.4 and later includes /migrate-to-skills for rules that have no globs and are not always applied.

Common mistakes

• Pasting a style guide. Cursor's docs suggest a linter for that. Agent already knows common conventions; rules should cover what is specific to you.
• Everything set to Always Apply. Each always-on rule takes context in every chat. Scope by file pattern or description where you can.
• Vague values instead of instructions. "Write good tests" changes nothing. "One behavior per test, use the factories in tests/factories" does.
• Copying code into rules. It goes stale. Point to a reference file with @ and let Agent read it.
• Forgetting .cursorrules is still there. Migrate it and delete it, so you aren't maintaining two sources of truth.
• Never updating rules. When Agent makes a mistake a rule should have prevented, fix the rule in the same pull request. Our guide to prompting for code quality covers the habits that make rules stick.

Frequently Asked Questions

What are Cursor rules?
Cursor rules are persistent instructions for Cursor's Agent. When a rule applies, its contents are included at the start of the model's context, so you don't have to repeat the same guidance in every chat. Cursor supports project rules, user rules, team rules and AGENTS.md.

Where do Cursor rules go?
Project rules go in .cursor/rules inside your repository as .mdc files and are version-controlled. User rules are set in Customize, Rules and sync with your Cursor account; user rule files in ~/.cursor/rules stay on that machine. Team rules live in the Cursor dashboard. AGENTS.md goes in the project root or any subdirectory.

Is .cursorrules deprecated?
Cursor's help center calls the .cursorrules file in the project root legacy and says it will be deprecated. To migrate, create a new project rule, paste the old contents in, set the type to Always Apply (which matches the old behavior) and delete .cursorrules.

What is the difference between .mdc and AGENTS.md?
A .mdc project rule has frontmatter (description, globs, alwaysApply) that controls when it applies. AGENTS.md is plain markdown with no metadata, so it is simpler but always in play for its folder. Cursor supports AGENTS.md in the root and in subdirectories, with more specific files taking precedence.

Why is my Cursor rule not being applied?
Check three things. The file must use the .mdc extension, because a plain .md file in .cursor/rules is ignored. An Apply Intelligently rule needs a description. An Apply to Specific Files rule needs a glob that matches files in context. Rules also do not apply to Tab completions or Bugbot pull request reviews.

Does Cursor read CLAUDE.md?
Yes. Cursor's help center says it reads CLAUDE.md files the same way it reads AGENTS.md, and that CLAUDE.md is always applied to every conversation regardless of any alwaysApply setting. Use project rules when you need conditional behavior.