第 5 章 · 01 代码审查(code-review)
第 5 章 · 01 代码审查(code-review)
本节摘要:code-review 是 Claude Code 内置的工程技能(skill),它把「给代码 diff 挑错」变成一套分级、多角度、可验证的程序化流程。核心是一个 effort(努力度)分级旋钮——low(1 轮 diff 扫描,无验证,≤4 个发现)、medium、high(3 正确性 + 5 清理角度,6 候选,1 票验证,≤10 发现)、max(10 角度 + 扫描补漏,≤15 发现)——努力度越高,覆盖越广但耗时越长。每个级别都遵循「收集 diff → 多角度找候选 → 验证 → 输出」的流程,只为召回(recall)真实 bug 服务,且明确区分正确性 bug(优先)与清理建议。本节讲透这套分级方法论,让你理解官方如何用多代理(L1 角度独立 + L2 验证)做高质量代码审查,并能复用到自己的审查工作流。
内容来源:Anthropic 官方 Claude Code 技能
bundled-skills/code-review/SKILL.md、low.md、max.md(随 Claude Code 分发,从泄露素材库提取),汉化并套用体系化模板。
学习目标
阅读完本节,你应当能够:
- 说清 code-review 技能的 effort 分级(low/medium/high/max)在覆盖范围与产出上的差异。
- 描述「收集 diff → 多角度找候选 → 验证 → 输出」的标准四阶段流程。
- 列举 high 级别的八大角度(逐行扫描、删除行为审计、跨文件追踪、复用、简化、效率、高度、约定)各自找什么。
- 理解验证阶段的三态判定(CONFIRMED/PLAUSIBLE/REFUTED)与召回偏好。
- 区分正确性 bug 与清理建议的优先级,以及 CLAUDE.md 约定检查的特殊规则。
一、分级方法论:effort 旋钮
code-review 的核心是一个 effort 参数,控制审查的彻底程度。级别越高,角度越多、候选越多、验证越严,但耗时越长。
low → 1 diff 扫描,无验证,≤4 发现 (快速过一遍,只看 hunk 内明显 bug) medium → 适中角度 + 验证,≤8 发现 high → 3+5 角度 × 6 候选,1 票验证,≤10 发现 (一次坐下来认真审,召回导向) max → 5+5 角度 × 8 候选,验证 + 扫描补漏,≤15 发现 (抓尽每个真实 bug) ultra → 云端深度多代理审查
💡 选级别的经验:日常小改用 low(快速);正式 PR 审查用 high(召回导向,宁可多报);关键路径(支付、安全、核心算法)用 max(抓尽 bug)。high 与 max 都明确「为召回服务」——在高努力度下,抓到真实 bug 比避免误报更重要,宁可想错也不愿漏。
二、标准流程:四阶段
无论哪个级别,流程骨架一致(只是角度数、候选数、是否验证不同):
阶段 0:收集 diff
git diff @{upstream}...HEAD # 有 upstream 时 # 或 git diff main...HEAD # 无 upstream git diff HEAD~1 # 最近一次提交 git diff HEAD # 含工作区未提交改动(审查常在提交前跑)
如果传了 PR 号、分支名或文件路径作为参数,就审查那个目标。把得到的 diff 当作审查范围。low 级别会跳过测试/夹具文件的 hunk(test/、spec/、__tests__/、*_test.*、fixtures/)——测试文件改动在这个级别不审。
阶段 1:多角度找候选
这是召回的核心。用 Agent 工具跑多个独立角度,每个角度产出一批候选发现(file/line/summary/failure_scenario)。high 级别有 8 个角度,max 有 10 个。关键原则:不要让一个角度的结论压制另一个——两个角度因不同原因标了同一行,两个都记。
阶段 2:验证
对每个候选(去重后)跑一个验证器:给它 diff、相关文件、候选,它返回三态之一。low 跳过此阶段。
阶段 3:输出
按严重度排序输出 JSON 数组,正确性 bug 永远排在清理建议之前。若输出上限迫使裁剪,先砍清理类。
三、high 级别的八大角度
high 级别跑 8 个独立角度,前 3 个找正确性 bug,后 5 个找清理与约定问题。
Angle A —— 逐行 diff 扫描:读 diff 每个 hunk 逐行,然后读每个 hunk 所在函数的完整代码——被触达函数里未改动行的 bug 也在范围内(PR 重新暴露或未修复它们)。对每行问:什么输入、状态、时序或平台会让这行错?找反转/错误条件、off-by-one、空指针解引用、漏 await、falsy-zero 检查、错变量复制粘贴、catch 里吞错误、未转义正则元字符。
Angle B —— 删除行为审计:对 diff 删除或替换的每行,说出它强制的不变量或行为,然后在新代码里找这个不变量在哪里重建。找不到就是候选:删了的守卫、丢了的错误路径、收窄的校验、删了覆盖真实场景的测试。
Angle C —— 跨文件追踪:对 diff 改的每个函数,找它的调用方(Grep 符号)检查改动是否破坏调用点:新前置条件、改了的返回形状、新异常、时序/顺序依赖。也检查被调方:同 PR 里的并行改动是否让某次调用不安全。
复用:标出重新实现了代码库已有功能的新代码——Grep 共享/工具模块,点名该调用的现有 helper。
简化:标出 diff 引入的不必要复杂度:冗余或可推导的状态、略变的复制粘贴、深嵌套、遗留死代码。点名更简单的等价形式。
效率:标出 diff 引入的浪费:冗余计算或重复 I/O、独立操作串行跑、阻塞工作加进启动或热路径。也标出从闭包/捕获环境构建的长生命周期对象——它们让整个外围作用域在对象生命周期内保活(作用域持有大值时是内存泄漏),建议改用只复制所需字段的结构。
高度(altitude):检查每个改动是否在正确的深度实现,而非脆弱的创可贴。在共享基础设施上叠特殊用例是修复不够深的信号——优先泛化底层机制而非加特殊用例。
约定(CLAUDE.md):找到治理改动代码的 CLAUDE.md 文件(用户级 ~/.claude/CLAUDE.md、仓库根 CLAUDE.md、改文件祖先目录里的 CLAUDE.md/CLAUDE.local.md),读每个存在的,检查 diff 是否明显违反所述规则。只在你能源引用确切规则和违反的确切行时才标——不要风格偏好、不要模糊的「文档精神」推断。
💡 约定检查的铁律:发现里要写明 CLAUDE.md 路径并引用规则原文,这样报告能引用。无 CLAUDE.md 适用就返回空。清理/高度/约定候选用同样的形状,但在
failure_scenario里写具体成本(重复了什么、浪费了什么、更难维护、违反了哪条规则)而非崩溃。
四、验证:三态判定与召回偏好
验证器对每个候选返回三态之一:
- CONFIRMED —— 能说出触发它的输入/状态与错误输出或崩溃,引用该行。
- PLAUSIBLE —— 机制真实,触发不确定(时序、环境、配置)。说出什么能确认它。
- REFUTED —— 事实错误(代码不是那样)或在别处守卫了,引用证明的行。
保留 CONFIRMED 与 PLAUSIBLE,丢掉 REFUTED。这是召回模式——单个非 REFUTED 票就保留发现,不要因不确定性丢弃。
⚠️ PLAUSIBLE 默认保留:不要因为「投机」或「依赖运行时状态」就反驳候选——当状态现实时:并发竞争、罕见但可达路径上的 nil/undefined(错误处理、冷缓存、缺失可选字段)、falsy-zero 当缺失、边界 off-by-one、重试风暴/部分失败、丢了锚点的正则/白名单。这些都是 PLAUSIBLE。只有能从代码构造出反证时才 REFUTED。
五、max 级别:多角度 + 扫描补漏
max 级别在 high 基础上加码:10 个角度(多了语言陷阱专家 Angle D、包装/代理正确性 Angle E),每角度最多 8 候选;验证后还多一个阶段 3 扫描——跑一个全新审查者,带着已验证列表,只找尚未列出的缺陷,最多补 8 个。扫描聚焦首轮易漏的:移动/抽取代码时丢了守卫或锚点;二阶陷阱(dataclass 默认值只算一次、hash() 非确定、锁范围缩小、谓词方法有副作用);测试 setup/teardown 不对称;配置默认值翻转。
输出上限也更高(≤15)。max 的精神:抓尽每个真实 bug,漏一个就上线了。
六、产出格式与命令行选项
所有级别统一输出 JSON 数组:
[ { "file": "path/to/file.ext", "line": 123, "summary": "一句陈述 bug", "failure_scenario": "具体输入/状态 → 错误输出/崩溃" } ]
按严重度排序,最严重在前。正确性 bug 永远排在清理/高度/约定发现之前。超过上限就留最严重的 N 个。验证后无幸存就返回 []。
命令行支持 --comment(把发现作为内联 PR 评论发布)与 --fix(审查后把发现应用到工作区)。这让审查技能能直接接入 PR 工作流。
七、可复用的审查模式
即便不用 Claude Code,这套方法论也能复用到人工或自建审查流程:
- 明确范围:先拿到 diff,界定审查边界(含未提交改动)。
- 多角度独立找:别让一个视角压制另一个,正确性、清理、约定分开找。
- 召回优先于精确:关键代码宁可多报,验证时三态判定,PLAUSIBLE 保留。
- 区分优先级:正确性 bug 先于清理建议;约定违规要引用确切规则。
- 扫描补漏:首轮后用新视角找遗漏的二阶陷阱。
本节要点回顾
- effort 分级:low(1 轮无验证 ≤4)、medium、high(8 角度 1 票验证 ≤10)、max(10 角度 + 扫描 ≤15);级别越高覆盖越广、召回导向(宁多报不漏)。
- 四阶段流程:收集 diff(含未提交)→ 多角度找候选 → 验证 → 输出 JSON。
- high 八大角度:逐行扫描、删除行为审计、跨文件追踪(正确性);复用、简化、效率、高度、约定 CLAUDE.md(清理)。
- 多角度不互相压制:两个角度因不同原因标同行,两个都记;正确性 bug 永远排清理之前。
- 三态验证:CONFIRMED(能说触发与错误)/PLAUSIBLE(机制真实触发不确定)/REFUTED(可构造反证);召回模式,单非 REFUTED 票即保留。
- 约定检查铁律:只标能引用确切规则与违反行的违规,无 CLAUDE.md 适用就返回空。
- max 扫描补漏:首轮后新视角找二阶陷阱(dataclass 默认值、hash 非确定、锁范围缩小、setup/teardown 不对称等)。
- 可复用模式:明确范围→多角度独立→召回优先→区分优先级→扫描补漏,适用于人工或自建审查。
下一节讲数据可视化(dataviz)技能——把「把图画好看」变成一套有表单启发式、可运行配色验证器、标记规范的程序化流程,核心心法是「颜色可计算,所以去计算它」。