How do you use Cursor rules (.cursor/rules) and which rule type should you pick?

Short answer

Project rules are .mdc files in .cursor/rules, kept in version control. The description, globs, and alwaysApply fields set one of four modes: Always Apply, Apply Intelligently, Apply to Specific Files, or Apply Manually. Cursor ignores a plain .md file in that folder; use AGENTS.md for plain markdown.

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

  1. Type /create-rule in Agent and describe what the rule should do. Or open Customize in the sidebar, go to Rules, and click Add Rule.
  2. Check that the file is in .cursor/rules/ and ends in .mdc. Subfolders are fine, for example .cursor/rules/frontend/.
  3. Pick the mode (below). It sets the fields at the top of the file.
  4. 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/.

Sources

  1. Cursor docs: Rules
  2. Cursor docs: Agent Skills
The first half hour · free

What does your AI forget?

  1. 01You tell us which AI you use and where it keeps starting over.
  2. 02We show what a shared memory changes there, on your own examples.
  3. 03You keep the plan, with or without Bombos.
Piet Baudoin
Piet BaudoinYou talk to Piet, from the Bombos teamDutch team from Utrecht and Nijmegen · data in Europe
We reply the same working day.