Why Cursor is ignoring your rules (.mdc + frontmatter)

On X and Reddit, “Cursor is ignoring my rules” is often not an adherence problem — the rule never entered context. Cursor project rules live in .cursor/rules/ as .mdc files with YAML frontmatter. A plain .md in that folder is ignored. Cursor also reads root AGENTS.md / CLAUDE.md as simpler always-on markdown.

Five checks before you rewrite the rule

1. Extension: file must end in .mdc inside .cursor/rules/.
2. Frontmatter fields: only description, globs, and alwaysApply control load mode.
3. Always Apply: alwaysApply: true puts the rule in every chat (use sparingly — it costs tokens every turn).
4. File-scoped: set globs and alwaysApply: false so it attaches when matching files are in context.
5. Apply Intelligently / manual: a description without globs lets the agent decide; with neither description nor globs nor alwaysApply, you typically need to @-mention the rule.

Minimal working example

---
description: TypeScript conventions for this repo
globs:
  - "**/*.ts"
  - "**/*.tsx"
alwaysApply: false
---

- Prefer explicit return types on exported functions
- Follow the patterns in @src/lib/result.ts instead of inventing new Result helpers

If it loads but still feels ignored

• Vague wording: “write clean code” loses to “use 2-space indentation” — Cursor’s docs ask for actionable rules.
• Conflicts: the same always/never restated differently across AGENTS.md and several .mdc files makes the model hedge. Cut one canonical line first.
• Too much always-on: large always-applied rules compete with the task. Prefer globs/skills for procedures.
• Stale pasted docs: reference canonical files; don’t paste whole style guides (Cursor explicitly warns against this).

Prefer a short AGENTS.md example for cross-tool basics, and reserve .mdc for activation control. Compare formats in CLAUDE.md vs AGENTS.md vs Cursor rules.