Writing Cursor rules that actually fire: activation modes explained
A Cursor rule that never fires is indistinguishable from a rule you never wrote. There is no warning, no log line, no UI flag. You find out when the agent, for the fifth time, generates API errors as raw strings despite your beautifully written rule saying not to. This article is about the activation mechanics that decide whether a rule loads at all. The frontmatter Every .mdc file in…
The article explains how Cursor rule activation works and how to avoid common pitfalls. Cursor rules are defined in .mdc files with YAML frontmatter containing three fields: description, globs, and alwaysApply. The frontmatter determines when a rule loads.
There are four activation modes: Always, Auto Agent, Agent Requested, and Manual. Always rules load on every request, costing tokens, and should be kept to a minimum. Auto Agent rules load when files matching the globs appear in the agent's context, making them the most common use case. Agent Requested rules fire when explicitly invoked in chat, useful for cross-cutting rules. Manual rules are invoked when mentioning the rule name in chat and are meant for heavyweight references.
The article outlines five failure modes. Broken globs are the most common, where the specified path matches no files, and the rule never loads without any indication. Single-string globs require an array format for multiple paths. Description-only rules in Agent Requested mode need to include the necessary trigger vocabulary for the model to match.
Every rule marked important with alwaysApply: true can lead to a bloated implicit CLAUDE.md. Lastly, filewatcher drift occurs when reorganizing the repository, causing scoped rules to fail quietly without any warning.
To catch these issues, the author recommends auditing the globs by checking if they match at least one real file in the repository. A Python script, rules_audit.py, is provided to automate this process. Alternatively, the AgentConfig Studio includes a validation harness that parses rule frontmatter, verifies required files and line budgets, and scans for placeholder rot. Following these guidelines ensures that Cursor rules fire as intended.
Written by urgent.news from Dev.to's reporting — not their text. Machine-written — may contain errors; check the original before relying on it.
