AI编程工具与团队协作
前八天讲的都是"我"怎么用 AI 写代码、改代码、测代码、修 bug。个人效率确实涨了。
但把镜头拉到团队，问题就来了：十个人十套 AI 习惯，产出风格反而更乱了——同一个项目里，有人让 AI 写中文注释，有人写英文；有人习惯 try-catch 兜异常，有人让异常往上抛；有人用 Result 模式，有人用异常码。AI 让个人效率分化，也让团队一致性崩坏。
解法不是"少用 AI"，是把个人习惯变成团队约定——写成 AI 读得懂、且必须遵守的规则文件。这就是 CodeBuddy 的规则体系。
一、两级规则 + 一个轻量入口
CodeBuddy 的规则分两层，职责清晰：
项目级规则——.codebuddy/rules/ 目录下的规则文件，随代码库进版本控制，团队共享、统一生效。写"这个项目必须怎样"。
用户级规则——~/.codebuddy/rules/，只在你本机生效。写"我个人偏好怎样"（比如你习惯的快捷键提示、个人常用的代码片段风格）。
轻量入口——项目根目录的 CODEBUDDY.md，打开项目时自动加载，兼容 AGENTS.md。适合放最核心的项目说明与约定，不用写一大堆规则文件。
三者关系一句话：CODEBUDDY.md 是门牌，项目级规则是制度，用户级规则是个人习惯。制度优先于习惯，门牌让 AI 一进门就知道这是谁家。
Day 28 我们已经给星辰 ERP 写过一份 CODEBUDDY.md 的初始版本。今天把它扩展成一套完整体系——但先讲清楚规则的三种生效方式，否则写了一堆没人用。
二、三种生效方式：不是所有规则都该"始终应用"
| 生效方式 | 适合放什么 | 例子 |
|---|---|---|
| 始终应用 | 全项目、全场景都要守的硬约定 | 命名规范、注释语言、异常处理风格、金额精度红线 |
| 智能体按需加载 | 只在特定任务里才相关的规则 | "写单测的规范"只在测试任务里加载；"数据库迁移规范"只在改库时加载 |
| 手动 @ 引用 | 备查型、低频使用的规范 | 发布流程、接口错误码表、运维红线——需要时手动带进对话 |
这里有个常见误区：把所有规则都设成"始终应用"。结果 AI 每次对话都背着一本 500 页的规范手册，上下文被挤满，反而记不住最关键的几条。始终应用的规则要少而硬，按需加载的规则要多而全——这是规则体系设计的第一原则。
三、/rules 一键生成初稿，再迭代
从零写规则文件很枯燥，而且容易漏。让 AI 自己总结——用 /rules 扫一遍现有代码库，把已经存在的习惯提炼成规则：
规则初稿生成 Prompt
用 /rules 扫描本项目的代码风格，生成 .codebuddy/rules/ 下的规则初稿：
1. 从现有代码中提炼约定，不要凭空发明
2. 按"始终应用 / 按需加载 / 手动引用"三类分组，说明每条为什么归到这一类
3. 重点覆盖：命名规范、注释语言、异常与错误码风格、 分层与目录约定、日志规范、金额与时间处理红线
4. 每条规则给出正例和反例各一个
5. 输出文件清单与内容，等我确认后再写入第 1 条和第 4 条是关键。规则必须从现存代码里提炼出来，还得配正反例——否则规则是"应该怎样"的理想，代码是"实际怎样"的现实，AI 夹在中间无所适从。有正反例，它才知道边界在哪。
迭代节奏建议：第一版别求全，
先写十条最痛的
（最常被 review 打回的问题）。每两周复盘一次 AI 生成的代码哪里不符合团队习惯，把那一条补进规则——规则库是活的，跟着事故和 review 意见一起长大。四、规则里到底写什么：一份可抄的清单
按团队的痛感排序，这六类最值得先写：
# .codebuddy/rules/naming.md （示意，具体字段以官方文档为准）
## 命名
- 类名 PascalCase，方法名 PascalCase，局部变量 camelCase
- 布尔变量以 Is/Can/Has 开头：isConfirmed、canConfirm
- 反例：flag、tmp、data1（禁止无意义命名）
## 注释语言
- 公共 API 必须写中文 XML 文档注释，含 param 与 returns
- 行内注释只在"为什么这么做"时写，不写"做了什么"
## 异常与错误码
- 业务异常统一抛 BizException(code, message)，禁止直接 throw new Exception
- 错误码必须引用常量类 ErrorCodes，禁止硬编码 "RCPT-1001"
- 禁止 catch 后不处理（空 catch）
## 金额与时间
- 金额一律 decimal 或 decimal128，禁止 double / float
- 时间一律使用 IClock 注入，禁止方法内直接 DateTime.Now最后两条是星辰 ERP 的事故换来的红线（金额精度出过问题、时间直连导致测试依赖运行日期）——好的规则库都带着伤疤。这也解释了为什么规则必须由团队自己迭代，而不是照抄别人的模板。
五、AI 生成代码的 Review 流程怎么改
有了统一规则，Review 的活也变了。核心变化是：AI 擅长的部分不用人盯了，人盯 AI 的弱项。
| 检查项 | 谁主力 | 说明 |
|---|---|---|
| 命名、格式、注释、日志 | 规则 + AI | 写进规则文件的机械项，交给 /cr 与智能评审扫 |
| 业务规则正确性 | 人（必须） | AI 不知道这个折扣是老板特批的 |
| 架构与分层 | 人（必须） | 是否越层调用、是否引入循环依赖，需要全局视角 |
| 安全性（越权、注入、密钥） | AI 一筛 + 人确认 | @problems 与评审能扫出模式化问题，判断仍要人 |
| 测试是否覆盖关键分支 | 人（看覆盖率） | Day 32 已讲：AI 管覆盖率，人管正确性 |
还有个低成本高收益的动作：提交信息里标注"AI 生成"。
AI 生成代码的提交信息模板
feat(receipt):
收货单 Excel 导入（AI 辅助生成）
- 生成方式：Craft 智能体生成骨架，人工补充租户校验
- 已人工确认：错误码映射、金额精度、事务边界
- 重点 review：并发导入的幂等处理（第 87-120 行）这不是"甩锅标记"，是给 reviewer 指路——他一看就知道哪些段落值得多看两眼。实测比"什么都不说"的提交，review 效率高一截。
六、团队共享：让经验跟人走，而不是跟人走丢
AI 时代的团队资产，除了代码本身，还多了三样东西：
- 规则库：项目级规则进 Git，新人 clone 下来就自带团队约定
- 自定义斜杠指令：把高频操作固化成团队专用指令——比如"按团队模板生成接口文档"，谁用都一样
- 业务上下文文档：把架构说明、术语表、错误码表、外部系统对接约定整理成 AI 可读的文件（AI 帮新人理解代码库，靠的就是这些）
第三条和第二阶段完全接上了——Day 15-23 那九类文档、Day 24 的模板库，不只是给人看的交付物，也是喂给 AI 的项目知识。同一份文档，对人是验收依据，对 AI 是上下文。这是"文档链"在第三阶段的第二次兑现。
七、质量度量与新成员培训
AI 代码引入团队之后，建议盯两个指标，但先观察，别急着考核：
- 缺陷率：按来源拆分——AI 生成后人工改过的、与未经修改直接提交的，分别统计线上缺陷密度。目的不是排名，是找出哪类任务 AI 不可靠
- 返工率：AI 生成的代码在 review 被打回的比例；持续偏高说明规则文件没写清，是补规则的信号
红线一条：不要用"AI 使用率""AI 采纳行数"考核个人。这两个指标一考核，采纳率会立刻虚高——大家开始往代码里塞 AI 生成的废话注释。指标要用来改进工具与规则，不用来评价人。
新成员培训则是最容易被低估的收益点。新人第一周最痛的不是不会写代码，是看不懂这个项目。让 AI 读着 CODEBUDDY.md 和业务上下文文档，带他从"这个模块负责什么"问到"为什么这里要加分布式锁"——相当于给每个新人配了一个读过全部文档的带教老师，而且它不会不耐烦。
八、模板与检查清单
规则体系建设四步：
① 立门牌：根目录写 CODEBUDDY.md——项目是什么、技术栈、最硬的几条红线
② 出初稿：/rules 扫代码库提炼约定，按"始终应用/按需加载/手动引用"分组，配正反例
③ 划边界：始终应用的规则要少而硬；按需加载的多而全
④ 常迭代：review 打回一次，补一条规则；每两周复盘一次
团队协作检查清单：
□ 项目级规则已进 Git，新人 clone 即生效
□ CODEBUDDY.md 有项目说明 + 最硬红线（兼容 AGENTS.md）
□ 始终应用的规则条数控制在个位数，其余按需加载
□ 高频操作已固化成团队共享的斜杠指令
□ 业务上下文文档（架构/术语/错误码）已整理为 AI 可读文件
□ 提交信息标注"AI 生成"并指出需重点 review 的段落
□ 缺陷率/返工率只用于改进规则，不用于考核个人
□ 新人上手路径 = 文档 + AI 带读，而非口口相传
明天 Day 35：《AI 辅助代码审查自动化》——/cr 与智能评审怎么接进 PR 流程，审查维度怎么配，误报怎么收。