A Deep Dive into Cursor Rules (> 0.45)

[haojixing]

Understanding Cursor Rules Deeply

Lately, I’ve noticed many people discussing issues with Rules not working as expected. After diving into Cursor 0.45’s Rules mechanism, I discovered that the official documentation is incomplete. It hints at certain concepts but doesn’t align with our intuition, leading to misunderstandings for beginners. This article provides an in-depth explanation of the Rules system and its principles. Feel free to discuss if you have questions.

---

User Rules

User Rules define global preferences, like the desired tone, how the model addresses you, and principles for communication. These rules follow the editor and apply across all projects. User Rules are always sent to the AI in all chat sessions and conversations triggered by pressing Command-K.

---

Project Rules

Purpose

Project Rules are project-specific, designed to align with the needs of individual projects. Cursor organizes them as .mdc files in a structured system that automatically creates directories and files when new rules are added.

└── .cursor
    └── rules
        ├── global.mdc
        └── only-html.mdc

An .mdc file is plain text with content that looks like this:

---
description: Always apply in any situation
globs: 
alwaysApply: true
---

When this rule loads, input: "Rule loaded: global.mdc."

Editing Limitations

Cursor offers an integrated but buggy UI for editing .mdc files, which hasn’t been fixed yet. Editing these files with external tools like VSCode is recommended.

Why Store Them in .cursor/rules/?

1. They integrate into the codebase.
2. Files in .cursor can be committed to Git repositories.
3. Teams can collaborate using shared rules, ensuring consistency as everyone pulls the same rules.

---

How Do Project Rules Work?

• Do rules placed in the .cursor/rules/ directory automatically activate? No.
• Do the same rules apply equally across ask/edit/agent modes? No.

---

Two Stages of Activation in Cursor

Stage 1: Injection

Rules are injected into the system prompt context but aren’t yet active. Whether a rule is injected depends on:

1. alwaysApply : Injects the rule into the context unconditionally, but does not control activation .
2. globs : Matches files based on patterns (e.g., filenames, extensions). If matched, the rule is injected into the context. Again, this does not control activation .

Stage 2: Activation

Whether a rule takes effect depends on its description field.

Cursor appends the following structure to the system prompt:

<available_instructions>

Cursor rules are user-provided instructions for the AI to follow to help work with the codebase.

They may or may not be relevant to the task at hand. If they are, use the fetch_rules tool to fetch the full rule.

Some rules may automatically attach to the conversation if the user links a file matching the rule's glob; those won't need to be fetched.

# RULES_1.name: RULES_1.description

# RULES_2.name: RULES_2.description

</available_instructions>

<cursor_rules_context>

Cursor Rules are extra documentation provided by the user to help the AI understand the codebase.

Use them if they seem useful to the user's most recent query, but do not use them if they seem unrelated.

# RULES_1

# RULES_2

</cursor_rules_context>

That’s the key prompt Use them if they seem useful to the user's most recent query, but do not use them if they seem unrelated.

Key Points About Activation:

1. description : The description defines the appropriate scenarios, and the model will evaluate the context to decide whether the rule should be applied., such as:

• Always active in all situations.
• Active during planning discussions.
• Active for frontend projects.
• Etc.

2. AI Intelligence Required : The model must have sufficient intelligence to properly interpret the description. Less capable models (e.g., GPT-4-mini) may fail to understand and apply the rules effectively.

---

Summary

For Project Rules to work as intended, you must understand how these parameters interact:

1. alwaysApply : Suitable for global rules.
2. globs : Matches files or directories based on naming patterns.
3. description : Determines activation during conversations by instructing the model through natural language.

Understanding these combinations ensures seamless rule integration in your workflows.

[ishmeet]

@haojixing

description: Always apply in any situation

Wow, the description is really the key to this. I always thought description is only for my own reference to what the rules do.

For others who are wondering where this goes in UI like me, refer to the attached screenshot.

Verified for Claude-3.7-sonnet-thinking

[Xcoderz]

Please where is the option to enable always apply

[ishmeet]

@Xcoderz this is not an option. You would create a rules file and then add it in the description on the top as shown in my screenshot. This has to be done for each rules file you have within .cursor/rules/ directory

[JuanuMusic]

It’s the little globe button next to the Auto Attach field.
Turned on when its blue

[batzel]

“Use them if they seem useful” implies a suggestion, not a rule.

Someone’s watched too much Pirates of the Carribean: Curse of the Black Pearl and thinks they’re more like “guidelines” than “rules”

[michaelito80us]

Actually, from my own experimentation I have a slightly different experience with rules:

Determining if the rule will ultimately be used after being added to the context doesn’t depend on the description, but on the AI’s interpretation of the content, if it’s relevant to the query. Similarly, a rule that was already in the context (because of alwaysApply or glob pattern matching) can still be omitted if it’s not really relevant to the query.

The frontmatter section of the rule has 3 fields (this is an mdc frontmatter, not a YAML one.. so don’t treat it like yaml or you will be getting strings all the time “”):

---
description:
globs:
alwaysApply:
---

There are 4 combinations that we can use and each will treat the rule differently

1. Always add the rule to the context (doesn’t mean it will be used):

---
description:  # Empty
globs:     # Empty
alwaysApply: true
---

2. Automatically add a rule to the context if the user attaches or mentions a file in the chat that matches the rule’s glob pattern. (This means the rule won’t be automatically added if the agent just works on a file that matches the glob):

---
description:  # Empty
globs: src/**/*.ts,src/**/*.tsx.  # for now, it seems we cannot combine types with { }
alwaysApply: false
---

3. Let the AI agent decide from the context of the query whether to consider a rule useful based only on its description. If the rule gets selected, then the agent requests the full contents of the rule and decides if it’s really relevant. If yes, it attaches it to the request:

---
description:  (description for the agent to decide if the rule seems relevant)
globs:    # Empty
alwaysApply: false
---

4. If you have a rule that you intend to only use by referencing it (in the chat with @ or from another rule using markdown link format [rule-name.mdc](mdc:location/of/the/rule.mdc) ) explicitly:

---
description:  #Empty
globs:    # Empty
alwaysApply: false
---

---

Frontmatter?

Now you may be asking how to get to this frontmatter format from the rule. Well, the answer is to disable the special UI for .mdc files and present them as regular markdown (this way it’s also very straightforward to programmatically generate rules). To do this go to your Cursor user or workspace settings and add the following:

"workbench.editorAssociations": {
    "*.mdc": "default"
  }

---

A few thoughts on how to use description:

• Remeber that this is for the AI Agent to consider the rule, not for you!
• Say what it’s for, or when to use it. Experiment!
• I’ve used: When the user types “compile” - very direct and specific.
• Remember not to have both globs and description. If the rule is set to match a specific pattern, don’t crowd the list of rules that the agent needs to consider from context (the more rules there are for the agent consider, the higher the chances of the agent missing something important)
• You can use the following guidelines:
  • Consistent “USE WHEN” prefix makes it clear these are trigger conditions
  • Consistent verb format (gerund form: creating, writing, modifying)
  • Clear action-based conditions
  • Example: USE WHEN writing or modifying tests

Final thought: the rules implementation and methodology seems to be evolving constantly, changes are being made (some improve the experience and some degrade it), so what seems the best strategy today, might not be the best strategy tomorrow. And since the change is happening so fast, i understand why the documentation can’t keep up (as frustrating as that is)!

Hope this helps.