A 2026 guide to Cursor's rule system: the four .mdc rule types, .cursor/rules vs legacy .cursorrules vs AGENTS.md, an original comparison table, and the gotchas that silently break rules.

Originally published at heycc.cn. This is a mirrored copy — the canonical version is kept up to date at the source.

How to Configure Cursor Rules in 2026 (.cursor/rules): The Complete Guide

Cursor's effectiveness depends less on the model you pick and more on the context you feed it. Rules are how you make that context durable: instead of re-explaining your stack, conventions, and "don't touch this" boundaries in every chat, you write them once and let Cursor load them automatically. In 2026 the way you do this has changed in two important ways. First, the single root-level .cursorrules file gave way to a modular .cursor/rules/ folder of .mdc files with per-file-pattern scoping. Second, AGENTS.md emerged as a cross-tool standard that several agents — Cursor included — read natively, so your instructions can be shared instead of duplicated per tool.

What follows is how the system works today: copy-paste examples for every rule type, a comparison table that lines up frontmatter against trigger and token cost, a recommended baseline setup, and the mistakes that quietly stop rules from loading at all.

The three layers of Cursor rules in 2026

Cursor assembles rules from three independent layers that combine in the Agent's context. Once you know which layer a rule lives in, its behavior is predictable.

• Project Rules — .mdc files in .cursor/rules/, version-controlled, scoped to the repo (or a subfolder). This is the primary, most flexible layer.
• User Rules — your global preferences in Customize → Rules (the Cursor Settings panel), applied across every project you open.
• AGENTS.md — a plain-markdown, cross-tool instructions file that Cursor reads alongside Project Rules.

These layers operate in parallel and stack: User Rules give your personal defaults, Project Rules give repo-specific scoping and precision, and AGENTS.md gives portable instructions that other tools also honor.

Where project rules live

Project rules live in the .cursor/rules directory as .mdc files, and they are version-controlled — you check them into git so the whole team gets the same behavior. The extension matters. Per the official docs, "A plain .md file in .cursor/rules is ignored by the rules system because it has no frontmatter to specify description, globs, and alwaysApply." Without that frontmatter, Cursor cannot decide when to load it.

You can also nest rules. Placing a .cursor/rules/ folder inside a subdirectory scopes those rules to that part of the codebase — handy in a monorepo where apps/web and services/api need different conventions.

my-repo/
  .cursor/
    rules/
      always-conventions.mdc
      react-components.mdc
      backend-rpc.mdc
  apps/
    web/
      .cursor/
        rules/
          web-specific.mdc
  AGENTS.md

The .mdc anatomy

An .mdc file is YAML frontmatter plus a markdown body. The frontmatter has three fields, and the combination of their values decides the rule type:

---
description: This rule provides standards for frontend components and API validation
globs: src/components/**/*.tsx
alwaysApply: false
---

# Frontend component standards

- Co-locate component, styles, and test in the same folder.
- Validate all external input at the boundary before use.
- Prefer composition over inheritance for shared behavior.

The markdown body is the actual instruction set Cursor reads. Keep it specific and imperative — write constraints the Agent must follow, not vague aspirations.

The four rule types with copy-paste examples

Cursor defines four project-rule types, each determined entirely by the frontmatter.

1. Always Apply — included in every chat. Set alwaysApply: true; globs and description are ignored.

---
alwaysApply: true
---
Use the existing framework. Do not introduce new dependencies without asking.
After edits, summarize files changed and how to verify.

2. Apply to Specific Files (Auto Attached) — auto-attached when a file matching globs is in context. Set alwaysApply: false plus a glob.

---
globs: src/components/**/*.tsx
alwaysApply: false
---
Prefer server components unless client interactivity is required.
Add "use client" only when necessary.

3. Apply Intelligently (Agent Requested) — the Agent reads the description and pulls the rule in when it judges it relevant. Set alwaysApply: false plus a clear description.

---
description: RPC service conventions and patterns for the backend
alwaysApply: false
---
All RPC handlers return typed errors. Never leak stack traces to clients.

4. Apply Manually — loaded only when you @-mention the rule. No description, no globs, alwaysApply: false.

---
alwaysApply: false
---
Database migration checklist: write the up and down migration, test rollback locally.

Comparison: rule type vs. frontmatter, trigger, and cost

As a default, reach for Auto Attached (precise, token-efficient), keep Always for the few things that must hold everywhere, use Agent Requested when relevance is contextual, and save Manual for procedures you invoke deliberately.

Project Rules vs. legacy .cursorrules vs. AGENTS.md

These three exist at once, so it helps to know what each is for.

