How Do You Write Cursor Rules That Actually Work?
Add a rule when Agent repeats a mistake, not before. Type /create-rule in the chat, or open Customize > Rules > Add Rule. Keep it short and concrete: real commands, your conventions, a pointer to a good example file, and things it must not touch. Project rules live in .cursor/rules and go in Git.
/create-rule Create a rule for this project from the corrections I've given you in this chat. Keep it under 30 lines. Include only: - Build and test commands that are specific to this repo - Conventions you got wrong, stated as direct instructions, for example: "Tests use Vitest, not Jest" - A pointer to one canonical example per pattern, such as @[example file], instead of pasted code - Files or folders not to edit Don't add general advice. Tell me which rule type you chose and why.
- Add a rule when a mistake repeats
- Name the tool: "Tests use Vitest"
- Point to one example file
- "Write clean code"
- "Follow best practices"
- Save a project rule as plain .md
Try it now
- 1Note one correction you've given Agent more than once.
- 2Type
/create-rulein the Agent input and describe it. Agent saves a file to.cursor/rules. - 3Start a new chat and give it a task where the mistake would show up. It worked if it does the right thing without being told. Commit the file so your team gets it.
Use it when
Any time you've given the same correction twice: the wrong test framework, a banned library, a file that's generated and mustn't be edited, a project-specific build command. Cursor's course lists build and test commands, code conventions, canonical examples and guardrails as what rules do best.
Skip it when
Don't paste a full style guide, because a linter does that job better. Don't document common tool commands the agent already knows, rare edge cases or copies of existing code. On a new prototype with no patterns yet, wait until you have conventions to write down.
Why it works
Models don't remember earlier chats, so anything you corrected yesterday is gone today. Cursor's docs explain that rules sit at the start of the model's context, so the agent has them from the first step. Specifics work because the agent can act on them: "Tests use Vitest" changes behavior, and "write clean code" doesn't. They also apply in all four modes. They cost space, though. Cursor's course warns that too many rules consume context and may confuse the agent.
Example
Cursor's course describes a team on Next.js, Tailwind and Vitest. Before rules, the agent uses Jest, creates CSS modules and scatters API routes. Three short lines fix it: one says tests use Vitest and names an example test file, one requires Tailwind utility classes instead of CSS modules, and one says where API routes go.
Going further
A file mention such as @service-template.ts in a rule isn't inlined. Agent reads it with its tools when it decides it needs to. That keeps rules short and stops examples going stale, but anything that must always be present belongs in the rule's body. Keep a rule under Cursor's 500-line guideline and split larger ones. You can also tag @cursor on a GitHub issue or PR to have Agent update a rule. If you still have a .cursorrules file, Cursor's help calls it legacy and says it will be deprecated, so move its content to a new Always Apply rule, which matches the old behavior, then delete it. To see what rules cost you, click the context ring and look at Rules.
Common mistakes
- Writing aspirations like "follow best practices", which give the agent nothing to act on.
- Saving a project rule as
name.mdin.cursor/rules. The docs say plain.mdfiles there are ignored, so it must be.mdc. - Expecting rules to change Tab suggestions. Cursor says they don't affect Tab.
- Never pruning. When conventions change, an old rule keeps enforcing the old way.
Sources
- Rules, Cursor Docs
- Rules, Cursor Help
- Customizing agents, Cursor Learn
- Agent mode, Cursor Help
- Agent Skills, Cursor Docs
Checked 6 November 2026. Products change often, so confirm details with the vendor.