Cursor rules: .mdc format, rule types and a team setup

Updated October 12, 2026 · 9 min read

Cursor rules are instructions that Cursor adds to the start of the model’s context when its Agent works. Cursor lists four kinds: project rules (.mdc files in .cursor/rules, checked into git), user rules (your own preferences), team rules (set from the dashboard on Team and Enterprise plans) and AGENTS.md. For a team that also uses other agents, put shared instructions in AGENTS.md, use project rules for guidance scoped to certain files, and keep team rules for the few things that must hold in every repository.

The Cursor facts below come from its rules reference and rules help page, read on 12 October 2026.

What kinds of Cursor rules are there?

When guidance conflicts, team rules come first, then project rules, then user rules. Cursor merges every rule that applies, and the earlier source takes precedence.

Rules reach Agent (Chat) only. Cursor’s help page says they do not apply to Tab completion, Inline Edit (Cmd/Ctrl+K) or Bugbot PR reviews.

What does a Cursor rule file look like?

A project rule is a markdown file with frontmatter, saved with the .mdc extension in .cursor/rules/. A plain .md file in that folder is ignored, because it has no frontmatter to say when it applies. If you want plain markdown with no metadata, Cursor points you to AGENTS.md instead.

The frontmatter has three fields: description, globs and alwaysApply. You can type them yourself or pick a type from the dropdown in the editor, which sets them for you.

---
description: How to add or change an RPC service in the backend
alwaysApply: false
---

- One service per file under `src/services/`
- Validate inputs at the service boundary
- Return errors as `{ code, message }`, never as raw strings
- For a new service, follow the structure of `@src/services/_template.ts`

Rules can sit in subfolders of .cursor/rules/, though the help page recommends a flat folder with descriptive names. Cursor identifies a rule by its full path, so two rules with the same file name in different folders both apply when their conditions match.

An @-mention of a file, like @src/services/_template.ts above, tells Agent where to look. Agent reads the file when it needs it; the contents are not pasted into the prompt. Anything that must always be in context goes in the rule body.

You can create a rule three ways: type /create-rule in Agent and describe it; open Customize, then Rules, then Add Rule; or run “New Cursor Rule” from the command palette (Cmd+Shift+P on Mac, Ctrl+Shift+P on Windows and Linux).

When does Cursor apply a rule?

The three fields decide it:

globs takes comma-separated patterns: **/*.ts matches TypeScript files in any directory, *.ts only those in the root, and docs/**/*.md, docs/**/*.mdx covers two extensions under docs/.

An Always Apply rule sits in every conversation whether it is relevant or not, so keep those few and short and scope the rest (our context engineering guide explains why). If a rule never loads, Cursor’s FAQ gives two causes: an Apply Intelligently rule with no description, or a glob that matches none of your files.

How many projects use Cursor rules?

Few, compared with the files other agents read. We checked the same 1,000 most-starred active GitHub repositories as our CLAUDE.md examples study, using the repo list from 1 October 2026, and looked for each file on 12 October 2026:

Only 34 repositories (3.4%) have Cursor rules. AGENTS.md is in more than ten times as many, and CLAUDE.md in more than seven times as many. Of the 10 with .cursorrules, 3 also have .cursor/rules, so 7 still rely on the legacy file alone. Of the 52 with a .cursor directory, 25 have no rules folder in it, and projects that do use project rules keep few: the median is 2 files. Our Copilot instructions guide reads the copilot-instructions.md files from the same list.

These are public projects whose contributors use many different tools, which favors files that every agent reads. A private team that has standardized on Cursor may look different; we did not measure that. The 259 counts a CLAUDE.md at the repository root; our CLAUDE.md examples page says 270 because it also counts CLAUDE.md files in .claude/.

How do I migrate from .cursorrules?

Cursor’s help page calls .cursorrules legacy and says it will be deprecated. Its steps:

1. Run “New Cursor Rule” from the command palette.
2. Copy the contents of .cursorrules into the new rule.
3. Set the type to Always Apply, which matches the old behavior.
4. Delete .cursorrules from the project root.

Then split it: lines for some files become rules with globs, procedures become Apply Intelligently rules, and lines every agent needs move to AGENTS.md.

Cursor rules examples

The RPC rule above is the Apply Intelligently kind. The illustrative rule below is scoped to test files. We left out an Always Apply example on purpose, since in a repository shared with other agents that content belongs in AGENTS.md.

---
globs: **/*.test.ts, **/*.test.tsx
alwaysApply: false
---

- Use Vitest. Import `describe`, `it` and `expect` from `vitest`
- One behavior per `it` block, named as a sentence
- Mock HTTP with `msw` instead of stubbing `fetch`
- Run only the file you changed: `pnpm vitest run <path>`

For starting points, awesome-cursorrules is a public collection whose README links more than 200 .mdc rules, grouped by area, such as frontend frameworks, testing and specific languages. It helps most when you adopt a new stack and want to see how others scope a rule. Treat what you copy as a draft. Cursor’s own advice is to skip whole style guides (use a linter), skip common commands Agent already knows, and add a rule only when Agent makes the same mistake more than once. Keep each rule under 500 lines and split large ones.

