skip to content

How do Cursor's four project-rule types map onto `alwaysApply`, `description` and `globs`, and when does each one reach Agent?

level: middleimportance: should knowfreq 11%

answer

  1. one dropdown, three fields
  2. true overrides the other two
  3. a pattern matched against files in context
  4. a description Agent reads to decide
  5. nothing set means mention only

basics

~20 s

alwaysApply: true is Always Apply, in every chat. globs with alwaysApply: false is Apply to Specific Files, attached when a matching file is in context. A description alone is Apply Intelligently, Agent decides. None of them is Apply Manually, used only when @-mentioned.

solid answer

~40 s

The type dropdown in a Cursor rule just edits three frontmatter fields. `alwaysApply: true` is **Always Apply**: the rule is in every chat, and its `globs` and `description` are ignored. With `alwaysApply: false`, a `globs` pattern makes it **Apply to Specific Files** — auto-attached when a matching file is in context. A `description` with no `globs` makes it **Apply Intelligently**: Agent reads the description and pulls the rule in when it judges it relevant. With neither, it is **Apply Manually** and is included only when someone @-mentions it, like `@my-rule`. So when a rule never fires, check the type: an intelligent rule needs a description, and a file rule's pattern must match the files actually in play.

code

markdown · 8 lines
markdown
---
description: RPC service conventions and error format for the backend
alwaysApply: false
---

- Define each service in its own file under `src/services/`
- Validate inputs at the service boundary
- Return structured errors with a `code` and a `message`

go deeper

for a junior

Name the four types — Always Apply, Apply Intelligently, Apply to Specific Files, Apply Manually — and know a manual rule is used by @-mentioning it.

for a middle

Map each type onto alwaysApply, description and globs, and explain that alwaysApply true makes the other two irrelevant. Be ready to write a glob that reaches nested folders.

for a senior

Diagnose a rule that never fires by checking its type, description quality and glob coverage, and pick types by weighing reliability against what every chat pays in context.

for a principal

Set a team convention for which knowledge is always on, path-scoped or on demand, so the always-on set stays small and reviewed while specialised guidance lives beside the code it governs.

## The three fields behind every rule A Cursor **project rule** is an `.mdc` file in `.cursor/rules`: markdown instructions under a YAML **frontmatter** block. Three frontmatter fields decide when the rule is included in Agent's context: - **`alwaysApply`** — `true` or `false`. - **`description`** — a sentence saying what the rule is about. - **`globs`** — one or more file patterns, separated by commas. When you create a rule from Customize or the command palette, a **type dropdown** offers four named types. Choosing one only rewrites these fields; there is no fourth hidden setting. ## The four types | Rule type | Frontmatter | When the rule is included | | :-- | :-- | :-- | | **Always Apply** | `alwaysApply: true` | Every chat session; `globs` and `description` are ignored | | **Apply to Specific Files** | `alwaysApply: false` + `globs` | Auto-attached when a matching file is in context | | **Apply Intelligently** | `alwaysApply: false` + `description`, no `globs` | Agent reads the description and pulls the rule in when relevant | | **Apply Manually** | `alwaysApply: false`, no `description`, no `globs` | Only when you `@`-mention the rule in chat | Two consequences are easy to miss: - A rule with `alwaysApply: true` cannot be narrowed by adding `globs` — they are ignored, and the rule still lands in every chat. - A rule with nothing set is not dead. It is a **manual** rule, waiting for `@rule-name`. Agent's toolset includes a **Fetch Rules** tool, documented as retrieving specific rules based on their type and description — the model-facing side of the relevance-based types. ## Writing a file-scoped rule ```markdown --- globs: src/components/**/*.tsx alwaysApply: false --- - Use named exports, not default exports - Keep components under 200 lines ``` Glob syntax follows the usual conventions, and Cursor's reference spells out the cases people get wrong: - `*` matches one file-name segment; `**` matches any number of directories. - `*.ts` matches `.ts` files **in the root only**; `**/*.ts` matches them in any directory. - `src/**` matches every file anywhere under `src/`. - Several patterns go in one comma-separated value: `docs/**/*.md, docs/**/*.mdx`. ## Creating a rule of the right type Three routes all produce an `.mdc` file in `.cursor/rules` with the frontmatter already filled in: - **`/create-rule`** typed in Agent, followed by a description of the rule you want — Agent writes the file with suitable frontmatter. - **Customize → Rules → Add Rule**, which creates the file and shows every rule with its status. - **New Cursor Rule** from the command palette, where the type dropdown sets the fields for you. A rule body can also mention files with `@filename`, so a manual rule for new services can carry its template with it. Commit the folder so the whole team gets the same rules. ## Why a rule seems not to apply Cursor's own troubleshooting starts with the type: 1. **Apply Intelligently** — is there a `description`? Without one, Agent has nothing to judge relevance by. A vague description ("backend stuff") gives it little more. 2. **Apply to Specific Files** — does the pattern match the files actually in context? `*.ts` silently misses every nested file. 3. **Apply Manually** — did anyone `@`-mention it? Nothing else brings it in. 4. **Extension** — a `.md` file in `.cursor/rules` is ignored altogether; rules must be `.mdc`. The **Rules** page under **Customize** lists every rule with its status, which is quicker than guessing. ## Choosing a type Each type trades reliability against context cost, because an included rule's text sits at the start of the model context: - **Always Apply** suits short, universal conventions — the copyright header, "never edit generated files in `dist/`". Everything here is paid for in every chat, so keep it brief. - **Apply to Specific Files** is the deterministic choice for conventions tied to a part of the tree: component patterns, migration rules for a `migrations/` folder. - **Apply Intelligently** fits topic knowledge that does not map to paths ("how our RPC services report errors"), at the price of depending on Agent's judgement and on a well-written description. - **Apply Manually** suits procedures used occasionally, such as a template for a new service, kept out of context until asked for. Cursor's guidance for all of them: keep each rule focused and under 500 lines, reference files with `@filename` instead of pasting their contents, and add a rule when Agent repeats the same mistake rather than before.

  • A rule sets `alwaysApply: true` and also lists `globs: src/**` — what happens?
    The rule is included in every chat session. With `alwaysApply: true`, Cursor ignores both `globs` and `description`. To limit it to `src/`, set `alwaysApply: false` and keep the `globs` — that makes it Apply to Specific Files.
  • How do you scope one Cursor rule to both `.md` and `.mdx` files under `docs/`?
    Put both patterns in `globs`, comma-separated: `docs/**/*.md, docs/**/*.mdx`. The `**` matters — `*.md` alone would match only files in the root.
  • An Apply Intelligently rule almost never gets pulled in — what do you change?
    First the `description`: Agent decides relevance from it, so it should name the subject the rule covers in the words a request would use. If the rule must apply every time a set of files is touched, stop relying on judgement and switch it to `globs`, or to Always Apply if it is short and universal.

  • A rule with alwaysApply false and nothing else set is never used
  • Adding globs to an alwaysApply true rule narrows it to those files
  • Apply Intelligently needs no description because Agent reads the rule body
  • The pattern *.ts matches TypeScript files in every directory
  • The rule type is stored in a setting separate from the file's frontmatter