译文｜Claude Code 团队如何进行代码审查

重新思考代码审查的目的#

当智能体开始编写代码时，变更数量会迅速增长。今年 5 月，Anthropic 单体代码库每天合入约 2,500 次变更；到了 9 月，这个数字已经超过 30,000。

Claude Code 使用独立的代码库，与单体代码库分开，但也面临着很大的压力。当交付速度达到这种程度时，人工逐行审查代码会变得极其困难，甚至不可能。

代码审查承担两项任务：

1. 在发布前发现并修复问题。
2. 在团队中建立共同的上下文，加深大家对代码库的理解。

本文主要讨论第一项任务，不过我们会在接近结尾时回到第二项。

我们认为，用“有没有人读过这段代码”来代替下面这个问题，并不够准确：

“这次变更可能出什么问题？应该用哪一种检查——自动检查还是人工检查——来发现它？”

提出这个问题，也改变了审查发生的时机。过去，审查是开发流程末尾的一道关卡：写完代码，提交 PR，然后等待同事审查。

现在，审查持续进行，更像写作时的拼写检查。大部分变更在交给人查看之前，已经至少经过一轮 Claude 的审查和修复。这能发现大多数常见错误，让团队把注意力留给更高层次的问题和更深入的检查。

稀缺的资源：人的时间和注意力#

我们希望把人的时间和注意力留给只有人才能解决的问题，其余问题则由自动检查发现。按照我们目前的变更速度，仍然有大量工作需要人来完成，团队几乎每天都会遇到新的挑战。

人的时间包含审查成本的两个方面：一方面是审查代码花费的时间，另一方面是修复有问题的代码所造成的破坏花费的时间。如果节省的审查时间只是转移到了后续修复上，那就没有意义。

因此，我们的目标是：Claude Code 各代码库——包括命令行工具、桌面应用、网页应用和移动应用——中的大部分 PR，最多只需一人参与即可合并，这个人可以就是作者本人，同时不增加回滚或事故。

为了衡量人的时间，我们追踪每个 PR 的人工批准次数，包括中位数和第 95 百分位数，以及人工评论数量、PR 等待人工处理的时长。

回滚率和事故率是约束指标：如果它们上升了，我们就没有节省人的时间，只是把时间成本转移到了别处。

一次变更的完整历程#

一次典型的变更，无论起点是工程师的电脑，还是 Slack 中的一次 Claude 会话，都会经过多层代码审查。

图 A｜一次变更的完整历程。 提交前验证 → 每个 PR 的 CI、AI 审查和安全审查 → 按风险决定人工审批人数 → 合并队列重新验证 → 内部先行使用 → 逐步发布 → 监控、修复或回滚。大部分步骤由自动化完成，人的注意力投入到存在风险的地方。

逐层检查#

图 B｜多层防线，而非单一关卡。 六层检查，下方还有回滚机制兜底。每一层都能发现一些问题，也会漏掉一些问题。能穿过全部防线的问题很少，剩下的由回滚处理。

我们如何改进审查器#

我们的代码审查流程始终处于持续改进的循环中。

现在，每次事故都会成为一个评测案例。团队收集过去引发事故的 PR，以及对应的后续修复和回滚，再请熟悉相关代码的工程师确认每个缺陷及其所在位置。审查器每天都会在这组数据上运行。

图 C｜事故就是我们的评测数据。 评测集由历史事故和回滚案例构成，每天运行；每次事故都会扩充评测集，审查器的每次变更都要在完整评测集上评分。

我们通过观察人们如何处理审查评论来衡量噪声。如果不介意报告大量并非缺陷的问题，那么发现更多缺陷并不难，因此我们需要约束这种情况。

我们根据 PR 参与者的回应，对审查器留下的每条评论进行分类：他们修复了问题、认为评论有误、说明该行为是有意设计的，或者判断它无关紧要。

我们还会让审查器检查已知没有问题的 PR，统计它报告的问题中，有多少会诱导别人做出有害修改。

我们明确写下的优先级是：首先发现真实缺陷，其次减少审查轮数。

当作者是智能体时，噪声的成本更高。人可以在几秒钟内忽略一个细枝末节的问题，智能体却会动手修复，进而产生一个新提交和新一轮审查。

审查必须能够收敛。智能体作者和智能体审查器可能让彼此无限忙碌下去。有一个命令行工具 PR，在一夜之间经历了超过 50 轮审查和修复，最后才被作者叫停。

我们对审查器不断指出的代码运行 git blame，发现其中约 59% 的代码从第一轮审查时就已经存在。审查器很少发现新的缺陷，而是在每一轮中再找出一些旧缺陷。

我们自己的习惯也加剧了这个问题。因为每轮审查都会发现新问题，我们已经习惯默认运行多轮审查。对高风险变更来说，这可能值得，但不该用于每一个 PR。

现在，团队除了追踪召回率，也会追踪通过审查所需的轮数，并调整了重复审查的方式：

