用 Cursor Rules / CLAUDE.md 把团队规范"固化"进 AI 编程工作流

核心观点：AI 编程产出的质量上限，取决于你提前喂给它的"项目记忆"，而不是模型本身。

一、一个被反复忽视的事实：AI 编程的质量上限不在模型，在上下文

过去两年，AI 编程工具经历了从"玩具"到"生产力工具"的跨越。GitHub Copilot、Cursor、Claude Code 这些产品，已经把"让 AI 帮你写代码"这件事从新奇变成了日常。但一个奇怪的现象也随之出现：同样是用最先进的模型，有的人写出来的代码可以直接合并进主干，有的人写出来的代码却需要反复返工，甚至引入一堆隐蔽的 Bug。

差别到底在哪？很多人第一反应是"模型不行"，或者"提示词写得不好"。但如果你观察那些真正把 AI 编程用出效果的高绩效团队，会发现他们几乎都做了同一件事：在项目里维护了一套给 AI 看的"项目记忆"。

这套项目记忆，在 Cursor 里叫 Rules （规则），在 Claude Code 里叫 CLAUDE.md ，在 OpenClaw 这类 Agent 框架里叫 AGENTS.md。它们的名字不同、格式略有差异，但本质是同一件事：一份放在项目根目录里的、专门写给 AI 看的指令文件，用来告诉 AI"这个项目长什么样、有哪些约定、哪些坑绝对不能踩"。

这份文件，决定了 AI 是"在这个项目的语境里工作"，还是"在一个它完全不认识的项目里瞎猜"。而这个差别，直接决定了产出质量的上下限。

为什么这么说？因为大模型本质上是一个"没有项目记忆的新同事"。你每开一个新会话，它就对你的项目一无所知。它不知道你的目录结构约定、不知道你的命名规范、不知道你用了什么依赖注入框架、不知道哪个模块是历史遗留的雷区。如果你不告诉它，它就只能靠"通用编程常识"去猜------而"通用常识"和"你这个项目的具体约定"之间的落差，就是返工和 Bug 的来源。

所以结论很直接：你喂给 AI 的上下文质量，决定了它产出的质量。模型再强，缺了项目记忆，也是在裸奔。

二、Rules / CLAUDE.md / AGENTS.md 到底是什么

在深入"怎么写"之前，先把这三个概念讲清楚，因为它们经常被混为一谈。

1. Cursor Rules（.cursor/rules/ 目录下的 .mdc 文件）

Cursor 从某个版本开始引入了 Rules 机制。你可以在项目根目录的 .cursor/rules/ 文件夹下放若干个 .mdc 文件（Markdown with Cursor 的扩展格式），每个文件描述一类规则。比如你可以有 architecture.mdc（架构约定）、naming.mdc（命名规范）、testing.mdc（测试要求）。

.mdc 文件头部有一段 YAML 风格的 frontmatter，可以声明这个规则什么时候生效、是否自动附带、适用范围是什么（比如只对特定目录或特定文件类型生效）。这让规则可以做得非常精细：有些规则"永远带上"，有些规则"只有在碰 Python 文件时才带上"。

2. CLAUDE.md（Claude Code 的项目记忆文件）

Claude Code 会自动读取项目根目录的 CLAUDE.md（以及父目录、用户目录下的 CLAUDE.md），把它作为每次会话的"开场上下文"注入。你可以在里面写任何你觉得 AI 应该知道的、关于这个项目的信息。它就是一个朴素的 Markdown 文件，没有特殊的 frontmatter 语法，越直白越好。

3. AGENTS.md（OpenClaw / 通用 Agent 框架的约定文件）

AGENTS.md 是 OpenClaw 以及一批类似 Agent 框架采用的约定：放在工作区根目录，用来告诉 Agent"你是谁、你该读哪些文件、有哪些红线、项目有什么约定"。它更像是"给 Agent 的操作手册"，不仅包含代码规范，还包含工作流程、记忆管理、边界约定等更宽泛的内容。

它们的共同点：都是"项目级指令文件"，都放在项目（或工作区）根目录，都会被 AI 在会话开始时自动读取并纳入上下文。

