Cursor rules: .mdc frontmatter, types and limits

Where rules live

Cursor's rules docs list four kinds of rule: project rules in .cursor/rules, User Rules set in the app, Team Rules managed from the dashboard on Team and Enterprise plans, and a plain AGENTS.md. All of them do the same job. The docs put it plainly: "Large language models don't retain memory between completions. Rules provide persistent, reusable context at the prompt level", and "when applied, rule contents are included at the start of the model context."

Project rules are the ones you commit. Each is one file in .cursor/rules, named whatever you like, and it must end in .mdc: "A plain .md file in .cursor/rules is ignored by the rules system because it has no frontmatter to specify description, globs, and alwaysApply." Subfolders inside .cursor/rules are allowed for organisation (the docs show frontend/components.mdc). If you want no frontmatter at all, the docs point you to AGENTS.md instead, which Cursor reads from the project root and from subdirectories.

The three frontmatter fields

An .mdc file is markdown with a YAML block on top. Three keys matter:

• alwaysApply: true or false. True means the rule is in every chat session.
• globs: file patterns. When a file matching one of them is in the context of the chat, the rule is attached. "Separate multiple patterns with commas."
• description: a sentence the Agent reads to decide whether the rule is relevant to the current task.

The glob syntax is the usual one: * for one path segment, ** for any depth. The docs' examples include src/**/*.tsx (all .tsx files under src/), tailwind.config.* and the comma form docs/**/*.md, docs/**/*.mdx. Here is a complete rule of the auto-attached kind:

---
globs: src/components/**/*.tsx
alwaysApply: false
---
- Use named exports, not default exports
- Co-locate styles in a module CSS file next to the component
- Keep components under 200 lines; extract subcomponents into the same directory

Anything in the body reaches the model as written. A file mention such as @service-template.ts is a pointer, not an include: "The file's contents are not inlined into the prompt, and this is the same in the editor, the CLI, and Cloud Agents. Put anything that must always be in context directly in the rule body."

The four rule types

The type dropdown in Cursor's rule editor (Always Apply, Apply Intelligently, Apply to Specific Files, Apply Manually) only writes these three fields. The docs give the mapping as a table; here it is with the exact behaviour text:

Two consequences are easy to miss. A rule with globs and a description is auto-attached by the globs; the description is still useful for people but is not what triggers it. And a rule with no frontmatter at all is a manual rule: it does nothing until someone types @its-name. If a rule "is not being applied", the docs' first advice is to check the type: "For Apply Intelligently, ensure a description is defined. For Apply to Specific Files, ensure the file pattern matches referenced files."

How rules load, and what they cost

Rules are prompt text, so they cost context on the requests they are attached to. The docs do not publish a token figure or a hard size limit. What they do say:

• Always rules are paid on every chat. Put only what every task needs there: the build and test commands, the layout, the handful of conventions that are not obvious from the code.
• Agent-requested rules cost their description every time. "The description of the rule will be presented to the Cursor Agent to decide if it should be applied", so the description is always in context and the body only when chosen. Write the description as a trigger ("RPC service conventions for the backend"), not a summary of the body.
• Auto-attached rules cost nothing until a matching file is in context, which makes them the cheapest way to hold rules for one corner of the codebase.
• Length: "Keep rules under 500 lines" and "Split large rules into multiple, composable rules."
• Precedence: "Rules are applied in this order: Team Rules → Project Rules → User Rules. All applicable rules are merged; earlier sources take precedence when guidance conflicts."
• Scope: rules are for Agent (Chat). "Rules do not impact Cursor Tab or other AI features", and User Rules "are not applied to Inline Edit (Cmd/Ctrl+K)."

The docs' own list of what to leave out is a good trim guide: whole style guides ("Use a linter instead"), every command ("Agent knows common tools like npm, git, and pytest"), rare edge cases, and copies of code that already exists in the repository. "Start simple. Add rules only when you notice Agent making the same mistake repeatedly."

