Why Cursor Rules Get Silently Ignored
A Cursor rule that the agent ignores is rarely wrong on the merits.
It is broken at the layer between disk and prompt.
Most of the fixes are mechanical.
What this covers
- Cursor rules fail silently most of the time. The file exists, the agent does not act on it, and nothing surfaces a warning.
- The common causes are frontmatter syntax errors, mixing the legacy .cursorrules file with the newer .cursor/rules/ directory, Agent mode bypassing the legacy file, and too many alwaysApply rules.
- Specificity matters. A vague rule gets averaged into general behavior and disappears.
- Pathrule routes rules by path and ships them at hook time, so the relevant slice arrives without depending on Cursor-specific rule discovery quirks.
Fast checks when a Cursor rule is being ignored
- Open Cursor Settings and confirm the rule is listed under Rules. If not, the frontmatter is the most likely cause.
- Confirm closing --- on the frontmatter is present and on its own line.
- YAML is case-sensitive. true is not True. globs must be an array.
- You do not have both a legacy .cursorrules file and a .cursor/rules/ directory active at the same time.
- You are not in Agent mode expecting the legacy .cursorrules file to be honored.
- Fewer than three rules are marked alwaysApply: true. More than that crowds the system prompt.
- The rule itself is specific, not abstract. Vague rules vanish into averaged behavior.
Comparison
| Symptom | Likely cause | First thing to try |
|---|---|---|
| Rule missing from Cursor Settings Rules panel | Frontmatter syntax error | Validate YAML, restore the closing fence |
| Rule listed but never applied | Description is too vague to match user requests | Rewrite the description and conditions to be directive and specific |
| Worked yesterday, ignored today | Switched into Agent mode where legacy .cursorrules is not loaded | Migrate to .cursor/rules/ format and delete the legacy file |
| All rules getting partly violated at once | Too many alwaysApply: true rules competing in the system prompt | Keep one or two alwaysApply rules and scope the rest by glob |
Cursor rules fail in a specific shape
The pattern is familiar enough that teams now expect it. A teammate writes a rule, commits it, opens Cursor, and the agent behaves as if the rule does not exist. There is no error message. The file is on disk. The agent simply does not act on it.
This is not the model being uncooperative. It is the layer between disk and the system prompt failing silently. Most of the fixes are mechanical and most of them are not in the file the team is staring at.
The good news is that the failure modes are well documented in the community discussions of the last year. The fixes are usually a few minutes of work once the root cause is identified.
Frontmatter is the most common silent killer
Cursor expects a strict YAML frontmatter block at the top of a rule file. Opening triple dashes, key value pairs, closing triple dashes. Any structural problem in that block makes the loader skip the rule with no surface warning.
Common breaks include a missing closing fence after a hand edit, a description value that an editor wrapped across multiple lines, special characters that were not quoted, and case mistakes inside YAML where True or False is silently not the boolean the loader was looking for.
The fast way to confirm is to open Cursor Settings, find the Rules panel, and check whether the rule is listed there. A rule with a broken frontmatter does not appear. A rule with a valid frontmatter does. That single check eliminates most ambiguity in under a minute.
The legacy file and the new directory do not coexist cleanly
Cursor used to support a single .cursorrules file at the repo root. It now supports a .cursor/rules/ directory with multiple typed rule files. Both still appear in the wild.
When both exist in the same repo, behavior gets unpredictable. Some sessions load the legacy file, some sessions load the directory, and reasoning about which rule applied to which session becomes guesswork.
The cleanest move is to pick one. Most teams have already migrated to the directory format for the typing and scope features. If yours has not, migrating fully and removing the legacy file eliminates a class of confusing behavior in one commit.
Agent mode is a different context surface
Agent mode changes the rule discovery behavior. In particular, the legacy .cursorrules file is not loaded the same way it is in older modes. A team that has not migrated to the directory format may see their rules disappear the moment they switch into Agent mode.
This is one of those changes that is easy to miss because the rule file looks unchanged. The team did not edit anything. The mode change quietly altered the discovery layer underneath.
The fix is the same migration path. Move rules to .cursor/rules/, write them with explicit globs and alwaysApply flags, and verify them in the Rules panel.
Too many alwaysApply rules crowd the system prompt
Each rule marked alwaysApply: true is injected into every request system prompt. Two such rules with sharp instructions can be very effective. Ten such rules compete with each other and with the user request. The model then produces a kind of averaged output that partially violates several of them.
A useful constraint is to treat alwaysApply as scarce. Reserve it for the small number of conventions that genuinely apply to every request. Scope the rest with globs so they only load when the agent is working on matching files.
A repo with thirty rules where only two are alwaysApply behaves dramatically better than the same thirty rules all marked alwaysApply. The information is the same. The delivery is different.
Vague rules disappear into averaged behavior
The remaining cause is the rule itself. A rule like "write good tests" gives the model nothing to compare against the current task. It blends into the model's general behavior and effectively vanishes.
A useful rule is specific about the trigger and the outcome. What file pattern does it apply to? What is the agent required to do, or required not to do? What is the failure case the rule prevents?
A rewritten rule that names the pattern and the constraint usually starts being observed in the next session. The file did not need a longer body. It needed a sharper one.
Where Pathrule fits next to Cursor rules
Cursor rules are a great mechanism when they work. They are also one delivery surface for one tool. Teams that use Cursor alongside Claude Code or Codex end up writing similar rules in three different formats and watching them drift apart.
Pathrule is a path-indexed knowledge graph for AI coding assistants. It routes team memories, rules, and skills into Cursor, Claude Code, Codex, Windsurf, and GitHub Copilot at hook time. The rule body is written once at the path where it applies. The slice the assistant sees on a given session is scoped to the work in front of it.
For a team that already has Cursor rules working, Pathrule is the layer above. The rules that really are cross-tool conventions live there. The Cursor-specific behavior stays where it is. Both layers are short, and neither one carries weight the other could carry better. Every signup gets three months of Pathrule PRO on the house, and [email protected] is open if you want help shaping the migration.