Why Cursor is ignoring your rules file

You wrote a rule. It is sitting in .cursor/rules/. Cursor is behaving exactly as if it does not exist — same tabs, same conventions ignored, same import style you told it three times not to use. There is no error, no warning, and no panel that says "this rule was applied", so there is nothing to search for.

That last part is the real problem. Rules fail silently and Cursor does not publish a way to see which ones were used in a given turn, so the usual debugging loop — change something, observe, repeat — has no observation step. What follows is the substitute: about ten distinct causes, each with a fingerprint you can check without needing to see inside the context window.

The rule type is not a setting. It is inferred from what you left blank

This is the single highest-yield thing to understand, and it explains most of the rest of this page.

There are four rule types, and none of them is declared. There is no type: field. Cursor works out which type your rule is from which frontmatter fields you filled in: alwaysApply: true makes it apply to every chat session; alwaysApply: false plus a description means the Agent decides based on that description; alwaysApply: false plus globs means it applies when a file matches the pattern; and alwaysApply: false with neither a description nor globs means it applies only when you @-mention it by name.

Read that fourth case again, because it is the default you fall into. A rule with alwaysApply: false and empty description and globs fields is not a broken always-rule. It is a valid, correctly-parsed, working manual rule that will do nothing at all until you type @my-rule. Cursor has no reason to warn you, because nothing is wrong.

So before anything else: open the file and decide which of the four types you actually wrote. Most people find they wrote the fourth one and meant the first.

Check the extension before you check anything else

Ten seconds, and it eliminates a whole class of this.

Project rules must use the .mdc extension. A plain .md file sitting in .cursor/rules is ignored by the rules system, because it has no frontmatter — and "ignored" here means invisible, not "loaded with defaults". Your rule is a text file in a folder Cursor is not reading it from.

This catches people two ways. You copied a rule from a blog post or a repo and saved it as .md out of habit. Or your editor helpfully appended an extension. Either way the file is right there in the folder, which is exactly why nobody suspects it.

"Apply Intelligently" shows the Agent your description and nothing else

If your rule has alwaysApply: false and a description, the Agent is deciding turn by turn whether to load it. The critical detail is what it decides on: the description of the rule is presented to the Cursor Agent to decide if it should be applied. Not the body. Not the filename. Just that one line.

This changes what a good description is. description: coding standards is not a summary — it is a selection key, and it is a bad one, because almost every request could plausibly be about coding standards and almost none of them obviously is. The same rule with description: use tabs, not spaces; named exports only; no default exports will be picked up when it should be, because the Agent can match those words against what you actually asked for.

The fingerprint for this cause is inconsistency. An always-rule either works or does not. An intelligently-applied rule with a vague description works on Tuesday and not on Wednesday, on the same codebase, which reads like flakiness and is actually a retrieval decision.

Cursor's own troubleshooting note is the short version: if a rule does not seem to apply, check the rule type, and for Apply Intelligently make sure you have added a description so the Agent knows when it is relevant.

The glob is matched against files, not against your request

A rule scoped with globs applies when a file matches the pattern. The word doing the work is file.

Two consequences that are not obvious. If you are having a conversation with no file attached and no file open that matches — a planning discussion, a "how should I structure this" question — a glob-scoped rule has nothing to match and does not fire. And if your pattern is src/**/*.ts while the file you are editing lives in app/ or packages/web/src/, it does not fire either, which is very easy to do in a monorepo where you wrote the pattern while thinking about one package.

If you need several patterns, they go in one field separated by commas rather than as several entries.

The fingerprint: the rule works when you have the right file open and appears to vanish in general conversation.

You are testing it in Cmd+K, where rules do not exist

This one is worth checking early because it invalidates your test rather than your rule.

Rules only apply to Agent, which is to say Chat. They do not apply to Tab completion, to Inline Edit, or to Bugbot PR reviews. The documentation is explicit that rules do not impact Cursor Tab or other AI features, and specifically that User Rules are not applied to Inline Edit — they are only used by Agent.