• .cursor/rules/*.mdc (Project Rules) — the current, recommended mechanism. Per-file-pattern scoping, always-on rules, agent-requested rules, and token efficiency.
• .cursorrules (legacy) — the original single root file. It still works in 2026 but is deprecated: Cursor introduced the modular .cursor/rules/ system in the 0.43 release and now recommends migrating to .mdc files for scoping and token efficiency. Note that the current official Rules docs page no longer documents .cursorrules at all — the deprecation is reflected in the 0.43 changelog and community guidance rather than the live docs page. The legacy file continues to load, but new projects should be authored as .cursor/rules/*.mdc.
• AGENTS.md — a simple markdown file with no required metadata or frontmatter. It is a cross-tool standard for agent instructions: it emerged from a multi-vendor collaboration (OpenAI Codex, Amp, Jules from Google, Cursor, and Factory) and is now stewarded by the Linux Foundation's Agentic AI Foundation. It is read natively by a growing list of agents — including Cursor, Codex, GitHub Copilot, Windsurf, Claude Code (via Cursor's CLI), Zed, JetBrains Junie, Gemini CLI, Aider, and more — and is used across 60,000+ open-source repositories. You can place AGENTS.md in any subdirectory; it applies to that directory and its children, with more specific (child) files taking precedence over parents.

If you also use Claude Code, note Cursor's CLI reads both AGENTS.md and CLAUDE.md from the project root and applies them as rules alongside .cursor/rules. For a deeper tool-by-tool breakdown, see Claude Code vs. Cursor in 2026.

User Rules and the inline-edit caveat

User Rules are global preferences set in Customize → Rules within the Cursor Settings panel. They apply across all your projects and are used by the Agent (Chat). The important caveat: User Rules are not applied to Inline Edit (Cmd/Ctrl+K) — that path only uses what is in the immediate edit context. If a behavior must hold during inline edits, encode it as a Project Rule, not a User Rule.

Generating rules fast, and keeping them lean

You do not have to hand-write frontmatter. In the Agent, type /Generate Cursor Rules and describe what you want; Cursor creates the .mdc file with the correct frontmatter for you. You can also turn an ad-hoc instruction from a chat into a saved rule so it persists across sessions.

Cursor's own best practices keep rules effective:

• Keep rules short and focused. Aim for a few hundred lines or fewer per file; split large rules into multiple composable files instead of one sprawling document.
• Make instructions concrete. Reference specific files, patterns, or commands rather than abstract principles the model has to interpret.
• Prefer scoping over always-on. Every Always rule costs tokens on every request. Use globs (Auto Attached) so a rule only loads when the relevant files are in play.
• Provide examples. A short good/bad code snippet inside the rule body steers the Agent more reliably than prose.

A recommended starting setup

For most repositories, a lean, predictable baseline looks like this:

1. One Always rule with the handful of non-negotiables: don't add dependencies without asking, follow the existing framework, summarize changes after edits.
2. A few Auto Attached rules scoped by area — one for *.tsx components, one for backend handlers, one for tests — so domain conventions load only when you're working in that domain.
3. One or two Agent Requested rules for specialized guidance (migrations, infra) that the Agent can pull on demand.
4. An AGENTS.md at the repo root for the portable, tool-agnostic instructions you'd want every agent — not just Cursor — to honor.

This keeps your always-on context small, scopes the rest, and gives you a single portable file other tools can read.

Common mistakes that silently break rules

• Plain .md files in .cursor/rules. No frontmatter means the rule is ignored. Always use .mdc.
• Overusing Always. Marking everything alwaysApply: true bloats every request and dilutes the signal. Reserve it for true non-negotiables.
• Vague Agent Requested descriptions. If the description doesn't clearly state when the rule applies, the Agent won't pull it in. Write the description as a trigger condition.
• Relying on User Rules for inline edits. They don't apply to Cmd/Ctrl+K. Encode edit-time behavior as a Project Rule.
• Assuming .cursorrules is still first-class. It loads, but it's deprecated and missing scoping and token-efficiency features. Migrate to .cursor/rules/*.mdc.
• A space after the comma in a multi-glob list. Two independent threads on Cursor's own community forum report the same failure: globs: src/**/*.ts, tests/**/*.ts (space after the comma) silently matches nothing, while globs: src/**/*.ts,tests/**/*.ts (no space) works. One user's exact diagnosis: "no spaces after commas... the IDE has no visual indication of a space" — there's no error, the rule just never attaches. If a glob-scoped rule seems to load for some files and not others, check for stray whitespace before anything more exotic.

How the claims here were grounded

The four rule types and their frontmatter behavior, the verbatim "plain .md file is ignored" line, the Customize → Rules location for User Rules, and nested per-folder scoping all come from the official Cursor Rules docs. The AGENTS.md details — native reads by Cursor, stewardship under the Linux Foundation's Agentic AI Foundation, and the "60,000+ open-source repositories" figure — come from agents.md itself, which describes "a growing ecosystem" without publishing a precise count of supporting tools, so no exact tool count is asserted above. The .cursorrules deprecation is the one fact not on the live Rules page (which no longer lists .cursorrules); it rests instead on Cursor's 0.43 changelog and the FlowQL migration write-up in Sources. The legacy file still loads, but new projects should be authored as .cursor/rules/*.mdc.

Sources

• Cursor Docs — Rules
• Cursor Changelog
• AGENTS.md — official site
• Cursor deprecated .cursorrules — migrate to Project Rules (FlowQL)
• Cursor Forum — Correct way to specify rules globs?
• Cursor Forum — Cursor rules globs inconsistencies