Fix Cursor Rules Not Working

Match the symptom

• A file under `.cursor/rules` never appears in Cursor.
• An Always rule works but a glob-scoped rule does not.
• An intelligently applied rule activates inconsistently.
• A rule affects Agent Chat but not Cursor Tab or Inline Edit.

First checks

Collect evidence before changing configuration

Customize > Rules
/create-rule
@rule-name

.cursor/rules/example.mdc

Diagnosis 1

Confirm Cursor recognizes the file

A Project Rule requires the `.mdc` extension and valid frontmatter; a plain `.md` file under `.cursor/rules` is ignored.

1. Open Customize → Rules and locate the rule by name.
2. Rename `.md` to `.mdc` only after adding valid frontmatter.
3. Keep the rule inside the active workspace's `.cursor/rules` directory.
4. Use `/create-rule` to generate a correctly structured starting file.

Decision: If the rule is missing from Customize, fix its path, extension, or frontmatter before testing its content.

Diagnosis 2

Match metadata to one activation mode

Cursor combines `alwaysApply`, `description`, and `globs` to decide when a Project Rule enters context.

1. Use `alwaysApply: true` for every Agent chat; globs and description are ignored in this mode.
2. Use a glob with `alwaysApply: false` for matching files.
3. Use a description without globs for intelligent relevance selection.
4. Leave both description and globs empty for manual `@` invocation.

---
globs: src/api/**/*.ts
alwaysApply: false
---

- Validate input at every API boundary.

Decision: Do not combine fields hoping to make activation stronger; choose the one behavior you can test.

Diagnosis 3

Test globs against the exact workspace path

A correct-looking rule still stays absent when its glob does not match the referenced file.

1. Reference a known matching file in Agent Chat.
2. Compare `*.ts`, `**/*.ts`, and `src/**/*.ts` carefully.
3. Use comma-separated patterns for multiple globs as documented by Cursor.
4. Test one known non-matching file to prove the scope is narrow.

Decision: When the matching file activates the rule and a control file does not, glob scope is working.

Diagnosis 4

Check product surface and conflicting guidance

Cursor documents different rule coverage across Agent, Tab, and Inline Edit, while multiple active rules can contradict each other.

1. Test Project Rules in Agent Chat first.
2. Do not expect rules to affect Cursor Tab.
3. Do not expect User Rules to apply to Inline Edit.
4. Disable unrelated rules temporarily and remove duplicated or conflicting instructions.
5. Replace copied style guides with linters and point to canonical code examples.

Decision: If a concise Always rule works alone, re-enable other rules in small groups to locate the conflict or context overload.

If it still fails, send this evidence

A useful support request is reproducible and does not expose credentials.

• Cursor version, operating system, and workspace root.
• Rule path, filename, and frontmatter.
• The exact file path expected to match the glob.
• Whether the test used Agent Chat, Inline Edit, or Cursor Tab.
• A minimal rule and prompt that reproduce the failure.