CURSORRULES VS MDC RULES

The .cursorrules file is Cursor's original single-file format; .cursor/rules/*.mdc is the current one, with frontmatter that scopes each rule. Cursor marks .cursorrules as legacy.

Zero retention: everything you type stays in this browser. Verify it yourself in DevTools.
Guide

What Is the Difference Between .cursorrules and .cursor/rules?

Last verified 2026-11-13 against the vendor documentation.

.cursorrules.cursor/rules/*.mdc
Status in CursorLegacyCurrent project rules
FilesOne file at the rootAny number, in folders
FrontmatterNonedescription, globs, alwaysApply
ScopingAlways appliesAlways, by glob, by relevance, or on mention
Other readersCline auto-detects it; Zed if first match; Windsurf imports its own legacy files, not this oneCursor only

Why Did Cursor Move to .mdc Rules?

A single file that is always included grows until it is mostly noise for any given task. Project rules let you keep the always-on part small and attach the rest only where it matters, such as test conventions for test files or component rules for src/components. The frontmatter is what makes that possible:

---
description: Conventions for React components
globs: src/components/**/*.tsx
alwaysApply: false
---

- Use named exports, not default exports.
- Keep components under 200 lines; extract subcomponents into the same folder.

When Is .cursorrules Still Useful?

  • Old projects where nobody has time to migrate yet: it may still work.
  • Tools that look for it by name, such as Cline's auto-detection or Zed's first-match list.

Even in those cases AGENTS.md is a better target, because Cline and Zed both read AGENTS.md too.

Where Does AGENTS.md Fit In?

Cursor supports AGENTS.md at the root and in subdirectories, as a plain alternative to rules. The clean split is: shared instructions in AGENTS.md, which every agent reads, and only Cursor-specific or glob-scoped rules in .mdc files. The 2prompt generator writes one always-on project.mdc that points to AGENTS.md without repeating it: Cursor already loads AGENTS.md on its own, so a copy would only spend context twice. Note that an @file mention in a rule points to a file rather than inlining it.

How Do You Migrate From .cursorrules?

  1. Paste .cursorrules into the .cursorrules to AGENTS.md converter to get a structured AGENTS.md.
  2. Add the real build, test and lint commands; the converter will not invent them.
  3. Move any rule that only applies to some files into a .mdc file with globs and alwaysApply: false.
  4. Add the generated project.mdc, a short always-on rule that points to AGENTS.md and holds any Cursor-only rules.
  5. Delete .cursorrules and run the linter on the new AGENTS.md.

How Should You Split One Big .cursorrules File?

Long .cursorrules files usually mix three kinds of content: facts about the project, rules for everyone, and conventions for one corner of the code. Sorting lines into those buckets makes the migration mechanical.

  • Project facts (stack, commands, layout) go to AGENTS.md.
  • Rules for every change (testing, dependencies, secrets, branches) go to AGENTS.md under working rules.
  • Conventions for some files (components, tests, migrations) go to separate .mdc files with globs.
  • Persona and motivational lines are deleted or rewritten as concrete rules.

Expect the always-on part to shrink noticeably. Many lines in old .cursorrules files are restatements of the same idea, or advice so general that no agent can act on it, and the linter will point those out. What remains is shorter, easier to review and read by more tools.

Do the split in one pull request so reviewers can see every line move from .cursorrules into its new home. Reviewing the old and new files side by side makes it easy to spot a rule that was lost, duplicated or quietly changed during the move. After it merges, ask one or two teammates to work as normal for a few days before deleting any backups.

What Goes Wrong in Migrations?

  • Saving new rules as .md instead of .mdc, so Cursor ignores them.
  • Leaving .cursorrules in place with older, conflicting rules.
  • Copying the whole old file into one alwaysApply rule, which changes nothing.
  • Dropping persona lines without replacing them with concrete rules.

More detail: Cursor rules format.

Frequently Asked Questions

Is .cursorrules deprecated?

Cursor's documentation labels .cursorrules as legacy. It is the older single-file format, and new rules should go in .cursor/rules as .mdc files or in AGENTS.md.

Can I keep both .cursorrules and .mdc rules?

You can, but it is a common source of contradictions because the two files drift. Migrate the content and delete .cursorrules so there is one place to edit.

Why is my rule in .cursor/rules ignored?

Most often it has a .md extension. Project rules must be .mdc files with frontmatter. Also check that a non-global rule has globs or a description, otherwise it only applies when mentioned.

Do other agents read .mdc rules?

Not that we verified. The .mdc format is Cursor-specific. Put rules you want every agent to follow in AGENTS.md, which Cursor also reads.

Was this helpful?