同一个团队，五个人用同一个工具，产出质量的差距能有十倍。差距不在工具，在身上那套没写下来的习惯：有人习惯一次让模型改二十个文件，有人只改一个函数；有人把验收条件说清楚，有人只说"优化一下"。
Playbook 的作用就是把这套习惯从个人身上搬到仓库里，让它可评审、可执行、可迭代。
1. 要固化的五件事
只固化五件，多了没人看。
| 序号 | 事项 | 落成什么 | 谁维护 |
|---|---|---|---|
| 1 | 仓库约定 | 仓库根目录的规则文件 | 技术负责人 |
| 2 | 任务粒度 | 一条"单次改动上限"的约定 | 团队共识 |
| 3 | 验收标准 | 每个任务写明的可执行断言 | 任务发起人 |
| 4 | 评审关注点 | 一张固定的评审清单 | 评审人 |
| 5 | 禁区清单 | 规则文件里的禁止项 | 技术负责人 |
五件事的共同点：都能写成句子，都能被引用，都不依赖某个人的记忆。
第 3 项最容易漏。没有验收标准的任务，评审时争的就不是"对不对"而是"你觉得行不行"。
2. 任务粒度：一次一个可验收的小目标
经验法则一句话：一次改动的 diff，评审人能在十分钟内看完并给出结论。
拆到能验收的粒度，参考这几条：
| 判断 | 该做的 | 不该做的 |
|---|---|---|
| 涉及文件数 | 3–8 个文件，同属一个模块 | 跨五个模块"顺手一起改" |
| 变更类型 | 只做一类（重命名、修类型、加测试） | 重构 + 改功能 + 升依赖混在一起 |
| 验收方式 | 一条命令能判定 | "看起来好多了" |
| 出错时 | 能整段回滚 | 与上一轮改动纠缠 |
粒度太细也有成本：每个任务都要重建上下文，模型反复读同一批文件。合适的平衡点是"一个可独立回滚的变更"。
坏的拆分：把用户模块重构一下，顺便修掉 lint，再补点测试
好的拆分：1) 修 user/ 下的类型错误，不动逻辑
2) 为 user/service 补三个边界用例
3) 把 user/dto 的字段命名统一（纯重命名）
三条各自能跑、各自能回滚、各自能评审。
3. 提示的四段结构
固定四段：背景、目标、约束、验收。缺任何一段，模型都会用自己的默认值填补。
【背景】
仓库 PATH，Node + pnpm，测试命令 pnpm test，类型检查 pnpm tsc --noEmit。
相关模块：src/user/。已知约束：Node 版本见 .nvmrc。
【目标】
让 pnpm tsc --noEmit 在 src/user/ 下零错误，不改变运行时行为。
【约束】
- 只改 src/user/ 下的 .ts 文件
- 不改 export 出去的签名
- 不用 any、不用 @ts-ignore、不放宽 tsconfig
- 不升级依赖
【验收】
1. pnpm tsc --noEmit 退出码 0
2. pnpm test 全绿
3. git diff --stat 只涉及 src/user/
【失败处理】
同一文件修两次仍报错 → 停止该文件，记入 blocked.md，继续下一个。
| 段落 | 回答的问题 | 常见缺失后果 |
|---|---|---|
| 背景 | 环境是什么 | 命令全猜错，反复失败 |
| 目标 | 做到什么程度停 | 无限扩展，越改越多 |
| 约束 | 不许碰什么 | 用禁用手段"通过" |
| 验收 | 怎么算完成 | 无法终止，也无法评审 |
照着改就是模板：把 PATH、命令、目录换成自己的，其余结构别动。结构比措辞重要——四个人用同一结构、不同措辞，产出仍然可比。
4. 评审看什么
不看格式（格式化工具管这个），看四样：
| 关注点 | 具体看什么 | 危险信号 |
|---|---|---|
| 边界条件 | 空值、空数组、超长输入、并发 | 只有 happy path 的处理 |
| 错误路径 | 异常被捕获后做了什么 | catch {} 空块、吞掉错误 |
| 变更范围 | 是否只在约定目录 | 顺手改了无关文件 |
| 绕过痕迹 | 检查被禁用、断言被放宽 | eslint-disable、skip、any |
评审清单可以直接抄成模板：
- [ ] diff 范围符合任务约定
- [ ] 新增分支覆盖了空值/空集合/异常入参
- [ ] 错误路径有明确处理，没有空 catch
- [ ] 未出现 eslint-disable / ts-ignore / skip
- [ ] 新增逻辑有对应测试，且测试断言了行为而非实现
- [ ] 无与任务无关的格式化或重命名噪音
最后一条很实在：无关的格式化噪音会让真正的改动淹没在 diff 里，评审直接失效。
5. 度量三项：怎么知道 Playbook 有没有用
只量三项，且都能从现有流程里捞，不需要新工具。
| 指标 | 定义 | 数据来源 | 看趋势 |
|---|---|---|---|
| 返工率 | 因同一任务再次开单的比例 | 任务单/PR 的关联标记 | 上升说明提示或粒度有问题 |
| 评审意见类型分布 | 边界/错误路径/范围/风格 各占多少 | 评审评论打标签 | 风格类占比高 → 规则文件没落地 |
| 返工原因归类 | 需求没写清 / 约束漏了 / 模型能力 / 评审过严 | 返工单上勾选一项 | 前三类可改流程，第四类改标准 |
采集方式要轻，重了就没人填：
每次返工，在任务单上补一行：
rework_reason: spec_unclear | constraint_missing | model_limit | review_too_strict
三项指标的正确用法是看趋势不看绝对值。返工率 20% 是好是坏取决于基线；但它从 20% 涨到 35%，就一定要查。
6. 新人上手路径
不要一上来就让人"用 AI 重构模块"。分四步，每步都有明确的失败边界。
| 阶段 | 任务类型 | 权限 | 通过标准 |
|---|---|---|---|
| 1 | 只读分析：解释某模块、列出调用链 | 只读沙箱 | 结论能被老同事核对无误 |
| 2 | 写文档/注释/测试用例 | 可写但限目录 | 评审一次通过 |
| 3 | 单文件小改动（修类型、改命名） | 工作区写 | diff 范围零越界 |
| 4 | 跨文件改造 | 工作区写 + 评审 | 能自己写出验收条件 |
第一阶段最关键：只读任务能暴露这个人会不会提要求。要求写得含糊的人，在只读阶段就会拿到一堆没法核对的结论，这时候纠正成本最低。
第 4 阶段的门槛不是"会用工具"，而是"能写出可执行的验收条件"。写不出验收条件的人，不该被允许跑无人值守的批量改动。
7. 把踩坑沉淀成规则文件，而不是群聊记录
群聊里的结论三天后就沉底。规则文件的价值是能被工具读到、能被评审引用。
放两处，分工不同：
AGENTS.md # 仓库根目录：全局约定、禁区、验收口径
docs/ai-playbook.md # 细则：提示模板、评审清单、拆分示例
规则文件写什么、不写什么：
| 该写 | 不该写 |
|---|---|
| 构建/测试/检查的确切命令 | "注意代码质量" |
| 禁区：不许改的目录与文件 | 大段风格偏好 |
| 验收口径：什么算通过 | 具体某个人的经验 |
| 提交信息格式 | 已废弃的历史决策 |
一个能用的最小规则文件：
# 约定
## 命令
- 安装：pnpm i
- 测试：pnpm test
- 类型：pnpm tsc --noEmit
- Lint：pnpm lint
## 禁区
- 不改 pnpm-lock.yaml、tsconfig.json、CI 配置
- 不用 any / @ts-ignore / eslint-disable
- 不改测试断言来让测试通过
## 验收
一次改动必须同时满足：类型检查 0 错、测试全绿、diff 只在指定目录。
规则与真实评审标准必须一致。规则里写着"不许 any"，评审时却放过了，规则文件两周内就会变成装饰品。宁可规则少三条，也不能有一条不执行。
8. 排错：四种"写了但没用"
| 现象 | 原因 | 处理 |
|---|---|---|
| 规则文件存在，产出照旧 | 没人读，也没被工具加载 | 在任务模板里引用它；让工具每次先读 |
| 规则与评审不一致 | 评审靠个人偏好 | 评审清单直接从规则文件生成 |
| 效率反而下降 | 约束过多，模型反复自我否决 | 删掉不可执行的条款，只留能判定对错的 |
| 新人不按流程走 | 上手路径缺失，直接上手大改造 | 按第 6 节补阶段门槛 |
第三行值得展开：把"代码要优雅""命名要语义化"这类条款写进规则，模型会反复重写同一段代码试图"更优雅"，最后交出一个和原版没差别的版本，白烧一轮。规则只写能判定对错的东西。
9. 边界：Playbook 管不到的地方
| 需求 | 靠什么 |
|---|---|
| 需求是否该做 | 产品判断，不进 Playbook |
| 架构分层与选型 | 设计文档 + 评审，规则文件只约束落地 |
| 跨团队接口契约 | 契约文件 + 双方评审 |
| 线上故障的应急改动 | 应急流程优先，事后补规则 |
| 个人能力的成长 | 上手路径 + 复盘，不是条款 |
一句话：Playbook 固化的是"重复的判断"，不是"所有的判断"。 把它写成一部法典，团队会绕开它；写成三条能执行的约定，团队会用它。
10. 自测
- Playbook 要固化的五件事里，哪一件最容易被漏掉，漏了会怎样？
- 判断任务粒度是否合适的经验法则是什么？
- 提示四段结构中，"约束"段缺失会导致什么具体后果？
- 评审时"不看格式"看什么，列四项。
- 三项度量指标中，哪一项的上升最能说明提示写得不好？
- 为什么规则文件里不该写"代码要优雅"这类条款？