(This may be correct today and wrong tomorrow 
)
When should rules run?
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 of the rule and it’s relevance 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 and depending on how you use them, the rule will be added to the context or not (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
- Always add the rule to the context (doesn’t mean it will be used):
--- description: # Empty globs: # Empty alwaysApply: true --- - 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 --- - Let the 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 --- - 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 - you attach the rule to the chat:--- 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.