Migrate .cursorrules to .cursor/rules/*.mdc

A single legacy .cursorrules file applies broad instructions even when they are irrelevant. Project Rules split context by purpose, so Cursor can always load core constraints, match file patterns, or select a rule from its description.

When to use

Apply language rules only to matching source files.
Keep a tiny set of repository-wide constraints always active.
Load specialized migration or testing guidance only when relevant.

Example

A monorepo keeps strict TypeScript rules always active, attaches API conventions only under src/server, and offers migration safety rules on demand.

TL;DR

Split one big .cursorrules into small rule files, each with its own scope.

bash

mkdir -p .cursor/rules

Steps

1
Always-on rule (keep it tiny)
Use alwaysApply only for constraints that matter to nearly every task; broad context competes with the user's request.
.cursor/rules/core.mdc
```
---
description: Core project rules
alwaysApply: true
---

- TypeScript strict. No `any`.
- Run `npm test` before finishing a task.
```
2
Rule attached to file patterns
Use globs when guidance should load automatically only for a known part of the codebase, such as server handlers.
.cursor/rules/api.mdc
```
---
description: API handler conventions
globs: src/server/**/*.ts
alwaysApply: false
---

- Validate input with zod.
- Return errors as { error: { code, message } }.
```

Rule the agent pulls in when relevant

No globs, not always applied: Cursor decides from the description.

.cursor/rules/migrations.mdc

---
description: How to write database migrations safely
alwaysApply: false
---

- Never drop a column in the same release that stops using it.

4
Delete the old file
After every useful instruction has a new home, remove the legacy file so duplicated or conflicting rules cannot load.
bash
```
git rm .cursorrules
```

Gotchas

.cursorrules still works but is legacy; do not keep both with conflicting rules.
Rules in nested .cursor/rules folders apply to that part of the repo.
Write precise descriptions or agent-requested rules never load.
Commit .cursor/rules so the whole team shares them.

Cheat sheet

alwaysApply: true	Always in context
globs: <pattern>	Auto-attach for matching files
description only	Agent decides
@rule-name in chat	Attach manually

Sources

Cursor docs: Rules

Reviewing agent output? CodeCrab reviews pull requests locally with your own AI tools.