.cursorrules is deprecated — here is the migration

What rules are for

A rule is a standing instruction. Instead of telling the agent “remember we use strict mode” in every conversation, you write it down once and Cursor supplies it automatically.

The old way was a single .cursorrules file at the root of your project — one flat list, always on, applying to everything. Simple, and fine until it grows. Once that file is forty lines long, every conversation carries instructions about your database migrations while you are editing a stylesheet, and the genuinely important lines get diluted.

The current system replaces that one file with a folder, .cursor/rules, holding as many rule files as you like — each of which can declare when it applies.

The four rule types

This is the part worth learning properly, because choosing the right type is most of the value of migrating. Cursor’s documented types are:

In the file itself these are expressed through frontmatter, using three keys — description, globs and alwaysApply — which combine as follows:

The documented migration

Cursor’s own steps are short:

1. Open the command palette and search for New Cursor Rule.
2. Copy your .cursorrules content into the new rule file.
3. Set the rule type to Always Apply — this matches the old behaviour.
4. Delete .cursorrules from your project root.

Follow those four and you are migrated, with behaviour identical to before. That is a perfectly respectable place to stop if you are busy. But it leaves you with one always-on blob, which is the thing that was mediocre about the old format — so if you have another ten minutes, keep going.

Splitting the monolith, which is the real win

Suppose your old file looked like this:

Use TypeScript strict mode everywhere.
Never edit files in dist/.
When working in src/api, validate all input before it hits the database.
Prefer named exports.
Write commit messages in the imperative mood.

Read it as a list of separate concerns rather than one document. Four of those lines are true everywhere. One — the API validation line — is only true in one folder, and it even says so in words. That sentence beginning “when working in src/api” is a scope description written in English because the old format had no way to express it properly. Now it does.

The always-on rule keeps what is genuinely universal:

---
alwaysApply: true
---
- Use TypeScript strict mode everywhere
- Never modify generated files in the `dist/` directory
- Prefer named exports over default exports
- Write commit messages in the imperative mood

And the API concern becomes its own scoped rule, which only attaches when a matching file is actually in context:

---
description: API route conventions
globs: src/api/**/*.ts
alwaysApply: false
---
- Validate all input before it reaches the database
- Return a problem+json body on error, never a bare string

The mistakes that break rules silently

1. Using .md instead of .mdc. Project rules must use the .mdc extension. A plain .md file in .cursor/rules is ignored by the rules system, because it has no frontmatter. Nothing warns you — the rule is simply never applied.
2. Keeping the old file “just in case.” Two sources of truth stating overlapping policies in different words is precisely how you end up debugging an instruction you believed you had deleted. The documented final step is to delete .cursorrules. Do that step.
3. Expecting User Rules to apply to Inline Edit. Cursor’s User Rules are used by Agent (Chat). If a rule works in chat but appears ignored under Cmd/Ctrl+K, that is the documented behaviour rather than a broken rule.
4. Assuming filenames create precedence. Cursor identifies rules by their full file path, not by name. Two rules with the same filename in different folders both apply if their conditions match — neither overrides the other.

Where rules live

• Project rules — .cursor/rules, version-controlled, scoped to that codebase. Keep the folder flat; subfolders work, but a flat structure is simpler to manage, and nesting buys you nothing for .mdc files.
• User rules — global to your Cursor environment, set under Customize → Rules. These are your personal preferences and do not belong in a shared repo.
• AGENTS.md — supported as a simpler alternative to .cursor/rules, placed at your project root. Nested AGENTS.md files combine with parent directories, with the more specific instructions taking precedence.

When several rules apply at once, the documented order is Team Rules → Project Rules → User Rules. All applicable rules are merged, and earlier sources take precedence where guidance conflicts.

Is .cursorrules actually dead yet?

Worth being precise, because the internet is not. Cursor’s wording is that the file is legacy and will be deprecated — future tense. The documentation gives migration steps but does not state a cut-off date, and does not spell out whether the file is still honoured today. So: migrate because the new format is genuinely better and the direction of travel is unambiguous, not because your setup is about to stop working on a known date. Anyone quoting you a specific version number for its removal is guessing.

What to read next

If you also keep a CLAUDE.md, read CLAUDE.md vs .cursor/rules next — Cursor reads that file too, and applies it to every conversation, which changes how you should split your instructions. For the wider setup, see Cursor setup that survives updates.