What is the Cursor rules file format?

Project rules use the .mdc extension (Markdown with metadata) inside .cursor/rules/. Each file has YAML-style frontmatter — description (what the rule is for), globs (file patterns it auto-attaches to), and alwaysApply (true = always in context). A plain .md file in .cursor/rules has no frontmatter, so the rules system ignores it — it must be .mdc.

What are the four Cursor rule types?

Always (alwaysApply: true — in context for every request), Auto-attached (globs match files in context), Agent-requested (the AI decides based on the description), and Manual (only when you @-mention the rule). The type is determined by which frontmatter fields you set.

Is .cursorrules deprecated? .cursorrules vs .cursor/rules?

.cursorrules is the legacy format — a single file at the repo root. It still works for backward compatibility, but Cursor has superseded it with Project Rules in the .cursor/rules/ directory, which support multiple scoped .mdc files, globs, and rule types. New projects should use .cursor/rules/; migrate a legacy .cursorrules by moving its content into a .cursor/rules/*.mdc file.

Where do Cursor rules live?

Project rules live in .cursor/rules/ at your repo root, and you can nest a .cursor/rules folder inside subdirectories so those rules apply only to that part of the codebase. User Rules (global, plain-text) are set in Cursor Settings and apply to every project.

Cursor rules (`.cursor/rules`) — format, examples, best practices

Q: Cursor rules vs AGENTS.md — which should I use?

Use both. AGENTS.md is the open, tool-agnostic standard read by Cursor and 28+ other tools — keep your shared, cross-tool instructions there. Use .cursor/rules/*.mdc for Cursor-specific power: glob-scoped rules, agent-requested rules, and per-directory nesting. A common setup is one AGENTS.md for the basics plus a few scoped .mdc rules for the parts Cursor can target precisely.

Cursor rules are reusable instructions you give Cursor's AI so it follows your project's conventions. Project rules live in .cursor/rules/ as .mdc files — each with frontmatter that decides when it's applied. Here's the format, the four rule types, a copy-paste example, and how it relates to .cursorrules and AGENTS.md.

Generate your .cursor/rules — free →

What are Cursor rules?

Large models don't retain context between sessions. Rules solve that: a rule is persistent, reusable context Cursor pulls into the model prompt so it codes the way your project expects — your stack, conventions, and the things to avoid. There are two kinds:

Project Rules — version-controlled .mdc files in .cursor/rules/, shared with your team and every Cursor agent on the repo.
User Rules — global, plain-text preferences set in Cursor Settings; they apply across all your projects.

The `.mdc` format

Project rules use the .mdc extension (Markdown + metadata) inside .cursor/rules/. A plain .md file there is ignored by the rules system — it has no frontmatter. Each rule has three frontmatter fields:

Field	What it does
`description`	One line on what the rule is for. Used when the agent decides whether to pull the rule in.
`globs`	File patterns (e.g. `src/*/.ts`). The rule auto-attaches when a matching file is in context.
`alwaysApply`	`true` = always in context (globs + description are then ignored). `false` = applied conditionally.

The four rule types

Which fields you set determines the rule type — Cursor exposes this as a dropdown:

Type	How it's set	When it applies
Always	`alwaysApply: true`	Every request — use sparingly, it costs context on every call.
Auto-attached	`globs` set, `alwaysApply: false`	When a file matching the glob is in context.
Agent-requested	`description` set, no globs	When the agent judges it relevant from the description.
Manual	none of the above	Only when you `@`-mention the rule in chat.

Example: `.cursor/rules/project.mdc`

---
description: Project conventions for the web app
globs: ["**/*.ts", "**/*.tsx"]
alwaysApply: false
---

# Web app — conventions

## Stack
Next.js 14 (App Router), TypeScript, Tailwind, Drizzle + Postgres.

## Conventions
- Server Components by default; add "use client" only when you need state or effects.
- No `any` — type everything; prefer `unknown` + a narrow.
- Co-locate tests as `*.test.ts` next to the file.

## Don't
- Don't touch `/legacy` — it's being removed.
- Don't add a dependency without checking it's not already in package.json.

That rule auto-attaches whenever a .ts/.tsx file is in context. For rules that should always apply (a short house style), set alwaysApply: true and drop the globs.

Where they live + nesting

Repo root: .cursor/rules/*.mdc — applies project-wide.
Nested: put a .cursor/rules/ folder inside a subdirectory (e.g. packages/api/.cursor/rules/) and those rules scope to that part of the codebase.
Global: User Rules in Cursor Settings → Rules — plain text, every project.

`.cursorrules` vs `.cursor/rules`

.cursorrules (a single file at the repo root) is the legacy format. It still works for backward compatibility, but Cursor has superseded it with Project Rules in .cursor/rules/ — which give you multiple scoped files, globs, rule types, and per-directory nesting instead of one monolithic file. New projects should use .cursor/rules/; to migrate, move your .cursorrules content into a .cursor/rules/project.mdc with appropriate frontmatter.

Cursor rules vs AGENTS.md

Cursor reads both. AGENTS.md is the open, tool-agnostic standard read by Cursor and 28+ other agents — keep your shared, cross-tool instructions there so they work in Claude Code, Copilot, Gemini, etc. too. Use .cursor/rules/*.mdc for Cursor-specific power: glob-scoped rules, agent-requested rules, and nesting. Many teams keep one lean AGENTS.md plus a few scoped .mdc rules. See AGENTS.md vs CLAUDE.md for the cross-tool picture.

Best practices

Keep them lean. Research (ETH Zurich, Evaluating AGENTS.md) found that dump-everything context files lowered agent success and raised cost; lean, curated ones helped. Scope with globs instead of one giant always-on rule.
One concern per file. A rule for API conventions, another for the front-end — easier to scope and maintain.
Prefer Auto-attached / Agent-requested over Always for anything that isn't universal — so it only costs context when relevant.
Be specific + give examples. "Use server actions for mutations (see app/actions/)" beats "write good code".
Commit them. .cursor/rules in version control = the whole team and every agent share the same conventions.

Generate it from one source

Maintaining .cursor/rules and AGENTS.md and CLAUDE.md and Copilot instructions by hand means they drift. Write your project rules once and compile all of them:

Open the free Agent Memory Compiler →

It outputs .cursor/rules/project.mdc + AGENTS.md + CLAUDE.md + .github/copilot-instructions.md + GEMINI.md from one input, with a token-budget warning. If you run TaskPrio, a project's context exports the same files automatically — over MCP (export_memory) or one click in the app.

FAQ

What is the Cursor rules file extension?

.mdc (Markdown with metadata), inside .cursor/rules/. Plain .md there is ignored — it has no frontmatter.

Is `.cursorrules` deprecated?

It's the legacy single-file format. Still supported for backward compatibility, but superseded by Project Rules in .cursor/rules/. Use the directory format for new projects.

Can I have different rules per folder?

Yes — nest a .cursor/rules/ folder in a subdirectory and those rules scope to that subtree.

Generate your agent rules — free → What is AGENTS.md →

Cursor rules (.cursor/rules) — format, examples, best practices