它们的区别：粒度不同、生效机制不同、覆盖面不同。Cursor Rules 偏向"细粒度、条件触发"的代码规范；CLAUDE.md 偏向"全量注入的项目背景"；AGENTS.md 偏向"Agent 的行为与流程约束"。

理解了这个，你就能根据自己的工具栈选择正确的载体。但无论用哪个，核心原则是一样的------我们下面要讲的"怎么写才有效"，对三者通用。

三、为什么"项目记忆"如此关键：三个具体场景

为了让"重要性"这件事不流于抽象，我们看三个具体的、每天都在发生的场景。

场景一：目录结构约定。 你的团队约定"业务逻辑放 services/、数据访问放 repositories/、公共组件放 shared/"。AI 不知道这个约定，它可能会把数据访问逻辑塞进 services/，或者自创一个 dao/ 目录。当你让它"加一个查询订单的功能"时，它写出来的代码位置全错，PR 被打回。而如果你在 Rules 里写清楚了目录职责，AI 每次都会把代码放到对的地方。

场景二：命名与风格。 你的团队约定"接口用 IXxxService，实现用 XxxServiceImpl"，或者"React 组件用 PascalCase，Hook 用 useXxx"。AI 不知道，它可能写出一堆 OrderService + OrderServiceImpl 之外的自创命名，或者混用多种风格。命名不一致是 AI 代码最容易被吐槽的点之一，而它完全可以通过一条规则避免。

场景三：禁踩的坑。 这个最要命。比如你的项目里"绝对不能直接 import moment，要用团队的 date-utils"；"数据库连接必须走连接池，不能每次 new 一个"；"这段老代码是遗留系统，改之前必须加回归测试"。这些是团队用血泪换来的经验，AI 不可能凭空知道。如果你不写进 Rules，它就会义无反顾地踩进去------而且踩得又快又标准。

这三个场景说明一件事：AI 编程的很多"质量事故"，根源不是模型不够聪明，而是它缺乏项目的领域知识和约束。而这些知识和约束，恰恰是你手上现成的、写下来就能反复复用的资产。

四、从零搭一份：怎么写才真正有效

知道"为什么"之后，关键是"怎么写"。一份好的项目记忆文件，不是把团队的《代码规范》文档复制粘贴过来，而是要为 AI 的"阅读方式"重新组织。下面是一个我反复验证有效的结构模板。

4.1 开头：一句话说清项目是什么

markdown 复制代码

# Project Context

这是一个用 TypeScript + NestJS 写的订单服务后端，对接 MySQL 和 Redis，
服务之间通过 gRPC 通信。测试用 Jest。

别小看这一句话。它让 AI 在第一时间建立起对技术栈和项目性质的正确认知，避免它用错误的语言、错误的框架假设来写代码。

4.2 目录结构与职责

用简洁的树形结构 + 一句话职责说明：

markdown 复制代码

## 目录结构
- `src/services/` ------ 业务逻辑层，每个 service 对应一个领域
- `src/repositories/` ------ 数据访问层，只做 DB 读写，不写业务
- `src/shared/` ------ 跨模块公共组件和工具函数
- `src/grpc/` ------ gRPC 接口定义和实现

4.3 命名规范（这是 AI 最容易翻车的地方）

markdown 复制代码

## 命名规范
- 接口：`I` 前缀，如 `IOrderService`
- 实现类：`Impl` 后缀，如 `OrderServiceImpl`
- React 组件：PascalCase，文件名与组件名一致
- Hook：`use` 前缀
- 数据库表名：snake_case，实体类用 camelCase

4.4 依赖与工具约定

markdown 复制代码

## 依赖约定
- 时间处理：统一用 `dayjs`，禁止引入 `moment`
- HTTP 客户端：统一用 `axios` 封装好的 `httpClient`，禁止裸写 fetch
- 日志：统一用 `logger`，禁止 `console.log`
- 状态管理：用 `zustand`，禁止再引入 `redux`

4.5 禁踩的坑（高危区，务必写全）

markdown 复制代码

## ⚠️ 绝对禁止
- 不要直接操作 `moment`，会导致包体积暴涨
- 不要在循环里执行 DB 查询，必须批量处理
- `src/legacy/` 目录是遗留代码，修改前必须先补测试
- 数据库连接必须走连接池，禁止每次请求新建连接

