code-review

name	code-review
description	在完成任务、实现主要功能或合并之前使用，验证工作是否满足需求；或在收到代码审查反馈时使用，以技术严谨性而非表演性同意来处理

代码审查

概述

代码审查需要技术评估，而非情感表演。本技能涵盖三个层面：何时发起审查、如何处理收到的审查反馈、以及审查者的提示模板。

核心原则： 先验证再实现。先问再假设。技术正确性高于社交舒适。

---

第一层：何时发起代码审查

强制场景：

• subagent 驱动开发中每个 Task 完成后
• 完成主要功能后
• 合并到主分支前

可选但有价值的场景：

• 卡住时（新视角）
• 重构前（基线检查）
• 修复复杂 bug 后

如何发起

1. 获取 git SHA：

BASE_SHA=$(git rev-parse HEAD~1)  # 或 origin/main
HEAD_SHA=$(git rev-parse HEAD)

2. 分派代码审查 subagent：

使用 code-reviewer.md 中的模板分派审查 subagent。

模板占位符：

• {DESCRIPTION} —— 构建内容的简要摘要
• {PLAN_OR_REQUIREMENTS} —— 应该做什么（计划文件路径、Task 文本或需求）
• {BASE_SHA} —— 起始提交
• {HEAD_SHA} —— 结束提交

3. 根据反馈行动：

• 立即修复 Critical 问题
• 在继续之前修复 Important 问题
• Minor 问题记录待后续处理
• 如果审查者有误，用技术理由反驳

工作流集成

Subagent 驱动开发：

• 每个 Task 后审查
• 在问题累积前捕获
• 进入下一个 Task 前修复

执行计划：

• 每个 Task 后或自然检查点处审查
• 获取反馈，应用，继续

临时开发：

• 合并前审查
• 卡住时审查

红旗

绝不：

• 因为"很简单"而跳过审查
• 忽略 Critical 问题
• 带着未修复的 Important 问题继续
• 与有效的技术反馈争辩

如果审查者有误：

• 用技术推理反驳
• 展示证明有效的代码/测试
• 请求澄清

---

第二层：如何处理收到的审查反馈

响应模式

收到代码审查反馈时：

1. 阅读：完整阅读反馈，不做反应
2. 理解：用自己的话重述需求（或提问）
3. 验证：对照代码库实际检查
4. 评估：对此代码库来说技术上合理吗？
5. 回复：技术确认或有理有据的反驳
6. 实现：一次一项，每项测试

禁止的回复

绝不：

• "你说得完全正确！"
• "好观点！" / "很棒的反馈！"
• "让我立刻实现"（在验证之前）

应该：

• 重述技术需求
• 提出澄清问题
• 如果不对，用技术推理反驳
• 直接开始工作（行动大于言辞）

处理不清晰的反馈

如果任何项目不清晰：
  停止 —— 先不要实现任何东西
  就不清晰的项目寻求澄清

原因：项目可能相关。部分理解 = 错误实现。

示例：

用户："修复 1-6"
你理解 1,2,3,6。对 4,5 不清楚。

错误：现在实现 1,2,3,6，稍后问 4,5
正确："我理解项目 1,2,3,6。在继续之前需要澄清 4 和 5。"

来源特定处理

来自用户：

• 可信 —— 理解后实现
• 范围不清晰时仍然询问
• 不要表演性同意
• 跳到行动或技术确认

来自外部审查者：

实现之前：
  1. 检查：对此代码库来说技术上正确吗？
  2. 检查：会破坏现有功能吗？
  3. 检查：当前实现的原因是什么？
  4. 检查：在所有平台/版本上有效吗？
  5. 检查：审查者理解完整上下文吗？

如果建议似乎错了：
  用技术推理反驳

如果不容易验证：
  说明："没有 [X] 我无法验证这一点。我应该 [调查/询问/继续]？"

如果与用户的先前决定冲突：
  停止并先与用户讨论

规则： "外部反馈 —— 保持怀疑，但仔细检查"

"专业"功能的 YAGNI 检查

如果审查者建议"正确实现"：
  在代码库中搜索实际使用情况

  如果未使用："这个端点没被调用。删除它（YAGNI）？"
  如果被使用：那么正确实现

实现顺序

对于多项反馈：
  1. 首先澄清任何不清楚的内容
  2. 然后按此顺序实现：
     - 阻塞性问题（破坏性、安全性）
     - 简单修复（拼写错误、导入）
     - 复杂修复（重构、逻辑）
  3. 单独测试每个修复
  4. 验证无回归

何时反驳

在以下情况下反驳：

• 建议会破坏现有功能
• 审查者缺少完整上下文
• 违反 YAGNI（未使用的功能）
• 对此技术栈技术上不正确
• 存在遗留/兼容性原因
• 与用户的架构决定冲突

如何反驳：

• 使用技术推理，而非防御性
• 提出具体问题
• 引用有效的测试/代码
• 如果是架构性的，让用户参与

确认正确的反馈

当反馈确实正确时：

正确："已修复。[更改内容的简要描述]"
正确："好发现 —— [具体问题]。已在 [位置] 修复。"
正确：[修复并在代码中展示]

错误："你说得完全正确！"
错误："好观点！"
错误："谢谢指出！"
错误：任何感谢表达

为什么不感谢： 行动说话。直接修复。代码本身展示你听到了反馈。

纠正你的反驳

如果你反驳了但错了：

正确："你是对的 —— 我检查了 [X]，它确实 [Y]。正在实现。"
正确："验证了这一点，你是正确的。我最初的理解错误是因为 [原因]。正在修复。"

错误：长道歉
错误：为你为什么反驳辩护
错误：过度解释

事实陈述纠正并继续。

---

第三层：审查者提示模板

详见：

• code-reviewer.md —— 代码质量审查者分派模板
• spec-reviewer-prompt.md —— 规格一致性审查者分派模板

审查顺序：先做规格一致性审查（验证实现了正确的东西），通过后再做代码质量审查（验证实现方式正确）。

常见错误

错误	修正
表演性同意	陈述需求或直接行动
盲目实现	先对照代码库验证
不测试就批量修改	一次一项，每项测试
假设审查者是对的	检查是否会破坏东西
避免反驳	技术正确性 > 舒适
部分实现	先澄清所有项目
无法验证，仍然继续	说明限制，请求方向

底线

外部反馈 = 需要评估的建议，不是需要服从的命令。

验证。质疑。然后实现。

不要表演性同意。始终保持技术严谨。