How to Fix Cursor Rules Not Working: Debugging .cursorrules and Glob Conflicts

When Cursor rules are not working or are silently ignored, the root cause is almost always glob pattern syntax mismatches in .cursor/rules/*.mdc, migration conflicts between legacy .cursorrules and modern project rules, malformed YAML frontmatter, or uncommitted worktree paths. Diagnosing the issue requires auditing frontmatter flags, verifying file glob resolution, checking rule precedence, and testing agent activation with deterministic prompts.

Why Is Cursor Ignoring Your Rules? (Quick Diagnostic Matrix)

Cursor ignores rules when the editor's rule engine cannot resolve the file's activation trigger or parse its YAML frontmatter headers. In most failure cases, Cursor does not display an explicit error modal; instead, the agent silently defaults to its standard system prompt, causing developers to assume the AI simply "forgot" instructions that were never injected into the context window.

According to the official Cursor AI Rules documentation: "Project rules are stored in .cursor/rules as .mdc files, which contain frontmatter to configure when and how the rule should be applied." When the editor initializes a chat or Composer turn, it parses active file tabs against these frontmatter configurations.

Use this diagnostic matrix to match your symptom to its root cause and immediate technical fix:

Why Does .cursorrules Fail After Migrating to .cursor/rules/*.mdc?

Legacy .cursorrules files frequently fail in newer Cursor versions (v0.40.0 and above) because the IDE gives precedence to modular .cursor/rules/*.mdc files whenever the directory exists. If a repository contains both a legacy .cursorrules file in the project root and a .cursor/rules/ folder, Cursor may partially or completely skip the root file without warning the user.

In earlier Cursor builds, the single root .cursorrules file injected all instructions indiscriminately into every conversation turn. While simple, this monolithic approach burned between 1,500 and 4,000 tokens on every interaction, even when writing trivial commit messages or editing markdown files. Cursor v0.42 introduced the modern .cursor/rules/ directory structure to solve context exhaustion by splitting guidelines into targeted, modular components.

When migrating from .cursorrules to .cursor/rules/, engineers frequently make three critical structural errors:

• Leaving a duplicate root .cursorrules: Having both files causes race conditions in rule parsing. Delete the root .cursorrules once your modular rules are created.
• Omitting the .mdc file extension: Cursor specifically parses Markdown Component (.mdc) files. Files named rule.md or rule.txt inside .cursor/rules/ are ignored by the automated loader.
• Copying raw prompt text without YAML frontmatter: Unlike the legacy format, modern Cursor rules require a structured header. A raw markdown file without frontmatter will not activate unless manually referenced with an @ mention.

How Do Glob Patterns Cause Cursor Rules to Silently Fail?

Glob patterns in .cursor/rules/*.mdc silently fail when path syntax contains leading slashes, incorrect directory separators, or unquoted wildcard strings. Cursor's internal matcher evaluates globs relative to the repository workspace root, meaning paths must omit leading slashes to resolve properly against active files.

According to the Cursor Project Rules and Glob Matching Specification, glob patterns use minimatch conventions. Consider the difference between an invalid pattern and a corrected, production-ready rule:

# ❌ BROKEN: /src/ has leading slash, unquoted wildcards, missing alwaysApply
---
description: React component standards
globs: /src/components/*.tsx
---
# The leading slash causes matching against root filesystem, skipping workspace files.

# ✅ CORRECT: Relative path, double star recursion, quoted string
---
description: React component formatting and hook safety rules
globs: "src/components/**/*.tsx"
alwaysApply: false
---
- Use named exports for all UI components.
- Do not call hooks conditionally.
- Co-locate unit tests alongside components in __tests__/.

