代码审查工作流：建立有效的审查习惯
学完你能做什么
- 在每个开发阶段主动请求代码审查
- 正确处理审查反馈，区分 Critical、Important、Minor 优先级
- 接收反馈时进行技术性验证，避免表演性同意
- 建立早期、频繁的审查习惯
你现在的困境
AI 代理在开发时容易陷入这些问题：
- 完成任务后直接进入下一步，没有审查环节
- 收到反馈后盲目实现，不验证技术正确性
- 审查流于形式，无法发现实际问题
- 认为"代码很简单"就跳过审查
这些问题会导致：
- 小问题累积成大问题
- 低质量代码进入主分支
- 技术债不断积累
- 后期维护成本高昂
核心思路
Review early, review often —— 早期审查，经常审查。
代码审查不是开发完成后的"过场"，而是开发流程中的核心环节。通过持续审查，你可以：
- 在问题变复杂前发现它们
- 保持代码质量基线
- 学习更好的编码实践
- 减少后期返工
什么时候用这一招
必须审查：
- 每个子代理任务完成后
- 完成主要功能后
- 合并到 main 分支前
建议审查：
- 卡住时（需要新视角）
- 重构前（建立基线）
- 修复复杂 bug 后
禁止跳过审查
即使代码看起来很简单，也不能跳过审查。"简单"代码往往藏着不易发现的 bug 或设计问题。
🎒 开始前的准备
确保已：
- 完成 子代理驱动开发 教程
- 熟悉基础 Git 操作（获取 SHA、查看提交）
- 已在当前分支完成至少一个开发任务
跟我做：请求代码审查
第 1 步：获取提交范围
为什么 需要告诉审查者从哪个提交开始看，到哪个提交结束。
bash
# 获取上一个提交的 SHA
BASE_SHA=$(git rev-parse HEAD~1)
# 或者对比 origin/main
BASE_SHA=$(git rev-parse origin/main)
# 获取当前提交的 SHA
HEAD_SHA=$(git rev-parse HEAD)你应该看到：
BASE_SHA变量包含起始提交的完整 SHAHEAD_SHA变量包含结束提交的完整 SHA
第 2 步：调用 code-reviewer 子代理
为什么 code-reviewer 是专门的审查代理，会系统性检查代码质量、架构和测试覆盖率。
bash
# 使用 Task tool 调用 code-reviewer 子代理
@code-reviewer
# 填写模板中的占位符：
- WHAT_WAS_IMPLEMENTED: 刚刚实现了什么功能
- PLAN_OR_REQUIREMENTS: 应该实现什么（引用计划文档或需求）
- BASE_SHA: 起始提交 SHA
- HEAD_SHA: 结束提交 SHA
- DESCRIPTION: 简要描述改动code-reviewer 子代理
code-reviewer 子代理定义在 agents/code-reviewer.md，它会从以下维度审查代码：
- 计划一致性
- 代码质量
- 架构设计
- 文档规范
- 安全性和性能
你应该看到：
- 子代理返回结构化的审查报告
- 报告包含：Strengths（优点）、Issues（问题）、Assessment（评估）
第 3 步：处理审查反馈
为什么 反馈分级帮助你确定优先级，合理分配修复时间。
| 优先级 | 含义 | 处理方式 |
|---|---|---|
| Critical | 必须修复 | 立即修复，否则无法继续 |
| Important | 应该修复 | 在继续下一步前修复 |
| Minor | 建议优化 | 记录下来，稍后处理 |
bash
# 示例：处理 feedback
# 1. 修复 Critical 问题
echo "Fixing Critical issue: missing error handling"
# 2. 修复 Important 问题
echo "Fixing Important issue: add progress indicators"
# 3. 记录 Minor 问题
echo "Minor issue: magic number (100) - defer to later"
# 4. 如果审查者判断错误，用技术理由推回
echo "Reviewer suggested removing legacy code, but we need it for backward compat. Keeping with note."你应该看到：
- Critical 和 Important 问题已修复
- Minor 问题已记录
- 有技术支撑的推回理由（如有）
检查点 ✅
- [ ] 已获取
BASE_SHA和HEAD_SHA - [ ] 已调用 code-reviewer 子代理
- [ ] 已修复所有 Critical 问题
- [ ] 已修复或计划修复 Important 问题
- [ ] Minor 问题已记录
接收反馈的技术原则
核心原则：Verify before implementing, ask before assuming.
响应模式
当收到代码审查反馈时：
1. READ: 完整阅读反馈，不要立即反应
2. UNDERSTAND: 用自己的话重述需求（或提问）
3. VERIFY: 对照代码库实际情况验证
4. EVALUATE: 技术上是否适合当前代码库？
5. RESPOND: 技术性确认或推回理由
6. IMPLEMENT: 逐项实现，每项都测试禁止的响应方式
| ❌ 禁止 | ✅ 正确 |
|---|---|
| "You're absolutely right!"（违反 CLAUDE.md） | "Checking codebase..." |
| "Great point!" / "Excellent feedback!"（表演性） | "I understand this to mean..." |
| "Let me implement that now"（验证前） | "Before implementing, let me verify..." |
处理不清晰的反馈
遇到不清晰的反馈
如果审查反馈中有任何项目不清晰，停止，不要实现任何内容，先请求澄清。
为什么：反馈项目可能相互关联。部分理解 = 错误实现。
示例：
你的搭档说："Fix items 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 检查
当审查者建议"正确实现"某个功能时：
bash
# 检查代码库中是否有实际使用
grep -r "functionName" .
# 如果没有使用
echo "这个端点没有被调用。删除它（YAGNI）？"
# 如果有使用
echo "好的，正确实现这个功能。"你的搭档的规则："你和审查者都向我汇报。如果我们不需要这个功能，就不要添加它。"
实现顺序
处理多项目反馈时：
- 先澄清任何不清晰的项目
- 然后按以下顺序实现：
- 阻塞性问题（破坏性、安全性）
- 简单修复（拼写、导入）
- 复杂修复（重构、逻辑）
- 逐项测试每个修复
- 验证没有回归
什么时候应该推回
推回场景：
- 建议破坏现有功能
- 审查者缺乏完整上下文
- 违反 YAGNI（未使用的功能）
- 对当前技术栈技术不正确
- 存在遗留/兼容性原因
- 与你的搭档的架构决策冲突
如何推回：
- 使用技术理由，而不是防御性态度
- 提出具体问题
- 引用可工作的测试/代码
- 如果涉及架构问题，让你的搭档参与
信号：如果你对公开推回感到不适，说："Strange things are afoot at the Circle K"
确认正确的反馈
当反馈是正确的时候：
| ✅ 正确 | ❌ 错误 |
|---|---|
| "Fixed. [简短描述改变的内容]" | "You're absolutely right!" |
| "Good catch - [具体问题]. 在 [位置] 修复了。" | "Great point!" |
| [直接修复并在代码中展示] | "Thanks for catching that!" |
| "Thanks for [任何内容]" | |
| 任何感谢表达 |
为什么不感谢：行动胜于言辞。直接修复它。代码本身表明你听到了反馈。
如果你发现自己想写"Thanks"：删除它。改写修复说明。
优雅地纠正你的推回
如果你推回了但结果是错的：
| ✅ 正确 | ❌ 错误 |
|---|---|
| "你是对的——我检查了 [X]，它确实 [Y]。正在实现。" | 长篇道歉 |
| "验证了这一点，你是正确的。我最初的理解是错的，因为 [原因]。正在修复。" | 为为什么推回而辩护 |
| 过度解释 |
如实地陈述纠正并继续。
GitHub 线程回复
在 GitHub 上回复内联审查评论时，在评论线程中回复（gh api repos/{owner}/{repo}/pulls/{pr}/comments/{id}/replies），而不是作为顶级 PR 评论。
常见错误
| 错误 | 修正 |
|---|---|
| 表演性同意 | 陈述要求或直接行动 |
| 盲目实现 | 先对照代码库验证 |
| 批量不测试 | 逐项实现，每项测试 |
| 假设审查者是对的 | 检查是否破坏东西 |
| 避免推回 | 技术正确性 > 舒适度 |
| 部分实现 | 先澄清所有项目 |
| 无法验证，但继续进行 | 说明限制，询问方向 |
真实示例
表演性同意（不好）：
审查者："Remove legacy code"
❌ "You're absolutely right! Let me remove that..."技术验证（好）：
审查者："Remove legacy code"
✅ "Checking... build target is 10.15+, this API needs 13+. Need legacy for backward compat. Current impl has wrong bundle ID - fix it or drop pre-13 support?"YAGNI（好）：
审查者："Implement proper metrics tracking with database, date filters, CSV export"
✅ "Grepped codebase - nothing calls this endpoint. Remove it (YAGNI)? Or is there usage I'm missing?"不清楚的项目（好）：
你的搭档："Fix items 1-6"
你理解 1、2、3、6，不清楚 4、5。
✅ "Understand 1,2,3,6. Need clarification on 4 and 5 before implementing."底线
外部反馈 = 要评估的建议，不是要遵循的命令。
验证。提问。然后实现。
禁止表演性同意。始终技术严谨。
与其他工作流集成
子代理驱动开发
- 每个任务后审查
- 在问题复合之前发现它们
- 在继续下一个任务之前修复
执行计划
- **每批任务后（3 个任务）**审查
- 获取反馈，应用反馈，继续
临时开发
- 合并前审查
- 卡住时审查
踩坑提醒
| 错误 | 后果 | 预防方法 |
|---|---|---|
| 认为"代码很简单"就跳过审查 | 隐藏的 bug 进入主分支 | 即使是 10 行代码也要审查 |
| 盲目实现审查建议 | 引入新问题或破坏现有功能 | 实现前对照代码库验证 |
| 逐项修复但不测试 | 回归 bug | 每项修复后立即测试 |
| 对错误的建议表演性同意 | 低质量代码累积 | 技术正确性 > 社交舒适度 |
| 部分理解就实现 | 错误实现 | 不清楚的项目先请求澄清 |
本课小结
代码审查工作流的核心是：
- Review early, review often —— 早期、频繁审查
- 技术验证优先 —— Verify before implementing
- 分级处理反馈 —— Critical/Important/Minor
- 禁止表演性同意 —— 技术正确性 > 社交舒适度
通过建立有效的审查习惯，你可以：
- 在问题变复杂前发现它们
- 保持代码质量基线
- 学习更好的编码实践
- 减少后期返工成本
下一课预告
下一课我们学习 Git 工作树隔离。
你会学到：
- 使用 Git 工作树创建隔离的开发环境
- 在多个功能之间同时工作而不干扰
- 保持主分支的清洁和稳定
附录：源码参考
点击展开查看源码位置
更新时间：2026-02-01
| 功能 | 文件路径 | 行号 |
|---|---|---|
| 请求代码审查技能 | skills/requesting-code-review/SKILL.md | 1-106 |
| 接收代码审查技能 | skills/receiving-code-review/SKILL.md | 1-214 |
| code-reviewer 代理定义 | agents/code-reviewer.md | 1-49 |
关键原则：
- Review early, review often：早期、频繁审查（
requesting-code-review/SKILL.md:10） - Verify before implementing：实现前验证（
receiving-code-review/SKILL.md:12） - Technical correctness > social comfort：技术正确性 > 社交舒适度（
receiving-code-review/SKILL.md:12）
反馈分级（agents/code-reviewer.md:37）：
- Critical（必须修复）
- Important（应该修复）
- Suggestions（建议优化）
禁止的响应（receiving-code-review/SKILL.md:29-32）：
- "You're absolutely right!"
- "Great point!"
- "Let me implement that now"