Cursor rules not applying? alwaysApply, globs and description

Updated 2026-10-25

In short: a Cursor project rule is a .mdc file in .cursor/rules, and three frontmatter fields decide when it loads. alwaysApply: true means every chat. globs means "when a matching file is in context". A description alone means "when the agent decides it's relevant". None of them means "only when I @-mention it". Most "my rule is ignored" problems are a wrong extension, a missing description or a glob that doesn't match.

The four rule types, and the frontmatter behind each

In the editor you pick a rule type from a dropdown. Under the hood, the Cursor docs say the dropdown just sets alwaysApply, globs and description, and these combinations decide what happens:

Two consequences people miss. First, alwaysApply: true wins outright: the docs say globs and description are ignored, so adding a glob to an always rule doesn't narrow it. Second, an Apply Intelligently rule with no description has nothing for the agent to match against, so it behaves like a manual rule.

Working examples you can copy

These follow the shapes in the docs. Save each as its own file under .cursor/rules/.

Always on (.cursor/rules/core.mdc). Keep this one short, because it lands in every chat:

---
alwaysApply: true
---

- Run `npm run lint` and `npm test` before saying a task is done.
- Never edit files in `dist/` or `build/`; they are generated.
- Ask before adding a new dependency.

Scoped to files (.cursor/rules/react-components.mdc):

---
globs: src/components/**/*.tsx
alwaysApply: false
---

- Use named exports, not default exports.
- Keep components under 200 lines; extract subcomponents into the same folder.

Picked by the agent (.cursor/rules/rpc-services.mdc). The description is the trigger, so say what the rule covers in words the agent will connect to the task:

---
description: RPC service conventions for the backend. Use when creating or changing files in src/services/.
alwaysApply: false
---

- One service per file under `src/services/`.
- Validate inputs at the service boundary.
- Return error objects with `code` and `message`; never throw raw strings.

Manual only (.cursor/rules/migrations.mdc), loaded when you type @migrations:

---
alwaysApply: false
---

- Every migration has both `up` and `down`.
- Never change a column type in place: add, backfill, then drop in a later migration.

You don't have to write frontmatter by hand. The docs list two ways to create a rule: type /create-rule in Agent and describe what you want, or open Customize, go to Rules and click Add Rule. Customize also shows every rule and its status, which is the quickest way to see what Cursor actually picked up.

Writing globs that match

The docs give these patterns, with multiple patterns separated by commas:

The classic mistake is *.ts when you meant **/*.ts: the first only matches files at the repo root. The docs' own examples write globs as a plain, unquoted, comma-separated value, so that's the safest form to copy. In a Cursor forum thread, a user reported that a quoted pattern and a YAML list both failed for them while the unquoted form worked, and later staff replies in other threads disagree on whether those forms work. If a glob rule never fires, rewrite it in the docs' form before debugging anything else.

Also know what "in context" means. In that same thread, Cursor staff said having a file open in an editor tab doesn't trigger a glob rule; the rule attaches when the agent works with a matching file. The same user found that a glob rule created in the middle of a conversation didn't take effect until they opened a new chat. So test a new rule in a fresh chat.

Why a rule doesn't load: a checklist

1. Wrong extension. Project rules must be .mdc. The docs say a plain .md file in .cursor/rules is ignored because it has no frontmatter. If you want plain markdown, use AGENTS.md instead.
2. Wrong place. Project rules live in .cursor/rules/ in the project. Subfolders such as .cursor/rules/frontend/ work too. User rule files go in ~/.cursor/rules and stay on that machine; user rules typed into Customize sync with your account.
3. Type doesn't match intent. An Apply Intelligently rule needs a description, and an Apply to Specific Files rule needs a glob that matches the files you're working on. This is the first thing the docs' own FAQ tells you to check.
4. Wrong feature. Rules only apply to Agent (Chat). The help page says they don't affect Tab completion or Bugbot PR reviews.
5. A legacy file. .cursorrules in the project root is legacy and will be deprecated. Move its content into a new rule set to Always Apply, which matches the old behavior, then delete the file.
6. A conflict, not a miss. When rules disagree, precedence is Team Rules, then Project Rules, then User Rules. Your project rule may be loading and losing to a team rule.
7. Too long or too vague. The docs recommend keeping each rule under 500 lines, splitting large rules, and avoiding vague guidance. A rule can load and still be followed badly.

If an Always Apply rule still seems ignored, @-mention it in the chat to force it in. Cursor staff suggested that workaround in an April 2026 forum bug report where always rules weren't being injected, so keep Cursor updated too.

Things that surprise people

• Referenced files aren't inlined. Writing @service-template.ts in a rule tells the agent where to look; it reads the file with its tools when it needs it. The docs say anything that must always be in context belongs in the rule body itself.
• CLAUDE.md is always on in Cursor. Cursor reads CLAUDE.md like AGENTS.md, and the help page says CLAUDE.md is applied to every conversation regardless of any alwaysApply frontmatter. If your CLAUDE.md is long, Cursor pays for it in every chat too (see why a long CLAUDE.md gets ignored).
• Nested AGENTS.md files are scoped. Cursor applies an AGENTS.md in a subfolder when working with files in that folder or below, combined with the parent files, with the more specific file taking precedence. That's a simple alternative to globs for folder-level rules.
• Same filename, different folders. Cursor identifies rules by full path, so two api.mdc files in different folders both apply if their conditions match. There's no override by name.
• The CLI uses the same rules. The Cursor CLI agent loads .cursor/rules the same way, and also applies AGENTS.md and CLAUDE.md from the project root.

Rules or skills?

Rules are for standing guidance; Agent Skills are for procedures. Cursor's skills docs describe a built-in /migrate-to-skills that converts Apply Intelligently rules (no alwaysApply, no globs) into skills, while Always Apply and glob rules stay rules because their triggers are explicit. A good split: always-on essentials and file-scoped conventions as rules, and multi-step workflows such as "plan a feature" or "prepare a release" as skills. For how to make a skill load when it should, see how to write a SKILL.md that actually triggers; it covers Cursor's disable-model-invocation too.

Using Cursor alongside Claude Code or Codex? The file-by-file comparison is in Cursor rules vs CLAUDE.md vs AGENTS.md, and the way to stop the copies drifting is in AGENTS.md vs CLAUDE.md: one source of truth.

Five-minute rule audit

1. List .cursor/rules/; rename any .md rule to .mdc and give it frontmatter.
2. Open Customize, then Rules, and check each rule's type and status.
3. Give every Apply Intelligently rule a description that names the task or folder it's for.
4. Rewrite globs in the docs' unquoted comma-separated form, with **/ where you mean "any folder".
5. Keep only a handful of lines in Always Apply rules and in CLAUDE.md; move the rest to scoped rules or skills.
6. Retire .cursorrules.
7. Test each rule in a new chat with a task that should trigger it.

FAQ

Sources

Official docs, checked 2026-10-25.

• Cursor docs: Rules
• Cursor help: Rules (storage, CLAUDE.md, troubleshooting)
• Cursor docs: Using the CLI agent (rules, AGENTS.md, CLAUDE.md)
• Cursor docs: Agent Skills (migrating rules to skills)