What Are Cursor Project Rules?
Project rules are Cursor's structured instructions. They live in .cursor/rules/, are committed with the code, and can be organized into subfolders. Each rule is a file with the .mdc extension: a plain .md file in that folder is ignored by the rules system because it has no frontmatter.
Last verified 2026-11-13 against the vendor documentation. Cursor also supports AGENTS.md in the project root and in subdirectories, as a simpler alternative for instructions that do not need scoping. Other agents do not read .mdc files; see the compatibility table.
What Goes in the .mdc Frontmatter?
Three fields control how a rule is applied:
alwaysApply: when true, the rule is included in every chat session, and globs and description are ignored.globs: file patterns, separated by commas; the rule attaches when the agent works on matching files.description: a sentence the agent reads to decide whether the rule is relevant.
A rule with none of these set applies only when you mention it. Here is the always-on rule 2prompt generates, which defers to AGENTS.md:
---
description: Project instructions for every task (mirrors AGENTS.md)
globs:
alwaysApply: true
---
# Project rules
The project instructions live in @AGENTS.md at the repository root, which Cursor loads automatically. They are not repeated here, so they cost context only once. Edit AGENTS.md, not this rule.
Before you change code, check the Commands and Working rules sections of AGENTS.md, and run its test and lint commands before you say a task is done.
Put Cursor-only rules below, or add scoped rules as more .mdc files with `globs` (for example `src/components/**/*.tsx`).
How Do You Scope a Rule to Some Files?
Set alwaysApply: false and give a glob. The rule then reaches the agent only when it works on matching files:
---
description: Conventions for React components
globs: src/components/**/*.tsx
alwaysApply: false
---
- Use named exports, not default exports.
- Keep components under 200 lines; extract subcomponents into the same folder.
- Keep always-on rules short: they load on every task.
- Move language or folder-specific rules into scoped files with globs.
- Give every non-global rule a clear description so the agent can pick it up when relevant.
Do @File Mentions Inline the File?
No. Cursor's documentation is explicit that a mention like @migration-template.sql tells the agent where to look; the agent then reads the file with its tools when it needs it. The contents are not pasted into the prompt. So an @AGENTS.md mention in a rule is only a pointer. That is fine for AGENTS.md itself, because Cursor loads AGENTS.md automatically, which is why 2prompt's generated rule points to it instead of repeating it.
What Happened to .cursorrules?
The single .cursorrules file at the repository root is Cursor's older format. Cursor's documentation marks it as legacy. Some other tools still detect it: Cline auto-detects .cursorrules, and Zed reads it if it is the first instruction file it finds. For new projects use .cursor/rules/*.mdc or AGENTS.md. See .cursorrules vs .cursor/rules and convert an old file with the .cursorrules to AGENTS.md converter.
How Should You Organize Several Rules?
Start with one always-on rule that holds the essentials, or let AGENTS.md hold them. Add a scoped rule only when a group of files has conventions the rest of the project does not share, such as database migrations, tests or UI components. Subfolders inside .cursor/rules are allowed, so mirror the shape of the codebase if that makes rules easier to find. Name files after what they govern, for example testing.mdc or migrations.mdc, so a reviewer can tell from the file list which rules exist.
What Are the Common Cursor Rules Mistakes?
- Saving rules as .md in .cursor/rules, where they are silently ignored.
- Marking everything alwaysApply: true, so every task carries every rule.
- A rule with no description, no globs and alwaysApply false, which only ever applies when mentioned.
- Expecting an @file mention to inline the file contents.
- Keeping a .cursorrules file and .mdc rules that disagree with each other.
The linter flags .mdc rules that can never apply, and the generator writes a correct project.mdc for you.
Frequently Asked Questions
What file extension do Cursor rules need?
Project rules in .cursor/rules must use the .mdc extension. A plain .md file in that folder is ignored because it has no frontmatter to say when it applies. If you prefer plain Markdown, use AGENTS.md instead.
What does alwaysApply do?
When alwaysApply is true, the rule is included in every chat session and its globs and description are ignored. When it is false, the rule applies to files matching its globs, or when the agent judges its description relevant, or when you mention it.
Does Cursor read AGENTS.md?
Yes. Cursor supports AGENTS.md in the project root and in subdirectories. Nested files combine with their parents, and the more specific instructions take precedence.
Is .cursorrules still supported?
Cursor labels .cursorrules as legacy. It may still work, but new rules should go in .cursor/rules as .mdc files or in AGENTS.md, which more agents can read.