Claude Code 团队如何做代码审查
How the Claude Code team does code review

我们之前提到过,Claude 编写了 Claude Code 约 90% 的代码。那么,在如此规模下,我们如何做代码审查?到底由谁来看代码?如果代码出了问题,会发生什么?
本文介绍我们团队在 Claude Code 中的代码审查流程,以及我们如何改进它。6 月至 9 月期间,合并到 Claude Code 代码库的拉取请求(PR)数量增长了一倍多,而不得不回滚的拉取请求(PR)占比下降了 40% 以上。
我们并没有停止代码审查。相反,我们已将大部分代码阅读工作自动化,并对其进行调优,以优化人的时间与精力投入。我们还投入了大量资源,以提高回滚错误的速度和便利性。
重新思考代码审查的目标
随着智能体编写代码,变更数量迅速增加。在我们的单体仓库(monorepo)中,5 月每天大约合并 2,500 项变更,而到今年 9 月,这一数字已超过 30,000 项。
虽然 Claude Code 并不在我们的单体仓库(monorepo)中,但它同样承受着很大压力。当你以这样的速度推进时,逐行手动进行代码审查会变得越来越困难,甚至不可能。
代码审查有两个目的:
- 在发布前发现并修正缺陷
- 建立对代码库的共同理解
本文主要关注第一个目标,但我们将在文末讨论第二个目标。
我们把“有人读过这段代码吗?”视为对“这项变更可能出什么问题,以及哪种检查——自动检查还是人工检查——才是发现问题的正确手段?”的一种不精确衡量。
这个问题也改变了代码审查的时机。传统上,代码审查是在事后执行的一项检查:代码已经写好,PR 已经提交,然后一个人等着另一个人来看。相反,我们已将代码审查融入工作流。它更像是你在写作过程中持续进行的拼写检查。
在请人查看之前,大多数变更已经由 Claude 至少审查并修正过一次。通过这种方式,我们能够发现大多数常规缺陷,并把人的注意力留给更高层面的考量。
人的时间与注意力
我们希望把人的时间和注意力留给只有人类才能处理的事情,同时确保有足够的自动化来覆盖其余部分。即使以我们目前的速度,人类仍有大量工作要做,而且我们的团队几乎每天都会遇到新的、独特的挑战。
因此,人的时间是一种双重成本。我们不仅要计算人们花在代码审查上的时间,还要计算他们花在修复由不良代码引入的缺陷上的时间。如果我们只减少前者而不减少后者,就并没有真正节省人的时间。
因此,我们的目标是:在 Claude Code 的各仓库(CLI、桌面端和 Web 应用以及移动应用)中,大多数拉取请求(PR)应当在最多只有一个人参与(可能是作者本人)的情况下合并,同时不增加回滚或事故。
我们通过每个 PR 的人工审批中位数(以及第 95 百分位数)、人工评论数量,以及 PR 等待某人处理的时间来衡量人的时间。我们将回滚率和事故率作为护栏指标:如果这些指标上升,我们就没有减少人的时间,只是把它转移到了别处。
一项变更会经历怎样的旅程?
一项典型的变更,无论来自工程师的笔记本电脑,还是来自 Slack 中的 Claude 会话,都要经过多层审查。

上图展示了 Claude Code 的一项典型变更,从作者环境到生产环境的流程。这一流程的大部分是自动化的,人的注意力集中在有风险的部分。
我们有六层检查,并配有回滚机制,用来处理任何漏过检查的问题。

