code-review

代码审查

介绍规范的代码审查实践，强调技术严谨性、基于证据的论断，以及验证优先于表面功夫。

概述

代码审查需要三种不同的实践：

1. 接收反馈 - 以技术评估为重，而非表面认同
2. 请求审查 - 通过 code-reviewer 子 Agent 系统地进行审查
3. 验证关卡 - 在声称完成任何工作之前提供证据

每种实践都有特定的触发条件和流程，详见参考文件。

核心原则

始终遵循 YAGNI、KISS 和 DRY 原则。 诚实、直接、切中要点，并保持简洁。

技术正确性优先于社交上的舒适。 实施前先验证。有疑问先询问，不要想当然。提出论断前先提供证据。

何时使用此技能

接收反馈

在以下情况触发：

• 收到来自任何来源的代码审查意见
• 反馈看起来不清楚或在技术上值得质疑
• 有多个审查事项需要确定优先级
• 外部审查者缺少完整背景信息
• 建议与现有决策冲突

参考： references/code-review-reception.md

请求审查

在以下情况触发：

• 在子 Agent 驱动的开发中完成任务后（每项任务之后）
• 完成重要功能或重构
• 合并到 main 分支之前
• 陷入困境、需要新的视角时
• 修复复杂错误后

参考： references/requesting-code-review.md

验证关卡

在以下情况触发：

• 即将声称测试通过、构建成功或工作已完成
• 提交、推送或创建 PR 之前
• 转向下一个任务时
• 任何暗示成功或完成的陈述
• 表示对工作感到满意时

参考： references/verification-before-completion.md

快速决策树

SITUATION?
│
├─ Received feedback
│  ├─ Unclear items? → STOP, ask for clarification first
│  ├─ From human partner? → Understand, then implement
│  └─ From external reviewer? → Verify technically before implementing
│
├─ Completed work
│  ├─ Major feature/task? → Request code-reviewer subagent review
│  └─ Before merge? → Request code-reviewer subagent review
│
└─ About to claim status
   ├─ Have fresh verification? → State claim WITH evidence
   └─ No fresh verification? → RUN verification command first

接收反馈流程

响应模式

阅读 → 理解 → 验证 → 评估 → 回复 → 实施

关键规则

• ❌ 不要表面认同：“你说得完全正确！”、“说得好！”、“感谢 [任何内容]”
• ❌ 未经验证，不要实施
• ✅ 重述要求、提出问题、基于技术理由反驳，或直接开始处理
• ✅ 如果不清楚：停止，并先询问所有不明确的事项
• ✅ 检查 YAGNI：实施建议的“完善”功能前，先用 grep 搜索其使用情况

处理不同来源

• 人类伙伴： 信任对方 - 理解后再实施，不要表面认同
• 外部审查者： 验证其技术正确性，检查是否会造成破坏；有误时提出反驳

完整流程： references/code-review-reception.md

请求审查流程

何时请求

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

流程

1. 获取 git SHA：BASE_SHA=$(git rev-parse HEAD~1) 和 HEAD_SHA=$(git rev-parse HEAD)
2. 通过 Task 工具调度 code-reviewer 子 Agent，并提供：WHAT_WAS_IMPLEMENTED、PLAN_OR_REQUIREMENTS、BASE_SHA、HEAD_SHA、DESCRIPTION
3. 根据反馈采取行动：立即修复 Critical；继续之前修复 Important；将 Minor 记录下来，稍后处理

完整流程： references/requesting-code-review.md

验证关卡流程

铁律

没有最新的验证证据，就不得声称已完成

关卡流程

确定命令 → 运行完整命令 → 阅读输出 → 验证输出确认论断 → 然后再提出论断

跳过任何一步 = 撒谎，而非验证

要求

• 测试通过：测试输出显示失败数为 0
• 构建成功：构建命令退出码为 0
• 错误已修复：复现原始症状的测试通过
• 满足要求：逐行核对清单并确认

危险信号 - 停止

使用“应该”、“大概”、“似乎”等措辞；验证前就表示满意；未经验证就提交；轻信 Agent 的报告；使用任何暗示成功、却未运行验证的措辞

完整流程： references/verification-before-completion.md

与工作流集成

• 子 Agent 驱动： 每项任务完成后都进行审查，确认无误后再继续下一项
• 拉取请求： 确认测试通过，并在合并前请求 code-reviewer 审查
• 一般原则： 声称任何状态前都先通过验证关卡，对无效反馈予以反驳

核心原则

1. 技术严谨胜于社交表现——不做表面上的附和
2. 系统化审查流程——使用 code-reviewer 子 Agent
3. 先有证据再做声明——始终通过验证关卡

验证。质疑。然后实施。提供证据。然后声明。