Rules

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

阅读目标：读完本章，你应该能判断一条指令应该放 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 开头。

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 文件结构

官方示例：

.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 写长期规则。
复制代码库里已经存在的内容。

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

深读：为什么 Rule 应该进 Git

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

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

本章自检

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

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

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

官方来源

Cursor Rules —— 官方说明 Rules 类型、文件结构、frontmatter、globs、创建方式和最佳实践。
Cursor Rules Help —— Help Center Rules 入门说明。