每一层都能发现一些缺陷,同时也会漏掉另一些。很少有缺陷能穿过所有层级,而如果真的有,我们也有回滚机制可用。
1. PR 前验证:
我们的大部分审查都在创建 PR 之前完成。我们会要求 Claude 做一些可运行的事情,例如运行测试、执行构建,或将截图与设计稿进行对比。我们不会只让它说任务完成了,而是要求它向我们展示结果。然后,由子智能体以全新的上下文审查代码差异。这两种策略都包含在我们的最佳实践指南中。
在创建 PR 之前,我们中的许多人还会运行一些内部技能——缺陷搜寻、差异缩减、端到端验证,以及根据设计准则检查 UI 变更。
Claude Code 的创造者 Boris Cherny 表示,为 Claude 配备一套验证流程,可能是实现更高质量结果的最关键因素。
他估计,验证流程能将 Claude 输出的质量提升两到三倍。
对于任何给定领域,验证流程都可能大不相同:
有时,它只是运行一条 bash 命令。有时,它是运行测试套件。有时,它是在浏览器或手机模拟器中测试应用。
如果自动审查者持续标记同一个问题,我们就会从源头修复它——通过技能本身、lint(静态代码检查)规则,或更新如下文档文件:
CLAUDE.md -- 项目描述文件,你可以用它向 Claude 提供有关项目的上下文(技术栈、约定、目标、非目标)。Claude Code 会在每一次审查中引入这个文件,因此对于大型代码库,我们会让它保持简短,并在这里引用其余文档。当代码违反该文件中的某项约定,或某次更新使其中某些内容过时,审查者会将其标记出来。
REVIEW.md -- 代码所有者用这个文件告诉审查者,在他们负责的代码部分中什么才是重要的。我们还会单独核实审查者是否真的遵循这些准则。好的准则应当简短,并聚焦于:
定义项目失败(文档不应说谎;配置不应错误路由);限制吹毛求疵;定义被忽略的路径;要求提供文件 + 行号引用,而不是猜测文件名;要求提供顶层摘要,包括数量以及对“没有问题”的明确说明。
2. 对每个拉取请求(PR)进行 AI 审查
每个 PR 都会在人工审查之前接受 Claude 审查。
代码差异会结合整个代码库以及 PR 作者所说明的 PR 意图进行分析。它会检查:该变更是否确实解决了问题;该变更是否契合更大的系统;该变更是否不会破坏代码库的其他部分。
在审查缺陷修复时,机器人会尝试找到根本原因。
我们的公开产品 Code Review for Claude Code 现已向所有 Team 和 Enterprise 客户提供。此外还有供本地使用的轻量版本——/code-review。
自推出研究预览版以来,我们内部获得实质性审查意见的 PR 占比已从 16% 升至 54%。对于超过 1,000 行的 PR,代码审查能在大多数 PR 上发现问题;对于大多数较小的 PR,则会返回无问题的结果。管理员可以将仓库配置为使用 Quick、Standard 或 Deep 模式。当漏掉一个 bug 的代价高于审查代码所花的时间时,Deep 模式会很有用。
审查发现会先由多个其他智能体审核,然后才进入人工审查:
多个智能体并行运行,以查找 bug
另有一轮独立投票判断某项审查发现是有效问题还是误报,只有获得足够票数的审查发现才会被确认
仅与代码风格、诊断或清理相关的审查发现会被过滤掉(我们在推广这些过滤器之前,已在自己的 PR 上做过 A/B 测试)
其余审查发现会以行内评论的形式呈现,按严重程度排序,并标记为:
Important(重要)、Nit(小问题)、Pre-existing(先前存在)(这样我们就不会因为并非由该 PR 引入的 bug 而不公平地惩罚作者)
所有审查发现都必须得到处理——要么修复,要么在说明原因后将讨论串标记为已解决。在许多情况下,智能体会连夜修复问题,因此作者回来时会看到一个已经过另一轮审查的 PR。
3. 可阻断合并的安全审查
我们还会运行自动安全审查。只要仍有未关闭的审查发现(无论是来自代码审查还是安全审查),任何 PR 都无法合并。作者可以修复该问题,也可以附上简短原因关闭讨论串(这就是我们处理误报的方式)。
如果后续提交解决了该问题,相关审查发现会被自动关闭。你可以通过开源的安全审查 GitHub Action 或 /security-review 命令设置同样的机制。有关如何设置的指南,请参阅 Claude Code 中的自动安全审查。
4. 可阻断合并的自动检查
标准检查包括:lint(静态代码检查)、类型检查、所有平台上的测试、构建。(我们在此处写过如何扩展持续集成(CI)。)一个典型的 CLI PR 在任何人查看之前,可能会先运行数十项检查。PR 模板中包含有关如何测试该更改以及如何回滚的问题。Claude 可以替你回答这些问题,但作者有责任审查这些回答。
5. 按风险分级的人工审批
有些更改比其他更改风险更高(例如文档修复与自动更新器更改),因此需要不同级别的审查。