The legacy .cursorrules file

Before .cursor/rules, Cursor read a single .cursorrules file at the project root: plain text, no frontmatter, applied to every chat. As of 14 October 2026 the rules docs page does not mention it, but Cursor's rules help page does: "The .cursorrules file in your project root is legacy and will be deprecated." No date is given for when it stops loading, so do not rely on it for anything new.

Migration is mechanical, and the help page gives the steps: create a rule with "New Cursor Rule" from the command palette, copy the old content in, set the type to Always Apply ("this matches the old behavior") and delete .cursorrules. By hand, that is one file, .cursor/rules/project.mdc, with alwaysApply: true and the old text as its body. Then, over time, pull the sections that only matter for part of the code into auto-attached rules with globs. If other agents also work in the repository, AGENTS.md is the other sensible destination; see AGENTS.md vs CLAUDE.md.

The browser checker has no option for .cursorrules. The Claude Code plugin recognises it as a legacy always-on file and runs the same general checks on it.

Common mistakes

• Saving the rule as .md. It is ignored. Rename it to .mdc.
• No frontmatter. The rule becomes manual and only applies when @-mentioned. Add alwaysApply, globs or a description.
• A glob that starts with * and is not quoted. In YAML, a value beginning with * is an alias, so globs: *.ts fails to parse in a strict parser and the rule may lose its frontmatter. Write globs: "*.ts" or a pattern that starts with a path, such as src/**/*.ts. The same applies to **/*.md.
• alwaysApply: "true" in quotes. That is the string "true", not the boolean. The docs' examples use the bare word.
• A description that does not say when to use the rule. "Backend notes" gives the Agent nothing to match. "RPC service conventions and patterns for the backend" (the docs' example) does.
• Expecting @file to paste the file in. It does not. If the content must always be present, put it in the body.
• Contradictions across rules. Always rules, auto-attached rules, Team Rules and User Rules are merged into one prompt. "Use named exports" in one file and "default exports for pages" in another leaves the model to guess. Make the exception explicit in one place.
• Testing with Tab or Inline Edit. Rules do not reach them. Test in Agent chat.

Cursor rules vs CLAUDE.md vs AGENTS.md

If your team uses more than one tool, it helps to see the three formats side by side. The CLAUDE.md column is from Anthropic's docs (see CLAUDE.md best practices); the AGENTS.md column from Cursor's and Codex's.

One thing catches mixed teams out. Cursor's help page says it "reads CLAUDE.md files the same way it reads AGENTS.md", and that "CLAUDE.md files are always applied to every conversation, regardless of any alwaysApply frontmatter setting." So a long CLAUDE.md written for Claude Code is also paid for in every Cursor chat.

For a mixed team: shared facts in AGENTS.md, Cursor-specific file-scoped rules as .mdc files with globs. A .claude/rules file with paths is the Claude Code equivalent, so the same rule text can live in both with only the frontmatter changed.

Checklist

• Every rule file ends in .mdc and sits under .cursor/rules
• Every rule has frontmatter that makes its type deliberate: alwaysApply, globs or a trigger-style description
• Globs that start with * are quoted
• alwaysApply is a bare true or false
• Only facts needed in every chat are in always rules; everything file-specific is auto-attached
• Each rule is under 500 lines, and nothing is pasted that @file could point to instead
• No rule contradicts another, including Team and User Rules
• No secrets, and no hidden text (HTML comments, invisible characters) you have not read

claude plugin marketplace add Katta041/asitis-agent-tools
claude plugin install asitis@asitis

Sources, read on 14 October 2026: Cursor docs, Rules, and Cursor help, Rules (.cursorrules and CLAUDE.md). Quotes are exact. The docs give no token figure and no hard file-size limit; the 500-line figure is their stated best practice. Related: AGENTS.md vs CLAUDE.md, GitHub Copilot custom instructions, GEMINI.md for Gemini CLI.