Cursor Rules 使用介绍：让 AI 按你的规矩来

用 Rules 把项目约定、编码习惯和保存路径写进规则，Agent 每次对话都会自动遵守。本文参考 Cursor 官方规则文档 整理。

---

一、Rules 是什么？

Rules（规则） 为 Agent 提供系统级指令，将提示词、脚本等内容打包在一起，便于在团队内管理和共享工作流。根据 官方说明，Cursor 支持四种类型的规则：

类型	存放位置 / 管理方式	作用范围
项目规则	.cursor/rules，受版本控制	限定在当前代码库内
用户规则	Cursor Settings → Rules	整个 Cursor 环境全局生效，由 Agent（Chat）使用
团队规则	Cursor 控制台集中管理	Team / Enterprise 方案，组织内统一
AGENTS.md	项目根目录或子目录	以 Markdown 编写的 Agent 指令，是项目规则的简洁替代

规则的工作原理：大型语言模型在不同补全之间不会保留记忆，规则在提示级别提供持久、可重用的上下文。应用后，规则内容会被加入到模型上下文的开头，为 AI 在生成代码、理解编辑或协助工作流时提供一致指导。

---

二、Rules 适合解决什么问题？

场景	适合用 Rules 吗	说明
博客/文章固定保存到某目录	✅	一条短规则即可
沉淀与代码库相关的领域知识	✅	项目规则典型用途
编码规范（命名、错误处理、注释）	✅	按语言或目录配 globs
接口/API 约定（如 REST 风格）	✅	项目级约定
自动化项目特定的工作流或模板	✅	如「分析应用时先跑 dev 再看日志」
多步骤复杂流程（如：建分支→改代码→提 PR）	❌ 更适合作 Skill	流程复杂时用 Skill
一次性临时要求	❌	直接对话里说就行

简单记：约定、规范、固定习惯 → Rules；多步流程、专项能力 → Skills。

---

三、项目规则：文件结构与生效方式

项目规则以 Markdown 文件形式存放在 .cursor/rules 中，并纳入版本控制。Cursor 支持 .md 和 .mdc 两种扩展名；带 frontmatter 的 .mdc 可通过 description、globs、alwaysApply 等更精细地控制生效条件。

1. 目录与文件组织

.cursor/rules/
  react-patterns.mdc       # 带前置元数据的规则（描述、globs）
  api-guidelines.md        # 简单 markdown 规则
  frontend/                # 可在子文件夹中组织规则
    components.md

2. 规则类型（应用方式）

在 Cursor 中创建/编辑规则时，可通过类型下拉菜单控制规则的应用方式，对应修改 description、globs、alwaysApply 等属性：

规则类型	含义
Always Apply	应用于每个聊天会话
Apply Intelligently	当 Agent 根据描述判断其相关时应用
Apply to Specific Files	当打开/引用的文件匹配指定模式时应用
Apply Manually	在对话中被 @ 提及时应用（例如 @my-rule）

3. Frontmatter 与正文

每条规则由 frontmatter 元数据 + 正文内容 组成。元数据控制「如何应用」，正文即规则本身。

---
description: "为前端组件和 API 校验提供规范"
alwaysApply: false
globs: "components/**/*.tsx"   # 可选，用于 Apply to Specific Files
---

- 定义服务时使用我们内部的 RPC 模式
- 服务名称始终使用 snake_case 命名

@service-template.ts

• description：规则简介，必填；Apply Intelligently 时 Agent 会据此判断是否引入该规则。
• globs：文件匹配模式，如 **/*.ts、backend/**/*.py，用于「仅对特定文件生效」。
• alwaysApply：为 true 时应用于每个聊天会话；为 false 时由描述或 globs 决定是否应用。
• @service-template.ts 表示可以参考的文件。

---

四、两条实用示例

示例 1：博客保存路径（Always Apply）

---
description: 写博客时固定保存到 docs/博客 路径
alwaysApply: true
---

# 博客保存路径

当用户要求撰写博客、文章或技术笔记时，一律保存到 `docs/博客/` 目录下。
文件名使用有意义的标题，如 `博客-主题名.md`。不要保存到根目录或其他随意路径。

示例 2：仅对 TypeScript 生效的规范（Apply to Specific Files）

---
description: TypeScript 错误处理与日志约定
globs: "**/*.ts"
alwaysApply: false
---

# TypeScript 约定

