Pillar guide
Cursor Rules: How to Write .cursor/rules That Actually Work
Cursor rules are persistent instructions that teach Cursor your conventions — stack, patterns, do's and don'ts. The modern format is one or more .mdc files under .cursor/rules/ (the single-file .cursorrules is deprecated). Good rules are short, scoped, and specific; vague or bloated rules get ignored.
What are Cursor rules?
Rules are reusable context Cursor loads automatically so you don't repeat yourself every prompt. They encode your conventions — "use our logger, not console.log", "prefer server components", "never edit generated files" — and apply across the project or to matching paths.
What format do Cursor rules use now?
The current format is one or more `.mdc` files in a `.cursor/rules/` directory. Each file has frontmatter (a description and optional file globs that scope when it applies) and a Markdown body of instructions. The old single-file `.cursorrules` at the repo root is deprecated — migrate to the directory format.
// .cursor/rules/typescript.mdc--- description: TypeScript & React conventions globs: ["**/*.ts", "**/*.tsx"] alwaysApply: false --- - Prefer function components and hooks. - Use our `@/lib/logger`, never console.log. - Validate all server-action inputs before use.
If you still have a root .cursorrules file, split it into scoped .mdc files under .cursor/rules/. The directory format is what current Cursor expects and lets you target rules by path.
How do I write rules Cursor will follow?
- Scope with globs — a React rule shouldn't load for your SQL migrations.
- Be specific and short — concrete do/don't lines beat paragraphs of philosophy.
- One concern per file — testing rules, style rules, and security rules separate.
- Show, don't lecture — a one-line example is worth a paragraph of description.
Why does Cursor ignore my rules?
The common causes: the rule isn't scoped to the files you're editing (wrong or missing globs), the rule is too long or contradictory so it's diluted, the .mdc frontmatter is malformed, or you're using the deprecated .cursorrules location. Tighten the glob, shorten the rule, and confirm it's a valid .mdc under .cursor/rules/.
In this guide
Frequently asked questions
Is .cursorrules deprecated?
The single-file .cursorrules is legacy. Current Cursor uses .cursor/rules/*.mdc files, which support per-path scoping via globs. Migrate existing rules into the directory format.
Where do I put Cursor rules?
In a .cursor/rules/ directory at your project root, as one or more .mdc files. You can also set global rules in Cursor's settings for conventions that apply everywhere.
Can I share rules across a team?
Yes — commit .cursor/rules/ to your repo so every teammate gets the same conventions. Team and Enterprise plans also support centrally managed rules.
Sources & last verified
Cursor ships frequently. Facts verified against primary sources on June 15, 2026.