代码审查技能
基于 Gregory Brown 的《有效代码审查》(《编程超越实践》,2015 年)的由外而内、风险驱动的代码审查方法。
平台集成和项目特定的检查在项目的规则中单独定义。
设置
当被要求设置、配置、入门或为此技能创建规则文件时:
- 阅读所有现有的项目规则(
.claude/rules/、CLAUDE.md)以了解已配置的内容。不要重复项目配置中已有的约定、命令或检查。 - 检查项目中的问题/PR 链接约定、CI 配置、linter/formatter 配置以及代码审查平台指示符。
- 使用选择对话框为用户展示每个技能特定决策的交互式选项,每个选项包括:
- 上下文收集 — 如何定位 PR 的相关问题或工单(分支命名、PR 主体关键词、任务管理集成)
- 构建验证 — 如何验证构建是否通过(CI 状态检查、特定命令)
- 编码约定 — 超出技能默认值的项目特定检查(架构规则、已由 linter 强制执行的样式规则)
- 输出格式 — 审查输出的自定义结构,或使用内置格式
- 发布机制 — 如何发布审查(GitHub PR 评论、内联评论、标准输出)
- 重新审查线程处理 — 在重新审查时,如何处理你自己先前的发现线程:回复并解决(默认——在线程中回复并解决已修复或已答复的线程)、仅回复(在线程中回复但将解决留给人类)、或仅摘要(绝不触碰先前的线程;仅在其摘要中报告状态)
- CI 集成 — 提供生成 GitHub Actions 工作流的选项,该工作流会在每个 PR 上自动运行此审查。始终询问此选项,即使
.github/workflows/目录尚不存在——这可能是项目的第一个工作流。提供模型选择:Opus(推荐) / Sonnet / 跳过。默认值:Opus。
- 编写
.claude/rules/code-review.md,仅包含用户的选择。省略任何用户接受默认值的决策——技能的默认行为会处理这些。 - 如果用户选择了 CI 集成:
a. 读取
assets/code-review.yml(与此技能捆绑)作为工作流模板。 b. 如果用户选择了不同的模型,将--model opus替换为--model <所选模型>。 c. 如果.github/workflows/code-review.yml已存在于项目中,显示差异并在覆盖前请求确认。 d. 将工作流写入.github/workflows/code-review.yml(如果.github/workflows/不存在则创建)。 e. 提醒用户将CLAUDE_CODE_OAUTH_TOKEN添加为仓库密钥:- 使用以下命令在本地生成令牌:
claude setup-token - 在以下位置添加:GitHub 仓库 → 设置 → 密钥和变量 → Actions → 新建仓库密钥
- 使用以下命令在本地生成令牌:
需要由人类处理的事项(CI 集成): 用户必须添加 CLAUDE_CODE_OAUTH_TOKEN 密钥并验证分支保护规则是否允许操作发布审查评论。设置无法检查或配置这些。
如果用户接受所有默认值且未做出任何选择,确认不需要规则文件并停止。
阶段 0:先前的审查状态(重新审查)
在审查之前,找出已讨论过的内容。
收集关于此更改的现有审查对话:
- 所有内联讨论线程,包括回复及其已解决/未解决状态——包括你的和人类审查者的。
- 你自己先前的审查摘要(如果存在,通过其隐藏标记识别——参见阶段 6)。
如果你的项目定义了平台发布机制,请使用它们获取此状态。如果没有配置平台机制(例如,审查输出到标准输出),则将其视为首次审查,并在摘要中注明无法检查先前的审查状态。
如果不存在先前的审查状态,这是首次审查——继续执行阶段 1,并跳过阶段 6 中的重新审查步骤。
读取每个线程;仅对自己的线程采取行动。 人类审查者的线程用于告知审查——切勿提出人类审查者已提出的问题,无论是否得到答复。通过你在每个发现中嵌入的隐藏标记(参见阶段 6)识别你自己的线程,永远不要通过发布账号——账号在 CI 和本地运行之间可能不同。
对于你自己先前的每个发现,对其进行分类,并将处理方式带入审查的其余部分:
- 已推送修复 — 作者更改了代码以响应。在审查期间验证当前差异中的修复。实际已修复:在线程中回复确认(例如,“在 <修订版> 中已验证修复”)并解决该线程。声称已修复但未实际修复:回复解释仍然缺少什么,并将线程保持打开状态。
- 已答复 — 作者解释或质疑了该发现。他们的回应具有权威性;不要重新提出。回复确认并解决该线程。
- 仍打开 — 没有回复,没有修复。不要发布重复的评论。保持线程不变,并在新摘要中将其列在“先前发现”下。
本次审查中真正的新发现照常在阶段 6 中发布。
如果你的项目配置了重新审查线程处理模式(参见设置),请遵循它——某些团队保留线程解决给人类。默认是回复并解决。
需要由人类处理的事项: 裁决争议——当作者反驳时,此技能保持让步;如果仍有争议点,人类审查者必须做出决定。自动审查者是否可以解决线程是团队约定——人类拥有它(通过设置配置)。
阶段 1:问题验证
从这里开始——在阅读一行代码之前。
问两个问题:
- 这段代码是否真正解决了它旨在解决的问题?
- 发布此改进是否将增加项目的整体价值?
如果任一答案为否——停止。不要审查代码。与决定构建内容的人联系并讨论。审查不会在生产中存活的代码是浪费时间。
要回答这些问题:阅读链接的问题或工单、支持文档以及任何相关讨论。如果你的项目定义了如何定位相关问题或工单(任务管理集成、分支命名约定),请遵循它。如果不存在问题或未配置集成,使用 PR 标题和描述作为事实依据。检查差异是否合理地解决了所述内容。
需要由人类处理的事项: 实际运行该功能并从用户的角度验证其是否正常工作。你可以验证所述问题与差异之间的逻辑一致性;人类必须验证它是否真正工作。
阶段 2:构建与可运行性
- 构建是否通过?如果没有,暂停审查。未通过的构建不可信。即使新更改正确工作,其他内容可能已损坏。不要假设构建失败是无害的。
- 代码是否在作者机器以外的其他地方运行?生产环境是理想的;临时环境或其他开发者的机器是可接受的冒烟测试。
- 让代码运行是否需要向他人求助?如果是,文档缺失或设置需要自动化——或两者兼有。
如果你的项目定义了如何验证构建状态(CI 系统、状态检查),请使用它。否则,检查更改上下文中任何可用的构建指示符。
需要由人类处理的事项: 在本地或临时环境中运行代码,从用户的角度尝试功能,并提出关于可用性、错误处理或意外行为的任何问题。
阶段 3:测试审计
修改或删除的测试是红旗——在其他任何事情之前先调查。
当你看到对现有测试的更改时,放慢速度。问:它们为什么被修改?在形成任何意见之前理解原因。
许多修改相对无害——删除行为不正确的测试、更改测试粒度或替换此 PR 替代的内容。这些都不是内在危险的,但需要思考。关键问题是:此修改是否更改了代码库其他部分依赖的契约?
- 对隔离、自包含代码的测试的更改 = 相对安全
- 对共享或重用代码的测试的更改 = 风险较高;需要明确的理由
如果你无法仅从差异中回答问题,暂停并向作者询问。这些对话建立共享理解,并在误解造成实际损害之前暴露它们。
阶段 4:覆盖范围评估
对更改进行分类,然后应用与风险相适应的期望。通过的测试套件仅与其描述的行为一样好——你不能自动化审查测试的过程。
错误修复
每个错误修复都应有回归测试。至少一个高级别验收测试,遵循错误报告中描述的相同路径——映射真实用户可能采取的行动,而不仅仅是内部失败的直接触发器。
单元测试应补充验收测试,用于任何复杂或严重的情况,以便在将来出现问题时提供更精细的反馈。
还要寻找矿工金丝雀模式:此错误是真正独特的,还是更深层、更广泛问题的迹象?检查代码库中其他地方是否存在类似模式。如果存在,提交工单——你不必现在全部修复,但暴露它们是一项重大贡献。
新功能
应用零测试思想实验:如果所有以下条件成立,则最小测试覆盖是可以接受的:
- 更改几乎完全包含新代码,仅依赖于基础设施、框架、库和通用数据访问对象
- 新功能隔离到其自身区域(其自己的页面、命名空间或端点)
- 它不引入新的系统范围副作用(没有更改的依赖、配置或共享资源负载)
- 它不计划用作路线图上其他功能的构建块
- 它不是工作流链中将其他功能联系在一起的中间步骤
- 故障不能向外逃逸并在其他地方引起不稳定
- 任何可想象的故障对利益相关者都是可接受的,不会造成重大损害
- 测试可以在以后编写而不会产生不可接受的成本或延迟
对于每个不满足的条件,期望测试专门解决该风险。一个允许失败、完全隔离且以后易于测试的功能不构成重大风险。一个与现有工作流关联、可能在其他地方引起故障或将在其上构建的功能——则是。
增强:附加
与现有功能共存的新代码。应用上述新功能标准,然后更进一步:因为它与现有功能相邻,故障隔离是主要关注点。
附加中的故障是否会导致现有功能瘫痪?考虑最坏情况的故障场景。是否覆盖了边界情况和边界条件?
增强:扩展
通过重用现有组件建立在现有行为之上。在评估新代码之前,对被重用的内容进行小型审计:
- 重用的组件是否有测试?
- 它们是否已在业务和/或代码级别记录?
- 它们是否设计为重用,还是被拉伸超出了其原始目的?
- 它们是否出现在最近或未解决的错误报告中?
- 它们更改的可能性有多大?如果它们更改,是否会破坏此扩展?
你不需要花费超过几分钟的时间——这是一个思想实验,而不是深入调查。但已知和计算过的风险总是比意外更好。为任何值得跟踪的事情提交工单。
增强:完善
修改现有系统行为。最高风险类别。 从应用扩展审查中的所有内容开始。然后进一步。
找到依赖于被修改代码的每个功能。每个依赖项都可能受影响。理想情况下,你会让每个都经过完整的审查过程,但实际上这很少可行。至少:识别依赖项,检查它们的测试是否仍然成立,并将完整列表标记给人类审查者手动测试。
阶段 5:项目特定检查
如果你的项目定义了编码约定、架构模式或样式规则,将它们应用于差异并检查违规。
如果没有定义项目约定,检查:差异内不一致的命名、更改引入的死代码、明显的重复、系统边界缺少错误处理以及安全问题(未净化的输入、硬编码密钥、过于宽泛的权限)。
如果你的项目定义了特定于平台的发布机制(如何发布审查、内联评论的格式等),在下一阶段遵循它们。
阶段 6:风险评估与输出
分配风险级别:
- 低 — 隔离更改,未触碰共享代码,测试干净且适合更改类型
- 中 — 触碰现有行为或共享代码,但测试良好且依赖关系已理解
- 高 — 修改具有依赖项的共享组件,测试因更改类型而更改或缺失,涉及安全或身份验证
生成审查摘要,包括:
- 上下文:PR 做什么,解决什么问题
- 好的方面
- 发现的问题(包括一般性和行级别的,如果适用)
- 在重新审查时:在“新问题”之前,先有一个先前发现部分,列出你每个先前的发现及其状态——已解决(已验证修复)、已答复(作者回复已接受)或仍打开。首次审查省略此部分。
- 风险级别和理由
生成人类审查者摘要(可选):在摘要末尾,你可以包含人类审查者摘要,其中包含人类可能想要手动测试的观察、问题或关注点。
发布审查: 如果项目定义了平台发布机制,使用它们。否则,将审查输出到标准输出。
对于每个行级别的问题,在 PR 差异上创建内联评论(如果平台支持)。每个内联评论应以唯一的隐藏标记开头,格式为:\n\n<!-- CR-SKILL-FINDING-<UUID> -->\n,你在阶段 0 中使用它来识别你自己的线程。如果平台不允许内联评论或未配置,将所有行级别问题以格式化列表形式包含在摘要中。