The 10 Most Common Cursor Rules Mistakes and How to Fix Them
You wrote the rule. You saved the file. You asked Cursor for code and it ignored you — gave you a class component when the rule says "use hooks," suggested moment when the rule says "use date-fns," wrote tests in unittest when the rule says "use pytest."
The rule isn't broken. The way you wrote it — or where you saved it, or how you scoped it, or what else is competing with it — is. Ten mistakes below that account for the vast majority of "my Cursor Rules don't work" complaints, each with the symptom, the cause, and the fix.
Mistake 1: The Rule Is Too Vague
Symptom: You wrote "write clean code," "use best practices," "handle errors properly." Cursor ignores the rule (or worse, interprets it any way it likes).
Cause: AI assistants need specifics. "Clean" is not a specification. "Best practices" in 2015 (callbacks, var) are not best practices in 2026.
Fix: Replace every adjective with a concrete requirement.
BAD: Write clean async code.
GOOD: All I/O is async. Use async/await, not .then() chains.
Every async function has a top-level try/catch or a named
error-returning type. No `await` inside a for-loop when
the iterations are independent — use Promise.all.
If you can't write a failing test for the rule, it's too vague.
Mistake 2: No Context About the Project
Symptom: Cursor writes generic code that could belong in any project — doesn't use your auth helpers, your DB client, your logger.
Cause: Cursor doesn't know your project's conventions exist unless you tell it. Rules that describe what you want Cursor to do without what already exists in the codebase produce code that ignores your utilities.
Fix: Tell Cursor what's in the repo.
# Project context (read every session):
- DB client: `src/lib/db.ts` exports a singleton `db`.
- Logger: `src/lib/logger.ts`. Never use console.log.
- Auth: `requireUser(req)` in `src/lib/auth.ts` — throws on
missing/invalid token.
- HTTP errors: use `src/lib/http-errors.ts` (NotFound, Forbidden, etc.)
Now Cursor imports from the real modules instead of inventing createDbClient() every time.
Mistake 3: Conflicting Rules, No Priority
Symptom: One rule says "prefer functional components." Another says "use class components for error boundaries." Cursor picks randomly.
Cause: Rules in the same file with overlapping scope and no hierarchy. The AI honors whichever matched last or whichever is more specific in its own judgment.
Fix: Make the precedence explicit.
# Priority order (highest first):
1. Security rules — NEVER violated, even if other rules suggest otherwise.
2. Framework-version rules (React 18 only, no v19 features).
3. Style rules — follow unless a higher rule conflicts.
Error boundaries are the ONLY class-component exception.
Ordering + an exception clause resolves the ambiguity.
Mistake 4: Rule in the Wrong File Location
Symptom: You put the rule in README.md, .cursorrc, cursor.config.js, or rules.md at the repo root. Cursor doesn't load it.
Cause: Cursor only reads from three specific locations:
~/.cursor/rules/*.mdc # global, per user
.cursor/rules/*.mdc # project, modular (recommended)
.cursorrules # project, legacy single file
Anywhere else is invisible.
Fix: Move the rule to .cursor/rules/<name>.mdc. Verify with the chat UI: after a request, Cursor shows "Rules applied: ..." — if your rule isn't listed, it isn't loaded.
Mistake 5: Stale Cache — Rules Not Reloading
Symptom: You edit a rule, save, ask Cursor for code, and it uses the old rule.
Cause: Cursor caches rules per session. Edits to .mdc files don't always hot-reload, especially if the file already had an active alwaysApply: true block.
Fix: Force a reload. In order of escalation:
1. Open a new chat (Cmd+N / Ctrl+N). Rules re-load per chat.
2. Reload the window (Cmd+Shift+P → "Developer: Reload Window").
3. Fully quit Cursor and reopen.
4. Confirm the rule fires — check the "Rules applied" badge in the
response.
If the rule still doesn't apply after a full restart, the rule file has a syntax error in the frontmatter (commonly: missing --- closing delimiter).
Mistake 6: No Scope — The Rule Fires Everywhere
Symptom: Your Python rule suggests Python idioms in TypeScript files. Your React rule fires in backend API code.
Cause: Missing globs in frontmatter, or alwaysApply: true on a rule that should be file-scoped.
Fix:
---
description: Python style (type hints, Ruff, pytest).
globs: ["**/*.py", "**/*.pyi"]
alwaysApply: false
---
Global application is a deliberate choice, not a default. Rules that apply everywhere are security baselines and commit conventions — nothing else.
Mistake 7: Prompt-Style Instead of Rule-Style
Symptom: You wrote "You are an expert React developer. Please write clean, idiomatic React code using hooks and modern patterns." Cursor treats it as flavor text.
Cause: You wrote a system prompt, not a rule. Rules are declarative constraints, not role-play.
Fix: Rewrite as a list of constraints.
BAD: You are an expert React developer. Use modern hooks.
GOOD: - Function components only. No class components except
for ErrorBoundary.
- State: useState for local, useReducer for complex, Zustand
for cross-component. No Redux.
- Data: TanStack Query v5 for server state. No SWR, no raw fetch
in components.
- Effects: useEffect only for subscriptions, timers, and DOM
APIs. Never for data fetching.
Each bullet is a testable constraint. The AI follows constraints far more reliably than it follows a persona.
Mistake 8: Hidden or Contradictory Global Rules
Symptom: The project rule says one thing, but Cursor does another. You can't figure out where the AI is getting the different idea.
Cause: A rule in ~/.cursor/rules/ (your global user rules) or a leftover legacy .cursorrules file at the root is silently overriding or conflicting with .cursor/rules/.
Fix: Audit every active rule:
# Global (just your machine)
ls ~/.cursor/rules/
# Project-modular
ls .cursor/rules/
# Project-legacy (delete if you have modular rules)
cat .cursorrules 2>/dev/null
# Inside a chat, ask Cursor: "List every rule currently in context
# and which file it came from."
Delete legacy .cursorrules when you have .cursor/rules/. Move personal preferences out of global and into project rules if they affect code.
Mistake 9: Rules Too Long — The AI Skims
Symptom: You wrote a 3,000-word Markdown essay explaining why each rule exists. Cursor ignores the last half.
Cause: AI context windows are large but not infinite, and longer rules reduce the attention each sentence gets. A 3,000-word rule file competes with the code context itself.
Fix: Rule files are reference cards, not textbooks.
GOOD (short, direct, enforceable):
- Use async/await, not .then().
- No `any` types; use `unknown` and narrow.
- Imports alphabetized; external before internal.
BAD (long, justifying, storytelling):
- "We prefer async/await because back in 2017 our team
adopted Promises and found that callback hell..."
Keep rationale in a separate RATIONALE.md that humans read. The .mdc file is for the AI, and the AI wants the rule.
Mistake 10: No Versioning — Rules Drift With Dependencies
Symptom: The rule says "use Next.js App Router." Six months later you upgraded from Next 13 to Next 15, the Router API changed, and the rule's examples produce deprecated code.
Cause: Rules referenced "Next.js" without pinning a version. When you upgraded, nobody updated the rule.
Fix: Version every library-specific claim, and update the rule in the same PR as the upgrade.
---
description: Next.js 15 App Router rules. Update when upgrading.
last-verified: Next.js 15.1.2
---
- App Router only. `app/` directory. No `pages/`.
- Server Components by default; add `"use client"` only when needed.
- Use `next/navigation` (not `next/router`).
- Route handlers in `route.ts`, not `api/*.ts`.
A dated, versioned rule tells the next contributor what the rule was tested against. An undated rule is a slow-motion bug.
The Quick Audit
Five minutes. Run through your rules and check each one:
[ ] Does it live in `.cursor/rules/*.mdc` (or `.cursorrules`)?
[ ] Does it have `globs` or an explicit "global" note?
[ ] Is it specific enough that you could write a failing test for it?
[ ] Does it pin library versions where relevant?
[ ] Is it under ~500 words?
[ ] Is it listed in "Rules applied" when you ask Cursor a question?
[ ] Are there no duplicates in `~/.cursor/rules/` or legacy `.cursorrules`?
Most "Cursor Rules don't work" reports resolve once those seven boxes are ticked.
Want rules that don't have these mistakes?
We maintain a Cursor Rules pack with production-ready, scoped, versioned rules for Python, TypeScript, React, Next.js, Go, Rust, Docker, Kubernetes, Terraform, and more. Every rule is written to the standard above — short, specific, scoped, enforceable.
Top comments (0)