Skip to content
agents.cli

Project Rules: .mdc frontmatter and the four rule types

AGENTS.md is always on. That’s its strength and its limit - there’s no way to say “load this rule only when editing API handlers” or “let the agent decide whether this is relevant.” That control is exactly what Cursor’s native .mdc format adds.

A Project Rule is a Markdown file with YAML frontmatter, living under .cursor/rules/:

budgetcli/
├── AGENTS.md                    ← always-on, portable, cross-tool
├── .cursor/
│   └── rules/
│       ├── api-validation.mdc   ← attaches when editing API files
│       ├── commit-style.mdc     ← agent decides relevance
│       └── migrations.mdc       ← invoked by hand: @migrations
└── src/...

The frontmatter carries three control fields - description, globs, and alwaysApply - and the combination you set maps to four behaviors. Cursor’s current UI terminology is Always, Auto Attached, Agent Requested, and Manual; older releases and tutorials use longer names, so follow the labels shown by your installed version:

.cursor/rules/api-validation.mdc
---
description: Validate every API request body with a Zod schema
globs: ["src/api/**"]
alwaysApply: false
---


All handlers under src/api/ validate input with a Zod schema before any
business logic. Reject invalid bodies at the boundary; never hand-roll
validation with if-checks.

The four types map to those fields like this:

  • Always - alwaysApply: true. The rule is loaded into every request in this project. Use it for repo-wide truths that must never be missed.
  • Agent Requested - alwaysApply: false with a description and no globs. The agent reads the description and decides whether the rule is relevant.
  • Auto Attached - a globs: pattern. The rule attaches when a matching file enters context - e.g. ["src/api/**"] for the validation rule above.
  • Manual - no automatic attachment. You pull the rule in on demand using the manual-rule affordance shown by your installed Cursor version.

This is the divergence from Codex and OpenCode in one paragraph: there, a rule is on or it isn’t. Here, a rule can be always-on, model-judged, file-scoped, or hand-invoked - and you choose per rule with two lines of frontmatter.

Four types, two lines of frontmatter, all under your control. Except one of the four isn’t as reliable as it looks. Next: the globbing sharp edge.