Cursor Rules
Cursor rules are persistent instructions for Cursor's AI agent: project rules as .cursor/rules/*.mdc files with frontmatter, plus User Rules and Team Rules.
Cursor rules are persistent instructions for Cursor's agent. Project rules are .cursor/rules/*.mdc files with frontmatter, applied as Always Apply, Apply Intelligently, Apply to Specific Files or Apply Manually; User Rules are personal, Team Rules are enforced from the dashboard. Cursor also reads AGENTS.md; .cursorrules has left the docs.
Cursor rules are the persistent instructions that Cursor includes in its agent's context, written as project rule files, personal User Rules, or organization-wide Team Rules.
Project rules "live in .cursor/rules as .mdc files and are version-controlled." The extension is not optional; a plain .md file in that directory is ignored because it lacks the frontmatter the rules system reads. That frontmatter has three fields, description, globs and alwaysApply, and the type dropdown in the editor sets them for you. The four types are Always Apply (every session), Apply Intelligently (the agent reads the description and pulls the rule in when relevant), Apply to Specific Files (a glob matches a file in context) and Apply Manually (only when @-mentioned). Older docs called these Always, Agent Requested, Auto Attached and Manual. When a rule applies, its content goes at the start of the model context, and a file mention inside it such as @migration-template.sql tells the agent where to look rather than inlining the file.
User Rules are global preferences set under Customize → Rules. Team Rules are free-form text created in the Team or Enterprise dashboard, with glob support and an enforce switch that prevents members from disabling them; precedence runs Team Rules, then Project Rules, then User Rules.
Two things have changed. The legacy .cursorrules file and nested .cursor/rules directories have dropped out of the documentation, and /Generate Cursor Rules was removed in Cursor 2.0 in favor of /create-rule. Meanwhile Cursor reads AGENTS.md in the project root and subdirectories as the plain-Markdown alternative, with more specific nested files taking precedence. It does not mention CLAUDE.md, which is why teams that pair Cursor with Claude Code tend to converge on AGENTS.md; the instruction-file comparison and Claude Code vs Cursor cover that decision, and the instruction-file-migrator skill converts between formats.
Frequently asked questions
- What are the four Cursor rule types?
- Always Apply (included in every chat session), Apply Intelligently (the agent decides from the rule's description), Apply to Specific Files (a glob pattern matches a file in context), and Apply Manually (only when you @-mention the rule). They map to the alwaysApply, description and globs frontmatter fields, and they used to be called Always, Agent Requested, Auto Attached and Manual.
- Is .cursorrules deprecated?
- The current Cursor docs no longer mention .cursorrules at all. The last documented wording, from July 2025, said it was still supported but deprecated in favor of Project Rules. No primary source states that reading it was removed, so migrate to .cursor/rules or AGENTS.md rather than relying on it.
- Should I use Cursor rules or AGENTS.md?
- Cursor's own docs position AGENTS.md as the alternative for straightforward cases: a plain Markdown file with no metadata, read from the project root and subdirectories. Use .mdc project rules when you need glob scoping, manual @-mention rules, or the agent to decide relevance from a description.
Filed under
cursor-rules · cursor · instructions · coding-agents · configuration
Related
- AGENTS.md vs CLAUDE.md vs Cursor Rules: Which Instruction File Do You Need?AGENTS.md, CLAUDE.md, Cursor .mdc rules, GEMINI.md, Copilot instructions, Codex, Devin Desktop and Cline compared: who reads what, nesting, and migration.
- CLAUDE.mdCLAUDE.md is Claude Code's Markdown instruction file, loaded at the start of every session to give Claude persistent project, user or organization guidance.
- AGENTS.mdAGENTS.md is a versioned instruction file that tells coding agents how to work in a repository — including commands, conventions, boundaries, and checks.
- Instruction File MigratorConvert and synchronize agent instruction files between formats: CLAUDE.md with @imports and CLAUDE.local.md, AGENTS.md nested per directory, Cursor rules (.cursor/rules/*.mdc with description, globs, and alwaysApply frontmatter, plus the legacy .cursorrules), GEMINI.md, GitHub Copilot's copilot-instructions.md and *.instructions.md with applyTo, Windsurf rules, and .clinerules. It preserves each rule's wording, keeps always-on rules separate from path-scoped ones, and reports every rule that has no one-to-one equivalent in the target. Use when a team runs more than one coding agent and the files have drifted, or when switching tools.
- Claude Code vs Cursor: Which AI Coding Tool in 2026?Claude Code vs Cursor compared honestly — terminal agent vs AI-first editor, autonomy vs inline control, pricing models, and when to run both.
- Convert RulesConvert one agent instruction file to another format (for example .cursorrules to CLAUDE.md, or CLAUDE.md to AGENTS.md), preserving wording and path scoping, and list the rules that did not map.
- CursorAn AI-first code editor built on VS Code with deep in-editor agent features, parallel agents, in-house Composer models, and a plugin marketplace.