Cursor Rules
Last reviewed
May 10, 2026
Sources
15 citations
Review status
Source-backed
Revision
v2 ยท 2,492 words
Improve this article
Add missing citations, update stale details, or suggest a clearer explanation.
Suggest edit
CtrlK
Last reviewed
May 10, 2026
Sources
15 citations
Review status
Source-backed
Revision
v2 ยท 2,492 words
Add missing citations, update stale details, or suggest a clearer explanation.
See also: Artificial intelligence terms
Cursor Rules are persistent natural-language instructions that steer the AI agent inside Cursor, the AI-powered code editor built by Anysphere. Rules let a developer or team encode project conventions, framework preferences, and recurring corrections into files the editor injects into every relevant prompt, so the model behaves consistently without retyping context. The original format used a single .cursorrules file at the project root. Since Cursor 0.45 (early 2025), the recommended format is one or more Markdown Domain Configuration (.mdc) files inside .cursor/rules/, each with YAML frontmatter that controls when the rule activates [1][2][3].
Cursor is a fork of Visual Studio Code that embeds large language models directly in the editor. The agent (formerly called Composer) can read files, run commands, and edit code using a chosen model such as Claude Sonnet, GPT, or Gemini. Without rules, the agent sees only what the user pastes plus whatever it autonomously decides to read. That works for short tasks, but on long sessions the model drifts: it forgets the project uses Drizzle instead of Prisma, reaches for any types, and rewrites tests in a style nobody else uses [1][3].
Rules solve this by adding a layer of always-available context. They are plain text, version-controlled with the rest of the codebase, and scoped so rules about React only fire when the agent touches React files. The mechanism resembles Claude Code's CLAUDE.md and GitHub Copilot's copilot-instructions.md, but Cursor goes further with structured frontmatter, glob-based scoping, and a declarative activation model [4][5].
| Benefit | What it looks like in practice |
|---|---|
| Customised agent behaviour | Agent prefers ?? over ||, picks fetch over axios, uses functional components over classes |
| Coding-standard enforcement | Strict typing, naming conventions, file layout, lint-clean output |
| Project context | Tech-stack summary, links to canonical files, pinned SDK versions |
| Hallucination reduction | Rule states "only use functions defined in src/lib/; do not invent new helpers" |
| Team alignment | Committing .cursor/rules/ to git keeps every developer's agent consistent |
| Recurring-issue mitigation | A new rule is added the third time the agent makes the same mistake |
Most teams that adopt rules follow the same arc: a single short .cursorrules file, then a folder of focused .mdc files as the project grows, then routine pruning when rules stop being useful [3][6].
Cursor itself launched in March 2023, built by Anysphere, incorporated in 2022 by Michael Truell, Sualeh Asif, Arvid Lunnemark, and Aman Sanger while they were students at MIT [7]. The first rules feature was a single .cursorrules file at the project root, treated as raw markdown that was always prepended to the agent's system prompt. Every rule was injected on every turn, eating tokens and confusing the model on unrelated tasks.
The modern Project Rules system shipped in Cursor 0.45.2 in early 2025. It introduced the .cursor/rules/ directory, the .mdc extension, YAML frontmatter, and four activation modes. Cursor 0.47 made the agent ignore .cursorrules by default, while still reading it when no .cursor/rules/ directory exists [3][8]. By Cursor 1.6 (mid-2025) the editor natively supported AGENTS.md, the cross-tool standard donated to the Linux Foundation in December 2025 and adopted by OpenAI Codex, Google Jules, Aider, and Zed [9][10].
| Cursor version | Rules milestone |
|---|---|
| 2023 launch | Single .cursorrules file at project root, always-on |
| 0.45.2 (early 2025) | Project Rules with .cursor/rules/*.mdc, four activation modes, glob scoping |
| 0.47 | Legacy .cursorrules deprecated, ignored by Agent mode unless no new rules exist |
| 1.6 (2025) | Native AGENTS.md support, including nested AGENTS.md files |
| Cursor 3.x (2026) | Continued use of .mdc; Cursor begins moving away from VS Code base |
Cursor recognises four layers of rules, evaluated in priority order from top to bottom [1][4]:
| Scope | Where it lives | Who maintains it | Applies to |
|---|---|---|---|
| Team Rules | Cursor dashboard (Team or Enterprise plans) | Org admins | Every member of the workspace |
| Project Rules | .cursor/rules/*.mdc in the repo | Anyone with commit access | Anyone working in that repo |
| User Rules | Cursor Settings, Rules tab | The individual developer | All projects on that machine, Agent chat only |
Legacy .cursorrules | Single file at project root | Repo committers | Read only when no .cursor/rules/ directory is present |
User Rules suit personal preferences such as "always write Python with type hints." Project Rules carry repository-specific knowledge: stack, conventions, file layout. Team Rules cover organisation-wide policies, security guardrails, or licence headers. Rules apply to Agent chat only and do not influence Tab autocomplete or the Cmd/Ctrl+K inline-edit feature [1][6].
A project rule is an .mdc (Markdown Domain Configuration) file. The first lines are a YAML frontmatter block, followed by the rule body in ordinary Markdown. The frontmatter has three optional fields:
---
description: "USE WHEN writing or editing React components"
globs: src/components/**/*.tsx, src/app/**/*.tsx
alwaysApply: false
---
# React conventions
- Functional components only; no class components.
- Use the canonical layout shown in `src/components/Button.tsx`.
- Co-locate styles in a sibling `*.module.css` file.
- No inline styles; use Tailwind utility classes.
| Field | Type | Purpose |
|---|---|---|
description | string | A short summary the agent reads to decide whether the rule is relevant to the current request |
globs | comma-separated patterns | File patterns that auto-attach the rule when matching files are referenced |
alwaysApply | boolean | When true, the rule is injected into every Agent session |
The combination of these three fields determines the activation mode [1][2][6].
Cursor's documentation and the community converged on four activation modes, sometimes called rule types. Choosing the right mode is the single most important decision when authoring a rule [1][3][6].
| Mode | Frontmatter combination | When the agent loads it |
|---|---|---|
| Always Apply | alwaysApply: true | Every Agent turn, regardless of files or topic |
| Auto-Attached | globs: set, alwaysApply: false | When the user references or the agent opens a file matching the glob |
| Agent-Requested | description: set, no globs, alwaysApply: false | When the model decides the description matches the user's intent |
| Manual | All three fields empty | Only when invoked with @rule-name in chat |
Always Apply rules are the most expensive: their entire body prepends every prompt, so a 500-word always-on rule can cost 700 tokens before the user types anything. The community guideline is to keep all alwaysApply: true rules combined under roughly 2,000 tokens, or about 500 lines [2][6]. Auto-Attached rules are the most reliable, because activation is a deterministic glob match; they suit framework-specific guidance such as a tests/**/*.py rule about pytest conventions [1][2]. Agent-Requested rules depend on the model interpreting the description, so they work best when the description starts with a trigger phrase such as "USE WHEN writing tests," and they fail silently on weaker models [3][8]. Manual rules sit dormant until the developer types @rule-name in the chat box and suit long checklists or migration guides that should not eat context every turn [2][6].
The fastest path is the command palette: press Cmd+Shift+P (or Ctrl+Shift+P), type New Cursor Rule, and pick a name. Cursor scaffolds an empty .mdc file with frontmatter inside .cursor/rules/. The same dialog is available under Cursor Settings, Rules and Commands, then Add Rule. Inside an Agent chat, typing /create-rule opens an interactive flow that helps draft the body and pick the activation mode [1][6]. Subdirectories may have their own .cursor/rules/ directory scoped to that folder, which is the natural way in a monorepo to separate apps/web rules from apps/mobile rules [1][2].
The following react-server-components.mdc is a typical Auto-Attached rule for a Next.js 15 project:
---
description: "React Server Components conventions for Next.js 15 App Router"
globs: app/**/*.tsx, app/**/*.ts
alwaysApply: false
---
# React Server Components
This project targets Next.js 15.2 and React 19.
- Default to Server Components. Add `"use client"` only when the file uses
hooks, browser APIs, or event handlers.
- Data fetching belongs in Server Components or `app/**/route.ts` route
handlers. Do not call `fetch` from a Client Component.
- Forms post to a Server Action declared with `"use server"`.
- Follow the canonical layout in `app/(marketing)/page.tsx`.
The rule activates whenever the agent touches a file under app/. It pins the framework version and points to a canonical file to copy from. Cursor's in-editor MDC view has historically mangled frontmatter, so community guides recommend a plain text editor for new rules [3][6].
The pattern that comes up across vendor docs, the Cursor forum, and writeups by teams such as Atlan and Trigger.dev is the same: keep rules short, specific, and reactive [3][11][12].
| Practice | Why it matters |
|---|---|
| Keep individual rule files under 500 lines | Long rules dilute attention; the model picks up the first few hundred tokens and skims the rest |
Cap combined alwaysApply rules under about 2,000 tokens | Prevents 8-12% of the context window being burned before any code is read |
| Pin SDK versions explicitly | "Next.js 15, React 19, Drizzle 0.38" beats "latest Next.js," which the model interprets from training data |
| Reference canonical files instead of pasting code | A path like src/components/Button.tsx stays current; pasted snippets go stale |
| Use forceful language for prohibitions | "NEVER call fetch from a Client Component" lands harder than "prefer not to" |
| Add verification steps | "After writing an API route, confirm it validates the request body with Zod" gives the model something to check itself against |
| Start minimal, expand when the agent repeats mistakes | Premature rules add noise; reactive rules earn their place |
Commit .cursor/rules/ to git | Shared rules are the only way to keep a team's agent behaviour aligned |
Avoid setting both globs and description | The two activation paths can fight each other; pick one |
The most common mistakes Cursor users describe are stuffing every preference into one giant .cursorrules file, marking everything alwaysApply: true, and writing vague guidance such as "write good code" [2][6].
Each of the major AI coding tools has its own configuration file and activation model. For a team that runs several tools side by side, the practical question is how much content can be reused.
| Tool | Config file | Format | Scoped activation | Applies to autocomplete? |
|---|---|---|---|---|
| Cursor | .cursor/rules/*.mdc (modern), .cursorrules (legacy), AGENTS.md (since 1.6) | Markdown plus YAML frontmatter | Yes, four modes including glob and intent matching | No, Agent chat only |
| Claude Code | CLAUDE.md at project root and in subdirectories | Markdown, with @path imports and a memory subsystem | Yes, hierarchical: subdirectory CLAUDE.md files load on demand | N/A, Claude Code is terminal-based |
| GitHub Copilot | .github/copilot-instructions.md plus path-specific *.instructions.md | Markdown | Repo-wide plus path-specific | No, Chat, code review, and coding agent only |
| AGENTS.md (cross-tool standard) | AGENTS.md at project root and nested | Plain Markdown | Hierarchical, by directory | Depends on the host tool |
Claude Code's CLAUDE.md and Cursor's project rules solve the same problem with different ergonomics: CLAUDE.md leans on file imports and a longer-form memory model, Cursor on glob-based scoping and frontmatter. For a team using both, the simplest path is an AGENTS.md file as the shared baseline, with tool-specific files added only when one tool needs something the other does not [4][5][9].
The largest curated collection is Awesome CursorRules, maintained by PatrickJS, with roughly 39,000 stars on GitHub and over 150 examples organised across thirteen categories. It covers Next.js, TypeScript, Python, Go, Rust, Solidity, and Unity templates [13]. Cursor Directory, founded by Pontus Abrahamsson in August 2024, is the other major hub; it reached the front page of Hacker News in its launch weekend and now distributes rules through a Raycast extension and a public API, with rankings based on copy count. It hosts rules for shadcn/ui, Trigger.dev, tRPC, Expo, and dozens more [14]. The awesome-cursor-rules-mdc collection by Sanjeed focuses on the modern .mdc format and includes 879 examples organised by stack [15].
Rules are strong context, not strong control. The agent still chooses whether to follow a given rule, and weaker models follow them less reliably. A few practical limits are worth knowing about:
description. Vague descriptions or smaller models leave the rule idle [3][8].alwaysApply rules eat into it before the user types anything [2][6].None of this makes rules a bad idea; it just means they are tooling, not policy. Treat them like a .editorconfig or .eslintrc for the model: useful and version-controlled, but not a substitute for code review.
CLAUDE.mdcopilot-instructions.md