- 捕获异常时必须记录日志，不能空的 catch。
- 对外抛出的错误使用自定义 Error 子类，并保留 cause。

---

五、最佳实践（来自官方建议）

好的规则应当聚焦、可操作且范围明确：

• 控制篇幅：单条规则建议在 500 行以内；较大的规则拆成多条可组合的规则。
• 提供具体示例或参考文件：用 @filename.ts 引用文件而不是在规则里大段复制代码，这样规则更短，且代码变更时规则不会失效。
• 写清楚、像内部文档：避免模糊的指导，给出「要怎么做 / 不要怎么做」的明确说明。
• 复用而非重复：在聊天里经常重复的提示，抽成规则复用。
• 先简单后迭代：先从简单规则开始，只有发现 Agent 反复犯同一类错误时再补充；在真正理解自己的模式之前不要过度优化。提交到 Git 后，整个团队都能受益；看到 Agent 出错时，可以更新对应规则，甚至在 GitHub issue/PR 里 @cursor 让 Agent 帮你改规则。

规则中应避免的内容

• 整篇照搬风格指南：交给 linter；Agent 已了解常见风格约定。
• 逐条记录所有可能的命令：Agent 知道 npm、git、pytest 等常见工具。
• 为极少出现的边缘情况写很长说明：让规则聚焦在你经常使用的模式上。
• 重复代码库里已有的内容：引用标准示例即可，不要大段复制。

---

六、AGENTS.md：更简单的替代

若你只需要简单、易读的 Agent 指令，不想维护 .cursor/rules 的 frontmatter 和多种类型，可以用 AGENTS.md。它是放在项目根目录或子目录的纯 Markdown 文件，没有元数据或复杂配置。

# Project Instructions

## Code Style
- Use TypeScript for all new files
- Prefer functional components in React
- Use snake_case for database columns

## Architecture
- Follow the repository pattern
- Keep business logic in service layers

嵌套 AGENTS.md：子目录里也可以放 AGENTS.md。处理该目录或其子目录中的文件时，这些指令会自动生效；子目录的指令会与父目录合并，更具体的指令优先级更高。例如：

project/
  AGENTS.md           # 全局指令
  frontend/
    AGENTS.md         # 前端专用指令
  backend/
    AGENTS.md         # 后端专用指令

---

七、用户规则与团队规则（简述）

• 用户规则：在 Cursor Settings → Rules 中定义，全局生效于所有项目，由 Agent（Chat）使用，适合设定交流风格或通用编码偏好，例如：「请以简洁风格回复，避免不必要的重复。」
• 团队规则：Team / Enterprise 在 Cursor 仪表盘 集中管理，可设为对成员强制执行。规则优先级一般为：团队规则 → 项目规则 → 用户规则。

---

八、导入规则与旧版说明

• 远程规则（GitHub）：在 Cursor Settings → Rules, Commands 中可通过「Remote Rule (GitHub)」从你有权限的仓库导入规则，并与之保持同步。
• Agent Skills：可从 Agent Skills 加载规则，作为「由 Agent 根据上下文决定是否应用」的规则，无法配置为 Always Apply 或 Manual。
• 旧版 .cursorrules：项目根目录的 .cursorrules 仍支持但即将废弃，建议迁移到项目规则或 AGENTS.md。

---

九、常见问题速览

• 规则没生效？ 检查规则类型：Apply Intelligently 需填好 description；Apply to Specific Files 需保证 globs 与当前文件匹配。
• 可以引用其他规则或文件吗？ 可以，在规则或聊天中用 @filename.ts 将文件加入上下文；也可在聊天中 @ 规则名手动应用。
• 规则会影响 Cursor Tab 或其他 AI 功能吗？ 不会，规则只影响 Agent（Chat）。
• 用户规则会应用到 Inline Edit（Cmd/Ctrl+K）吗？ 不会，用户规则仅被 Agent（Chat）使用。

---

十、小结

• Rules = 系统级、持久可复用的 Agent 指令，分为项目规则、用户规则、团队规则与 AGENTS.md 四种。
• 项目规则 放在 .cursor/rules，用 frontmatter（description / globs / alwaysApply）和规则类型控制「何时应用」。
• 适合：保存路径、编码规范、领域知识、模板与工作流约定；复杂多步流程交给 Skills。
• 写好规则后，说「按规范改这段 TS」，Agent 就会按你的规矩来。

更多细节与图示见 Cursor 官方规则文档。