# Cursor Rules

> Source: https://aiwiki.ai/wiki/cursor_rules
> Updated: 2026-06-24
> Categories: Artificial Intelligence
> From AI Wiki (https://aiwiki.ai), a free encyclopedia of artificial intelligence. Quote with attribution.

*See also: [Artificial intelligence terms](/wiki/artificial_intelligence_terms)*

**Cursor Rules** are persistent natural-language instructions that steer the AI agent inside [Cursor](/wiki/cursor), the AI-powered code editor built by Anysphere. They 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. Cursor's official documentation frames the feature plainly: "Rules provide system-level instructions to Agent" and, because "large language models don't retain memory between completions," rules "provide persistent, reusable context at the prompt level" [1]. 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].

## Overview

Cursor is a fork of [Visual Studio Code](https://en.wikipedia.org/wiki/Visual_Studio_Code) that embeds [large language models](/wiki/large_language_model) directly in the editor. The agent (formerly called Composer) can read files, run commands, and edit code using a chosen model such as [Claude](/wiki/claude) Sonnet, [GPT](/wiki/gpt), or [Gemini](/wiki/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 are a form of applied [prompt engineering](/wiki/prompt_engineering) and [AI code generation](/wiki/ai_code_generation) configuration: standing instructions, not one-off prompts.

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](/wiki/claude_code) and GitHub Copilot's `copilot-instructions.md`, but Cursor goes further with structured frontmatter, glob-based scoping, and a declarative activation model [4][5].

### What are Cursor Rules used for?

| 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].

## When were Cursor Project Rules introduced?

Cursor itself launched in March 2023, built by [Anysphere](https://en.wikipedia.org/wiki/Anysphere), incorporated in 2022 by [Michael Truell](/wiki/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 OpenAI released in August 2025 and contributed in December 2025 to the [Linux Foundation's](/wiki/linux_foundation) newly formed Agentic AI Foundation (AAIF), alongside the Model Context Protocol and Block's goose; by mid-2026 AGENTS.md had been adopted by more than 60,000 open-source projects and tools including OpenAI Codex, Google Jules, GitHub Copilot, Devin, Aider, and Zed [9][10][16].

| 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 |

## What are the different types of Cursor Rules?

Cursor recognises four layers of rules, evaluated in priority order from top to bottom; the official docs describe the merge as "Team Rules, Project Rules, User Rules. All applicable rules are merged; earlier sources take precedence" [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. Per Cursor's own FAQ, User Rules "are not applied to Inline Edit (Cmd/Ctrl+K); they are only used by Agent (Chat)," and "rules do not impact Cursor Tab or other AI features" [1][6].

## What does a .mdc rule file look like?

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]. Rules can also pull in other files with an `@filename` reference, which keeps a rule short by pointing at a canonical example instead of pasting it, and avoids the snippet going stale [1].

## What are the four Cursor rule types?

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].

## How do you create a Cursor rule?

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].

### A worked example