Now consider how people naturally test a rule. You want a fast loop, so you select a line, hit Cmd/Ctrl+K, ask for a small change, and watch whether the rule was respected. It was not, because you are in the one surface rules do not reach. Meanwhile Tab keeps completing in the old style all day, which reinforces the conclusion.

If your evidence that the rule is broken comes from Tab or Inline Edit, you have no evidence yet. Re-run it in Chat.

What it is not: the mode you are in

Worth ruling out explicitly, because it is a common suspicion and it is wrong.

Project rules, user rules and team rules all apply in Agent, Ask, Plan and Debug modes. Switching from Agent to Plan does not drop your rules. If the behaviour changed when you changed mode, the cause is the next section, not this one.

Switching modes starts a fresh context window

Each mode uses its own context, so switching modes starts a fresh context window.

Rules are re-applied to that new context — but everything else you had established is gone. If you spent twenty messages explaining your architecture in Agent and then switched to Plan, the rules survived the switch and your explanation did not, and the output degrades in a way that looks like the rules stopped working.

The same reasoning applies to long single-mode sessions that have drifted a long way from where they started. Cursor's own advice is to start a new chat when you finish a feature or switch tasks, and it is worth taking literally rather than treating a chat as a document you keep forever.

A team rule can outrank yours, and it is not in your repository

If you are on a team plan, this is the cause that is genuinely invisible from your checkout.

Rules are merged, not selected — all applicable rules apply together — and when their guidance conflicts, precedence runs Team Rules, then Project Rules, then User Rules, with earlier sources winning. So a team rule saying one thing and your project rule saying the opposite does not produce an error or a warning. It produces your rule being applied and losing, quietly, on exactly the point you wrote it for.

The fingerprint is very specific and easy to recognise once you know it: the rule is followed on everything except one instruction, and that one instruction is the one somebody else has an opinion about. Team rules are free-form text and they sync from your Cursor account rather than from git, so grepping the repository will never find them.

The same filename in two folders is two rules, not an override

People try to override a rule by copying it into a nested .cursor/rules folder closer to the code and editing the copy. That is not what happens.

Cursor identifies rules by their full file path, not by name alone, so two rules with the same filename in different folders both apply if their conditions match. You have not replaced anything. You now have two rules loaded simultaneously, saying different things, and the merge behaviour above decides the outcome.

Nested folders do work — Cursor discovers rules by scanning, so subfolders are found — but a flat directory is easier to reason about precisely because it makes this mistake impossible to make by accident.

AGENTS.md is a different mechanism with different placement rules

If some of your instructions live in AGENTS.md and some in .cursor/rules, do not assume they behave alike.

AGENTS.md files can be placed in any subdirectory of your project, and they are automatically applied when you are working with files in that directory. That is directory-scoped by location, which is closer to the glob-rules model than to the always-apply model — and it means an AGENTS.md in your repository root is not a global instruction set in the way an alwaysApply: true rule is.

The order to check these in

Since you cannot see which rules were applied, sequence is the substitute for observation. Cheapest and most eliminating first:

1. Is the file .mdc, in .cursor/rules, with frontmatter? If not, stop — nothing else matters.
2. Are you testing in Chat, not Tab or Cmd/Ctrl+K?
3. Open the frontmatter and name the type. alwaysApply: false with no description and no globs is a manual rule and needs an @-mention.
4. If it is glob-scoped, is the file you are editing actually inside the pattern?
5. If it is description-scoped, does the description contain the words your request would contain?
6. Set alwaysApply: true temporarily. If the behaviour appears, your problem was selection, and you can go back and fix the description or the glob knowing that.
7. If it still does not appear and you are on a team plan, look for a team rule that contradicts it.

Step 6 is the closest thing to a debugger available here: it removes every retrieval decision at once, so a rule that works with alwaysApply: true and fails without it has told you which half of the problem you are in.