Troubleshooting

Cursor Rules Not Working? Here's How to Fix It (2026)

Cursor Rules Not Working? Here's How to Fix It (2026)

Last updated: May 2026 · Covers Cursor 0.47+ with .cursor/rules/ and .cursorrules formats

You wrote careful rules. Cursor ignores them anyway. The AI invents APIs you told it never to use, skips the testing patterns you defined, and structures files differently from your conventions — every single session.

This is one of the most common complaints in the Cursor community, and in 2026 it has gotten more complicated because Cursor now has two coexisting rule formats with different loading behaviours, activation modes, and Agent mode compatibility. Most guides online still describe the old single-file setup, which explains a lot of the confusion.

This guide covers every confirmed reason Cursor ignores rules, with a specific fix for each.

Quickstart: Diagnostic Checklist

Run through this list first to identify your issue, then jump to the relevant fix below.

  1. Using Agent mode with a .cursorrules file? → Fix #1
  2. Both .cursorrules AND .cursor/rules/ exist in your project? → Fix #2
  3. More than 3–4 rules with alwaysApply: true? → Fix #3
  4. Rule file longer than 500 lines? → Fix #4
  5. Rules are vague ("write clean code", "follow best practices")? → Fix #5
  6. Rules contradict existing code patterns in your project? → Fix #6
  7. Glob patterns not targeting the right files? → Fix #7
  8. Edited rules but Cursor still uses the old version? → Fix #8

Fix #1 — .cursorrules Is Silently Ignored in Agent Mode

This is the most common issue in 2026 and the least documented.

When you activate Agent mode in Cursor, the AI switches to a different context loading path. The .cursorrules file is not loaded in Agent mode — at all. This is not a bug. It is a deliberate architectural decision: Agent mode has its own context mechanism that bypasses the legacy single-file format entirely.

If your team has adopted Agent mode for refactors, feature implementation, or code review workflows, your .cursorrules file is providing zero guidance during those sessions.

How to confirm this is your problem:

Ask Cursor directly in an Agent session:

What rules are you currently following for this project?

If it does not mention your .cursorrules content, Agent mode is the culprit.

The fix: migrate to .cursor/rules/*.mdc

The .mdc format is loaded in all Cursor modes — Chat, Composer, and Agent. Create a .cursor/rules/ directory at your project root and move your rules into .mdc files:

project-root/
└── .cursor/
    └── rules/
        ├── general.mdc
        ├── typescript.mdc
        └── testing.mdc

Minimal .mdc file structure:

---
description: General project conventions
alwaysApply: true
---

You are working on a Next.js 15 App Router project with TypeScript strict mode.
Never use default exports except for Next.js pages.
Never use `any` types — use `unknown` and narrow it.
Maximum function length: 40 lines.

Once you have .mdc files in place, your rules load in every mode including Agent. You can keep the .cursorrules file as a fallback for non-Agent sessions, but read Fix #2 first.

Fix #2 — Having Both Formats Causes Undefined Behaviour

If you have both a .cursorrules file and a .cursor/rules/ directory, their interaction is unpredictable. In practice: .mdc rules take precedence over .cursorrules on conflicting instructions, and .cursorrules is silently overridden without any warning.

This means if you are testing new .mdc rules alongside your existing .cursorrules, you may find your old rules being ignored — not because they are wrong, but because the .mdc format wins.

The fix: pick one format and delete the other.

  • Use .cursor/rules/*.mdc if you use Agent mode, have a multi-layer project (frontend/backend/tests), or want glob-based rule scoping.
  • Use .cursorrules only if your project is simple, you never use Agent mode, and you want the fastest possible setup.

For most projects in 2026, .mdc is the correct choice. Migrate fully and delete .cursorrules to eliminate format conflicts.

Fix #3 — Too Many alwaysApply Rules Overload the Context Window

Every rule marked alwaysApply: true is injected into the system prompt of every Cursor request — regardless of what you are working on. If you have 10 or more rules all set to alwaysApply: true, you are consuming a significant portion of the context window before the conversation even begins.

The practical result: the model tries to satisfy all rules simultaneously, produces "average" output that partially violates most of them, and prioritizes the rules near the top of the file. Rules at the bottom get the least weight.

The fix: be selective about alwaysApply

Only 1–2 rules should have alwaysApply: true. These should be your project identity rules — the short, universal instructions that apply to every single interaction:

---
description: Core project identity
alwaysApply: true
---

Next.js 15 App Router. TypeScript strict. Tailwind CSS.
Never use Pages Router. Never use `any`. Never use class components.

Everything else should use globs to activate only when relevant files are open:

---
description: React component conventions
globs: "**/*.{tsx,jsx}"
alwaysApply: false
---

