cfdaily
7.5 KiB
name, description
| name | description |
|---|---|
| code-review-quality | 代码评审质量纪律：评审闭环必须包含最终代码确认、枚举一致性检查、 设计-代码三层对照、评审者自我纠正。在发评审、收评审结果、做评审时触发。 |
代码评审质量
来源：从三国团队（庞统/司马懿/诸葛亮）~2GB 对话历史中蒸馏 卡片数：6（合并自批次1卡片5/12 + 批次2卡片1/2/3/5）
适用场景
- 发出代码评审请求时
- 收到评审结果需要处理时
- 自己作为评审者审查他人代码时
- 多步骤开发中方案评审 → 实现的闭环确认时
经验清单
1. 评审闭环必须包含最终代码确认（severity: high）
场景：多步骤开发中，方案评审通过后，实现阶段可能有微调。评审者只确认了方案而没看最终代码，Bug 被遗漏。
正确做法：
- 一键三连 = 改文档 → 改代码 → 司马懿确认最终代码片段
- 每个方案落地后，必须把最终代码（不是方案描述）发给评审者确认
- 司马懿在评审中多次引用代码行号做交叉验证，这种精度只有看最终代码才能做到
⚠️ 常见错误：
- 实现后只说"已采纳建议"，没发最终代码让评审者确认
- "已采纳" ≠ "已验证"——采纳后的代码可能引入新问题
关键细节：
- 庞统在 M2 阶段让司马懿 review 了方案但没发最终代码，用户发现后指出：[pangtong/experience]
"一键三连最终肯定是以司马懿 review 完你的最终成果物收尾的"
- 司马懿多次在代码评审中发现方案评审没暴露的 Bug（如
_do_retry续杯失效） - 续杯评审中，司马懿看到最终代码才发现
on_complete=None导致幻觉门控丢失
来源：批次2卡片1（评审闭环，freq=5+）
2. 状态机枚举值一致性是高频 Bug 根源（severity: high）
场景：系统有多处引用任务/节点状态值，枚举定义与实际使用不一致会导致静默失败。
正确做法：
- 状态枚举集中定义，所有引用点从枚举取值，硬编码字符串零容忍
- 状态转换函数只保留一个入口（如
_transition_status），禁止分散在多个模块 - 评审时重点检查：新代码中的状态值是否与枚举定义一致
⚠️ 常见错误：
- SQL 查询用
'executing'但实际枚举值是'working'，导致重启恢复遗漏 [pangtong/simayi-review] failed→pending转换不清assignee，与另一路径行为不一致max_per_agent=2vs 设计文档的1，配置与设计不一致
关键细节：
- 司马懿在 counter v2.1 评审中发现配置值与设计文档不匹配
- auto-sync 可能静默修改配置文件，需要与设计文档对照
- P0-2 状态不一致导致任务永久卡住，P0-1 导致重启恢复失败
来源：批次2卡片2（枚举一致性，freq=3+）
3. 评审者自我纠正是高质量评审的标志（severity: high）
场景：评审者在审查代码时可能做出错误判断。高质量的处理不是掩盖，而是主动承认并修正。
正确做法：
- 庞统发现两处自己之前的判断有误，主动发邮件给司马懿修正：
"修正 1: 问题4 recent_compact 不是死代码，是设计实现遗漏" [pangtong/mail]
- 司马懿回复："你说得对，我判断错了" [simayi/mail]
- 修正邮件明确标注"修正"而非静默修改，保留审计轨迹
⚠️ 常见错误：
- 不主动修正，错误判断被当作已确认结论传播
- 后续实现基于错误假设，导致更严重问题
关键细节：
- 评审者翻回设计文档交叉验证，是发现误判的有效手段
- 庞统和司马懿在同一次评审中都做了自我纠正——交叉验证机制在工作
- 评审者不是全知的，承认错误比坚持错误更有价值
来源：批次2卡片3（自我纠正，freq=3）
4. 设计文档-代码一致性审查不可省（severity: high）
场景：迭代开发中设计文档更新不及时，或代码实现偏离设计。需要 PRD→设计→代码的三层一致性审查。
正确做法：
- 每次代码评审前，先对设计文档逐条检查实现覆盖度
- 设计文档用明确编号（§B1/B2/B3）便于逐条追踪
- 安排"背靠背一致性审查"：PRD→设计→代码全覆盖审计
- 司马懿的核心职责就是做这种三层对照
⚠️ 常见错误：
- 设计文档 §B2（compact 进行中继续等）在代码中完全遗漏
- 司马懿初评时也未发现，直到庞统重新读设计文档才暴露 [pangtong/mail]
"代码只实现了 B1/B3/B4，B2 遗漏了。recent_compact 是 B2 实现的数据基础"
关键细节：
- 庞统专门发了 #311 邮件请求"PRD→设计→代码三层一致性审查"
- 司马懿在 counter 生命周期评审中发现设计说 crash 3 次标 failed，但代码只 release counter 无计数
- 三层审查的顺序：先 PRD→设计（需求是否覆盖），再设计→代码（实现是否忠实）
来源：批次2卡片4（设计-代码一致性，freq=4+）
5. 要求深度评审而非最小改动（severity: medium）
场景：将问题发给评审者时，评审标准应该是从需求和设计角度出发，而不是做最小改动。
正确做法：
- 评审时明确要求从需求和设计角度出发
- 不接受以"延后到后续版本"为由的需求降级
- 评审要回答"这个方案是否满足原始需求"
- 用户说"全部做"时，不接受延后建议
⚠️ 常见错误：
- 只要求评审者做"最小改动"或接受"需求降级"的建议
- 采纳评审者的"延后"建议，一步步推进
- 用户说"不要一步一步来"意味着要一次到位 [frag_2087]
关键细节：
- "需求降级"是 agent 常见的偷懒方式——把困难的需求推到下个版本
- "你知道的"暗示用户偏好一步到位，这是长期偏好
- 评审意见分为采纳和拒绝，延后=拒绝
来源：批次1卡片5（评审标准，freq=1）+ 批次1卡片12（不延后，freq=1）+ 批次2卡片5（闭环标准，freq=2）合并
6. 方案确认的完整闭环标准（severity: medium）
场景：多方案并行开发时，哪些方案算"完成"容易模糊。
正确做法： 一键三连收尾标准（用户明确定义）：
- 改文档（设计/方案）
- 改代码（实现）
- 司马懿 review 并确认最终代码片段
每步完成都要有明确证据（邮件编号、代码片段引用）。
⚠️ 常见错误：
- 只跟踪"方案评审"状态，没跟踪"最终代码确认"状态
- 未闭环的方案被标记为"已完成"
关键细节：
- 状态跟踪表要包含三列：方案评审 / 最终代码确认 / 状态
- 司马懿的确认必须是具体的（"代码片段与实际改动一致"），不是笼统的"通过"
来源：批次2卡片5（闭环标准，freq=2）
检查清单（快速参考）
- 评审请求是否包含最终代码（不是方案描述）？
- 状态/枚举值是否全部从集中定义取用？有无硬编码字符串？
- 状态转换是否只有一个入口函数？
- 设计文档是否逐条检查了实现覆盖度？有无遗漏的 § 节？
- 发现评审误判时，是否主动发出修正（而非静默修改）？
- 是否有不合理的"延后到下一版本"建议？用户偏好一步到位
- 一键三连是否闭环：文档→代码→最终代码确认？
- 评审结果处理完是否把修改后的代码再发评审者确认？