4.6 关键：写"约束"而非"描述"

这是整个环节里最重要的一个认知。很多人写的规则是这样的：

markdown 复制代码

# 代码规范
我们的项目注重代码质量，建议使用 TypeScript，代码应该保持整洁。

这种写法，AI 看完基本等于没看。因为它不是"约束"，是"抒情"。AI 需要的是明确的、可执行的、非黑即白的指令：

markdown 复制代码

# 代码规范
- 本项目必须使用 TypeScript，禁止 JavaScript
- 所有函数必须标注返回类型，禁止使用 any（除非有明确理由并加注释）
- 提交前必须通过 eslint 和 type check

注意这两个版本的差别：第一个版本是"建议"，第二个版本是"必须/禁止"。AI 对"必须"和"禁止"这两个词的响应，远强于"建议"和"注重"。 因为大模型在训练中见过海量的规范文本，它本能地知道"必须/禁止"是需要严格遵守的硬约束，而"建议/注重"是可以妥协的软建议。如果你把规则写成软建议，AI 就会把它们当成耳边风。

所以写规则时，能用量化词就用量化词，能用"必须/禁止/统一"就不用"建议/最好/尽量"。你写得越像一条"军规"，AI 执行得越到位。

五、反模式：把规则写成了"文档"而不是"约束"

这一节专门讲反模式，因为这是 90% 的团队第一次做这件事时会踩的坑。

反模式一：直接粘贴整本《代码规范》文档。 团队通常已经有一份几十页的代码规范文档，里面充满了背景说明、历史沿革、正反例对比、评审流程等等。有人图省事，直接把这份文档整个塞进 Rules。结果是：上下文被大量"非指令性"内容占据，真正该执行的规则被淹没在长篇大论里，AI 抓不住重点，反而更容易出错。记住：给 AI 的文件是"约束清单"，不是"培训教材"。 要的是精炼的、可执行的条目，而不是详尽的论证过程。

反模式二：规则之间相互矛盾或含糊。 比如一处写"统一用 A 库"，另一处写"B 库也可以"。AI 面对矛盾指令时，会随机选一个执行，结果就是不可预测。写之前先清理自己的规范，确保每一条都是明确的、无歧义的、不互相打架的。

反模式三：只写"正面规范"，不写"禁止清单"。 很多人写了"应该怎么做"，却漏了"绝对不能怎么做"。但对 AI 来说，"禁止清单"往往比"正面规范"更有效------因为 AI 默认会用"最通用、最常规"的写法，而这些"最常规"的写法，恰恰可能就是你们团队禁止的。把"禁踩的坑"单独列一节，用醒目的方式标出来，效果最好。

反模式四：写了就再也不更新。 规则文件不是一次性写完就完事的。项目在演进，约定在变化，如果 Rules 停留在三个月前的状态，它就会从"助力"变成"误导"。建议把 Rules 文件纳入代码评审的一部分，任何规范变更都要同步更新它。

反模式五：规则文件写得像给新人看的，而不是给 AI 看的。 给新人看的文档，可以省略一些"显而易见"的约定，因为新人会问、会自己查。但 AI 不会问，它只会照着上下文里有的东西执行，没有的东西它就自由发挥。所以给 AI 的文件要"宁多勿缺"，把那些你以为"大家肯定都知道"的约定也写进去。

六、落地闭环：把这份规范接进 Code Review，让所有人都受益

前面讲的都是"怎么让 AI 守规矩"，但如果只做到这一步，价值还只是一半。真正让这套东西产生复利的是第二步：让规范反向约束人，形成一个"AI 和人共同遵守"的闭环。

6.1 让 AI 帮你执行 Code Review

当你把规范固化进 Rules 之后，AI 就不仅能在"写代码"时遵守它，还能在"审代码"时用它来把关。你可以在 Code Review 时让 AI 用同一份 Rules 去检查 PR，看有没有违反命名规范、有没有踩了禁止清单里的坑。这样，规范的执行就从"靠人自觉"变成了"AI 自动巡检"。

6.2 让 Code Review 反向完善 Rules

反过来，每次 Code Review 里发现的新问题、新约定，都应该沉淀回 Rules 文件。比如这次评审发现"有人又在循环里查数据库了"，那就把这条加进"绝对禁止"清单。这样 Rules 会越来越完整，越来越贴近团队的真实实践，形成一个正向循环。

