Rules
Write rules when Agent repeats a mistake, choose the right rule type, and move occasional instructions into skills.
-
AGENTS.md, Project Rules, User Rules or Team Rules: Which Do You Need? Use AGENTS.md for simple instructions in plain markdown, project rules in .cursor/rules when you need control over when they load, user rules for personal preferences across all projects, and team rules to set standards across an organization. Level 3: Workflows
- User RulesCustomize, your account
- Project Rules.cursor/rules, in Git
- Team Rulesdashboard, can be enforced
-
Which Cursor Rule Type Should You Use? A project rule is an .mdc file with three frontmatter fields, and they decide when it loads. Level 3: Workflows
- 1Always Applyevery chat, keep it very short
- 2Apply to Specific Fileswhen a matching file is in context
- 3Apply Intelligentlywhen the description fits
- 4Apply Manuallyonly when you @-mention it
-
When Should a Cursor Rule Be a Skill Instead? If something is needed only sometimes, make it a skill. Level 3: WorkflowsRuleswhat it should always know
- Loaded every conversation
- Always uses context
- Always-on conventions
Skillswhat it can do when asked- Loaded when relevant
- Full cost only when used
- Specialized workflows
-
How Do You Write Cursor Rules That Actually Work? Add a rule when Agent repeats a mistake, not before. Level 3: WorkflowsDo
- Add a rule when a mistake repeats
- Name the tool: "Tests use Vitest"
- Point to one example file
Don't- "Write clean code"
- "Follow best practices"
- Save a project rule as plain .md
Three decisions for every rule
Decide what it says, when it loads and where it lives. What it says should be concrete enough to act on. When it loads is set by the type: always, for matching files, when relevant, or only when mentioned. Where it lives decides who gets it: the repo, your account or your whole team.
Rules aren't the right tool for everything
Formatting belongs in a linter. Procedures you run sometimes belong in a skill. And Tab ignores rules altogether, according to Cursor's docs. Rules also don't guarantee anything, so Cursor warns against using them as your only security control. Commit them to Git, and update them when your conventions change.
Where do Cursor rules go?
Project rules go in the .cursor/rules folder as .mdc files. Personal rules go in Customize then Rules, and AGENTS.md goes in your project root or a subfolder.
Why isn't my Cursor rule working?
Check the file extension first, since plain .md files in .cursor/rules are ignored. Then check the type: Apply Intelligently needs a description, and Apply to Specific Files needs a pattern that matches files in context.
Is .cursorrules still supported?
Cursor's help calls the .cursorrules file legacy and says it will be deprecated. To migrate, run New Cursor Rule from the command palette, copy the content in, set the type to Always Apply, and delete the old file.
How long should a Cursor rule be?
Cursor's guidance is under 500 lines, but shorter is better. Rules take up context, and its course warns that too many can confuse the agent, so split large ones and reference files rather than pasting them.