---
title: "Rules"
description: "基于 Cursor 官方 Rules 文档解释 Project、User、Team Rules、AGENTS.md、frontmatter、globs 和规则最佳实践。"
verifiedAt: "2026-05-09"
---

Rules 是 Cursor 给 Agent 的系统级长期指令。官方文档说明，Rules 可以把 prompts、scripts 等打包在一起，方便团队管理和共享 workflow。它解决的是“每次都要重复告诉 Agent 的项目约定”。

> [!NOTE]
> **阅读目标**：读完本章，你应该能判断一条指令应该放 Project Rule、User Rule、Team Rule、AGENTS.md，还是不要写成长期规则。

## 1. 四类 Rules

官方文档列出四类规则。

| 类型 | 落点 / 范围 | 适合 |
| --- | --- | --- |
| Project Rules | `.cursor/rules`，进版本控制，作用于代码库 | 项目架构、目录、测试、生成文件禁区 |
| User Rules | 全局 Cursor 环境，用于 Agent Chat | 个人偏好，不适合团队约束 |
| Team Rules | Dashboard 管理，Team / Enterprise 可用 | 团队统一规范 |
| AGENTS.md | markdown agent instructions，`.cursor/rules` 的简单替代 | 简单项目、跨 agent 兼容入口 |

真实项目优先 Project Rules，因为它随仓库走，能 code review，也能让团队看到同一套约束。

## 2. Rules 怎么生效

官方说明，LLM 不会在 completions 之间保留记忆。Rules 提供 prompt-level 的 persistent reusable context。规则被应用时，其内容会放到 model context 开头。

```mermaid
flowchart TD
  Task["Agent task"] --> RuleMatch["Rule matching"]
  RuleMatch --> Context["Included at start of model context"]
  Context --> Agent["Agent follows guidance"]
  Agent --> Diff["Code / command / answer"]
```

所以 Rule 不应该写废话。它会占上下文，也会影响每次任务判断。

## 3. Project Rule 文件结构

官方示例：

```text
.cursor/rules/
  react-patterns.mdc
  api-guidelines.md
  frontend/
    components.md
```

Cursor 支持 `.md` 和 `.mdc`。如果需要 frontmatter 控制 `description`、`globs`、`alwaysApply`，用 `.mdc` 更清晰。

## 4. Rule 类型和 frontmatter

官方 Rule Type 对应这些行为：

| Rule Type | 行为 |
| --- | --- |
| Always Apply | 每个 chat session 都应用 |
| Apply Intelligently | Agent 根据 description 判断是否相关 |
| Apply to Specific Files | 文件匹配 globs（文件路径模式，如 `src/**/*.ts`）时应用 |
| Apply Manually | 在 chat 中 `@my-rule` 手动提及才应用 |

frontmatter 组合：

| `alwaysApply` | `description` | `globs` | 行为 |
| --- | --- | --- | --- |
| `true` | 任意 | 任意 | 总是 included |
| `false` | 空 | provided | 匹配文件时 auto-attached |
| `false` | provided | 空 | Agent 根据 description 拉取 |
| `false` | 空 | 空 | 只能 `@` mention |

## 5. 写 rule 的尺度

官方最佳实践：good rules are focused, actionable, and scoped。

应该做：

- 保持 rule 低于 500 行。
- 大规则拆成多个可组合 rules。
- 提供具体例子或引用文件。
- 避免 vague guidance。
- 当同一个 prompt 重复出现时复用 rule。
- 引用 canonical files，而不是复制全文。

不要做：

- 复制整份 style guide，交给 linter 更合适。
- 记录所有常见命令，Agent 已经知道 npm、git、pytest 等常用工具。
- 为少见 edge case 写长期规则。
- 复制代码库里已经存在的内容。

> [!IMPORTANT]
> 从简单开始。只有当你发现 Agent 反复犯同一个错误时，再更新 rule。

<details>
<summary>深读：为什么 Rule 应该进 Git</summary>

Project Rules 进入 `.cursor/rules` 并版本控制后，它们会变成团队工程资产：可以 review、可以追溯、可以和代码一起演进。个人 User Rules 不适合承载团队规范，因为别人看不到，也无法保证 CI、review 和 onboarding 一致。

如果一个规则影响代码结构、测试要求、目录边界或发布流程，它应该是 Project Rule 或 Team Rule，而不是个人口头经验。
</details>

## 本章自检

完成本章后，用这 3 个问题检查自己是否真正理解：

1. Project Rule 和 User Rule 的边界是什么？
2. `alwaysApply`、`description`、`globs` 如何决定 rule 是否被 included？
3. 为什么不要把整份 style guide 复制进 Rule？

通过标准：你能为一个项目写出 2-3 条 focused Project Rules，并解释每条规则的触发方式。

## 官方来源

- [Cursor Rules](https://cursor.com/docs/rules.md) —— 官方说明 Rules 类型、文件结构、frontmatter、globs、创建方式和最佳实践。
- [Cursor Rules Help](https://cursor.com/help/customization/rules.md) —— Help Center Rules 入门说明。

## 接下来去哪

<Cards>
  <Card title="MCP" description="继续理解怎么把外部工具和数据源接入 Cursor Agent。" href="/docs/cursor/official/02-context-customization/21-mcp" />
  <Card title="Skills" description="当规则不够表达多步流程时，继续学习 Skills。" href="/docs/cursor/official/02-context-customization/22-skills" />
</Cards>
