The four kinds of rules
Cursor has four kinds of rules. They look alike until you ask who manages them:
| Kind | Where | Who it is for |
|---|---|---|
| Project Rules | .cursor/rules/ in the repository, as .mdc |
Everyone working in that repository |
| User Rules | Customize > Rules | Only you, across all projects, Agent (Chat) only |
| Team Rules | The Cursor dashboard, managed by team admins | The whole team, on a Team or Enterprise plan |
| AGENTS.md | Project root or a subdirectory | Everyone, and other AI tools too |
This page covers Project Rules, since those are the ones you set up yourself. Team Rules are covered in How do you share context and team rules in Cursor.
How to add a rule
- Type
/create-rulein Agent and describe what the rule should do. Or open Customize in the sidebar, go to Rules, and click Add Rule. - Check that the file is in
.cursor/rules/and ends in.mdc. Subfolders are fine, for example.cursor/rules/frontend/. - Pick the mode (below). It sets the fields at the top of the file.
- Commit the file, so everyone in the repository gets the same rule.
A rule, for example .cursor/rules/api.mdc, looks roughly like this:
---
description: Conventions for API routes and error handling
globs: src/api/**/*.ts
alwaysApply: false
---
Always use the error class from src/lib/errors.ts.
Return a 4xx with a readable message, never a stack trace.
The four modes
| Mode | Fields | When the agent uses it | Use it for |
|---|---|---|---|
| Always Apply | alwaysApply: true |
Every chat session | A few hard agreements: language, style, things that must never happen |
| Apply Intelligently | alwaysApply: false, a description, no globs |
When the agent decides it is relevant based on the description | Knowledge you need sometimes, like how to write a migration |
| Apply to Specific Files | alwaysApply: false with globs |
When a file matches the globs | Rules per part of the code: tests, API, styling |
| Apply Manually | alwaysApply: false, no globs, no description |
Only when you @-mention it, for example @api |
Procedures you call on purpose now and then |
The fields behind that choice are description, globs, and alwaysApply. For Apply Intelligently, the description is everything: it is the only line the agent sees when deciding. So write when the rule applies, not what is in it.
The common mistake: .md versus .mdc
A lot of advice online says you can drop plain markdown into .cursor/rules. Cursor’s own docs say otherwise: project rules must use the .mdc extension, and a plain .md file in .cursor/rules is ignored by the rules system. If you want plain markdown without fields, use AGENTS.md in the root or in a subdirectory. Nested AGENTS.md files are combined with their parents, and the more specific one wins.
A second trap is setting everything to Always Apply. Every always-on rule takes space in every conversation. Cursor recommends keeping rules under 500 lines and splitting big ones. Keep Always Apply for the few things that truly always hold, and let globs or a good description pick the rest.
When a skill fits better
A rule that is only sometimes needed and describes a whole procedure, with steps or scripts, often works better as a skill: a folder with SKILL.md that the agent loads when it needs it. The difference is explained in Cursor rules vs skills.
What this means for a team
Project Rules and AGENTS.md travel with the code when committed to the repository: whoever clones it has them. User rules stay on your own account, and a correction in one chat does not automatically become an instruction for every future chat. So when you give the same correction twice, put it in a rule and commit it. If part of the team uses another AI tool, put shared agreements in AGENTS.md rather than in .mdc files that only Cursor reads. Rules are not the only shared context: Cursor Projects also keep context that agents learn, see How do you share context and team rules in Cursor.
Where Bombos fits
Rules are instructions you write and maintain yourself. Cursor’s .mdc rules are tool-specific; AGENTS.md can provide shared instructions for compatible agents. Bombos is a plugin that gives every AI tool your team uses, Cursor included, one shared memory: team knowledge, rules it learns from corrections, and what already sits in email, documents, and repos, traceable, in the cloud or on your own server. One developer can try it first next to their own rules.
Related questions
Why is my rule not doing anything?
First check the extension: Project Rules require .mdc, and Cursor ignores plain .md files in .cursor/rules. Then check the rule type, the description, and the file patterns: an empty or vague description under Apply Intelligently means the agent rarely picks it.
How long can a rule be?
Cursor recommends keeping each rule under 500 lines and splitting large rules into multiple, composable rules.
What is the difference between a project rule and a user rule?
A project rule lives in the repository and applies to everyone who works in it. A user rule is set in Customize > Rules, applies across all your projects, and only to Agent (Chat).
Where do I add Cursor rules?
Type /create-rule in Agent, or open Customize in the sidebar, go to Rules, and click Add Rule. Project rules end up in .cursor/rules/.
