Cursor Rules: Project, User and Team Rules with Examples

November 11, 2026 · 12 min read

Cursor Rules: Write Project, User and Team Rules (With Examples)

Cursor rules are persistent Markdown instructions that Cursor's Agent reads before it writes code, so you stop repeating the same conventions in chat. Project rules live as .mdc files in .cursor/rules, User Rules follow you across projects, and Team Rules come from your org. Below you'll build a working three-file set.

What Are Cursor Rules and How Does Cursor Use Them?

Every new Agent chat starts without your project's conventions. Rules fix that by adding the same guidance to every relevant conversation. According to Cursor's rules documentation, an applied rule's contents go at the start of the model context, before your prompt.

Cursor supports four kinds of rules:

  • Project Rules: .mdc files in .cursor/rules, committed to git and scoped to one codebase.
  • User Rules: your personal preferences, applied across every project you open.
  • Team Rules: org-wide rules managed from the Cursor dashboard on Team and Enterprise plans.
  • AGENTS.md: a plain Markdown file with no frontmatter, read from the project root and subfolders. Cursor also applies a root CLAUDE.md to every chat. Our guides to the AGENTS.md file and the CLAUDE.md file explain how to write each one.

Rules only reach Agent (the chat). They don't change Tab completion, and they don't feed Bugbot's pull request reviews. The rule body is ordinary Markdown, and headings and short bullets give the model a clear structure to follow. Our explainer on Markdown in AI covers why that format suits language models.

The Cursor Rules File: .mdc Format and Frontmatter Fields

A Cursor rules file is a Markdown document with a .mdc extension. You can name it anything and group files in subfolders. The extension matters: a plain .md file inside .cursor/rules is ignored, because the rules system needs frontmatter to decide when to load it.

.cursor/rules/
  project-basics.mdc        loaded as a rule
  api-guidelines.md         ignored (wrong extension)
  frontend/
    components.mdc          subfolders work too

Each file opens with a small YAML block between two --- lines, then the rule body in ordinary Markdown. Cursor reads three fields:

  • description: a sentence Agent uses to judge whether the rule is relevant.
  • globs: file patterns that attach the rule automatically, separated by commas.
  • alwaysApply: true loads the rule in every chat and ignores the other two fields.

That header is the same kind of block static site generators use, so our guide to Markdown frontmatter explains the YAML syntax if it's new to you. Cursor's editor also sets these fields for you through a type dropdown, so you rarely type them by hand.

The Four Rule Types: Always, Specific Files, Intelligently and Manually

The dropdown in Cursor offers four rule types. Each one is just a combination of the three frontmatter fields:

Rule typeFrontmatterWhen Cursor loads it
Always ApplyalwaysApply: trueEvery chat session
Apply to Specific FilesalwaysApply: false plus globsWhen a matching file is in context
Apply IntelligentlyalwaysApply: false plus descriptionWhen Agent decides the description fits the task
Apply ManuallyalwaysApply: false, no globs or descriptionOnly when you @-mention it, such as @my-rule

Older guides and community repos call the second and third types Auto Attached and Agent Requested. Only the labels changed; the behaviour is the same.

Globs follow the usual patterns. src/**/*.tsx matches every .tsx file anywhere under src/, **/*.ts matches TypeScript in any folder, and docs/**/*.md, docs/**/*.mdx combines two patterns with a comma. If a glob rule never fires, compare the pattern with a real file path first. A misspelled folder name is the usual culprit.

How to Create a Rule and Migrate From .cursorrules

You have three ways to create a project rule, and all of them write a file into .cursor/rules:

  1. Type /create-rule in Agent chat and describe what you want. Agent writes the file with frontmatter.
  2. Open Customize in the sidebar, choose Rules, then click Add Rule.
  3. Open the command palette (Cmd+Shift+P on Mac, Ctrl+Shift+P on Windows and Linux) and run New Cursor Rule.

You can also create the .mdc file yourself in any editor. Cursor picks it up from the folder.

Older projects often keep a single .cursorrules file in the repo root. Cursor's help page on rules calls that file legacy and says it will be deprecated. Migrating takes four steps:

  1. Create a new rule with New Cursor Rule.
  2. Copy the contents of .cursorrules into the new rule file.
  3. Set the rule type to Always Apply, which matches the old file's behaviour.
  4. Delete .cursorrules from the project root.

If you're starting from scratch, our CLAUDE.md generator is a browser form that fills CLAUDE.md, AGENTS.md, a legacy .cursorrules file and .github/copilot-instructions.md from one project description. It doesn't write .mdc files, so treat its .cursorrules output as the body you paste into a new Always Apply rule.

Cursor Rules Examples: A Three-File Set for a Real Project

Fragments are easy to find. A complete set is more useful, so here are three small rules for a TypeScript Next.js app that uses pnpm. Each file shows a different rule type.

The first file holds the facts Agent needs in every chat. Keep it short, because it costs context on every request.

---
alwaysApply: true
---

- This is a Next.js app written in TypeScript with strict mode on
- Use pnpm for every install and script, never npm or yarn
- Run `pnpm lint` and `pnpm test` before you call a task finished
- Never edit files in `.next/`, `dist/` or `src/generated/`
- Read environment values through `src/env.ts`, not `process.env`
- Ask before adding a new dependency

Save it as .cursor/rules/project-basics.mdc. Cursor includes it in every Agent chat in this repo.

The second file only matters when you touch components, so a glob scopes it.

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