Cursor ignores glob patterns in .cursor/rules/*.mdc if file paths include a leading forward slash, because glob matchers evaluate paths relative to the repository workspace root without a leading slash. Furthermore, a .cursor/rules/*.mdc file configured with alwaysApply: false and no glob pattern defined will never attach automatically to agent sessions and can only be invoked by manually referencing the rule with @ in chat.

If you coordinate multiple editor formats across teams, compare how Cursor's glob matching contrasts with Windsurf's directory rules in our guide on Cursor Rules vs Windsurf Cascade Rules, or examine cross-agent execution in Google Antigravity vs Cursor Rules.

How Do Global User Rules and Project Rules Collide in Precedence?

Global user rules configured in Cursor Settings override or dilute project-level rules when their instructions express conflicting engineering conventions. Cursor concatenates global user rules and active project rules into the prompt preamble, and when instructions contradict each other, large language models either compromise on both constraints or favor whichever rule was parsed last.

For example, if your personal Cursor settings (Cursor Settings > General > Rules for AI) instruct the assistant to "Always use TypeScript interfaces with PascalCase and explicit type annotations", but your team's project rule in .cursor/rules/types.mdc mandates type aliases over interface, the model will oscillate inconsistently between the two styles.

To resolve precedence conflicts between global and repository instructions:

1. Keep global user rules strictly behavioral: Reserve global Cursor settings for universal communication preferences (e.g., "Be concise", "Do not write conversational pleasantries", "Show unified diffs").
2. Keep code conventions exclusively in project rules: Move all framework choices, testing patterns, and architectural conventions into git-versioned .cursor/rules/*.mdc files.
3. Audit team-wide dotfiles: Ensure teammates are not maintaining contradictory local rules that cause diverging code output on the same PR branch.

The Sprawl Moment: When Rules Break Across Worktrees and Machines

You spend forty minutes dialing in a specialized .cursor/rules/api-routes.mdc rule on your development laptop, testing it until Composer reliably generates compliant zod validation schemas on every route. Two hours later, you clone the repository on your secondary machine to patch a production bug. You prompt Cursor to add a new endpoint, expecting the same clean schema structure. Instead, the model outputs unstructured inline types, ignoring your naming rules and error conventions entirely. You check the folder: the rule was committed to git, but your secondary machine is running an older Cursor version that fails to parse nested glob syntax without throwing an error, while your local user settings override the project rule with an outdated global prompt you forgot you wrote six months ago. The rule exists on disk, but your agent is working completely blind.

This breakdown illustrates why local file storage alone cannot solve agent instruction management. When rules live in unmanaged directories, switching laptops, spinning up a git worktree, or switching between Cursor, Claude Code, and terminal CLIs forces you to re-debug the same missing instructions over and over again. Read our technical breakdown on fixing broken agent instructions across repos and worktrees for additional architectural patterns.

How Do You Deterministically Verify That a Cursor Rule Is Active?

You can deterministically verify that a Cursor rule is active by injecting a temporary verification sentinel into the rule body or by checking the active context reference pills in Composer. Relying on casual code inspection is unreliable because models may naturally mimic project patterns from open files even when the rule itself failed to load.

Follow this three-step verification protocol to confirm rule execution:

How Does Cursor Rule Resolution Compare to Claude Code, Antigravity, and Windsurf?

Cursor rule resolution relies on active file globs and editor UI tabs, whereas tools like Claude Code, Google Antigravity, and Windsurf resolve instructions through filesystem dotfiles, terminal directories, and autonomous planning loops. Understanding these mechanical differences prevents engineers from expecting non-Cursor tools to respect .cursor/rules/ configurations.

The comparison table below details how the four leading developer agent environments discover, scope, and enforce instructions:

For developers working across both Anthropic and Cursor ecosystems, see our detailed architectural breakdown in Claude Skills vs Cursor Rules, CLAUDE.md, and AGENTS.md.

Step-by-Step Checklist to Fix and Prevent Cursor Rule Drift

To ensure your Cursor rules load reliably without silent failures, apply this five-step audit across your repository:

1. Consolidate to .cursor/rules/: Delete any root .cursorrules file and move directives into discrete .cursor/rules/*.mdc files grouped by domain (e.g., database.mdc, react.mdc, api.mdc).
2. Strip Leading Slashes from Globs: Audit all frontmatter glob patterns. Replace globs: "/src/**" with globs: "src/**", and ensure paths with wildcards are wrapped in quotes.
3. Explicitly Configure alwaysApply: For rules that must govern every conversation (e.g., git commit standards, formatting, concise prose), set alwaysApply: true. For file-specific rules, set alwaysApply: false and define a clear globs pattern.
4. Validate Frontmatter Formatting: Use standard 2-space indentation in YAML headers, ensure closing triple dashes (---) sit on their own line, and quote any descriptions containing colons.
5. Centralize Rules in a Unified Manager: Prompttly eliminates local rule desynchronization by treating your AI instructions as a single, version-controlled library that compiles deterministically into .cursor/rules, ~/.claude/skills, and AGENTS.md.

If you need to author new custom instructions or optimize existing prompts, build them using our free Custom Instructions Generator or package them as agent skills using the Claude Skill Creator.

For macOS power users managing large libraries of rules and prompts across multiple tools, summon your entire instruction collection instantly using the native Prompttly Mac menu bar app with sub-200ms global hotkey access.

Frequently Asked Questions About Cursor Rules Troubleshooting

These are the questions software developers and AI engineers most frequently ask when troubleshooting broken or unapplied Cursor rules.