AI AI Tools Guidebook
Troubleshooting

Cursor Rules File Not Being Loaded

Composer ignores your .cursorrules — usually wrong filename, wrong location, or new-format/old-format mismatch.

Published: Author: AI Productivity Guide Team 🌐 查看中文版本

You wrote a careful .cursorrules telling Composer to prefer TypeScript, avoid any, and never inline styles — but the next generation does all three. The rules file is sitting in the repo; the model is acting like it does not exist. Usually the file is in the wrong place, named for the wrong era of Cursor (the project switched from .cursorrules to .cursor/rules/*.mdc in late 2025), or scoped to a path the current request never touched.

This article walks the file-loading order, how to confirm whether a rule actually reached the model, and how to migrate cleanly between the two formats.

Common causes

1. File at the wrong path

.cursorrules must sit at the repo root next to package.json. Inside src/ or apps/web/ it is ignored. New-format .cursor/rules/*.mdc files must live under .cursor/rules/ at the repo root, not inside a sub-package.

How to judge: ls -la .cursorrules .cursor/rules/ 2>/dev/null at the repo root. If neither exists at the root, that is the issue.

2. Old format vs new format confusion

Cursor 0.42+ deprecated single-file .cursorrules in favor of multiple .cursor/rules/*.mdc files with frontmatter. Both still work in the latest builds, but if a project has both, only one wins and the rules silently merge in unpredictable order.

How to judge: if both .cursorrules and .cursor/rules/ exist, pick one and delete the other.

3. .mdc file missing frontmatter or marked manual

New-format rules need frontmatter declaring when they apply. Without it, or with alwaysApply: false and no glob pattern, the rule attaches to nothing.

How to judge: open the .mdc file. If the top of the file has no --- block, or has alwaysApply: false with no globs: entry, the rule never auto-attaches.

4. Rule scoped to globs the current file does not match

A rule with globs: ["src/api/**/*.ts"] will not load when you are editing src/components/Button.tsx. The rule exists but is silent for unrelated files.

How to judge: check the rule’s globs and compare to the file path Composer is editing.

5. Workspace rules vs user rules collision

Settings > Rules for AI (user-level) and .cursorrules (project-level) both feed into the system prompt. If they contradict each other, the model picks one and you cannot tell which.

How to judge: open Settings > Rules for AI and skim the user-level text. Anything contradicting your project file is a problem.

6. Cursor still indexing or the agent did not refresh

After editing a rules file you sometimes need to start a new Composer chat for the new rule to load — existing chats keep their original system prompt.

How to judge: did you change rules mid-chat? Start a fresh Composer thread and retest.

Before you start

  • Confirm Cursor version: Cursor menu > About. 0.42+ uses the new .mdc format.
  • Note whether you are using Composer, Cmd+K, or chat — Cmd+K respects fewer rules than Composer.
  • Commit before changing rules so you can bisect which rule caused which behavior.

Information to collect

  • Output of find . -maxdepth 3 -name '.cursorrules' -o -path '*/.cursor/rules/*'.
  • Full contents of every rules file in the repo.
  • Settings > Rules for AI text (user-level).
  • The exact prompt and file path where the rule was supposed to apply.
  • Composer message tool-call chain showing which files the model read.

Step-by-step fix

Step 1: Confirm the rule actually reached the model

Easiest probe: add a canary line to the top of your rules file:

CANARY-2026-05-23: If you read this, start your next response with the word "PINEAPPLE".

Save, open a new Composer chat, ask anything. If the response starts with PINEAPPLE, the rule loaded. If not, the file is not reaching the model and you can stop debugging behavior — debug loading first.

Step 2: Move the file to the correct location

For the legacy single-file format:

# Must be at repo root
mv src/.cursorrules .cursorrules
git add .cursorrules
git commit -m "move cursorrules to repo root"

For the new format:

mkdir -p .cursor/rules
mv .cursorrules .cursor/rules/general.mdc

Then add frontmatter at the top of general.mdc:

---
description: General coding conventions for this repo
alwaysApply: true
---

Step 3: Pick exactly one format and delete the other

Keep both formats and you get unpredictable merging. Either:

  • Delete .cursor/rules/ and keep .cursorrules, or
  • Delete .cursorrules and split rules across .cursor/rules/*.mdc files.

The new format is recommended going forward — it supports per-glob scoping and is the only format Cursor will support long-term.

Step 4: Use alwaysApply for global rules

For rules that should attach to every request regardless of file:

---
description: TypeScript and styling conventions
alwaysApply: true
---

- Prefer TypeScript over JavaScript.
- Never use `any`. Use `unknown` and narrow.
- Never inline styles. Use Tailwind classes or CSS modules.

Step 5: Use globs for path-scoped rules

---
description: API route conventions
globs:
  - "src/api/**/*.ts"
  - "src/pages/api/**/*.ts"
---

- API handlers return `Response` objects, not Express-style res.json().
- Wrap handlers in `withErrorHandler` from src/utils/api.ts.
- Validate input with Zod before any DB call.

Step 6: Reload the rule in a fresh chat

After every rules change:

  1. Save the file.
  2. Close the current Composer / chat tab.
  3. Open a new Composer chat.
  4. Rerun the canary probe.

Existing chats keep their original system prompt; only new chats see the updated rule.

Verify

  • Canary probe (Step 1) confirms the rule reached the model.
  • Rerun the original failing request — Composer should now respect the rule.
  • Ask Composer “What conventions are you following from .cursorrules or .cursor/rules?” — it should paraphrase your rules back.
  • A teammate cloning the repo and running Composer should see the same behavior, confirming the rule is in version control and not in personal settings.

Long-term prevention

  • Always keep rules under version control at the repo root — never in personal user settings only.
  • Use the canary line trick during onboarding so new devs can confirm the rule chain in one command.
  • Split rules by domain into multiple .mdc files (api, frontend, testing) rather than one giant file — easier to scope with globs and easier to audit.
  • Add a CI check that fails if both .cursorrules and .cursor/rules/ exist in the same branch.
  • Re-read your rules file once a quarter; outdated rules cause more harm than missing ones.

Common pitfalls

  • Adding rules but never starting a new chat — old chats stay on the old system prompt.
  • Writing huge rules files (5000+ tokens) that crowd out actual context; keep rules sharp and short.
  • Negative-only rules (“never do X”) without positive guidance (“do Y instead”) — the model reverts to defaults.
  • Project-level rule contradicting user-level rule; one silently overrides.
  • Editing the file inside a Docker volume that does not sync back to the host where Cursor reads from.

FAQ

Q: Do rules count against my context window? A: Yes — they are prepended to the system prompt. Keep them under 2000 tokens for a healthy context budget.

Q: Can I disable rules per-message? A: Not directly, but you can add IGNORE PRIOR RULES FOR THIS MESSAGE inside the prompt and the model usually complies.

Q: Are .cursor/rules/*.mdc files synced to Cursor cloud? A: No — they are in your repo. Only Settings > Rules for AI (user-level) syncs to your Cursor account.

Q: Can Cmd+K read rules? A: Partially — Cmd+K reads alwaysApply: true rules but ignores glob-scoped ones since it has limited context about file paths.

Tags: #Cursor #ide #Troubleshooting

Related Articles