Understanding Cursor Rule Attachment

You've meticulously crafted rules for your .cursor/rules directory, expecting the Cursor AI agent to leverage them. Yet, they seem to be ignored. This common frustration stems not from a faulty AI model, but from a misunderstanding of how rules are attached to the chat context. The core issue is that the rule never even enters the active context because its frontmatter configuration is incorrect.

Cursor has four distinct mechanisms for a rule to become active in a chat session. Each of these mechanisms is controlled by specific frontmatter fields within the rule's .mdc file. If these fields are misconfigured, the rule remains inert, sitting on disk without influencing the AI's responses.

Let's break down the four rule types and the critical frontmatter that governs them. Mastering this is key to unlocking the full potential of your custom AI behavior within Cursor.

The Four Rule Types and Their Frontmatter Triggers

A rule file, typically located at .cursor/rules/*.mdc, can be classified into one of four types based on its frontmatter. This classification dictates when and under what conditions the rule will be considered by the Cursor agent.

Always Apply Rules

These are the most straightforward rules. As the name suggests, they are designed to be active in every chat session, regardless of the specific files you're editing or referencing. The sole frontmatter key required for this type is:

  • alwaysApply: true

When this flag is set, Cursor will ensure this rule is part of the context for every interaction. This is ideal for fundamental instructions or guardrails you want to apply universally, such as coding style guides or project-specific terminology definitions.

Auto Attached Rules

Auto Attached rules are more context-aware. They trigger when the agent detects that you have either edited a file that matches a specific glob pattern or have explicitly referenced a file within your prompt or context. The frontmatter keys for this type are:

  • glob: ""
  • description: ""

The glob pattern is crucial here. It functions similarly to file matching in shell environments or build tools, allowing you to specify which files or file types should activate this rule. For example, glob: "src/**/*.py" would ensure the rule is considered for any Python file within the src directory and its subdirectories. The description field provides a human-readable explanation of the rule's purpose, which can be helpful for debugging and understanding.

User Attached Rules

User Attached rules offer explicit control. They are activated only when the user manually includes them in the chat prompt or through specific UI actions within Cursor. The frontmatter for these rules is:

  • description: ""

While there isn't a specific key to *force* attachment like alwaysApply or glob, the description field is still important. It helps Cursor understand the intent when you refer to the rule. To activate a User Attached rule, you might explicitly mention it in your prompt, such as, "Using the rule about optimized database queries, refactor this code." The agent then looks for rules with matching descriptions that are available for user attachment.

Implicitly Attached Rules

These rules are less common and are primarily for system-level or highly specific internal use cases. They are attached implicitly by Cursor itself based on certain internal states or configurations. As a user, you typically do not directly control these rules through frontmatter in your custom rule files. Their frontmatter might not even be exposed or relevant for user-defined rules.

Common Mistakes That Prevent Rules from Firing

The majority of issues where custom rules fail to activate can be traced back to three primary mistakes in frontmatter configuration:

1. Incorrect or Missing Glob Patterns

For rules intended to be Auto Attached, the glob pattern is paramount. If the pattern is syntactically incorrect, too broad, too narrow, or simply missing, the rule will never be associated with the files you are working on. For instance, a pattern like glob: "*.js" will only match JavaScript files in the root directory of your project, ignoring any in subfolders. A more robust pattern might be glob: "**/*.js" to include files in all subdirectories. Always double-check your glob syntax and ensure it accurately reflects the files you want the rule to apply to.

2. Misunderstanding of `alwaysApply`

While alwaysApply: true seems straightforward, developers sometimes misuse it. This flag should be reserved for rules that genuinely need to be active in *every single* chat. Overusing alwaysApply can lead to performance degradation or unexpected behavior, as the agent has to consider a larger set of rules for every interaction. If a rule is only relevant to specific file types or project contexts, an Auto Attached rule with a precise glob pattern is a more appropriate choice.

3. Inadequate or Missing Descriptions

The description field serves a dual purpose. Firstly, it aids Cursor in understanding the rule's intent, especially for User Attached rules. If your description is vague, misspelled, or doesn't accurately reflect the rule's function, the agent might struggle to associate it with your prompts. Secondly, it acts as crucial metadata for you and other developers working on the project. A clear, concise description makes it easier to manage and debug your rule set. Forgetting this field entirely means losing valuable context and potentially making rules harder to identify later.

Ensuring Your Rules Are Attached

To guarantee your rules fire correctly, follow these best practices:

  • Verify Frontmatter: Always start by checking the frontmatter of your .mdc rule files. Ensure alwaysApply is set correctly, or that your glob patterns are accurate and cover the intended files.
  • Use Specific Globs: Be as specific as possible with your glob patterns to avoid unintended activations and ensure rules only apply where needed. Test your globs with tools if necessary.
  • Write Clear Descriptions: Provide descriptive, accurate text for the description field. This aids both the AI and human understanding.
  • Understand Rule Types: Choose the rule type (Always, Auto Attached, User Attached) that best fits the intended scope and activation method for your rule.
  • Check for Typos: Simple typos in key names (e.g., alwayApply instead of alwaysApply) or values can silently disable a rule.

By paying close attention to these frontmatter details, you can ensure that your custom Cursor rules are correctly attached to the chat context and function as intended, enhancing your AI-assisted development workflow.