Your .cursorrules File Is Being Silently Ignored in Cursor Agent Mode (Here's the Fix)

You set up .cursorrules. You wrote your stack preferences, your naming conventions, your "never do this" list. You hit run.

The agent does whatever it wants.

No error. No warning. Just ignored.

---

Why .cursorrules Breaks in Agent Mode

The .cursorrules file format is legacy. Cursor still reads it in standard chat, but Agent Mode — the mode that actually runs multi-step tasks autonomously — uses a newer system: .cursor/rules/*.mdc files.

When you run an agent, Cursor evaluates which .mdc rule files apply to the current context. If your rules still live in .cursorrules, the agent runs with zero rule enforcement. Silently. Without telling you.

This explains:

• Why your agent keeps using the wrong framework
• Why naming conventions get ignored mid-run
• Why the same instruction works in chat but not in agent tasks

---

The Fix: Migrate to .mdc

Here's the minimal working structure:

your-project/
└── .cursor/
    └── rules/
        ├── always.mdc          ← global rules, always loaded
        ├── backend.mdc         ← loaded for backend files
        └── no-defaults.mdc     ← hard blocks (never use X)

always.mdc — Rules that must always apply

---
description: Core project rules for all agent tasks
alwaysApply: true
---

# Project Rules

- Stack: Next.js 14, TypeScript strict, Tailwind CSS
- Never use `any` type — use explicit types or `unknown`
- All components in `/components`, never inline in pages
- Write tests for every exported function
- Commit messages: conventional commits format

The key field is alwaysApply: true. Without it, the agent may skip the rule file entirely.

backend.mdc — Context-specific rules

---
description: Rules for API routes and server-side code
globs: ["app/api/**", "lib/server/**"]
alwaysApply: false
---

# Backend Rules

- All API routes must validate with Zod
- Never expose raw database errors to the client
- Use the shared `apiResponse()` helper for all responses

The globs field tells Cursor when to load this rule. If the agent is touching app/api/users/route.ts, it'll pick up the backend rules automatically.

---

Common Migration Mistakes

1. Putting alwaysApply: false on your global rules
Without alwaysApply: true, the agent only loads the rule when the file glob matches. Global rules need to be global.

2. Keeping both .cursorrules and .mdc files
Cursor will sometimes pick up the legacy file in chat but ignore it in agent mode. Delete .cursorrules once you've migrated. Clean state is safer.

3. One giant .mdc file
Rule files are evaluated per-context. A single 500-line .mdc with all rules applied at once is worse than 4 focused files. Split by domain: always-apply globals, language-specific, framework-specific, no-go lists.

4. Missing the YAML frontmatter
The --- block at the top is required. A valid .mdc without frontmatter may not load at all.

---

Quick Migration Checklist

• [ ] Create .cursor/rules/ directory in your project root
• [ ] Create always.mdc with alwaysApply: true for global rules
• [ ] Copy your most critical .cursorrules content into always.mdc
• [ ] Split domain-specific rules into separate .mdc files with globs
• [ ] Delete .cursorrules or rename to .cursorrules.bak
• [ ] Test: run a simple agent task and confirm rule enforcement

---

Going Further

If you want a battle-tested set of .mdc rules ready to drop in, the Cursor Rules Pack v2 includes 15+ pre-built rule files covering TypeScript, React, Next.js, API design, testing, and commit conventions — all in the correct .mdc format with proper frontmatter.

Not ready to pay? Grab the free starter pack first. It includes basic .mdc templates you can use today.

---

The .cursorrules deprecation is quiet and undocumented in most tutorials. If your agent keeps ignoring your rules, this is almost certainly why.

Fix the format. The rules will follow.

---

Olivia — building agent-native development workflows at oliviacraft.lat