Named exports only. Props interface defined above the component.
No inline styles. No useEffect for data fetching — use React Query.

---
description: API route conventions
globs: "**/app/api/**/*.ts"
alwaysApply: false
---

All responses use NextResponse.json(). Include status code explicitly.
Validate request body with Zod before processing.

This way, your React rules only load when you are editing React files, and your API rules only load when you are editing API routes. Token usage drops, and rules are more reliably followed because the AI is not juggling irrelevant context.

Fix #4 — Rule Files That Are Too Long

A single .cursorrules file or .mdc file that exceeds 500 lines is reliably problematic. The AI deprioritises instructions towards the bottom of long files as the conversation history grows and the context window fills.

The most common symptom: rules at the top of the file are followed consistently, rules at the bottom are followed intermittently or not at all.

The fix: split into multiple focused files

Instead of one general.mdc with 800 lines covering everything:

.cursor/rules/
├── 01-project-identity.mdc    # ≤ 50 lines — alwaysApply: true
├── 02-typescript.mdc          # ≤ 100 lines — globs: **/*.ts,tsx
├── 03-react-components.mdc    # ≤ 100 lines — globs: **/*.tsx
├── 04-api-routes.mdc          # ≤ 80 lines  — globs: **/api/**
├── 05-error-handling.mdc      # ≤ 80 lines  — globs: **/*.ts
└── 06-testing.mdc             # ≤ 100 lines — globs: **/*.test.*

Files are loaded in lexicographical order. Use numeric prefixes to control priority. Each file should cover one concern and stay under 150 lines. Keep your alwaysApply: true file (project identity) under 50 lines.

Fix #5 — Rules That Are Too Vague to Follow

Vague rules are ignored not because Cursor is broken, but because they provide no actionable guidance. The AI already tries to write "clean, readable, maintainable" code by default. Restating that in your rules adds noise without changing behaviour.

Rules that do not work:

- Write clean, readable code
- Follow best practices
- Use good naming conventions
- Keep code simple and maintainable
- Follow the project architecture

Rules that work:

- Maximum function length: 40 lines. Extract helpers if longer.
- Named exports only. No default exports except Next.js pages.
- No `var`. Use `const`. Use `let` only when reassignment is needed.
- All async functions must use try/catch. Never use .catch() chains.
- Components: one file per component. File name matches component name exactly.

The test for a good rule: could you write a linter for it? If yes, it is specific enough. If not, rewrite it until you can answer yes.

Special case — negative rules ("never do X")

Negative rules require stronger phrasing to be followed reliably. Instead of:

- Don't use console.log

Write:

- NEVER use console.log in any file under any circumstances. Use the logger at src/lib/logger.ts.

The all-caps emphasis and the specific alternative both increase compliance significantly.

Fix #6 — Rules That Contradict Your Existing Codebase

This one surprises many developers. Cursor infers patterns from your existing files as part of its context — and if your codebase consistently uses a pattern you are trying to ban, the AI will often follow the codebase rather than your rule.

Common example: your rule says "no default exports" but 80% of your components use default exports. Cursor follows the codebase.

Another example: your rule says "use the service layer for all business logic" but you have no service layer folder. Cursor cannot follow a rule about something that does not exist structurally.

The fix depends on the situation:

If the codebase uses the old pattern and you are migrating:

- New files only: named exports. Legacy files use default exports — do not change them unless explicitly asked.
- Service layer: all new business logic goes in src/services/. Do not add business logic to existing components even if the surrounding code does.

If you are starting fresh and the folder structure does not exist yet:

- Create src/services/ if it does not exist. All business logic goes there.

If the conflict is a library API change:

- Next.js 15 App Router patterns only. Ignore any patterns from Next.js 12/13 you see in the codebase — those files are legacy and will be migrated separately.

The general principle: rules work best when they describe something that already exists structurally in your project, or when they explicitly acknowledge the legacy state and define the transition behaviour.

Fix #7 — Glob Patterns That Do Not Match Your Files

If you use globs to scope a rule to specific file types, a wrong glob pattern means the rule never activates. This fails silently — no error, no warning, the rule just does not load.

Common glob mistakes:

