第六章：代码审查、反馈处理与分支收尾

6.1 为什么 AI 也需要代码审查

AI 生成代码速度快，但也容易在局部最优中遗漏问题：

• 满足了显性需求，但破坏了隐含约定。
• 测试覆盖了快乐路径，却遗漏安全和错误路径。
• 引入不必要抽象，违反 YAGNI。
• 没有遵守项目风格。
• 修改了不相关文件。

requesting-code-review 的目的就是在问题扩散前引入第二视角，尤其是在子 Agent 驱动开发中，每个任务完成后都应审查。

6.2 requesting-code-review 的核心原则

该 Skill 强调「早审查，勤审查」。必须审查的场景包括：

• 子 Agent 驱动开发中每个任务完成后。
• 完成重要功能后。
• 合并到 main 之前。

可选但有价值的场景包括：

• 调试卡住时。
• 大重构之前。
• 修复复杂 Bug 之后。

审查不是走形式，而是为审查者提供清晰上下文：实现了什么、预期是什么、要比较的 base/head SHA 是什么、关注哪些风险。

6.3 审查上下文应该包含什么

好的审查请求应包含：

• 实现摘要： 这次改动做了什么。
• 需求或计划来源： 设计文档、计划文档或用户需求。
• 变更范围： 主要文件和模块。
• 验证结果： 已运行哪些测试或构建。
• 对比范围： base commit 和 head commit。
• 关注点： 安全、性能、兼容性、可维护性等。

如果只说「帮我审查一下」，审查者可能缺少判断标准，容易泛泛而谈。

6.4 处理审查反馈的正确姿势

receiving-code-review 的核心原则是：先验证再实施，技术正确性优先于社交舒适度。

收到反馈后的流程：

1. 阅读。 完整读完反馈，不急于回复。
2. 理解。 用自己的话复述，必要时提问。
3. 验证。 对照当前代码库检查反馈是否成立。
4. 评估。 判断对当前项目是否技术上合理。
5. 回应。 技术性确认或有理有据反驳。
6. 实施。 一次一项，逐个测试。

特别注意：外部审查者的反馈是待评估建议，不是必须执行命令。用户或核心维护者的明确要求权重更高，但仍要澄清范围。

6.5 不明确反馈不要猜

如果反馈包含多项，其中有几项不理解，不要先实现理解的部分再回头问。正确做法是先澄清所有不明确项，因为这些项可能互相关联。

例如：

第 1、2、3 项我理解了。第 4 项中「统一错误模型」具体是指复用现有 ErrorKind，还是新增 API 响应结构？澄清后我再一起处理。

这比盲目猜测更高效，也能避免部分修改导致后续返工。

6.6 何时反驳审查意见

以下情况应技术性反驳或请求讨论：

• 建议会破坏现有功能。
• 审查者不了解完整上下文。
• 建议违反 YAGNI，当前没有调用方。
• 与项目技术栈不兼容。
• 存在兼容性或历史原因。
• 与用户已确认的设计决策冲突。

反驳时不要情绪化，应引用代码、测试、约束和事实：

我检查了当前调用链，这个接口仍被旧版客户端使用。直接删除会破坏 v1 API 兼容性。建议先标记 deprecated，并在下个主版本移除。

6.7 中文代码审查的叠加使用

在中文团队中，requesting-code-review 和 receiving-code-review 负责流程，chinese-code-review 负责表达方式。

推荐反馈分级：

• [必须修复] 安全漏洞、数据丢失、逻辑错误，不修不能合。
• [建议修改] 性能、可维护性、校验不足，可本次或下次修。
• [仅供参考] 命名、风格、替代方案，不强制。
• [问题] 不确定意图，需要作者解释。

这种分级既保留中文沟通的缓和语气，又不会让关键问题被客气话淹没。

6.8 finishing-a-development-branch 的收尾流程

当实现完成并准备集成时，使用 finishing-a-development-branch。它要求先验证测试，再提供 4 个选项：

1. 在本地合并回基础分支。
2. 推送并创建 Pull Request。
3. 保持分支现状，稍后处理。
4. 丢弃这项工作。

注意：在提供选项之前必须运行测试或项目验证命令。如果测试失败，不能继续合并或创建 PR。

6.9 分支收尾前的验证

收尾前至少确认：

• 工作区没有意外未提交文件。
• 相关测试和构建通过。
• 文档或示例已更新。
• 代码审查中的 Critical / Important 问题已处理。
• 如果使用 Worktree，知道当前工作树位置和基础分支。
• 如果创建 PR，PR 描述包含摘要和测试计划。

对于文档站点，本仓库这类 Jekyll 项目通常应运行站点构建命令；对于 Node 项目可能是 npm test、npm run build；对于 Go 项目可能是 go test ./...。

6.10 PR 描述建议

一个适合 superpowers-zh 工作流的 PR 描述可包含：

## 摘要

- 新增/修改了什么
- 为什么这样做
- 影响范围

## 验证

- [x] 运行单元测试
- [x] 运行构建
- [x] 完成代码审查

## 风险与回滚

- 主要风险
- 回滚方式

中文团队可以结合 chinese-git-workflow 中的 PR/MR 模板，补充需求链接、部署注意事项、截图录屏和影响范围。

6.11 常见反模式

只在最后审查

最后才审查会让问题叠加，修复成本高。更好的方式是每个独立任务完成后审查。

审查反馈全盘接受

外部建议要验证，尤其是会改变架构、删除兼容逻辑或新增复杂功能的建议。

为了面子放过问题

中文团队可以语气温和，但 [必须修复] 问题不能放过。

测试失败仍创建 PR

如果验证失败，应如实报告失败并修复，不能用「CI 上再看」代替本地验证。

丢弃分支不确认

finishing-a-development-branch 要求丢弃前精确确认，避免误删成果。

6.12 本章小结

代码审查和分支收尾让 AI 编程从「写完」走向「可合并」。requesting-code-review 提供审查入口，receiving-code-review 保证反馈处理严谨，chinese-code-review 让中文团队沟通更顺畅，finishing-a-development-branch 则把验证、PR 和清理纳入结构化流程。