Last updated: June 2026 · Quick diagnostic for when .cursorrules stops working
Cursor is ignoring your .cursorrules file and you want a fast answer, not a long explanation. This checklist covers every confirmed reason — tick them off in order until you find yours.
For detailed explanations and fixes for each issue, see the Cursor Rules Not Working — Complete Fix Guide.
1. Is the file in the project root?
.cursorrules must sit at the root of your project — the same directory as your package.json, pyproject.toml, go.mod, or equivalent. Not inside src/, not in a subdirectory, not in your home directory.
✅ my-project/.cursorrules
❌ my-project/src/.cursorrules
❌ my-project/config/.cursorrules
2. Is the filename spelled correctly?
Common typos that cause silent failure:
❌ .cursorrule (missing the 's')
❌ .cursor_rules (underscore instead of nothing)
❌ .cursor-rules (hyphen)
❌ cursorrules (missing the dot)
❌ .CursorRules (wrong case on case-sensitive systems)
✅ .cursorrules (correct)
3. Is the file UTF-8 encoded?
Cursor expects UTF-8. If you copied rules from a Word document or PDF, special characters (curly quotes, em-dashes, non-breaking spaces) can corrupt the file silently. Paste into a plain text editor first, then copy into .cursorrules.
4. Is .cursorrules listed in your .gitignore?
If .cursorrules is in .gitignore, some editor configurations may exclude it from being read. Check your .gitignore file and remove the entry if it is there.
5. Are you using Agent mode?
This is the most common reason in 2026. .cursorrules is not loaded in Agent mode. It only works in Chat and Composer (non-agent) sessions.
To verify: ask Cursor in an Agent session "What rules are you following?" If it does not mention your rules content, this is your problem.
Fix: Migrate to .cursor/rules/*.mdc format, which loads in all modes including Agent. See Cursor Rules Not Working for the full migration guide.
6. Do you have both .cursorrules AND .cursor/rules/ in the same project?
Having both formats creates undefined behaviour. .mdc rules take precedence and .cursorrules is silently overridden.
Fix: Delete .cursorrules if you have .cursor/rules/ files. Or delete the .cursor/rules/ directory if you want to use .cursorrules. Use one format only.
7. Did you edit the rules file in the current session?
Rule changes take effect in new sessions only. Editing .cursorrules during an active chat window does not update the rules for that window.
Fix: Open a new chat window after every rules edit. Do not test changes in the same session.
8. Are your rules too vague?
Vague rules are parsed but not acted on. The AI treats them as background preference rather than instruction.
❌ Write clean, readable code
❌ Follow best practices
❌ Use good naming conventions
✅ Maximum function length: 40 lines. Extract helpers if longer.
✅ Named exports only — no default exports except Next.js pages.
✅ NEVER use console.log. Use logger at src/lib/logger.ts instead.
Test: could you write a linter rule for it? If not, it is too vague.
9. Is the file longer than 500 lines?
Rules near the bottom of long files get deprioritised as the context window fills during longer conversations. Symptoms: rules at the top followed, rules at the bottom ignored intermittently.
Fix: Keep .cursorrules under 300 lines. Move to .cursor/rules/*.mdc with multiple files split by concern if you need more.
10. Do your rules contradict the existing code in the project?
Cursor infers patterns from your codebase alongside your rules. If 80% of your components use default export but your rule says "no default exports," the codebase wins.
Fix: Acknowledge the transition explicitly:
Legacy files use default exports — do not change them.
All NEW files: named exports only.
11. Do you have more than 3–4 rules marked as critical or "always"?
If everything is marked as critical, nothing is treated as critical. The AI tries to satisfy all equally and partially satisfies most.
Fix: Reserve strong language (NEVER, ALWAYS, MUST) for 3–5 genuinely non-negotiable rules. Everything else uses neutral phrasing.
.mdc format only)12. Is your glob pattern matching the wrong files?
If you use .mdc files with globs: targeting, a wrong pattern means the rule never activates.
# Wrong — only matches a file literally named "component.tsx"
globs: "component.tsx"
# Wrong — comma-separated string does not work
globs: "**/*.ts, **/*.tsx"
# Correct
globs: "**/*.tsx"
# Correct for multiple patterns
globs: ["**/*.ts", "**/*.tsx"]
Fix: Use a broad pattern and narrow it incrementally. Ask Cursor "which rules are active for this file?" to verify.
13. Is alwaysApply set to false with no globs?
If alwaysApply: false and no globs pattern is set, the AI decides based on the description field whether the rule is relevant. If the description is unclear or no files match its concept, the rule may never load.
Fix: Either set alwaysApply: true for rules that should always load, or add an explicit globs pattern.
14. Ask Cursor directly
In a new session, type:
List all the rules you are currently following for this project.
If Cursor lists your rules accurately, they are loading. If it does not mention them or lists generic responses, the file is not being read.
15. Test a specific rule
If you have "NEVER use console.log," ask:
Add a debug statement to this function. What would you use?
If Cursor suggests logger.ts, the rule works. If it suggests console.log, either the rule is not loading or the phrasing is too weak.
16. Check Agent mode separately from Chat mode
Rules can load in Chat but not Agent (if you are using .cursorrules), or load in Agent but not apply correctly. Test both modes explicitly with the verification questions above.
| Symptom | Most likely cause | Quick fix |
|---|---|---|
| Rules ignored only in Agent mode | .cursorrules not loaded in Agent |
Migrate to .cursor/rules/*.mdc |
| Rules ignored in all modes | File not in project root, or filename typo | Check path and spelling |
| Rules work sometimes, not always | File too long, or context window pressure | Split into multiple shorter files |
| Rules at top followed, bottom ignored | File too long | Keep under 300 lines |
| New rules not working | Tested in same session | Open new chat window |
| Some rules followed, others not | Too many "critical" rules | Reserve strong language for 3–5 rules max |
Agent ignores rules despite .mdc |
Both .cursorrules and .mdc present |
Delete .cursorrules |
| Glob-targeted rules never load | Wrong glob pattern syntax | Use ["**/*.ts", "**/*.tsx"] array format |
| Rules ignored despite correct format | Rules contradict existing codebase | Acknowledge transition explicitly in rules |
If you have checked everything on this list and rules are still being ignored, the issue is likely one of two remaining causes:
Context window saturation in long sessions. As a conversation grows, earlier context (including rules) gets less weight. Rules work in short sessions but fade in long ones. Start a new session for any task where rule compliance is critical.
Model-specific behaviour. Some models handle system prompt injection differently. Try switching to a different model (Claude Sonnet 4.6 typically has strong instruction-following) and test whether rules are respected with that model specifically.
project-root/
└── .cursor/
└── rules/
├── 01-core.mdc # alwaysApply: true, ≤ 50 lines
├── 02-typescript.mdc # globs: **/*.{ts,tsx}
├── 03-api.mdc # globs: **/api/**
└── 04-testing.mdc # globs: **/*.test.*
Delete .cursorrules entirely. Commit the .cursor/rules/ directory. This setup loads in Chat, Composer, and Agent mode, splits concerns into manageable files, and uses glob targeting to avoid context overload.
Full guide with templates for every major stack: Cursor Rules — Complete Guide.