层级由更改本身决定,而不是由作者决定。一个分类器会根据更改内容确定风险级别。另一个分类器会判断某项具体更改是否实际需要额外审批,即使该层级并未这样规定。有些路径始终需要额外审批——任何被所有者标记为敏感的内容,以及任何持续集成(CI)工作流文件。
只有仓库受信任名单上的作者才能享受更宽松的审查要求,而这份名单通常就是拥有该仓库的团队。其他所有人都需要第二个人审批。智能体审批不计入人工审批。自动审查可以让低风险更改通过,但在需要人工审批时,它不能代替人工。
更改的作者对更改负责,因此如果由智能体创建 PR,该智能体的操作者始终会被计为必需的审查者之一。PR 审批仅对一次提交有效。如果出现一个无法信任的新提交(例如智能体推送了某些内容,或有人手动解决了合并),则必须重新审批该 PR。
6. 合并队列、功能开关与分阶段发布
合并队列确保所有检查都在应用了该更改的 main 分支上运行。这可以防止将两个各自成功的 PR 合并后得到一个损坏的 main 分支。通常,新功能会在功能开关的控制下发布,Anthropic 员工会首先获得访问权限。由于我们广泛使用该产品,我们经常能在用户之前发现回归问题。
当我们公开发布时,更改会先进入 latest 渠道,stable 渠道则随后跟进。
7. 快速反馈与回滚
有些糟糕的合并不可避免地会漏过去。这是我们的最后一道防线,重点在于尽可能快地识别出这些合并。由功能开关控制的更改无需部署即可禁用。
Claude Code 实行每周值班轮换,任何事故复盘都会回顾本应由哪一层发现该问题。除了监控回滚和事故仪表板外,发现糟糕合并仍然要靠作者和值班人员。我们还没有能据此调整审批要求的熔断机制,但随着我们在减少合并中的人工干预方面取得进展,这也是我们正在研究的事项。
一位团队成员指出,放慢速度并减少产出实际上可以提高准确性,但这主要是因为整体完成的工作量减少了。我们的优先事项实际上是提升快速识别和纠正问题的能力。
我们如何让审查者变得更好
我们的代码审查流程是一个持续改进的循环:
我们将事故作为评估指标。团队收集了导致事故的 PR、这些 PR 的前向修复和回滚,并让熟悉代码库的工程师核实每个 bug 的位置及其判定是否正确。审查系统每天都会基于这个集合进行评估。

每一起事故都会加入该集合,审查系统的每一次更改都会针对整个集合进行评估。
为了衡量噪声,我们会观察人类对审查评论的反应。如果我们愿意报告大量非 bug,提高 bug 发现率是很容易的,因此这需要受到约束。我们会根据 PR 上的人员对每条审查评论的处理方式对其进行分类:修复了问题、驳回了评论、澄清这是有意为之,或认定它无关紧要。此外,我们会在已知没有问题的 PR 上运行审查系统,并观察系统多频繁地报告出若采纳就会导致有害更改的问题。
我们声明的优先事项是:第一,发现真正的 bug;第二,减少审查循环次数。
当作者是智能体时,处理一条审查评论的代价会更高。人类只需一秒钟就能驳回一个小问题,但当智能体必须处理它时,就会产生另一个提交和又一轮审查。
审查流程必须收敛。智能体作者和智能体审查者有可能无限循环下去。我们观察到 CLI 项目中的一个 PR 在一夜之间循环了五十多次,原因是智能体作者与智能体审查者之间来回往复。这个循环是被手动停止的,但它本可能无限持续下去。
当我们对审查系统反复标记的内容运行 git blame 时,其中 \~59% 是自首次审查以来就一直存在的代码。实质上,审查系统很少发现新 bug,而是在每一轮中多发现几个旧 bug。
我们把情况弄得更糟,因为我们已经习惯了默认运行多轮审查,而每一轮都可能发现不同的 bug。虽然对高风险更改来说,反复进行多轮审查可能有用,但并非每个 PR 都需要这样做。我们团队开始除召回率外还跟踪通过所需的轮次数,并更新了重新审查规则,使其:
限制循环次数。审查系统会在三轮之后要求作者重新评估方案。在最初几轮之后,将重新审查限制为仅审查 diff。明确 bug 类别,以便作者能全部修正,而不只是修正一行。避免重复报告已经观察到的问题。审查智能体还会在夜间针对当前代码库运行,帮助我们在历史 bug 扩散之前发现它们。

Convergence 之后,每个内部拉取请求(PR)的平均审查轮次数有所减少。
人工参与
让资深工程师停下手头工作去审查一个常见错误,与将这一过程自动化相比,成本很高。在某些任务中,人工审查者仍然不可或缺:
- 我们究竟该不该构建它?决定是否构建某项内容,并为产品设定愿景、品味和目标。
有一个团队声称已经解决了代码审查的瓶颈,但对于来自团队外部的变更,他们仍然会进行人工审查,以确保要构建的是正确的功能。
- 审计危险代码(计费、自动更新程序、持续集成(CI)工作流)。
- 架构审查,因为这些选择会确立其他人遵循的惯例。
- 核验证据(测试输出、运行过的命令、截图、审查者评论)。如果你说不清这些检查会遗漏什么,那就不要只求一个 👍,你需要的是真正的审查!
- 承担责任。每一次上线的变更都要由一个人负责,无论代码是谁写的。
团队背景
代码审查一直兼具沟通代码库变更的双重目的。阅读同事变更的 diff,是人们通常了解发生了什么变化以及代码库如何运作的方式。如果大部分阅读工作都由机器完成,那么学习代码库的方式又会变成什么?
我们对此没有任何正式机制。团队中没有任何成员在脑中拥有 Claude Code 的完整心智模型,我们也认为没有人需要这样。相反,当有人想了解代码库的某一部分时,他们会请 Claude 针对那个确切的切片生成一份讲解。这只需要几分钟,而且讲解始终是最新的。

