Claude Code 团队如何做代码审查

我们之前提到,Claude Code 约 90% 的代码由 Claude 编写。那么,面对这样的规模,我们如何做代码审查?还有谁会读代码?代码出错了又怎么办?

本文介绍 Claude Code 团队的代码审查流程,以及我们如何不断改进它。从 6 月到 9 月,合并进 Claude Code 代码库的 pull request 数量翻了一倍多,而需要回滚的 pull request 比例下降了 40% 以上。

我们并没有停止代码审查。相反,我们把大部分代码阅读工作自动化,并进行调优,以尽量节省人的时间和精力。与此同时,我们也投入了大量精力,让错误回滚得更快、更容易。

重新思考代码审查的目标

随着 agent 开始编写代码,变更量会迅速增长。在我们的 monorepo 中,今年 5 月每天大约合并 2,500 项变更,到 9 月已经超过 30,000 项。

Claude Code 虽然不在这个 monorepo 里,但同样承受着很大的变更压力。在这样的开发速度下,逐行进行人工代码审查会越来越困难,甚至根本不可能。

代码审查有两个目的:

  1. 在上线前发现并修复 bug
  2. 让团队共同了解代码库

本文主要讨论第一个目标,第二个目标会在接近文末时展开。

我们认为,“是否有人读过代码”并不是一个准确的衡量标准。更该问的是:“这项变更可能出什么问题?用哪种检查最适合发现它——自动检查还是人工检查?”

这个问题也改变了代码审查发生的时机。传统上,代码写完、PR 提交后,才会有人等待另一位同事来审查。我们则把代码审查融入了工作流,它更像写作时持续进行的拼写检查。

在请人查看之前,大多数变更已经由 Claude 审查并修正过至少一次。这样一来,大部分常见 bug 会提前被发现,人的注意力可以留给更高层次的问题。

人的时间和注意力

我们希望把人的时间和注意力留给只有人才能处理的事情,同时用足够的自动化覆盖其余工作。即使以当前的开发速度来看,仍有大量工作需要人来完成,而且团队几乎每天都会遇到前所未见的新挑战。

因此,人的时间要从两头算。我们不仅计算人们花在代码审查上的时间,也计算他们修复劣质代码所引入 bug 的时间。如果只减少前者,却没有减少后者,就不是真正节省了人的时间。

所以,我们的目标是:Claude Code 各代码库(CLI、桌面和 Web 应用,以及移动应用)里的大多数 pull request,最多只需一人参与(可以就是作者本人)便能合并,同时不增加回滚或事故。

我们通过每个 PR 的人工批准数中位数(以及第 95 百分位数)、人工评论数和 PR 等待人工处理的时长,来衡量投入的人力。回滚率和事故率则是护栏指标:如果它们上升,我们并没有减少人的时间,只是把时间花到了别处。

一项变更要经历什么?

一项典型变更,无论来自工程师的笔记本电脑,还是 Slack 中的一次 Claude 会话,都会经过多层审查。

上图展示了一项典型的 Claude Code 变更如何从作者的开发环境进入生产环境。大部分流程已经自动化,人的注意力集中在有风险的部分。

我们设置了六层检查,并用回滚机制处理漏过这些检查的问题。

每一层都能发现一部分 bug,也会漏掉另一些。能穿过所有检查层的 bug 很少;即使真有漏网之鱼,我们也准备了回滚机制。

1. PR 前验证:

大部分审查都在创建 PR 之前完成。我们会要求 Claude 执行可验证的操作,例如运行测试和构建,或者把截图与设计稿对比。我们不接受它只说任务已经完成,而是要求它展示结果。之后,再让一个拥有全新上下文的 subagent 审查 diff。这两种方法都收录在我们的最佳实践指南中。

在创建 PR 之前,我们中的许多人还会运行一些内部 skill,例如查找 bug、缩减 diff、端到端验证,以及按照设计规范检查 UI 变更。

Claude Code 的创造者 Boris Cherny 认为,为 Claude 配备一套验证流程,可能是提高结果质量最关键的一步。

他估计,一套验证流程可以让 Claude 的输出质量提升两到三倍。

不同领域的验证流程可能截然不同:

有时只需运行一条 bash 命令,有时要运行测试套件,有时则要在浏览器或手机模拟器中测试应用。

如果自动审查工具反复指出同一个问题,我们就会从源头修复它——修改 skill 本身、增加 lint 规则,或者更新如下文档:

