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

Clogmeter — Wed, 04 Nov 2026 16:23:52 +0000

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

Extension: file must end in .mdc inside .cursor/rules/.
Frontmatter fields: only description, globs, and alwaysApply control load mode.
Always Apply: alwaysApply: true puts the rule in every chat (use sparingly — it costs tokens every turn).
File-scoped: set globs and alwaysApply: false so it attaches when matching files are in context.
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.

How long should CLAUDE.md / AGENTS.md be?

Clogmeter — Wed, 04 Nov 2026 16:22:56 +0000

Every always-on instruction file costs tokens on every turn, and past a point it starts costing adherence too. Here is what Claude Code, Cursor and Codex actually document about size, plus a checklist for trimming.

Originally published on clogmeter.vercel.app.

Short answer: aim for a lean always-on file — roughly under 200 lines per CLAUDE.md
(Anthropic’s documented target) and treat Cursor project rules as under 500 lines each,
split by concern. There is no universal “perfect” line count. The real limit is whether the model
still follows the rules that matter once system prompt, tools, skills and the task compete for the
same attention budget.

No invented benchmarks here. The numbers below come from vendor docs and published guidance as of late 2026.

What the tools themselves say

Tool	File	Published guidance
Claude Code	`CLAUDE.md` / rules	Target under 200 lines per file; longer files consume more context and reduce adherence. Imports organise files but still load with the parent.
Cursor	`.cursor/rules` / `AGENTS.md`	Keep rules under 500 lines; split large rules into focused files. Prefer references over pasting whole docs.
OpenAI Codex	`AGENTS.md`	Combined project instruction files are capped (default 32 KiB); overflow is truncated.

Community write-ups often talk about a practical “~150 instruction” attention budget for frontier
models before adherence drops — that is research/context, not a hard file limit. Your instruction
file shares that budget with the agent’s system prompt and tool descriptions, so leave headroom.

Why bloated files get ignored

Everything always-on costs every turn. Root CLAUDE.md / AGENTS.md is re-read at session start; fat files tax every message and every general-purpose subagent.
Markdown is advisory. Claude Code docs treat memory files as context, not enforced config. A “never” in prose can still be skipped; hooks and permissions enforce must-holds.
Conflicts cancel each other. Duplicate or contradictory always/never rules across files make the model pick arbitrarily.
Long sessions compress early rules. Mid-thread, package-manager or style rules often shrink first while code stays — which feels like “Cursor/Claude is ignoring my rules.”

A practical size checklist

Measure first. In Claude Code, run /context (and /doctor for trim proposals). For any stack, paste the files into Clogmeter to see token weight vs common windows and spot duplicates/conflicts.
Keep always-on content tiny. Project identity, hard constraints, build/test commands, and pointers. Delete anything the agent can discover by reading the repo.
Move procedures to skills. Release checklists and long how-tos should load on demand, not on every prompt.
Scope directory rules. Nested AGENTS.md / path-scoped Cursor or .claude/rules files beat one giant root file.
Enforce never-rules outside markdown. If ignoring it once would hurt, use a hook, linter or CI check.
One source of truth. Prefer a canonical AGENTS.md with thin CLAUDE.md / Cursor adapters instead of divergent copies.

How long is “too long” in practice?

If the root file is hundreds of lines, mixes architecture essays with one-off workflows, or repeats
the same rule in three places, it is already too long for reliable adherence — even if the model
still “sees” the file. Vendors warn that longer instruction files reduce compliance before hard
truncation kicks in (Codex’s 32 KiB cap being the blunt case).

A useful rule of thumb many teams use: if you would not ask a new teammate to memorise the whole
file before their first PR, do not force the agent to either. Make the root file the map; put the
territory in scoped docs and skills.