Cursor configuration

Configure Cursor Rules

Configure Cursor project rules with valid .mdc files, Always Apply, intelligent, glob-scoped, and manual activation, or use AGENTS.md for simpler projects.

Last verifiedAugust 13, 2026

Quick answer

Store version-controlled Project Rules as `.cursor/rules/*.mdc`. Choose exactly how each rule activates: always, by matching glob, by description relevance, or by manual `@` mention. Use a root or nested `AGENTS.md` instead when plain shared Markdown is enough.

Choose the right scope

ChoiceUse it forAvoid it for

Always Apply

A short rule required in every Agent chat for this project.

Large style guides or rare edge cases.

Apply to Specific Files

Rules tied to a file type or directory through `globs`.

Patterns that do not match the paths Cursor actually sees.

Apply Intelligently

A focused domain rule with a description clear enough for Agent to select.

Critical safety requirements that must always be present.

Manual

Specialized procedures invoked with `@rule-name`.

Rules expected to activate automatically.

AGENTS.md

Simple readable instructions at root or nested directory scope.

Rules needing MDC metadata and activation modes.

Configuration 1

Create a valid .mdc Project Rule

Cursor ignores plain `.md` files inside `.cursor/rules`; Project Rules require the `.mdc` extension and frontmatter.

Use `/create-rule` in Agent or Customize → Rules → Add Rule.
Name the file for one concern rather than one framework.
Commit Project Rules so the team reviews changes alongside code.

.cursor/rules/api-validation.mdc

---
description: API validation and error response rules
globs: src/api/**/*.ts
alwaysApply: false
---

- Validate all request input at the route boundary.
- Return the repository's structured error format.
- Use `src/api/example.ts` as the canonical implementation.

Configuration 2

Set one intentional activation mode

The `alwaysApply`, `description`, and `globs` fields combine to determine when content enters context.

Activation matrix

Always:      alwaysApply: true
File scoped: globs provided + alwaysApply: false
Intelligent: description provided, no globs + alwaysApply: false
Manual:      no description, no globs + alwaysApply: false

Important: If Always Apply is true, Cursor ignores globs and description for activation.

Configuration 3

Scope rules to real file paths

Use glob-scoped rules to prevent frontend, API, documentation, or migration guidance from entering unrelated tasks.

Test the rule against a known matching file and a known non-matching file.
Reference canonical code with `@filename` instead of copying examples into the rule.
Use nested AGENTS.md for simpler directory-based scope.

Useful glob examples

src/**/*.tsx
src/api/**/*.ts
docs/**/*.md, docs/**/*.mdx
tailwind.config.*

Configuration 4

Choose Cursor Rules or AGENTS.md

Cursor supports root and nested AGENTS.md files as a simpler cross-agent alternative.

Use AGENTS.md for shared commands, architecture, boundaries, and validation.
Use `.mdc` when you need automatic file matching, relevance-based selection, or manual invocation.
Avoid maintaining the same instruction in both systems unless one clearly owns the canonical text.

Important: Rules affect Agent, but Cursor's current documentation says they do not affect Cursor Tab. User Rules apply to Agent Chat, not Inline Edit.

Validation checklist

Open Customize → Rules and confirm every intended `.mdc` file appears.
For an intelligent rule, ask a matching and a non-matching question and inspect whether it activates.
For a glob rule, reference a matching file and verify attachment.
For a manual rule, invoke it explicitly with `@rule-name`.
Remove or fix any `.md` file mistakenly placed under `.cursor/rules`.

Common configuration mistakes

A rule never appears

Use the `.mdc` extension and validate frontmatter.

A file-scoped rule never attaches

Test the glob against the exact workspace-relative file path.

An intelligent rule is skipped

Write a specific description that matches the tasks where it is useful.

Too much context is always loaded

Split rules and use globs, intelligent selection, or manual invocation.

Related paths

All configuration guides

Official sources

Loading order, configuration formats, and commands were checked on August 13, 2026. Recheck official documentation before enforcing a configuration across a team.

Cursor Docs: Rules