CLAUDE.md —— 项目说明文件,可以用来向 Claude 提供项目的技术栈、约定、目标和非目标等上下文。Claude Code 每次审查都会读取这个文件,因此对于大型代码库,我们会尽量保持它简短,并在其中引用其余文档。如果代码违反了文件中的约定,或者某项更新导致文件内容过时,审查工具就会指出来。

REVIEW.md —— 代码所有者用这个文件告诉审查工具,自己负责的代码中哪些问题最重要。我们还会另行验证审查工具是否真的遵守了这些准则。好的准则应当简短,并着重于:

定义项目何时算失败(文档不能说假话;配置不能把请求导向错误位置);限制吹毛求疵的评论;定义忽略路径;要求给出文件和行号,而不是猜测文件名;要求提供顶层摘要,其中包含问题数量;如果没有问题,也要明确说明

2. 每个 pull request 都接受 AI 审查

每个 PR 在人工审查之前,都会先接受 Claude 审查。

系统会结合整个代码库和 PR 作者所描述的变更意图来分析 diff,并检查:变更是否真正解决了问题;变更是否适合整个系统;变更是否会破坏代码库的其他部分

审查 bug 修复时,bot 会尝试找到根本原因。

我们的公开产品 Code Review for Claude Code 现已向所有 Team 和 Enterprise 客户开放,另有一个较轻量的本地版本:/code-review。

自 research preview 阶段启动以来,收到实质性审查评论的内部 PR 比例从 16% 上升到了 54%。对于超过 1,000 行的 PR,Code Review 大多都能发现问题;对于规模较小的 PR,它通常会返回没有问题的结果。管理员可以为代码库配置 Quick、Standard 或 Deep 模式。如果漏掉一个 bug 的代价高于代码审查所花的时间,Deep 模式就很有用。

在提交给人工审查之前,多名其他 agent 会先核验这些发现:

多名 agent 并行查找 bug

另一组 agent 分别投票,判断一项发现确有问题还是误报;只有获得足够票数的发现才会被确认

只涉及代码风格、诊断或清理工作的发现会被过滤掉(正式推广前,我们先在自己的 PR 上对这些过滤规则做了 A/B 测试)

其余发现会按严重程度排序,以行内评论的形式呈现,并标记为:

重要;吹毛求疵;既有问题(这样就不会把 PR 引入之前便已存在的 bug 不公平地算在作者头上)

所有发现都必须处理——要么修复,要么说明理由并解决相应审查意见。很多时候,agent 会在夜间修复问题,等作者回来时,PR 已经又经过了一轮审查。

3. 可阻止合并的安全审查

我们还会运行自动安全审查。只要代码审查或安全审查中仍有未解决的发现,PR 就不能合并。作者可以修复问题,也可以简短说明理由后关闭相应审查意见(我们就是这样处理误报的)。

如果后续 commit 解决了问题,对应发现会自动关闭。你可以使用开源的安全审查 GitHub Action,或 /security-review 命令搭建同样的机制。具体设置方法请参阅 Claude Code 的自动安全审查指南。

4. 可阻止合并的自动检查

标准检查包括:lint、类型检查、全平台测试和构建。(我们曾撰文介绍如何扩展 CI。)一个典型的 CLI PR,在有人查看之前可能就会运行几十项检查。PR 模板会询问变更如何测试以及如何回滚。Claude 可以替你回答,但作者有责任审核这些回答。

5. 按风险确定人工批准要求

有些变更比其他变更风险更高(例如修改文档与修改自动更新程序),所以需要不同程度的审查。

审查等级由变更本身决定,而不是由作者决定。一个分类器根据变更判断风险等级,另一个分类器判断某项具体变更是否真的需要额外批准,即使所属等级没有这样的要求。有些路径始终需要另一人批准——所有被所有者标为敏感的路径,以及所有 CI 工作流文件。

只有代码库可信名单中的作者才能享受较宽松的审查要求,一般就是负责该代码库的团队。其他人的变更都需要第二个人批准。Agent 的批准不算人工批准。自动审查可以放行低风险变更,但在必须有人批准时,它不能代替人。

变更作者要对变更负责。因此,如果 PR 由 agent 创建,操作该 agent 的人始终算作一名必需的审查者。PR 的批准只对一个 commit 有效。如果新提交的 commit 不能直接信任(例如由 agent 推送,或有人手动解决了合并冲突),PR 就必须重新获得批准。

6. 合并队列、功能开关与分阶段发布

合并队列会把变更应用到最新的 main 分支后,再确保所有检查都能通过。这样可以避免把两个各自成功的 PR 合并成一个损坏的 main 分支。新功能通常会先放在功能开关后面,由 Anthropic 员工率先使用。因为我们大量使用自己的产品,所以常常能比用户更早发现回归问题。

