.cursorrules doing nothing in Cursor agent mode? Here's exactly why (and the fix)

You wrote .cursorrules. You put real work into it — 40 lines of carefully worded conventions, stack-specific patterns, things that took you weeks of trial and error to figure out. You committed it. You expected Cursor to follow it.

In agent mode, Cursor ignores all of it. Silently. No error. No warning. Just... nothing.

Here's exactly why this happens and how to fix it in under 10 minutes.

---

Why agent mode ignores .cursorrules

Cursor has two separate rule-loading systems, and they do not overlap:

• Ask / Edit mode reads .cursorrules from your project root
• Agent mode reads .mdc files from .cursor/rules/

When you run agent mode, Cursor's context pipeline skips .cursorrules entirely. It looks for Markdown Component (.mdc) files with a specific frontmatter schema. If it doesn't find them, it runs without any project rules at all — and gives you zero indication that this is what's happening.

This isn't a bug that's being fixed. It's an architectural split between legacy rule format (.cursorrules) and the current Project Rules system (.mdc). The formats coexist in the codebase but serve different execution paths.

The practical consequence: if you've been relying on .cursorrules to control agent behavior, you've been running agent mode with no guardrails.

---

The .mdc format: what it actually looks like

An .mdc file lives in .cursor/rules/ and uses YAML frontmatter to declare scope and application behavior.

Minimal example that applies globally in agent mode:

---
description: "Core project conventions"
alwaysApply: true
---

Use TypeScript strict mode. Never use `any`.
Prefer named exports over default exports.
All async functions must handle errors explicitly — no unhandled promise rejections.

Save this as .cursor/rules/core.mdc.

To scope a rule to specific file types:

---
description: "React component conventions"
alwaysApply: true
globs: ["**/*.tsx", "**/*.jsx"]
---

Components are function components only — no class components.
Props interfaces are named `<ComponentName>Props`.
Never use `React.FC` — annotate the return type instead.
Use `useCallback` for handlers passed as props.

Save as .cursor/rules/react.mdc.

The globs field is important. Without it, alwaysApply: true loads the rule but Cursor may deprioritize it in long context windows. With a glob, the rule is treated as directly relevant to the current file — higher pickup rate in practice.

---

How to migrate: step by step

Step 1: Create the rules directory if it doesn't exist.

mkdir -p .cursor/rules

Step 2: Split your .cursorrules by concern. Don't copy it as one block — long single-file rules have lower compliance than short scoped ones. Aim for one file per domain: core.mdc, react.mdc, api.mdc, testing.mdc.

Step 3: Convert each section. The pattern is:

---
description: "<what this covers>"
alwaysApply: true
globs: ["<relevant glob>"]  # omit for global rules
---

<your rules here, one concern per line>

Step 4: Delete or rename .cursorrules. Keeping both creates ambiguity. In agent mode it won't matter (agent ignores .cursorrules), but in Ask/Edit mode both might apply — or conflict. Rename it to .cursorrules.bak until you've verified the migration, then delete it.

Step 5: Test. Open a new agent session, ask it to write something your rules would normally constrain, and verify it complies. If it doesn't, the issue is usually rule length (over 200 lines in a single file degrades pickup) or missing alwaysApply: true.

---

The 3 rules that break most silently in this transition

These are the rule categories that users report failing after migration — not because the format is wrong, but because they need additional adjustments to work correctly in .mdc.

1. "Always use X library for Y"

In .cursorrules, a rule like "Use Zod for all schema validation" works because it's repeated every session. In .mdc, if the rule is in a global file without a glob, agent mode may decide it's not relevant to a non-schema file and skip loading it entirely.

Fix: Move library-preference rules to a scoped .mdc file with the glob of the files that would actually import that library. zod.mdc with globs: ["**/*.ts", "**/*.tsx"] has much higher pickup than a global rule buried in core.mdc.

2. Negative rules ("never do X")

Rules written as prohibitions — "never use var", "don't use any", "avoid mutation" — have lower compliance in agent mode than positive rules. The model processes instructions, and negative framing requires an extra inference step.

Fix: Reframe as positive imperatives. "Use const and let only" is more reliable than "never use var". "All types must be explicit" is more reliable than "don't use any".

3. Long prose paragraphs

If you wrote your .cursorrules as paragraphs explaining the reasoning behind each rule, those explanations consume context budget without improving compliance. Agent mode doesn't need the rationale — it needs the constraint.

Fix: Strip explanations. One line per rule, imperative verb first. The context budget saved goes toward following the rules.

---

The alwaysApply trap

alwaysApply: true means the rule is loaded into context on every agent run, regardless of which files are being edited. But "loaded" and "followed" aren't the same thing.

Cursor 0.16+ introduced quiet rule downgrading: rules that are very long (200+ lines) or very generic get silently deprioritized during context compaction. There's no log entry for this. The rule appears to be loaded but has no practical effect.

The combination that actually works:

---
description: "TypeScript conventions"
alwaysApply: true
globs: ["**/*.ts", "**/*.tsx"]
---

alwaysApply: true ensures it loads. The glob ensures it's treated as high-relevance when TypeScript files are in context. Neither alone is as reliable as both together.

---

What "agent-mode tested" actually means

A rule is agent-mode compliant when:

1. It lives in .cursor/rules/ as an .mdc file
2. It has alwaysApply: true in frontmatter
3. It's scoped with a glob matching the files it should govern
4. It's under 50 lines per file
5. Each rule is a single imperative sentence

Rules that pass all five conditions have consistent pickup in agent sessions. Rules that fail any one of them are a coin flip.

Most .cursorrules files fail conditions 1, 2, and 3 by definition — they predate the .mdc format. That's why agent mode is ignoring yours.

---

Quick validation script

After migrating, run this to verify your .mdc files have the required frontmatter:

for f in .cursor/rules/*.mdc; do
  echo "=== $f ==="
  head -6 "$f"
  echo ""
done

Every file should show alwaysApply: true (or alwaysApply: false if intentionally opt-in) and a description field. If you see a file that starts directly with rule text — no --- delimiters — that file won't load correctly.

---

TL;DR

• .cursorrules = Ask/Edit mode only. Agent mode ignores it.
• Agent mode reads .mdc files in .cursor/rules/ with alwaysApply: true frontmatter.
• Migrate by splitting .cursorrules into scoped .mdc files, one domain per file.
• Add globs to every file that targets a specific stack or file type.
• Keep each file under 50 lines and each rule to one imperative sentence.

This is the migration that users in the Cursor forums have been asking about since 2025. The fix is mechanical once you know what's happening — the hard part is that Cursor never tells you anything is wrong.

---

If you'd rather not debug this yourself — the Cursor Rules Pack at oliviacraftlat.gumroad.com/l/wyaeil ships 50 rules across 14 stacks, pre-structured in .mdc format with correct frontmatter, glob scoping, and agent-mode compliance baked in. One-time $27, instant download. No migration required — drop it in .cursor/rules/ and you're done.