Does Cursor have team rules?

Yes, on Team and Enterprise plans; our guide to the Cursor Teams plan covers its seat prices and admin roles. Admins create them in the Cursor dashboard, and they apply to Agent (Chat) for every member across all repositories and projects. Two settings control each rule:

• “Enable this rule immediately”: unchecked saves the rule as a draft.
• “Enforce this rule”: members cannot turn it off in Customize. Rules that are not enforced are on by default, and each member can switch them off.

Team rules are free-form text with no folder structure, and profile exports leave them out. They support globs such as **/*.py; a rule without one applies to every conversation. Cursor adds that AI guidance should not be your only security control, even when a rule is enforced.

Use team rules for the few standards that cross repositories. Keep repository-specific rules in .cursor/rules, where changes go through pull requests with the code they describe. Cursor does not import rules on their own: to bring rules in from a GitHub repository, it has you package them in a plugin and publish that plugin through a marketplace.

How do I keep Cursor rules in step with CLAUDE.md and AGENTS.md?

Each tool reads a different set of files:

• Cursor reads AGENTS.md in the root and in subdirectories. Nested files combine with their parents, and the more specific one wins.
• Cursor reads a root CLAUDE.md the same way and applies it to every conversation, whatever its frontmatter says.
• Claude Code reads CLAUDE.md. By default it reads AGENTS.md only when there is no CLAUDE.md or CLAUDE.local.md in your working directory or above it, and reading AGENTS.md directly needs Claude Code v2.1.277 or later (Anthropic’s memory docs). A CLAUDE.md that imports @AGENTS.md gets both.
• Anthropic’s memory docs list the files Claude Code loads, such as CLAUDE.md, CLAUDE.local.md, .claude/rules/ and AGENTS.md; .cursor/rules is not on that list.

A layout that gives every agent one source of truth:

AGENTS.md              # commands, conventions, architecture: for every agent
CLAUDE.md              # @AGENTS.md, then a few Claude Code notes
.cursor/rules/
  tests.mdc            # globs: **/*.test.ts
  migrations.mdc       # globs: db/migrations/**/*.sql
  feature-flags.mdc    # description only, pulled in when relevant

Give each instruction one home. If a convention is in AGENTS.md, do not repeat it in an .mdc file, where the two copies will drift. Because Cursor applies CLAUDE.md to every conversation, anything else you write there reaches Cursor’s Agent too, so keep it to the import and lines that hold for both tools. We have not tested how Cursor treats the @AGENTS.md line itself; its docs say @-mentions in rules are not inlined, and Cursor loads AGENTS.md on its own anyway.

The AGENTS.md guide lists what Codex, Claude Code and other agents read, and the CLAUDE.md guide covers imports and scopes. For how teams structure the Claude side, see Claude Code best practices.

What do Cursor rules not cover?

Rules are short instructions that Cursor loads into a conversation, and project and team rules reach only Cursor’s Agent. Knowledge that is not an instruction, such as why the team picked a vendor, what an incident review found or how three services fit together, outgrows a 500-line rule, and the other agents need it too.

For a team that runs only Cursor and shares only conventions, project rules and team rules are enough; if several agents need the same conventions, AGENTS.md in git covers it at no cost. A shared wiki fits what grows past that.

Dexio is a hosted wiki that AI agents read and write over MCP. Cursor, Claude Code, Codex and your other agents search, read, write and link markdown pages in one wiki, and people see what their agents know as a page graph. Every change names the agent that made it and can carry a note saying why. It is open source (AGPL-3.0), free for one person, and agents never count as paid members.

Cursor connects through ~/.cursor/mcp.json; the Cursor MCP guide has the steps. Then add a rule that tells Agent when to use the wiki:

---
description: Team wiki. Use before working on an unfamiliar area, and to record decisions
alwaysApply: false
---

- Search the Dexio wiki with `search_pages` before you work on a topic
- When you work out something the team will need again, update the page
  that exists or write a new one
- Pass the `base_version` from `read_page` when you change a page
- Put "Cursor" in the `agent` field on every change

FAQ

Is .cursorrules deprecated?

Cursor’s help page calls it legacy and says it will be deprecated. Move its contents into an Always Apply project rule, then split it up.

Do Cursor rules apply to Tab and Inline Edit?

No. Rules apply to Agent (Chat) only, not to Tab, Inline Edit or Bugbot PR reviews.

How long should a Cursor rule be?

Under 500 lines, per Cursor. Split anything longer into focused rules.

Sources

• https://cursor.com/docs/rules
• https://cursor.com/help/customization/rules
• https://github.com/PatrickJS/awesome-cursorrules
• https://code.claude.com/docs/en/memory
• https://dexio.wiki/agents.md
• https://dexio.wiki/docs/
• https://dexio.wiki/pricing/