• 限制轮数。 三轮之后，审查器会要求作者退一步，重新考虑实现方案。
• 最初几轮之后，只重新审查新增的代码差异。
• 指出缺陷所属的类别，让作者修复所有同类情况，而不是只改一行。
• 不重复报告已经发布过的问题。

审查智能体还会每晚检查现有代码，帮助我们在旧缺陷于其他地方暴露之前发现它们。

图 D｜能够收敛的审查。 调整前后内部 PR 的对比显示，改进收敛机制后，每个 PR 所需的审查轮数减少了。

哪些环节仍然需要人#

让一名资深工程师从深度工作中抽身，去发现一个常见错误，其代价远高于一次自动审查。

在 Anthropic，我们的工作已经从阅读每一份代码差异，转向机器不擅长的决策：

• 我们究竟该不该做这件事？ 包括方向、品味和范围。有个团队宣布审查瓶颈已经解决，但仍然保留了对团队外部变更的人工审查，确保有人会问：“我们到底该不该做这个？”
• 高风险代码。 例如计费、自动更新器和持续集成工作流。
• 会成为后续范例的架构。 因为其他人会模仿这些设计。
• 阅读证据。 包括测试输出、执行的命令及其返回结果、截图，以及审查器发现的问题。如果你说不清这些检查会漏掉什么，就应该要求一次真正深入的审查，而不是快速批准。
• 对结果负责。 无论代码是谁写的，每次上线变更都必须有人承担责任。

图 E｜由人作决定的地方。 五类决策仍由人负责，其他地方则广泛运行自动检查。人的工作从阅读每份代码差异，转向机器不擅长的判断。

在团队中共享上下文#

代码审查的第二项任务，一直是传播对代码库的理解。阅读同事的代码差异，是了解发生了什么变更、各部分如何配合的一种方式。

如果大部分阅读工作都由机器完成，人又该如何学习代码？

我们没有为此建立正式流程。团队里没有人会在脑海中保留 Claude Code 完整的心智模型，我们也不认为有人需要这样做。

当某人想理解代码库中的某个部分时，就让 Claude 针对那个具体部分写一份说明。只需几分钟，而且说明反映的是代码当前的实际状态。

图解｜机器读代码，人如何学习？ 先确定想理解的部分，例如托管设置，再向 Claude 提问：“Claude Code 如何获取托管设置？”Claude 可以生成说明，也可以创建小型可视化作品，以适合个人的方式帮助理解。

我们中的一些人还会更进一步，让 Claude 制作一个小型可视化作品，展示那部分代码，并按照自己喜欢的学习方式来讲解。

如果目标是合理使用人的注意力，这比逐行阅读琐碎的代码差异更有效。修改一行文案，几乎教不会你什么；而一份解释你即将修改的模块的说明，则能让你学到很多。

我们默认在公开 Slack 频道中开展工作的文化也有帮助，因为你能在其他人开发的过程中，看到他们正在构建什么。

“谁合入，谁负责”#

如果你合入了一项小型或中型变更，之后仍然出了问题，团队的惯例是通常由你来修复。

以下几点让这套做法能够良好运转：

• 变更规模小，因此容易审查、调试和回滚。
• 一切都可以撤销。功能开关、回滚和分阶段发布，让大多数错误能在几分钟内被撤销。
• 影响范围决定要求。出错代价高的代码，需要更多人参与、更多检查。
• 遥测和内部使用能快速暴露回归。
• 这不是追责。由你修复，是因为你最了解上下文；事故复盘关注的是系统。

责任也是共享的。团队中的许多人在公开频道工作，任何人都能看到别人正在构建什么、接手某段讨论，或者让 Claude 去补上某个缺口。反馈也来自并不负责相关代码的人。

这种开放性，是我们无需对每一行代码都设置人工关卡、仍能保持高质量的重要原因。

我们什么时候改变方向#

智能体让启动工作的成本变得很低，因此有些工作最终就不应该合入。

通常，频道里会有人问为什么要做、指出之前已经作出的决定，或者提出更简单的路径。随后，作者会关闭 PR，或重新调整它。

因为代码写得很快，关闭 PR 并不会让人觉得损失很大。

关键是尽早在讨论中提出不同方向，而不是等 PR 已经完成，再留下一条阻止合并的评论。

你的团队如何采用这套流程#

现在，实现这套流程所需的大多数组成部分都已经具备。

接下来会如何发展#

Code Review 的发布公告曾表示，批准 PR 仍然是人的决定；产品负责报告发现的问题，而不负责批准。

我们自己的代码库走得更远一些：允许负责人决定哪些低风险变更可以仅凭自动检查合并，而且这条边界仍在不断变化。

当审查漏掉问题时，我们会追问：模型当时缺少什么信息？随后，把相应改进加入 CLAUDE.md、某项技能，或者新的检查中。

目标始终没有改变：减少每次变更所需的人工时间，同时不让回滚变得更多。

如果你的团队允许智能体创建 PR，我们很想听听：哪些检查已经自动化，哪些仍然需要人，以及你认为我们哪里做得不对。

感谢 Emma Webb、Michael Segner 和 Amie Rotherham 对本文的审阅。

阅读英文原文