The following `react-server-components.mdc` is a typical Auto-Attached rule for a [Next.js](https://nextjs.org) 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].

## What are the best practices for writing Cursor Rules?

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. Cursor's own documentation states the headline rule directly: "Keep rules under 500 lines" and "split large rules into multiple, composable rules" [1][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].

## How do Cursor Rules compare to CLAUDE.md and AGENTS.md?

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](/wiki/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](/wiki/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](/wiki/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](https://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. AGENTS.md, which describes itself as "a README for agents: a dedicated, predictable place to provide the context and instructions to help AI coding agents work on your project," is the closest thing to a neutral common denominator across the ecosystem [4][5][9][16].

## The community ecosystem

The largest curated collection is [Awesome CursorRules](https://github.com/PatrickJS/awesome-cursorrules), maintained by PatrickJS, with roughly 40,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](https://cursor.directory), founded by Pontus Abrahamsson in August 2024, is the other major hub; it reached the front page of [Hacker News](/wiki/hacker_news) in its launch weekend with about 364,000 page views 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][17]. The `awesome-cursor-rules-mdc` collection by Sanjeed focuses on the modern `.mdc` format and includes 879 examples organised by stack [15].

## What are the limitations of Cursor Rules?

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:

- **Coverage gap.** Rules apply to Agent chat; per Cursor's FAQ, User Rules are not applied to Inline Edit (Cmd/Ctrl+K) and rules do not impact Cursor Tab autocomplete, so the same project can produce inconsistent code depending on which surface was used [1][6].
- **Activation guesswork.** Agent-Requested rules rely on the model interpreting the `description`. Vague descriptions or smaller models leave the rule idle [3][8].
- **Context budget.** The Cursor agent has a finite context window, and `alwaysApply` rules eat into it before the user types anything [2][6].
- **Frontmatter fragility.** Cursor's in-editor MDC view has historically corrupted frontmatter, particularly when copying rules from web pages with smart quotes [3][6].
- **Skill atrophy.** Developers on the Cursor forum and Hacker News have flagged that aggressive rule use combined with broad agent autonomy reduces the amount of architecture the developer thinks through directly [3][12].

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.

## Related concepts

- [Cursor](/wiki/cursor): the editor that hosts the rules system
- [Claude Code](/wiki/claude_code): Anthropic's terminal-based agent, configured through `CLAUDE.md`
- [GitHub Copilot](/wiki/github_copilot): Microsoft's AI assistant, configured through `copilot-instructions.md`
- [Prompt engineering](/wiki/prompt_engineering): the discipline of writing instructions like rules
- [AI code generation](/wiki/ai_code_generation): the broader practice rules are meant to steer
- [Large language model](/wiki/large_language_model): the underlying model class

## References

1. Cursor, "Rules," Cursor Docs, https://cursor.com/docs/rules
2. Morph, "Cursor Rules Best Practices: Complete .mdc Guide," 2026, https://www.morphllm.com/cursor-rules-best-practices
3. Cursor Community Forum, "A Deep Dive into Cursor Rules (> 0.45)," https://forum.cursor.com/t/a-deep-dive-into-cursor-rules-0-45/60721
4. Agent Rules Builder, "Cursor Rules vs CLAUDE.md vs Copilot Instructions," https://www.agentrulegen.com/guides/cursorrules-vs-claude-md
5. DeployHQ, "CLAUDE.md, AGENTS.md and Copilot Instructions: Configure Every AI Coding Assistant," https://www.deployhq.com/blog/ai-coding-config-files-guide
6. Vibe Coding Academy, "Cursor Rules: Complete .mdc Guide and 15 Templates," 2026, https://www.vibecodingacademy.ai/blog/cursor-rules-complete-guide
7. Wikipedia, "Cursor (code editor)," https://en.wikipedia.org/wiki/Cursor_(code_editor)
8. Cursor Community Forum, "Using the project-rules in 0.45.2," https://forum.cursor.com/t/using-the-project-rules-in-0-45-2/44447
9. agents.md, "AGENTS.md: A simple, open format for guiding coding agents," https://agents.md/
10. InfoQ, "AGENTS.md Emerges as Open Standard for AI Coding Agents," August 2025, https://www.infoq.com/news/2025/08/agents-md/
11. Atlan Engineering, "Cursor Rules in Action: How Our Engineers Use It at Atlan," https://blog.atlan.com/engineering/cursor-rules/
12. Trigger.dev, "How to write great Cursor Rules," https://trigger.dev/blog/cursor-rules
13. PatrickJS, "Awesome CursorRules," GitHub, https://github.com/PatrickJS/awesome-cursorrules
14. Cursor Directory, https://cursor.directory/
15. Sanjeed, "awesome-cursor-rules-mdc," GitHub, https://github.com/sanjeed5/awesome-cursor-rules-mdc
16. Linux Foundation, "Linux Foundation Announces the Formation of the Agentic AI Foundation (AAIF)," December 9, 2025, https://www.linuxfoundation.org/press/linux-foundation-announces-the-formation-of-the-agentic-ai-foundation
17. Pontus Abrahamsson (@pontusab), "Last weekend, we launched Cursor Directory and reached the front page of Hacker News with 364k page views," X, August 2024, https://x.com/pontusab/status/1830284322794045556