Why your Cursor rule isn't applied, and which rule is actually running

Cursor has several things called a rule: project rules in .cursor/rules, User Rules saved to your account, Team Rules from the dashboard, rules that ship with a plugin, and the legacy .cursorrules file. They load differently, and one can win over another without either being wrong.

So "my rule is ignored" has an earlier question: was it discovered, and was it loaded as the type you think? An alwaysApply: true rule delivered as agent-requestable will look ignored. So will a file-scoped rule that never saw a matching file.

Run Cursor → About Cursor; the ~/.cursor/rules answer changes by build. In the CLI, agent --version or agent about; older posts say cursor-agent.

Checked against Cursor's documentation and changelog on 27 October 2026.

Status, 27 October 2026: the ~/.cursor/rules question is version-dependent. Help describes user rule files there; staff said in June and August 2026 that the folder is unsupported and that discovery walks up from the open folder (#158551, #170099); a 26 October report on 3.24.12 says Customize → Rules lists those files (#174724). Check your build with the canary below.

The things Cursor calls a rule#

The rules reference documents project rules, User Rules, Team Rules, and AGENTS.md; plugin rules and .cursorrules are not listed as types.

AGENTS.md and CLAUDE.md are the documented plain-markdown route; the Cursor AGENTS.md page covers when they attach and when they drop out.

The frontmatter decides, not the dropdown#

The type dropdown writes three fields, and their combination decides what happens:

The docs say a matching file in context; a Cursor staff reply in May 2026 describes the trigger as a file read (#160133). If your file reached the chat another way, test it.

Use the docs' comma-separated string, quoted because YAML treats a leading * as special:

globs: "**/*.ts, **/*.tsx"

A March 2026 report found only the comma string worked (#155902); a May 2026 staff reply corrected that, saying the YAML list works and two separately quoted values on one line do not (#160133). The comma string is documented; the list is an accepted alternative.

When description and globs are both set, a March 2026 report says the panel shows "Apply Intelligently" (#155902); the docs do not define that combination, so leave description out of a file-scoped rule. A plain .md in .cursor/rules is ignored; the file must end in .mdc. Rules are identified by path, not filename, so two style.mdc files in different folders both apply (Help).

The legacy file#

.cursorrules is the old single file at the repo root. Help calls it legacy, says it will be deprecated, and says to copy the text into an Always Apply rule and delete it. It is not hard-disabled: the reporter retracted the February 2026 report the same day, saying both formats load and .mdc wins on conflicts; a 4 March 2026 re-test found .cursorrules working again (#152046, updated 4 March 2026).

User Rules, and the `~/.cursor/rules` question#

User Rules are the supported account-wide route: plain text, stored with your account, synced, and applied to every project, with no frontmatter, globs, or per-file scoping (Help). A .mdc body pasted there turns its frontmatter into literal text.

Help also lists a third location: user rule files in ~/.cursor/rules (Windows: %USERPROFILE%\.cursor\rules) stay on the machine and do not sync. Staff contradicted that twice. On 25 June 2026: "Cursor doesn't support storing user rules in ~/.cursor/rules" (a Cursor staff reply in #158551). On 31 August 2026: Customize → Rules does not list those files, and discovery only walks up from the open folder, so a home-level file applies only when the folder sits inside your profile (#170099).

A 26 October 2026 report on 3.24.12 says Customize → Rules does list local files from that folder, while old account rules were missing (#174724). Listing is not applying, and the report does not say whether the workspace was outside the home folder.

Test it with a canary (a unique marker you plant to see whether it reaches the model): a .mdc file in ~/.cursor/rules with alwaysApply: true, and a project outside your home directory. If the file is listed but the marker never appears, the folder is listed but not applied; if neither appears, it is not a user-rules location on your build. If the marker appears and the rule is still ignored, the problem is adherence.

Three routes that work today: User Rules; a parent-folder .cursor/rules, which staff say applies to every project under it (#171325, 11 September 2026); or a local plugin under ~/.cursor/plugins/local with a rules/ folder, the staff workaround that the plugin docs describe. Enterprise administrators can turn local plugin imports off.

Team and plugin rules#

Team Rules are dashboard-managed free text: without a glob they apply to every conversation, with one they apply when matching files are in context. Optional rules can be switched off in Customize; enforced ones cannot. Precedence is Team → Project → User, and all applicable rules merge, earlier sources winning on conflict (rules reference).

Plugin rules are .mdc files in a plugin's rules/ folder, shown in Customize with the plugin docs' Always, Agent Decides, and Manual modes (plugin docs). In early 2026, plugin rules with alwaysApply: true were reported downgraded, and staff confirmed it; fixes were announced for 3.6 and 3.7.36+ (#154223, #157484). Glob-enabled plugin rules were still reported as not applied (#163738, open, updated 5 September 2026). Copying the rule into the project's .cursor/rules sends it through the loader local rules already use.

Which rule is actually running#

No view lists the rules the agent selected; this section narrows down which copy of a rule is loaded.

Start with the inventory, not the model.

1. Customize → Rules. It lists project, user, team, and plugin rules; the type label (shown as a badge) is the type Cursor thinks each one is. Filter by scope. With the filter cleared, absent means not discovered; with a filter active, switch to All first. The wrong badge means the panel and the frontmatter disagree. A badge is a claim about the file, not proof of what the model received.
2. Read the first ten lines. A rule edited through the panel can end up with duplicated frontmatter; one report describes the settings UI adding a second block when the type changed (#157484, 3.0.16). The file is the source of truth.
3. Find other copies. Rules are identified by path, so two files with the same name both apply: find. -path '*/.cursor/rules/*' -name '*.mdc'.
4. Run a canary. Add a rule that asks every reply to begin with RULE-CANARY-7, set alwaysApply: true, and start a new Agent chat. If the marker appears, that rule loaded and was followed on that turn. If not, @-mention it and ask again. Working when mentioned but not on its own means it is delivered as requestable, not always-applied: a classification problem, not wording.

There is no built-in view of which agent-selected rules were pulled into a conversation; a Cursor staff reply said so on 9 May 2026 (#158551). If you need Cursor support to inspect the request, copy the Request ID from the chat's three-dot menu first.

When it loaded and still isn't followed#

Now the rule is listed, the frontmatter is right, and the canary worked — or it worked for a while and stopped. That is the other failure. A rule is context: the docs say its contents are included at the start of the model context (rules reference). Nothing there makes the model obey.

The general mechanics — long context, conflicts, vague rules, negative rules — are not Cursor-specific; the Claude Code page on loaded but ignored instructions explains them. Cursor's version: a staff reply on 16 February 2026 called adherence probabilistic, said earlier context gets less weight as a chat grows, and recommended positive wording, short and scoped rules, a reminder in the prompt, and a fresh chat (#152025). On 7 September 2026, a staff reply: rules are "strong guidance to the model, not a hard filter" (#170752).

Two Cursor-specific facts decide whether a rule survives a long session. Root always-applied rules sit near the system prompt and survive summarization (staff reply, 22 May 2026, #158551). In the editor, nested AGENTS.md files and file-scoped rules attach to a Read result once per conversation; the CLI changelog for v2026.10.22 says edits and creates now attach nested AGENTS.md there too (CLI changelog). After summarization the text can drop out and is not re-attached, while Cursor still thinks it is attached (#175331, staff confirmed 19 October 2026); the Cursor AGENTS.md page has the mechanism. After a summary, re-read the file or @-mention the rule; a new chat resets a rule that existed only in the conversation.

For a rule that must hold, use a layer outside the model:

Hooks are code, but not automatically a security boundary. A command hook that crashes, times out, or exits with anything other than 2 fails open by default; set failClosed: true when a failure must block. Invalid JSON from a permission hook blocks the action, and permission: "ask" is accepted by the preToolUse schema but not enforced today (hooks reference). The Cursor hooks page covers load order and the plugin gaps.

Permissions are separate: permissions.json for the editor's terminal and MCP allowlists (MCP is the protocol Cursor uses to connect external tool servers), and ~/.cursor/cli-config.json or .cursor/cli.json for the CLI (permissions reference, CLI permissions). The editor reference calls its allowlists best-effort convenience, not a security guarantee. The project-level permissions.json has a documented-versus-observed disagreement; the Cursor permissions guide covers which file is actually read.

Keep the explanation in the rule and the boundary in the hook or permission file. Do not name the forbidden token; staff said naming it keeps putting it back in the prompt (#170752). Keeping the rule positive and specific is the same advice; "MUST ALWAYS" is not a staff quote.

Where to go next#

• Cursor guides — the rest of the set.
• Does Cursor read AGENTS.md? — when the instruction file is not a .mdc rule.
• Why Cursor keeps asking for permission — when the rule needs a boundary.
• Why your Cursor hook doesn't fire — when the enforcement layer is the thing failing.
• Claude Code loaded your CLAUDE.md but isn't following it — the general mechanism behind a loaded rule that loses.