公开发布时,变更会先进入 latest 渠道,stable 渠道稍后跟进。

7. 快速反馈与回滚

难免会有糟糕的合并穿过所有检查。这是我们的最后一道防线,重点是尽快发现它们。放在功能开关后的变更无需部署就能停用。

Claude Code 团队实行每周轮换值班。每次事故复盘都会回头检查,本应由哪一层发现问题。除了监控回滚和事故看板,作者和值班人员仍需主动发现糟糕的合并。我们还没有根据这些指标动态调整批准要求的熔断机制,不过随着我们逐步减少合并过程中的人工干预,这正是我们在研究的方向。

一位团队成员指出,放慢速度并减少产出确实可能提高准确率,但主要原因是整体完成的工作变少了。我们真正优先考虑的是提升快速发现并纠正问题的能力。

如何让审查工具不断改进

我们的代码审查流程处在持续改进的循环中:

我们把事故作为评估指标。团队收集了引发事故的 PR、对应的后续修复和回滚,再由熟悉代码库的工程师核实每个 bug 的位置和判断是否正确。审查系统每天都会在这个集合上接受评估。

每次事故都会成为集合中的新案例,审查系统的每项变更也都会在整个集合上接受评估。

为了衡量噪声,我们会观察人们如何回应审查评论。如果不介意报告大量并非 bug 的问题,提高 bug 发现率很容易,因此必须约束误报。我们会根据 PR 参与者的处理方式给每条审查评论分类:修复问题、拒绝意见、澄清这是有意为之,或者认为问题无关紧要。此外,我们还会在已知没有问题的 PR 上运行审查系统,观察系统有多大概率报告那些一旦照做反而会带来有害变更的问题。

我们明确的优先级是:第一,发现真正的 bug;第二,减少审查轮次。

当作者是 agent 时,处理一条审查评论的成本更高。人只需一秒就能忽略一条吹毛求疵的意见,但 agent 为了处理它,会产生另一个 commit,继而触发新一轮审查。

审查过程必须收敛。Agent 作者和 agent 审查者可能永远循环下去。我们曾观察到 CLI 项目中的一个 PR,因为两者来回拉扯,一夜之间循环了五十多次。这个循环最后由人工终止,否则可能一直持续下去。

当我们对审查系统反复指出的代码运行 git blame 时,发现其中约 59% 从第一次审查起就已经存在。换句话说,审查系统很少发现新 bug,只是在每一轮多找出几个旧问题。

我们让情况变得更糟,是因为养成了默认运行多轮审查的习惯,毕竟每一轮都有可能发现不同的 bug。对于高风险变更,多迭代几轮可能有用,但并非每个 PR 都需要。除了召回率,我们的团队开始跟踪通过审查所需的轮数,并把重新审查流程改为:

限制审查轮数。三轮之后,审查系统会要求作者重新评估处理方式。首轮过后,重新审查仅检查新的 diff。明确指出 bug 类别,让作者一次纠正整类问题,而不是只修一行。避免重复报告已经发现的问题。审查 agent 也会在夜间对当前代码库运行,帮助我们在历史 bug 扩散之前发现它们。

完成收敛机制改造后,每个内部 pull request 的平均审查轮数有所下降。

人在流程中

相比让资深工程师停下手头工作去审查一个常见错误,把这个过程自动化的成本要低得多。不过,有些任务仍然离不开人工审查:

  • 我们究竟该不该做这个?是否构建某项功能、设定产品愿景、品位和目标,都要由人决定。

有一个团队声称自己已经解决了代码审查的瓶颈,但对团队外部人员提交的变更,他们仍会进行人工审查,以确认这项变更确实值得做。

  • 审计危险代码(计费、自动更新程序、CI 工作流)。
  • 审查架构,因为这些选择会成为其他人遵循的约定。
  • 验证证据(测试输出、运行过的命令、截图、审查评论)。如果你说不清这些检查会漏掉什么,就不要只求一个 👍;你需要的是真正的审查!
  • 承担责任。每一项上线的变更都要有人负责,无论代码由谁输入。

团队上下文

代码审查一直还有另一个作用:让团队了解代码库发生了哪些变化。阅读同事变更的 diff,通常是人们了解改了什么、代码库如何运作的方式。如果大部分阅读工作都交给机器,大家又该怎样熟悉代码库?

我们没有为此建立任何正式机制。团队中没有人能在脑中完整掌握 Claude Code,我们也不认为这有必要。有人想了解代码库的某一部分时,就让 Claude 针对那个部分生成一份说明。只需几分钟,而且说明永远与当前代码保持一致。