# React component rules

- Use named exports, never default exports
- Style with Tailwind utility classes, not inline styles
- Type props with an interface named after the component
- Keep each component under 150 lines; split out subcomponents

## Testing

- Put tests next to the component as `Name.test.tsx`
- Test behaviour through the rendered output, not internal state

Save it as .cursor/rules/react-components.mdc. Cursor attaches it when a matching .tsx file is in context.

The third file has no glob, only a description. Agent reads that sentence and decides when the rule applies.

---
description: Conventions for writing and reviewing SQL database migrations
alwaysApply: false
---

- Every migration needs a matching rollback
- Never change a column type in place. Add a new column, backfill it,
  then drop the old one in a later migration
- Name files `YYYYMMDDHHMM_short_description.sql`
- Read @db/migration-template.sql for the expected structure first

Save it as .cursor/rules/database-migrations.mdc. Agent pulls it in when it judges the description relevant, such as when your request involves migrations. The @db/migration-template.sql mention isn't pasted into the prompt. Agent opens that file with its tools when it needs it, so anything that must always be present belongs in the rule body itself.

Before you save a rule, check that its headings and lists read cleanly. The editor below holds the body of the component rule, and you can paste your own rule in its place. Our preview doesn't render the YAML frontmatter block, so leave that part out and check the Markdown alone.

React component rules

  • Use named exports, never default exports
  • Style with Tailwind utility classes, not inline styles
  • Type props with an interface named after the component
  • Keep each component under 150 lines

Testing

  • Put tests next to the component as Name.test.tsx
  • Test behaviour through the rendered output
File Convention
Button.tsx export function Button
Button.test.tsx Render it, click it, check the result
83 words465 characters16 lines
Markdown

User Rules and Team Rules: Global Preferences vs Org Standards

Cursor user rules, sometimes called global rules, hold your personal preferences. You set them in Customize, under Rules, and they apply to every project you open. They sync with your Cursor account, so a new machine picks them up when you sign in. The help page also lists local rule files in ~/.cursor/rules, which stay on that machine and don't sync.

User Rules suit personal taste: reply tone, how much explanation you want, a preferred test style. Keep project facts out of them, since your teammates never see your User Rules.

Cursor team rules sit one level higher. On Team and Enterprise plans, admins write them in the Cursor dashboard as free-form text, without the .mdc folder structure. An admin can mark a rule as enforced, so members can't turn it off, or leave it optional. Team Rules also accept globs such as **/*.py.

When several sources apply, Cursor merges them in this order: Team Rules, then Project Rules, then User Rules. If guidance conflicts, the earlier source wins. A practical split looks like this:

  • Team: security and compliance basics that every repo shares.
  • Project: stack, commands, folder layout and file-specific conventions.
  • User: your own tone and working style.

Cursor Rules vs Skills: Which Should You Use?

Skills are Cursor's other way to teach Agent. A skill is a folder holding a SKILL.md file, stored under .cursor/skills/ or .agents/skills/ in the project, or the same folders in your home directory. You run one with /skill-name, attach it with @, or let Agent pick it from its description.

Cursor's skills help page draws the line clearly:

RulesSkills
PurposeShort guidelines and constraintsMulti-step workflows and procedures
LengthA few lines to a few hundredOften longer, with step-by-step detail
How appliedIncluded as context in every or matching chatInvoked on demand, or chosen by Agent
ExampleUse TypeScript for all new filesDeploy to staging: test, build, deploy, verify

From Cursor 2.4, the built-in /migrate-to-skills skill converts slash commands and rules that have neither alwaysApply: true nor globs into skills. It skips Always Apply and glob rules, because their triggers don't map onto how skills load. It also skips User Rules, which aren't stored as files.

We prefer keeping always-on rules to a handful of lines and moving any procedure longer than a checklist into a skill. The always-on rule then stays cheap, and the long procedure only loads when you need it.

Cursor Rules Best Practices and Where to Find More Examples

Cursor's own guidance is short and worth following. The list below comes straight from its docs:

  • Keep each rule under 500 lines, and split big ones into focused files.
  • Reference files with @path instead of copying code that will go stale.
  • Don't paste a whole style guide. A linter enforces style better, and Agent already knows common conventions.
  • Add a rule only after Agent repeats the same mistake.
  • Check .cursor/rules into git so the whole team gets the same guidance.

Write rules the way you'd write clear internal docs: short sentences, one instruction per bullet. Our guide to writing documentation in Markdown applies almost word for word. Rules also differ from a README: the README explains the project to people, while a rule tells the agent what to do.

One limitation is easy to forget. Rules are context, not enforcement. Agent can still ignore or misread them, so anything that must never happen belongs in a linter, a test or a CI check.

For ready-made examples, the community list awesome-cursorrules on GitHub collects .mdc rule files grouped by framework and language. It's where many people look first for the best Cursor rules for a given stack, and community sites such as cursor.directory gather similar collections.

Treat any community rule as a draft: delete the lines your project doesn't need before you commit it. To bring rules in from a GitHub repository, Cursor's docs say to package them in a plugin and publish it through a marketplace.

Frequently Asked Questions

Good Cursor rules stay small. Keep one always-on file with the facts Agent needs every time, a few scoped rules for specific folders, and skills for anything that reads like a procedure. Start with the three-file set above, then add a rule only when Agent repeats a mistake. To draft a starting body, try the CLAUDE.md generator, then check the Markdown in the editor before you save it as an .mdc file.