Cursor Rules: How to Write .cursor/rules That Actually Work

Rules are reusable context Cursor loads automatically so you don't repeat yourself every prompt. They encode your conventions ("use our logger, not console.log", "prefer server components", "never edit generated files") and apply across the project or to matching paths.

Rules are one of three primitives, and the cleanest way to tell them apart is by analogy. A rule is you should always wear your seat belt, a standard Cursor abides by on every change. A skill is this is how you parallel park, a recipe the agent runs through when the task calls for it. A sub-agentA child agent a main agent spawns to work in parallel with its own context window, handing results back so the parent's context stays clean. Press Enter for the full definition. is your car on autopilot, parking on its own, a specialist persona you hand a job to. All three are just Markdown files that read differently. Reach for a rule when you want a standard that's always in force.

The analogy hides the cost. A seat belt is free to keep wearing and a rule is not, since every line of it sits in the prompt next to the work you actually asked for. Most of what follows is about narrowing when a rule fires rather than about what it says, and that emphasis is deliberate.

The current format is one or more `.mdcMarkdown-Cursor rule file. The file format for a Cursor rule; set always_apply to false and scope it so the rule only fires on the files that need it instead of burning context every request. Press Enter for the full definition.` files in a `.cursor/rules/` directory. Each file has frontmatter (a description and optional file globs that scope when it applies) and a Markdown body of instructions. The old single-file `.cursorrules` at the repo root is deprecated. Migrate to the directory format.

---
description: TypeScript & React conventions
globs: ["**/*.ts", "**/*.tsx"]
alwaysApply: false
---

- Prefer function components and hooks.
- Use our `@/lib/logger`, never console.log.
- Validate all server-action inputs before use.

Splitting one file into several looks like busywork from the outside. What the directory format adds is the frontmatter block above, and those three fields are the entire mechanism: description, globs and alwaysApply are what decide whether a rule is included at all. Give your Python conventions their own globbed file and they stay out of context on every React edit.

Don't author the .mdc by hand. Cursor ships a default `/create rule` skill that generates the rule from code you already have. Point it at a file: /create rule create a generic API rule based on @main.py, and the agent writes the frontmatter and body for you. Then iterate the same way: ask the agent to update the rule until it captures the convention you mean.

Then read what it wrote. A generated rule tends to describe the file it came from, and the part worth keeping is the part nobody could have inferred from the code around it, so most of the editing is deletion. Where the rule needs to show a shape rather than describe one, Cursor's docs suggest pointing at the file (@component-template.tsx) instead of pasting its contents in. The rule stays short that way, and it doesn't go stale when the template changes.

That's the case for a rule over inference: exotic conventions the agent can't guess from existing files. Team-specific practices, JSON-config test parameters, remote-deploy or dev-server setup steps that live outside the test code. Scope the rule to the directory it governs and it travels into context exactly when it's needed.

Cursor follows rules that are easy to apply and hard to misread. Four habits get you most of the way:

• Scope with globs: a React rule shouldn't load for your SQL migrations.
• Be specific and short: concrete do/don't lines beat paragraphs of philosophy.
• One concern per file: testing rules, style rules and security rules separate.
• Show, don't lecture: a one-line example is worth a paragraph of description.

Short means shorter than you'd guess. Cursor's own open-source rules run about eight lines each. Context is a scarce resource, and every line of an always-on rule competes with the actual task for the model's attention.

I used to read "keep it short" as a token-budget argument. That's part of it and the smaller part: a short rule is also a rule with nowhere to hide a contradiction, and long rules usually got long by accreting exceptions that now disagree with each other. So read for contradictions first and cut for length second.

Cursor's docs carry a list of what to leave out, and I find it more useful than the list of what to put in. The agent already knows npm, git and pytest, so documenting your commands buys nothing. Edge cases you hit twice a year still cost context on every request that pulls the rule in. And anything already visible in the codebase should be pointed at rather than copied, because the copy stops matching the code the next time somebody edits it.

Use a rule when you want guidance that's always in force; use a skill when you want a procedure the agent will reliably run through. A rule that says "use the development build profile" can work, but it's soft: the agent may or may not follow it. A skill encodes the definitive steps, so the agent runs the whole workflow rather than interpreting a hint.

The reverse case gets less airtime. A skill has to be invoked, either by you or by the agent judging it relevant, which makes it a poor container for a constraint that has to hold on every change. Use our logger, never console.log is a standing condition on whatever work happens to be running, so it belongs in a rule and stays there.

A rule's frontmatter decides when it loads. Create rules from Settings > Rules, Skills, and Sub Agents > project > Rules > New, which writes an .mdc file under .cursor/rules/ with a name, description and apply header.

There are four apply modes, and they sit on a spectrum from always-on to never-unless-asked. Always loads into every prompt, apply intelligently lets the agent pull the rule in when the description matches, file-glob scopes it to matching paths, and manual waits for an @-mention. Pick the narrowest mode that still fires when you need it.

Where a rule lives decides who gets it. The same .mdc mechanics apply at every level, from rules that follow you personally to rules an admin sets for a whole org:

• User scope: personal rules that travel with you across projects.
• Repository scope: committed .cursor/rules/ every collaborator inherits.
• Team scope: on Teams and Enterprise, rules saved in the codebase or pushed team-wide so anyone in the repo inherits them.
• Org scope: admins scope configs per group, so the design team, PMs and security each get their own set.

Rules and skills start local; to share them you promote them up that ladder. An org-wide security rule is the cleanest example: when writing SQL, don't allow injections, enforced across every team automatically rather than left to each developer to remember.

How far up to push depends on how many people sit downstream. On a team of four, committed repository rules cover it. Everyone touches everything, and a rule someone disagrees with gets argued out the same afternoon. The same rule pushed org-wide at four hundred people has no such loop, because the person it annoys has no obvious route back to whoever wrote it. Team RulesRules promoted to apply across a whole organisation and shared consistently between the Cursor IDE, Agent and Bugbot. Press Enter for the full definition. can be saved without enforcement, which leaves the on/off switch with each member, and on a large org that's where I'd start.

There's a sideways route as well. From Customize you can add a Remote Rule pointing at a GitHub repository you have access to, public or private, and Cursor pulls the .mdc files it finds there into .cursor/rules/imported/<repoName> and syncs them. Useful when one platform team maintains the rules and a dozen product repos consume them, though the imported copies do land in your tree.

The common causes: the rule isn't scoped to the files you're editing (wrong or missing globs), the rule is too long or contradictory so it's diluted, the .mdc frontmatter is malformed or you're using the deprecated .cursorrules location. Tighten the glob, shorten the rule and confirm it's a valid .mdc under .cursor/rules/.

The first thing to rule out is the surface you tested on. Rules don't reach Cursor TabCursor's original autocomplete: multi-line, edit-aware suggestions you accept with the Tab key. Press Enter for the full definition. at all, and User Rules are read by Agent (Chat) and not by Inline Edit, so a User Rule you watched get ignored inside a ⌘+K edit was never in scope there. Re-run the same request in the agent panel before you touch any frontmatter.

After that, the glob. When it isn't the glob, the rules fix page walks the remaining causes in the order they're worth checking.