我们中的一些人还会多走一步,让 Claude 生成一个小型产物,把这部分代码可视化,并按照自己喜欢的方式讲解。

这比逐行阅读无关紧要的 diff 更值得投入人的注意力,因为那样几乎学不到东西(例如只改一行文案)。为即将修改的模块生成一份说明,反而能学到很多。

此外,我们通常默认公开协作:在开放的 Slack 频道里工作,也能实时看到其他人在构建什么。

“谁合并,谁负责”

如果你合并了一项小型或中型变更,之后仍然出了问题,通常就应该由你自己修复。之所以不会因此失控,有几个原因:

  • 变更规模小,容易审查、调试和回滚。
  • 所有东西都能回滚。功能开关、代码回滚和分阶段发布可以在几分钟内撤销大多数错误。
  • 影响范围决定审查门槛。代价越高的代码,就会有越多人查看,并接受越多验证。
  • 遥测数据和内部使用会迅速暴露回归问题。
  • 这不是追责游戏。修复问题的人负责,是因为他掌握的上下文最多;事故复盘审视的是整个系统。
  • 此外,团队在开放频道中工作,也让很多职责得以共享。任何人都能看到其他人在构建什么、加入对话,或让 Claude 查找遗漏。非代码所有者也可以提供反馈。正是这种开放性,让我们无需给每一行代码都设置关卡,仍能保持高质量。

改变方向

有了 agent,启动一项新工作的成本很低,但有时根本不该开始。常见情况是,频道里有人指出拟议变更走错了路(引用以前的决定,或建议更好的方案),随后作者关闭 PR 或更改实现。

因为代码一开始就很容易写出来,关闭 PR 也不会让人觉得损失很大。关键是尽早在对话中转向,而不是等 PR 全部完成后,才在最后留下阻止合并的评论。

如何实施

这套方法的大多数组成部分,你的团队现在就能采用。

创建 pull request 之前

  • 给 agent 一份可运行的检查清单,并把这些检查列在一份简短的 CLAUDE.md 文件中
  • 通过 hook 让 agent 调用格式化工具和 linter
  • 在本地运行 /code-review 和 /security-review,或让一个拥有全新上下文的 subagent 审查变更
  • 创建 REVIEW.md,用它记录反复出现的审查问题

每个 pull request 上都要做的事

  • 强制执行 CI
  • 在 PR 模板中加入“测试”“风险”和“如何回滚”
  • 先在一个代码库中加入 AI 审查工具(Code Review for Claude Code 或 Claude Code GitHub Action),花几周迭代 REVIEW.md,再推广到更多代码库
  • 加入自动安全审查
  • 要求所有审查意见都得到解决后才能合并
  • 根据风险确定审查严格程度:常规变更快速检查,高风险区域(bug 代价高昂)全面审查。Code Review 提供 Quick、Standard 和 Deep 三个等级
  • 限制审查轮数;经过几轮后,只审查新增的 diff

批准

  • 定义由变更而非作者决定的风险等级。起初从严,再随着证据积累逐步放宽
  • 只为可信作者保留宽松的批准路径
  • Bot 的批准不能满足必需的批准要求。推送新 commit 后,撤销之前的所有批准
  • 对控制身份验证、计费、CI、发布工作流和安装程序的代码及策略,指定人工批准者。使用 CODEOWNERS 和分支保护实现这一点

合并与合并后

  • 设置合并队列
  • 试用功能开关
  • 先向内部用户发布
  • 分阶段发布
  • 建立一步即可完成的回滚机制
  • 通过记录事故和回滚建立一套 eval
  • 每次更改审查工具的 prompt、工具或模型后,都重新评分
  • 跟踪人力投入,并以回滚率和事故率作为护栏指标

未来会走向哪里

Code Review 发布时曾明确表示,最终批准仍由人来决定,产品本身只负责给出审查结果。但在我们自己的代码库里,我们走得更远:代码所有者正在决定,哪些低风险变更可以在自动检查通过后自动合并。这个边界还会继续变化。

因此,每当审查工具漏掉什么,我们都会问:模型的上下文里缺了什么?然后把答案写进 CLAUDE.md 文件、做成 skill,或变成一项新检查。我们的目标并没有改变:在回滚率不高于当前水平的前提下,减少每项变更需要投入的人力。

所以,如果你也允许 agent 创建 pull request,请告诉我们:你自动化了哪些检查,哪些环节仍然必须由人完成,以及我们还有哪些地方做得不对。

根据我们原来的这篇 文章 重写,并使用 Pangram 检查。