Convert .cursorrules to .cursor/rules (.mdc)
Cursor's documentation calls the root .cursorrules file legacy and points to project rules in .cursor/rules (or AGENTS.md) instead. Project rules are .mdc files with a small frontmatter block that controls when each rule loads.
The converter splits your file at every ## heading, writes one .mdc file per section with alwaysApply: true, and keeps code blocks intact. You then decide which sections deserve narrower scoping.
Input
Everything runs in your browser. Files are never uploaded.
Output
Converted files appear here. Conversion report
How each rule type converts
| In .cursorrules (legacy) | Becomes | Result |
|---|---|---|
Each ## Heading section | .cursor/rules/<heading>.mdc, Always Apply | Kept |
| Text before the first heading | .cursor/rules/overview.mdc | Kept |
File without ## headings | One project.mdc | Kept |
| Headings inside code blocks | Left alone (not treated as sections) | Kept |
Steps
- Paste your
.cursorrulesor drop the file. Split by ## headings is already on. - Download the .zip and unpack it at the repository root.
- Open each generated file and narrow it where it makes sense: set
globs(for exampletests/**) andalwaysApply: false, or write adescriptionso the agent pulls it in only when relevant. - Delete
.cursorrulesonce the new rules work, so Cursor doesn't see the same instructions twice.
Worked example
This output is generated by the same converter you use above, from an illustrative rule set.
Input
.cursorrules
You are working on a Python 3.12 FastAPI service.
## Code style
- Type hints on every public function.
- Format with ruff; line length 100.
## Testing
- Use pytest. Put tests in tests/ mirroring the package layout.
- Run `uv run pytest` before you finish a task.
## API
- Validate request bodies with Pydantic models.
- Return errors as {"detail": "..."} with the right status code.Output
.cursor/rules/overview.mdc
---
description:
globs:
alwaysApply: true
---
You are working on a Python 3.12 FastAPI service..cursor/rules/code-style.mdc
---
description:
globs:
alwaysApply: true
---
- Type hints on every public function.
- Format with ruff; line length 100..cursor/rules/testing.mdc
---
description:
globs:
alwaysApply: true
---
- Use pytest. Put tests in tests/ mirroring the package layout.
- Run `uv run pytest` before you finish a task..cursor/rules/api.mdc
---
description:
globs:
alwaysApply: true
---
- Validate request bodies with Pydantic models.
- Return errors as {"detail": "..."} with the right status code.Report for this example
- kept Overview: Written to .cursor/rules/overview.mdc as "Always Apply".
- kept Code style: Written to .cursor/rules/code-style.mdc as "Always Apply".
- kept Testing: Written to .cursor/rules/testing.mdc as "Always Apply".
- kept API: Written to .cursor/rules/api.mdc as "Always Apply".
Things to watch for
- Cursor's docs say a plain
.mdfile in.cursor/rulesis ignored by the rules system. Keep the.mdcextension. - Every split section starts as Always Apply, which costs the same context as the old file. The benefit comes from scoping the sections afterwards.
- If you also use other agents, converting
.cursorrulesto AGENTS.md may be the better move: Cursor reads AGENTS.md too.
FAQ
Is .cursorrules still supported?
Cursor's docs describe it as legacy and say it will be deprecated; they recommend project rules or AGENTS.md. Migrating now avoids a surprise later.
What do description, globs and alwaysApply do?
alwaysApply: true loads the rule in every chat. globs loads it when matching files are in context. A description alone lets the agent decide. With none set, you @-mention the rule manually.