How to figure out why your cursor rules aren't working

Guides
1

if your .mdc rules aren’t being followed, here’s how to narrow it down. i tested 7 common breakage modes and most of them are easy to fix once you know where to look.

step 1: check your frontmatter

open your .mdc file. it needs to start with valid YAML frontmatter between --- markers:

---
description: your rule description
alwaysApply: true
---
your rule content here

if the closing --- is missing or the frontmatter isn’t there at all, the rule silently doesn’t load. no error, no warning. this is the most common thing i see people hit.

step 2: check alwaysApply

you’d expect alwaysApply: false to prevent the rule from loading, but in my tests it still loaded in agent mode. and leaving alwaysApply out entirely also worked. so if your rule isn’t loading, this probably isn’t the problem. check your frontmatter formatting first.

step 3: check for conflicts

if you have the same rule in both .cursorrules and .cursor/rules/, the .mdc version wins silently. the .cursorrules version gets ignored. if you’re editing .cursorrules and nothing changes, check if there’s a .mdc file overriding it.

step 4: check your globs

if you set globs: ["*.xyz"] but you’re working on a .ts file, you’d think the rule wouldn’t load. in my tests, alwaysApply: true overrides the glob and the rule still loaded. but if you’re relying on globs to scope rules to specific file types without alwaysApply, test that it’s actually scoping correctly.

step 5: check your rule content, not just the setup

if the rule loads but the model still ignores it, the problem might be the rule itself. vague rules like “write clean code” get ignored. specific rules like “all type aliases must use the Branded prefix” get followed. i tested this across multiple models and the prompt quality mattered more than which model i used.

quick reference

issue breaks the rule?
malformed YAML (no closing ---) :cross_mark: silent failure
no frontmatter at all :cross_mark: silent failure
missing alwaysApply :white_check_mark: still works
alwaysApply: false :white_check_mark: still works in agent mode
wrong glob pattern :white_check_mark: alwaysApply overrides it
empty description :white_check_mark: still works
.cursorrules + .mdc conflict :white_check_mark: .mdc wins

tested on cursor CLI 2026.02.13-41ac335.

3

Great debugging guide. One thing I’d add - sometimes rules “work” (they load fine, frontmatter is correct) but they’re still hurting you because they waste tokens on vague instructions or overlap with other context files.

I built a small CLI tool that shows you exactly how many tokens each rule file costs:

```

npx ai-context-kit measure

```

Gives you a per-file token breakdown so you can spot which rules are eating your context budget. Also lints for conflicts if you have both `.cursor/rules` and a `CLAUDE.md` or `AGENTS.md` in the same project.