Migrate .cursorrules to Project Rules (.mdc)

Why Migrate from .cursorrules to Project Rules?

Cursor IDE's legacy .cursorrulesformat served developers well as the original way to customize AI behavior — a single plain-text file at your project root that the AI assistant reads on every interaction. But as projects and teams grew, its limitations became clear: a single file can only describe one set of conventions, forcing monorepo and multi-language teams to cram unrelated rules into the same document. There is no way to tell Cursor "apply these rules only to frontend files and those rules only to backend files." Every rule applies everywhere, all the time, regardless of context.

Project Rules (.mdc) solves these problems with a modern, multi-file architecture. Instead of one file, you create a .cursor/rules/ directory containing as many .mdc files as your project needs. Each file has YAML frontmatter with a description for human readability, globs for targeting specific file patterns, alwaysApply to control whether the rule runs globally, and an optional version field. This means your React component rules only apply when editing .tsx files, your Go backend rules only fire in .go files, and your universal testing standards can be flagged to apply everywhere with alwaysApply: true. The result is more relevant AI output, lower token usage on irrelevant rules, and a codebase that is easier for new team members to navigate.

Understanding Project Rules: Cursor Rules V2

Before you start migrating, it helps to understand the core concepts of Project Rules. Every .mdc file lives inside the .cursor/rules/ directory and consists of two parts: YAML frontmatter and a markdown body. The frontmatter is metadata that tells Cursor when and where to apply the rules. The body is the actual rule content — the same kind of instructions you already have in your .cursorrules file, but now organized by domain.

