How to Migrate .cursorrules to .cursor/rules (.mdc), Step by Step

Published 2026-10-31 · 5 min read · by AgentKit Co

If your project still has one big .cursorrules file in the root, it is worth moving it. Cursor's current Rules docs describe four kinds of rules: project rules in .cursor/rules, user rules, team rules and AGENTS.md. The single root .cursorrules file is not mentioned there at all, so a new setup should not depend on it.

The good news: the migration takes about 20 minutes, and you end up with rules that load only when they are relevant instead of one wall of text in every chat. Everything below was checked against Cursor's Rules docs on 2026-10-31. Cursor changes quickly, so re-check anything you depend on.

What you are moving to

There are two destinations, and most projects use both:

AGENTS.md has a second advantage: Cursor is not the only tool that reads it. GitHub Copilot, OpenAI Codex and many other agents do too, so your project-wide rules stop being Cursor-only (see AGENTS.md vs CLAUDE.md vs Cursor rules).

Step 1: Sort every line in your .cursorrules

Open the old file and put each rule in one of four buckets:

1. Whole project, always true (stack, commands, "never edit dist/"). These go to AGENTS.md.
2. Only for some files ("components use named exports", "migrations need a down step"). These become .mdc rules with globs.
3. Only for some tasks ("how we write RPC services"). These become .mdc rules with a description, so the agent decides when to load them.
4. Vague, duplicated, or already enforced by a linter ("write clean code", "use 2-space indent"). Drop these. Cursor's docs say to use a linter instead of copying a style guide, and that the agent already knows common tools.

Bucket 4 is usually bigger than people expect. A shorter file is easier for the agent to follow.

Step 2: Create the folder and pick the right frontmatter

Project rules must use the .mdc extension. The docs are explicit that a plain .md file in .cursor/rules is ignored by the rules system. Subfolders are fine.

your-repo/
  AGENTS.md
  .cursor/rules/
    components.mdc
    migrations.mdc
    rpc-services.mdc

Three frontmatter fields decide when each rule is used. This is Cursor's table in plain words:

A file-scoped rule (bucket 2):

---
globs: src/components/**/*.tsx
alwaysApply: false
---

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

A rule the agent pulls in when relevant (bucket 3):

---
description: Conventions for writing RPC services in src/services
alwaysApply: false
---

- One service per file under src/services/
- Validate inputs at the service boundary
- Return { code, message } errors, never raw strings

Separate several glob patterns with commas, for example docs/**/*.md, docs/**/*.mdx.

Step 3: Write the AGENTS.md

Put bucket 1 into an AGENTS.md in the repo root. Keep it short and concrete:

# Project
Next.js app (App Router) with TypeScript and Postgres.

## Commands
- Install: [npm ci]
- Test: [npm test]
- Lint: [npm run lint]

## Boundaries
- Never edit files in dist/ or generated/
- Ask before adding a dependency

Replace the bracketed commands with the ones your project really uses. If you want a head start, our free AGENTS.md generator reads your package.json or pyproject.toml and fills them in. For what makes a good line, see how to write an AGENTS.md.

Step 4: Let the agent do the first draft (optional)

If your old file is long, ask Cursor's agent to sort it for you, then review the result:

Migrate the legacy file `.cursorrules` as follows. Do not delete it yet.

1. Put rules that apply to the whole project into a new AGENTS.md
   (sections: Project, Commands, Layout, Conventions, Boundaries).
2. Put rules that apply to certain file types into separate files in
   `.cursor/rules/` with the `.mdc` extension. Use frontmatter with
   `globs:` and `alwaysApply: false`. One topic per file.
3. Drop rules that are vague, duplicated, or already enforced by a linter.
4. Show me a table: original rule | new location | or "dropped, because".
Ask before writing files.

The table in step 4 is the important part: it lets you check that nothing you care about was lost.

Step 5: Test it, then delete the old file

Before you delete .cursorrules, check that the new rules actually load:

1. Open Customize in Cursor's sidebar and go to Rules. Cursor's docs say you can see all rules and their status there.
2. Open a file that matches one of your globs and ask the agent to make a small change that a rule covers. See whether it follows the rule.
3. For a description-based rule, ask for a task that matches the description, and check that the rule is picked up.

When the new setup behaves the way the old one did, delete .cursorrules so you don't keep two copies that drift apart.

Common mistakes

• Saving rules as .md inside .cursor/rules. They are ignored. Use .mdc.
• Setting alwaysApply: true on everything. Then every rule is in every chat, which is the problem you were trying to fix. Keep "always" for the few rules that really are always true, and put those in AGENTS.md.
• A description-based rule with no description. The docs' own FAQ says to check that a description is defined for "Apply Intelligently" rules.
• Globs that don't match. *.ts matches only the root folder; **/*.ts matches every folder.
• Copying the whole style guide. Use a linter for formatting and keep rules for things a linter can't check.

More troubleshooting is in Cursor rules not working? 8 fixes, and ready-made examples are in Cursor rules examples.

Want the files ready-made?

The AI Coding Agent Config Kit has 8 Cursor .mdc rules with correct frontmatter, AGENTS.md templates for 12 stacks, Claude Code and Copilot files, and 12 prompts, including the migration prompt above and a five-task test for any instruction file. It is guidance, not enforcement: no instruction file guarantees an agent will obey every line.

Keep reading