6.3 让新人 onboarding 变快

一份好的 Rules/CLAUDE.md，本身就是一份极佳的项目速览。新人来了，读完这份文件，再配合 AI 编程助手，就能很快上手，因为 AI 会替新人"记住"那些规范，新人不至于一上来就犯低级错误。

6.4 让"规范"从墙上走进工作流

很多团队的代码规范，是写在 Wiki 里、挂在墙上、贴在群里，但没人真正遵守------因为"看规范"是一件需要主动去做的事，而人天生会偷懒。把规范固化进 AI 工作流之后，遵守规范变成了一件"默认发生"的事：AI 写代码时自动遵守，审代码时自动把关。规范不再需要人去"记得遵守"，而是被系统性地强制执行。 这才是"固化"这个词真正的含义。

六点五、进阶技巧：让规则更聪明、更省心

如果你已经用上了基础版规则文件，下面三招能让它从"能用"进化到"好用"。

第一招：规则分层------全局、项目、个人三层各司其职。 不要把什么都堆在项目根目录那一份文件里。可以这样分：用户级规则（放在用户目录，写"我个人的偏好"，比如我习惯用双引号、我偏好函数式写法）管全局习惯；项目级规则（放在项目根目录）管"这个项目"的约定；团队级规则（放在团队共享的模板里）管"全团队统一"的规范。AI 会同时读到这三层，并按"项目优先、用户兜底"的顺序综合。这样既能保证团队规范一致，又给个人习惯留了空间，还避免了把个人偏好误写进项目文件污染团队协作。

第二招：条件触发------用 glob 匹配让规则"该出现时才出现"。 Cursor 的 .mdc 规则支持在 frontmatter 里声明 globs 字段，指定这条规则只对哪些文件类型生效。比如测试规范那条规则，只在 .spec.ts、.test.ts 文件里生效；前端样式规范那条，只在 .css、.scss 文件里生效。这样做的好处是：上下文不会被无关规则挤占，AI 在写后端逻辑时不会看到一堆前端样式规则，注意力更聚焦，执行更精准。把"高频、通用"的规则设为全局常驻，把"低频、领域相关"的规则设为条件触发，这是经验证的黄金配比。

第三招：把规则接进 CI，让它"自动巡检 + 自我更新"。 更进一步，你可以在 CI 流水线里加一步：让 AI 用这份规则文件去自动检查提交的代码，把违反规则的条目自动标出来，甚至生成一份"规则执行报告"。反过来，当团队评审中发现了新约定，也顺手让它把新约定写回规则文件。这样，规则文件就从一份静态文档，变成了一个有生命力的、随项目一起进化的"活的约束系统"------它既约束 AI，也约束人，还能自我更新。

这三招的共同点，是都在往一个方向使劲：让规则真正进入工作流，而不是躺在仓库里吃灰。 分层让它组织清晰，条件触发让它精准投放，CI 接入让它持续运转。做到了这三点，你就把"AI 编程"这件事，从"偶尔用用"变成了"系统性地、可复用地、可持续地用"。

七、总结：一份好规则文件的 Checklist

最后，用一个可直接对照的清单收尾。当你写完一份 Rules / CLAUDE.md / AGENTS.md 之后，逐条对照：

开头有一句话说清项目是什么、用了什么技术栈
目录结构及其职责说明清晰
命名规范明确、无歧义、无矛盾
依赖与工具约定写全（统一用 A，禁止用 B）
有一个醒目的"绝对禁止"清单，覆盖历史踩过的坑
全部用"必须/禁止/统一"这类硬约束词，而非"建议/最好"
条目精炼、可执行，而不是长篇大论的文档
纳入 Code Review 流程，随项目演进持续更新

做到这七条，你的 AI 编程助手就从"一个会写代码的陌生人"，变成了"一个熟悉你项目所有约定、并严格遵守它们的资深成员"。而这，才是 AI 编程真正的正确打开方式。

记住那句话：AI 编程的质量上限，从来不是模型给的，而是你喂给它的"项目记忆"给的。模型可以持续变强，但项目记忆，只能靠你自己写出来。