The four key frontmatter fields are: description(a human-readable summary shown in Cursor's rules panel), globs (an array of file-matching patterns like "src/components/**/*.tsx" that limit where the rule applies — leave empty for global application), alwaysApply (a boolean; when true, Cursor includes these rules in every AI interaction regardless of which file you are editing — ideal for universal conventions like code style and testing requirements), and version (an optional semantic version string for tracking rule changes over time). Unlike .cursorrules, where all rules are always active, Project Rules lets you be surgical: frontend rules for frontend files, backend rules for backend files, and shared standards everywhere.

Cursor IDE also supports AGENTS.md, a single markdown file at your project root that is simpler than Project Rules — no frontmatter, no glob targeting, no file splitting — but excellent for small projects and quick onboarding. The three formats can coexist: you can have .cursor/rules/ for team domain rules, an AGENTS.md for contributor onboarding, and even keep a legacy .cursorrules for backward compatibility during a gradual migration. However, Cursor prioritizes Project Rules when present, so migrating is the recommended path forward.

Step-by-Step Migration Guide

Step 1: Back Up Your Existing .cursorrules

Before making any changes, create a backup of your current .cursorrules file. You can simply copy it to a safe location or commit the current state to version control. This ensures you can always revert if something goes wrong during the migration. Since .cursorrules is a hidden file, use cp .cursorrules .cursorrules.backup or stash it in a separate branch. If your project uses git, run git add .cursorrules && git commit -m "backup: snapshot .cursorrules before migration" so the original state is preserved in your commit history.

Step 2: Create the .cursor/rules/ Directory

Project Rules live in a dedicated directory under your project root. Create it with mkdir -p .cursor/rules. This directory will hold all your .mdc files. Cursor IDE automatically scans this directory when you open the project — there is no configuration panel to visit and no plugin to install. The directory name starts with a dot, making it hidden on macOS and Linux, which keeps your workspace clean while still being visible in your editor and version control. You can organize .mdc files however you like within this directory — flat, nested, grouped by domain. Cursor reads them all recursively.

Step 3: Split Rules by Domain

This is the core of the migration. Open your backup .cursorrules and identify logical domains — look for sections about code style, naming conventions, framework-specific patterns, testing requirements, and architectural guidelines. Create a separate .mdc file for each domain. For example, a React + Go monorepo might produce:

• code-style.mdc — indentation, quotes, semicolons (applies everywhere)
• react-components.mdc — component patterns, hooks conventions, JSX rules
• go-backend.mdc — error handling, package structure, naming idioms
• testing-standards.mdc — test framework, coverage expectations, mock patterns

The goal is separation of concerns: each file should contain only rules relevant to its domain. This keeps files short and focused, making them easier to maintain and review. If you are unsure where to start, begin with three files — code style, framework-specific rules, and testing — then iterate as you discover more natural groupings.

Step 4: Add MDC Frontmatter to Each File

Every .mdc file must start with YAML frontmatter delimited by --- on its own line at the top and bottom of the metadata block. At minimum, include a description field so teammates can understand what each file covers without opening it. For domain-specific rules, add globs to target the right files. For universal rules like code style, set alwaysApply: true. Here is a minimal frontmatter for a React component rules file:

---
description: React component conventions for the frontend team
globs:
  - "src/components/**/*.tsx"
  - "src/pages/**/*.tsx"
alwaysApply: false
version: "1.0.0"
---

# React Component Rules

- Use functional components with TypeScript interfaces for props
- Prefer named exports over default exports
- Keep components under 200 lines; extract hooks and utilities
- Use Tailwind CSS for styling — no inline styles or CSS modules

The globs field accepts standard glob patterns. You can target specific directories, file extensions, or even individual files. Multiple globs in the array are combined with OR logic — the rule fires if any pattern matches. For testing standards that should apply everywhere, simply set alwaysApply: true and omit or leave globs empty. The version field is optional but recommended for teams — it makes it easy to track when rules were last updated and whether all team members are on the same version.

Step 5: Configure Application Mode (alwaysApply / globs)

The power of Project Rules comes from controlling when rules are active. There are three common patterns:

• Always-on rules — Set alwaysApply: truefor conventions that should influence every AI interaction: code style (indentation, quotes, semicolons), naming patterns, and universal testing standards. These rules are always in the AI's context.
• Domain-targeted rules — Set alwaysApply: false and define globs for framework-specific rules. Your React rules only activate when editing .tsx files; your Go rules only fire for .gofiles. This keeps the AI's context lean and relevant.
• Hybrid approach — Combine always-on rules (code style) with domain-targeted rules (framework patterns). The AI always follows code style conventions and additionally applies framework-specific rules when editing matching files.

Choose your pattern based on team size and project structure. Small single-framework projects can get by with one or two always-on files. Large monorepos benefit most from domain-targeted rules that keep irrelevant context out of every AI call — this also reduces token usage and improves response quality since the AI is not processing instructions meant for a different part of the codebase.

Step 6: Test Your Migration and Iterate

After creating your .mdc files, test them by asking Cursor to generate code in different parts of your project. Open a frontend component file and ask the AI to create a new component — it should follow your React rules. Open a backend file and ask for a new function — it should follow your Go or Python rules. Open any file and check that code style conventions (indentation, quotes, semicolons) are consistently applied. If the AI produces output that does not match your expectations, review the relevant .mdc file and make the rules more specific.

You can keep your old .cursorrules file in place during testing — Cursor IDE reads both, and Project Rules take priority where they overlap. Once you are confident the migration is working correctly, remove or archive the old .cursorrules file and commit the new .cursor/rules/ directory. Notify your team so everyone knows the new rule files are the source of truth. As your project evolves, iterate on your rules: split files that grow too large, add new domains as you add new technologies, and increment the version number when you make significant changes.

Migration Example: Before and After

Here is a real-world example showing how a typical .cursorrules file for a React + Go project transforms into Project Rules. The original file is a single document mixing frontend, backend, and general conventions. After migration, the same rules are split into focused .mdc files, each targeting only the relevant files.

Before: Single .cursorrules File

You are an expert React, TypeScript, and Go developer.

Code Style:
- Use 2-space indentation
- Single quotes, no semicolons
- Arrow functions with explicit return types

React Components:
- Use functional components with TypeScript interfaces
- Prefer named exports
- Keep components under 200 lines
- Use Tailwind CSS for styling

Go Backend:
- Always handle errors explicitly
- Use context.Context as first parameter
- Follow standard library naming conventions
- Package names should be short and lowercase

Testing:
- Jest + React Testing Library for frontend
- Go testing package for backend
- Every component needs at least one render test
- Backend functions must have table-driven tests

Architecture:
- Frontend in src/ directory
- Backend in cmd/ and internal/ directories
- Use React Query for server state
- Use gorilla/mux for HTTP routing

After: Organized .cursor/rules/ Directory

The same rules, now split into domain-specific .mdc files with proper frontmatter. Each file is short, focused, and applies only where relevant.

.cursor/rules/code-style.mdc

---
description: Universal code style conventions
alwaysApply: true
version: "1.0.0"
---

# Code Style

- Use 2-space indentation
- Single quotes, no semicolons
- Arrow functions with explicit return types
- Follow language-specific naming conventions

.cursor/rules/react-components.mdc

---
description: React component conventions
globs:
  - "src/components/**/*.tsx"
  - "src/pages/**/*.tsx"
alwaysApply: false
version: "1.0.0"
---

# React Component Rules

- Use functional components with TypeScript interfaces
- Prefer named exports over default exports
- Keep components under 200 lines; extract hooks and utilities
- Use Tailwind CSS for styling — no inline styles or CSS modules
- Use React Query (TanStack Query) for server state

.cursor/rules/go-backend.mdc

---
description: Go backend conventions
globs:
  - "cmd/**/*.go"
  - "internal/**/*.go"
alwaysApply: false
version: "1.0.0"
---

# Go Backend Rules

- Always handle errors explicitly — never ignore them
- Use context.Context as the first parameter in all functions
- Follow standard library naming conventions
- Package names should be short, lowercase, single-word
- Use gorilla/mux for HTTP routing

.cursor/rules/testing-standards.mdc

---
description: Testing requirements across the entire codebase
alwaysApply: true
version: "1.0.0"
---

# Testing Standards

- Frontend: Jest + React Testing Library
- Every component needs at least one render test
- Backend: Go standard testing package
- Backend functions must use table-driven tests
- Aim for meaningful coverage over percentage targets

The migrated structure is cleaner, more maintainable, and more efficient. When a developer edits a React component, Cursor only injects code-style.mdc, react-components.mdc, and testing-standards.mdc — the Go backend rules are completely excluded. This keeps the AI context focused, reduces token costs, and eliminates the risk of backend conventions leaking into frontend code generation.

Frequently Asked Questions

Does my old .cursorrules still work after migration?

Yes. Cursor IDE reads both .cursorrules and .cursor/rules/*.mdc simultaneously. If you keep both, Project Rules take priority where they overlap, but any rules in .cursorrules that are not covered by your .mdc files will still apply. This means you can migrate gradually — move rules to .mdc files one domain at a time and remove them from .cursorrules as you go. Once all your rules are migrated, you can safely delete the old file.

Can I mix .cursorrules and .mdc files in the same project?

Absolutely. This is actually the recommended approach during migration. Keep your existing .cursorrules for rules you have not yet migrated, and add .mdc files for the ones you have. Cursor merges all sources at runtime. However, be aware that duplicated rules across both formats can cause conflicts — Project Rules take priority, which may lead to unexpected behavior if the same convention is defined differently in both places. For a clean setup, complete the migration fully and remove the old file.

Can AGENTS.md and Project Rules coexist?

Yes, they serve different purposes and complement each other well. Use Project Rules (.mdc) for domain-specific AI behavior — code style per directory, framework-specific patterns, testing requirements with glob targeting. Use AGENTS.mdfor contributor-facing documentation: project overview, onboarding instructions, architectural decisions, and conventions that human developers need to read. AGENTS.md is also visible to Cursor's AI, so it doubles as both human documentation and AI context. For open-source projects especially, AGENTS.md is valuable because every contributor sees it immediately at the repo root.

Is there any risk in migrating?

The migration itself is low-risk because you can keep your old .cursorrules file active during the entire process. The main risk is introducing inconsistencies if you accidentally define the same rule differently across multiple .mdc files. To mitigate this, migrate one domain at a time, test each new .mdc file in isolation, and remove the corresponding rules from .cursorrules only after confirming they work. Also, commit your .cursor/rules/ directory to version control so you can track changes and revert if needed. There is no data loss risk — your rules are just moving from one file format to another.

How should teams coordinate migration?

For team migrations, designate one person to create the initial .cursor/rules/ structure and draft the .mdc files. Open a pull request so the team can review the proposed split and frontmatter configuration before merging. During the review period, everyone continues using the existing .cursorrules file. After the PR is merged, announce the migration in your team channel with a link to the new directory. Schedule a brief window (a few days to a week) where both formats coexist so any issues surface before the old file is removed. Finally, delete .cursorrules in a follow-up PR and mark the migration as complete. For large teams, consider adding a README.md inside .cursor/rules/ explaining the file organization so new contributors can quickly understand the structure.

Can I use the Cursor Rules Generator to create .mdc files?

Yes! Our interactive generator supports all three formats — Project Rules (.mdc), AGENTS.md, and legacy .cursorrules. Select your tech stack, configure your preferences, choose Project Rules as the output format, and the generator produces properly structured .mdc files with correct frontmatter. This is the fastest way to create your initial .cursor/rules/ directory, especially if you are starting fresh or want to replace hand-written rules with generator-optimized versions. You can then customize the generated files to add project-specific conventions.