Cursor

41.1 The Rules System #

Cursor uses .cursor/rules/*.mdc, Markdown with YAML frontmatter, replacing the legacy single .cursorrules file. It also reads AGENTS.md, and merges both.⁷⁵

Four activation modes exist, and choosing the right one constitutes the whole skill:

---
description: React component conventions for this codebase
globs: ["src/**/*.tsx", "src/**/*.jsx"]
alwaysApply: false
---
- Function components only. No class components.
- Props interfaces are named `<ComponentName>Props` and exported.
- No inline styles. Use the token system in `src/styles/tokens.ts`.

---
description: >
  Database migration standards. Use when creating, altering, or reverting
  a migration, or when a schema change is requested.
alwaysApply: false
---
- Every migration has both `up` and `down`.
- Never alter a column type in place. Add, backfill, drop in a later migration.
- Index creation on tables over 1M rows uses `CONCURRENTLY`, in its own migration.

@migration-template.sql

The second is agent-requested: no globs, so it fires on description match. The @migration-template.sql reference loads only if the rule fires.

41.2 Keep Always-Apply Small #

Community guidance converges on keeping alwaysApply: true rules under roughly 200 words, and the reasoning is exactly §15.5’s: every token loads in every request. Treat the always-apply set as a strict budget and push everything else into globs or descriptions.

The migration from .cursorrules pays for this reason alone. A single monolithic file is always-loaded by construction; the split format lets most of the same content become conditional.

41.3 Rules and AGENTS.md Together #

The two are not competitors, since Cursor reads both and merges them. The allocation rule that avoids duplication:

• Cross-tool standards → AGENTS.md. Anything true whether someone uses Cursor, Codex, or Claude Code. Stack, commands, architecture boundaries.
• Cursor-specific behavior → .mdc. Anything that depends on glob activation or references Cursor features.

Do not duplicate content between them. Where they overlap, precisely-scoped .mdc rules tend to carry more contextual weight, which makes duplication actively harmful rather than merely wasteful.

41.4 What Is Distinctive #

The four-mode activation model is the most granular available and the agent-requested mode in particular is a different mechanism—it is a skill’s description-matching applied to rules. Used well, it produces a very small always-on footprint with a large library of conditional guidance, which is the ideal shape described in §14.1.

The corresponding failure mode is a large collection of rules with vague descriptions, none of which fire, which is worse than a single well-written always-on file. Description quality is the constraint here as it is with skills (§16.2).