对我们中的一些人来说,我们会更进一步,让 Claude 生成一个小型工件,将这一区域可视化,并以我们偏好的风格进行讲解。
与逐行阅读琐碎的 diff 相比,这是集中人类注意力的更好方式,因为后者教给你的东西很少(例如一行的文案修改)。针对你将要修改的模块创建一份讲解,能教给你很多东西。
此外,我们默认是开放的,在公开的 Slack 频道中工作,并在其他人构建东西时看到他们的进展。
“你合入,你负责”
如果你合并了一个小型或中型变更,而仍然出了问题,普遍的期望通常是你会自己修复它。这种情况不会失控,有几个原因:
- 小变更易于审查、调试和回滚。
- 一切都可以回滚。功能开关、回滚和分阶段发布可以在几分钟内逆转大多数错误。
- 影响范围决定标准。代价更高的代码会得到更多关注和验证。
- 遥测和内部使用会迅速暴露回归问题。
- 这不是追责游戏。修复问题的人之所以负责,是因为他们掌握最多的上下文。事故复盘关注的是系统。
- 此外,团队中很多人通过在公开频道中工作来分担责任。任何人都能看到别人在构建什么、加入对话,或让 Claude 查找缺口。反馈也来自非代码所有者。这种开放性是质量得以保持高水平、而无需对每一行设卡的重要原因。
改变方向
有了智能体,启动新工作的成本很低,但有时你并不应该这么做。这通常发生在频道中有人指出提议的变更是一条无效路径(引用之前的决定或建议更好的路径),然后作者要么关闭 PR,要么更改实现。
因为一开始写代码就很容易,所以关闭 PR 并不会让人觉得是损失。关键在于在讨论串中尽早转向,而不是等到最后才对已定稿的 PR 提出阻塞性评论。
如何实施
这种方法的大多数组成部分已经可供你的团队使用。
提交拉取请求(PR)之前
- 给智能体一份它可以运行的检查清单。把这些检查列在一个简短的 CLAUDE.md 文件中
- 设置智能体通过钩子调用格式化和 lint(静态代码检查)工具
- 在本地运行 /code-review 和 /security-review,或让具有新上下文的子智能体审查变更
- 创建 REVIEW.md,并用它跟踪反复出现的审查问题
在每个拉取请求(PR)上
- 强制持续集成(CI)
- 更新你的 PR 模板,加入“测试”、“风险”和“如何回滚”
- 在一个仓库中,添加一个 AI 审查者(Code Review for Claude Code,或 Claude Code GitHub Action),并在几周内迭代你的 REVIEW.md,然后再推广到更多仓库。
- 添加自动安全审查
- 要求在合并前解决所有审查讨论串
- 根据风险应用审查严格度:对常规变更快速过一遍,对高风险区域(缺陷代价高昂的地方)进行彻底审查。Code Review 有 Quick、Standard 和 Deep 三个级别。
- 限制审查轮数,几轮之后只审查新的 diff。
审批
- 定义风险等级,风险等级基于变更而非作者来设定。从严格开始,随着看到证据逐步放宽。
- 为可信作者保留宽松的审批路径。
- 机器人审批不能用于满足必需的审批要求。推送新提交时,应撤销所有审批。
- 为管控认证、计费、持续集成(CI)和发布工作流的代码与政策以及安装程序指定人工审批者。为此使用 CODEOWNERS 和分支保护。
合并与合并后
- 设置合并队列
- 试用功能开关
- 先向内部用户发布
- 分阶段发布
- 建立一步式回滚机制
- 通过记录事故和回滚来构建一套评估集
- 每当更改审查者的提示词、工具或模型时,重新对其进行评分
- 跟踪人工投入,并以回滚率和事故率作为护栏
未来走向
Code Review 发布时的意图是,最终审批决定仍由人工做出。该产品所做的只是发布其审查发现。但在我们自己的仓库中,我们走得更远:负责人正在决定哪些低风险变更可在自动检查通过后自动合并。而这一边界还将继续演变。
因此,每当我们的审查者漏掉某些内容时,我们都会问自己模型的上下文中缺少了什么,并将其转化为 CLAUDE.md 文件、一项技能或一项新检查。我们的目标也没有改变:减少每次变更的人工投入,同时让回滚率不高于当前水平。
因此,如果你也允许智能体创建拉取请求(PR),请告诉我们你自动化了哪些检查、哪些需要人工处理,以及我们哪里做错了。
*这是对我们原始* 文章 *的改写,并经 Pangram 检查。*