code-review

代码审查

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

概览

代码审查包含三项不同的实践：

1. 接收反馈 — 重视技术评估，而非表面附和
2. 请求审查 — 通过 code-reviewer 子 Agent 进行系统化审查
3. 验证关卡 — 提出任何完成声明前都要有证据

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

核心原则

技术正确性高于社交舒适感。 实施前先验证。先询问，再假设。声明前先提供证据。

何时使用此技能

接收反馈

在以下情况下触发：

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

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

请求审查

在以下情况下触发：

• 在子 Agent 驱动的开发中完成任务后（每项任务完成后）
• 完成主要功能或重构后
• 合并到 main 分支前
• 遇到阻碍，需要新的视角
• 修复复杂 Bug 后

参考： 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
• Bug 已修复：针对原始症状的测试通过
• 满足要求：已逐行核对清单

验证命令

# Tests (prefer bun)
bun test  # or: npm test

# Build
bun run build  # or: npm run build

# Lint
bun run lint  # or: npm run lint

# Type check
bun run typecheck  # or: bunx tsc --noEmit

危险信号 — 停止

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

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

与工作流集成

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

核心原则

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

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