NanoFile

Cursor rules

Cursor keeps its instructions in `.cursor/rules` as `.mdc` files, which are markdown with frontmatter. The frontmatter decides when a rule is pulled into context, and that is the part people get wrong.

Checked against the official documentation in August 2026. These tools change quickly, so the date is part of the answer.

A path-scoped rule
---
description: React component conventions
globs:
  - "src/components/**/*.tsx"
alwaysApply: false
---

# Components

- One component per file, named after the file
- Props typed inline, no separate Props interface unless reused
- No default exports

description: React component conventions globs: - "src/components/**/*.tsx" alwaysApply: false

Components

  • One component per file, named after the file
  • Props typed inline, no separate Props interface unless reused
  • No default exports

Attached automatically when a matching file is in context, and otherwise absent.

A rule that is always on
---
alwaysApply: true
---

- Never edit files under `generated/`
- Use pnpm, not npm

alwaysApply: true

  • Never edit files under generated/
  • Use pnpm, not npm

With alwaysApply true, description and globs are ignored entirely.

The four apply modes

Cursor's own documentation uses "four types of rules" for something else: Project Rules, User Rules, Team Rules and AGENTS.md. The four below are the ways a single project rule can be applied, which is the part that decides whether your rule does anything.

Apply mode When it applies How you get it
Always Every chat session alwaysApply: true
Applied intelligently When the agent judges it relevant a clear description, no globs
Applied to specific files When a matching file is in context globs patterns
Manual Only when you @-mention it neither description nor globs

Files and folders

Rules live in .cursor/rules and can be organised into subdirectories. They must be .mdc files: a plain .md in that folder is ignored, with one exception, which is AGENTS.md.

Cursor also reads AGENTS.md in the project root and in any subdirectory, combining the nested instructions with the parent ones and letting the more specific win. The older .cursorrules file at the root still works but the rules directory has replaced it.

User rules, set under Customize and then Rules, apply across all your projects, but only to the agent in chat rather than to inline edit or tab completion.

What usually goes wrong

  • A .md file in .cursor/rules is silently ignored, AGENTS.md included. Rules have to be .mdc, and this is the most common reason a rule does nothing. An AGENTS.md belongs in the project root, not in the rules folder.
  • alwaysApply: true overrides the rest: the description and the globs stop mattering. Pick one mechanism per rule.
  • A rule meant to apply intelligently needs a description that says when it is relevant, not what it contains. The agent reads that line to decide.
  • User rules do not reach inline edit or tab completion, so a preference set there will still be ignored by half of the editor.

Where it behaves differently

PlatformBehaviour
Cursor.cursor/rules/*.mdc for scoped rules, AGENTS.md in the root or a subdirectory for plain markdown, and Team Rules from the dashboard.
Claude CodeDoes not read Cursor rules at runtime, but /init reads .cursor/rules/ and .cursorrules and folds the relevant parts into the CLAUDE.md it generates.

Questions

What happened to .cursorrules?

Cursor no longer documents it. The rules directory replaced it and gives you scoping a single file cannot, so treat `.cursorrules` as a file you may still find in an old repository rather than one to create. Claude Code's `/init` still reads it when it exists.

Can one repository serve Cursor and Claude Code?

Yes. Put the shared content in AGENTS.md, which Cursor reads directly, and have CLAUDE.md import it. Keep only tool-specific instructions in the tool-specific files.

Related