# Too narrow — only matches files literally named "component.tsx"
globs: "component.tsx"

# Correct — matches all .tsx files anywhere in the project
globs: "**/*.tsx"

# Wrong separator on Windows paths (use forward slashes always)
globs: "src\components\**"

# Correct
globs: "src/components/**"

# Multiple patterns require an array, not a comma-separated string
globs: "**/*.ts, **/*.tsx"   # ← does NOT work

# Correct
globs: ["**/*.ts", "**/*.tsx"]

Testing your glob patterns:

Ask Cursor to confirm which rules are loaded for a specific file:

Which rules are active right now for this file?

If your glob-targeted rule does not appear, the pattern is not matching. Use a broader pattern and narrow it incrementally.

Fix #8 — Cursor Is Not Reloading Edited Rules

After editing a .cursorrules or .mdc file, Cursor does not always reload rules immediately in an active session. Changes to rule files take effect in new sessions — not in the current chat window.

The fix: after editing any rule file, open a new chat window before testing. Do not test rule changes in the same session where you made the edit.

For .mdc files specifically: if you add a new file to .cursor/rules/, Cursor needs to detect the new file before it appears in the active context. In most cases, closing and reopening the project resolves this.

Verification: Confirming Rules Are Working

After applying fixes, verify that rules are actually loading before assuming they work.

Step 1: Ask Cursor directly

List all the rules you are currently following for this project.

Step 2: Test a specific rule

If you have a rule "never use console.log", ask:

Add a debug statement to this function. What would you use?

If Cursor suggests logger.ts instead of console.log, the rule is working. If it suggests console.log, the rule is not loaded or not specific enough.

Step 3: Check rule loading in Agent mode separately

Rules load differently in Chat vs. Agent mode. Test both. Ask the rule-listing question in an Agent session specifically to confirm .mdc files are loading there.

The Most Reliable Setup for 2026

If you want rules that work consistently across all Cursor modes, here is the setup that causes the fewest issues:

project-root/
└── .cursor/
    └── rules/
        ├── 01-core.mdc          # alwaysApply: true, ≤ 50 lines
        ├── 02-[stack].mdc       # globs: for your primary language
        ├── 03-components.mdc    # globs: **/*.tsx (if applicable)
        ├── 04-api.mdc           # globs: your API path
        └── 05-testing.mdc       # globs: **/*.test.*

Template for 01-core.mdc:

---
description: Project identity — always loaded
alwaysApply: true
---

[Your stack in one line: framework, language, version]
[3–5 absolute rules that apply to every file]
[What to do if a task is ambiguous — ask before proceeding]

Delete .cursorrules entirely if you have one. Commit the .cursor/rules/ directory to git so the whole team benefits from the same configuration.

Frequently Asked Questions

Why does Cursor follow the rules sometimes but not others?

The most likely cause is context window pressure. As a conversation grows longer, earlier context (including rules) gets less weight. Start a new session for tasks where rule compliance is critical. Also check that you are not overloading alwaysApply: true — too many always-on rules cancel each other out.

Will my rules work in Cursor's background agents?

Background agents use the same context loading mechanism as Agent mode. This means .mdc files load and .cursorrules does not. Ensure all your rules are in .cursor/rules/*.mdc format before running background agents.

How long should my rules be?

The entire .cursor/rules/ directory should stay under 500 total lines across all files. Your alwaysApply: true core file should be under 50 lines. Individual glob-targeted files should be under 150 lines each. If you need more, split into additional files rather than extending existing ones.

My rule says "never do X" but Cursor keeps doing X. Why?

First, check that the rule is actually loading (ask Cursor to list active rules). If it is loading, the phrasing may be too weak. Add NEVER in uppercase and provide a specific alternative: "NEVER use console.log. Use src/lib/logger.ts instead." If the codebase has many examples of X, add "even if existing code uses X, all new code must use Y."

Should I use .cursorrules or .cursor/rules/?

Use .cursor/rules/*.mdc for any project where you use Agent mode, which is most projects in 2026. The .cursorrules format is only appropriate for simple projects that never use Agent mode. If you are starting a new project today, go straight to .mdc.

Do Cursor rules affect the AI model's memory between sessions?

No. Rules are injected fresh into each session — they are not stored in any form of persistent model memory. The AI does not "learn" from your rules across sessions; it reads them at the start of each conversation. This is why starting a new session after editing rules is the correct way to test changes.

Related

Enjoyed this article?

Share it with your network

Back to all articles