Cursor .mdc Rules Explained: Frontmatter, Globs, alwaysApply (with Examples)

Your Cursor rule gets ignored, or it fires everywhere even though it was meant for components only? It almost always comes down to three frontmatter fields.

This guide explains how .mdc files work, which rule types exist and what glob patterns look like, with example rules to copy.

What is an .mdc file?

Cursor rules give the Agent persistent context. As the Cursor docs put it, large language models don't retain memory between completions, so when a rule applies, its contents are included at the start of the model context.

Project rules live in .cursor/rules/ and are version-controlled with your code. Each rule is a Markdown file with frontmatter and the extension .mdc. Subfolders are allowed:

.cursor/rules/
  react-patterns.mdc       # recognized as a project rule
  api-guidelines.md        # ignored (wrong extension)
  frontend/
    components.mdc

Besides project rules, Cursor supports User Rules (global to your Cursor environment), Team Rules (Team and Enterprise plans, managed from the dashboard) and AGENTS.md.

The frontmatter fields: description, globs, alwaysApply

At the top of the file sits a YAML block between --- lines. Three fields control when the rule loads:

• description: a short summary. The Agent reads it and decides whether the rule is relevant.
• globs: file patterns. The rule attaches when a matching file is in context.
• alwaysApply: true means the rule is included in every chat session.

---
description: Conventions for API routes and input validation
alwaysApply: false
---

- Validate every input with zod
- Return errors as an object with `code` and `message`

The four rule types

In Cursor you pick the type from a dropdown, which sets the three fields for you:

Decision table: field combination → behaviour

Rule of thumb: alwaysApply: true wins. If you set globs and leave true in place, the rule applies everywhere.

Glob patterns that work

Separate multiple patterns with commas.

Common mistakes:

• *.ts instead of **/*.ts: matches the root only, not src/.
• Missing comma: two patterns without a comma aren't split.
• globs plus alwaysApply: true: the globs have no effect.

.mdc vs .md

The docs are explicit: project rules must use the .mdc extension. A plain .md file in .cursor/rules is ignored because it has no frontmatter to specify description, globs and alwaysApply.

Prefer plain Markdown without metadata? Use AGENTS.md instead (see below).

Three example rules to copy

1. TypeScript (Apply to Specific Files): .cursor/rules/typescript.mdc

---
globs: src/**/*.ts, src/**/*.tsx
alwaysApply: false
---

- TypeScript strict, no `any`
- Named exports instead of default exports
- Derive API response types from zod schemas

2. Testing (Apply Intelligently): .cursor/rules/testing.mdc

---
description: Conventions for writing or changing tests
alwaysApply: false
---

- Test files sit next to the code: `name.test.ts`
- One behaviour per test; the name describes the expected result
- Run the test suite after changes before reporting done

3. Git hygiene (Always Apply): .cursor/rules/git.mdc

---
alwaysApply: true
---

- Never commit `.env` files or secrets
- Commit messages follow Conventional Commits (feat, fix, docs, chore)
- Don't edit files in `dist/` or `build/`

You can also create rules by typing /create-rule in Agent and describing what you want. The Agent generates the rule file with proper frontmatter.

Keep rules short

Best practices from the Cursor docs:

• Keep rules under 500 lines.
• Split large rules into multiple, composable rules.
• Reference files instead of copying them. Mentioning a file such as @service-template.ts tells the Agent where to look, but the file's contents are not inlined into the prompt. Anything that must always be in context belongs in the rule body.
• Don't copy entire style guides. Use a linter instead.
• Reuse rules when you keep repeating prompts in chat.

Note: according to the docs, rules do not impact Cursor Tab or other AI features.

AGENTS.md and CLAUDE.md in brief

AGENTS.md is plain Markdown, described by Cursor as a simple alternative to .cursor/rules. Cursor reads it in the project root and in subdirectories. Nested files are combined with their parent directories, with more specific instructions taking precedence.

Claude Code reads CLAUDE.md. Reading AGENTS.md directly requires Claude Code v2.1.277 or later. To keep one source for both, import AGENTS.md from your CLAUDE.md:

@AGENTS.md

## Claude Code
- Use plan mode for changes under `src/billing/`.

The Claude Code counterpart to file-scoped .mdc rules is .claude/rules/*.md, scoped with paths: frontmatter. paths is the only frontmatter field Claude Code reads there; other fields such as globs or alwaysApply are ignored without an error:

---
paths:
  - "src/api/**/*.ts"
---

- Every API endpoint validates its inputs

Which file to use when is covered in our guide Cursor Rules vs. AGENTS.md. For reusable workflows in Claude Code, see the SKILL.md template.

Rather start from ready-made rules?

13 stack-neutral starter rules instead of a blank file, plus AGENTS.md and CLAUDE.md templates: the Cursor + Claude Code Rules Pack by Aramac is checked against the Cursor rules format (.mdc, as of October 2026). Personal, non-commercial use only (licence). €19 incl. VAT. Free updates until 16.04.2027.

FAQ

Why is my Cursor rule being ignored?
Check the extension first: project rules must be .mdc, and .md files in .cursor/rules are ignored. For Apply Intelligently, the rule needs a description; for Apply to Specific Files, the glob pattern must match the referenced files.

What does alwaysApply do?
With alwaysApply: true the rule is included in every chat session. globs and description are then ignored.

How do I separate multiple globs?
With commas, for example: docs/**/.md, docs/*/*.mdx.

Does Cursor read AGENTS.md?
Yes. Cursor supports AGENTS.md in the project root and in subdirectories as a simple alternative to .cursor/rules.

Do Cursor rules apply to Cursor Tab?
No. According to the Cursor docs, rules do not impact Cursor Tab or other AI features.

Sources

• Cursor docs: Rules
• Anthropic, Claude Code docs: How Claude remembers your project (CLAUDE.md, AGENTS.md, .claude/rules/)
• AGENTS.md

All checked October 16, 2026.

---

An independent product by Aramac GmbH. Not affiliated with or endorsed by Anysphere (Cursor) or Anthropic. Cursor and Claude are trademarks of their respective owners.