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

If Cursor keeps skipping your project rules, it's usually frontmatter, scoping or context pressure rather than the model. Here are the common causes and how to fix each one.

Originally published on clogmeter.vercel.app.

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.

Checklist below matches Cursor’s public Rules docs (keep rules under 500 lines; split large ones).

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.

If you want to see where your own AGENTS.md, CLAUDE.md or Cursor rules spend tokens, I built a free browser-only checker that also flags duplicates and always/never conflicts: Clogmeter.