> ## Documentation Index
> Fetch the complete documentation index at: https://base.bangwu.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent 写代码时代的评审

> 当 Agent 承担大部分代码量时，如何用分层检查、发现验证、按风险分层审批、收敛限制和评审器评测保证变更可审；同时别让审批权限变成摆设。

# Agent 写代码时代的评审

当 Agent 产出大部分 diff 时，"每个改动都有人逐行读过吗"已经不是一个有用的指标。更该问的是：**这个改动可能出什么问题，哪一道检查——自动的还是人工的——最适合抓住它？**

Anthropic 的 Claude Code 团队公开了他们的一种答案：该仓库约九成代码由 Claude 编写，6 月到 9 月合并的 PR 数量翻了一倍多，同期需要撤回的比例下降了四成多。这些是单个团队自报的结果，不是照搬流程就必然复现的承诺。

## 把单一门禁换成多层检查

只设一道评审门禁，风险集中在一个方向：全部依赖评审者的注意力。分层的好处是容忍单点遗漏，因为每一层覆盖不同的失败类型。

| 层 | 应抓住的问题 | 常见手段 |
| - | - | - |
| PR 之前的自我验证 | 只有"已完成"的说法，没有证据 | 测试、构建、截图、新上下文子代理评审 |
| 每个 PR 的自动评审 | 快速扫读会漏掉的逻辑与集成 bug | 并行查找 + 独立验证 |
| 安全评审 | 可被利用的改动 | 独立评审，发现问题必须处理 |
| 阻塞式 CI | 机械性破坏 | Lint、类型、跨平台测试、构建 |
| 按风险分层的审批 | 判断力与影响范围 | 由**改动**而非作者决定档位 |
| 合并队列、开关、分批发布 | 两个各自通过的 PR 组合出错 | 在 `main` 上重跑检查；可回滚的发布 |
| 快速发现 | 仍然漏过去的错误 | 看板、on-call、一键回滚 |

最后一层不能省。只增加自动化、却无法快速发现并撤销坏改动，并没有降低风险，只是把发现成本推到了下游。

## 先验证，再提交评审意见

一个什么都报的评审器比没有更糟，因为每条噪音都要多花一轮；当作者也是 Agent 时代价更大——它会去修补那个 nit，而不是判断它无关紧要。

Claude Code 的 Code Review 在 Anthropic 基础设施上分四步：

1. **查找（Find）**：多个 Agent 并行检查 diff 与周边代码。
2. **验证（Verify）**：对候选问题回到代码核对，过滤误报。
3. **排序（Rank）**：去重后按严重程度排序。
4. **发布（Post）**：行内评论、摘要，以及 PR 上的 check run。

每条问题只有三种级别：**Important**（合并前应修复）、**Nit**（次要）、**Pre-existing**（代码里本来就有、不是本 PR 引入的 bug）。第三类很关键：没有它，无关的历史遗留问题会被读成作者的锅，评审器的可信度随之下降。

有两个产品行为容易被误读：

* **评审从不批准、也不阻塞 PR。** 合并权仍在团队手里，check run 也不会判为失败。
* **没问题不等于安全。** 官方文档明确写着：没有发现问题，不代表代码正确或安全。

如果想让 CI 依据评审结果做门禁，就要显式解析机器可读的结论行。文档指出：结论行缺失代表**没有结论**（评审失败、超时或被更新的一次取代），而不是零问题。把"缺失"当成通过，等于让门禁失效。

## 让审批权限真正有约束力

风险分层只有在无法绕过时才有意义。Claude Code 团队的规则可作为一组参考：

* **档位由改动决定，不由作者决定。** 一个分类器读改动内容，第二个分类器再判断这次改动是否仍需人工。
* **轻量路径只对受信作者开放。** 其他人一律需要第二位审批人。
* **机器人的批准不能顶替人工名额。** 自动评审可以让低风险改动过关，但替代不了必须的人。
* **让 Agent 干活的人算必选评审人**，等同于自己动手写了这些代码。
* **一次批准只对应当前提交。** 出现系统无法担保的新提交——Agent 推送、手工解决冲突的合并——需要重新审批。
* **某些路径永远需要人。** 敏感路径和 CI 工作流文件是典型例子；用 `CODEOWNERS` 和分支保护强制执行，而不是靠约定。

这些控制属于仓库和 CI 配置，不属于提示词。"不要合并高风险改动"这句话不是权限边界。这个道理和[付费操作要交还用户确认](/zh/env/agent-harness#把候选查询与购买审批分开)是同一个。

## 让评审能够收敛

Agent 作者和 Agent 评审者可以无限互相消耗。公开案例里有一个 CLI PR 通宵走了五十多轮评审与修复，最后被作者叫停。追溯评审者反复指出的位置，约 59% 是它第一轮就已经存在的代码——它在每轮多挖出一些旧问题，而不是新问题。

有助于收敛的做法：

* **限制轮次。** 大约三轮后停下来重新考虑方案，而不是再要一轮。
* **前几轮之后只看新增 diff**。
* **按 bug 类别提出**，让作者修掉所有同类实例，而不是改一行。
* **不重复**已经提过的问题。
* **跨轮去重**：与仍打开的讨论比对。

除了召回率，还要跟踪"通过所需轮次"。多找出一点点却要多花一倍轮次，通常是净亏。

## 用安全护栏衡量省下的人工时间

只优化评审分钟数会引来明显的反噬：省下的时间以线上事故的形式还回去。护栏让这笔交易可见。

Claude Code 团队跟踪每个 PR 的人工批准次数（中位数与 95 分位）、人工评论数、以及 PR 等待人的时长，并把**撤回率和事故率当作天花板**。撤回率一升，省下的评审时间就不算省下。

他们还通过观察作者对评论的反应来衡量**噪音**：修了、说评审错了、说这是有意行为、或者没管。另外会在已知干净的 PR 上跑评审器，统计会导致有害改动的误报。召回率很容易注水，反应分布才是诚实信号。

## 把事故变成评审器的评测集

这是整套流程里最可复用的部分：把过去导致事故的 PR（连同其 fix-forward 和撤回）收集起来，请熟悉该代码的工程师确认每个 bug 及位置，让评审器每天对着这个集合跑。评审器的提示词、工具或模型一变，就重新打分。

这和[用人工标签校准 LLM 裁判](/zh/env/ai-evals#用人工标签校准裁判)是同一套纪律：保留带标签的真实失败、纳入干净样本、配置一改就重新验证。

## 把评审指令写在正确的文件里

有两个文件会决定报什么，二者不能互换：

* **`CLAUDE.md`** 承载项目背景——技术栈、约定、非目标。每次评审都会加载；违反其中约定的改动可能成为问题项。
* **`REVIEW.md`** 承载只针对评审的规则：这个仓库里各级别的含义、nit 上限、要跳过的路径、证据要求。

好指令通常很短且行为化。有效的写法：

* 为这个仓库重新定义 **Important**——文档仓库和计费服务的标准差别很大。
* **限制 nit 数量**，让摘要仍可执行。
* 跳过生成代码、lockfile，以及 CI 已经覆盖的检查。
* 行为类结论要求 **`file:line` 证据**，而不是从命名推测。

有一个安全属性值得理解：`REVIEW.md` 从 PR 的**基础分支或默认分支读取，绝不从 PR 自己的改动里读**。否则一个 PR 就能削弱审判自己的规则。部分指令——降低级别、排除路径、限制 nit——只有在受保护的默认分支根文件中才生效；如果服务无法确认分支保护状态，可能完全不读 `REVIEW.md`。依赖这些调整之前，先保护分支。

## 落地清单

PR 之前：

* 给 Agent 可运行的检查，写进简短的 `CLAUDE.md`，并用 hook 跑 formatter 和 linter。
* 本地跑 `/code-review`、`/security-review`，或让新上下文的子代理评审。
* 把反复出现的评审意见搬进 `REVIEW.md`。

每个 PR：

* 强制 CI，并在模板里加入 **Testing**、**Risk**、**How to revert**。
* 先在一个仓库启用 AI 评审，调几周指令，再扩大范围。
* 合并前要求所有评审讨论已解决。
* 按风险匹配强度；限制轮次，前几轮之后只看新增 diff。

审批与事后：

* 写下风险档位，从严格开始，有证据再放宽。
* 用 `CODEOWNERS` 和分支保护让敏感路径始终需要人。
* 机器人的批准不能顶替必需的人工；新提交要重新审批。
* 把事故与撤回变成评审器的评测集；用人时和撤回率一起衡量。

## 参考资料

* [宝玉：Claude Code 团队的审代码做法](https://x.com/dotey/status/2111384189656252712) — 2026-10-17 的 Folo 线索，指向该团队原文
* [How the Claude Code team does code review](https://claude.dev/blog/solving-code-review-at-anthropic/) — 分层检查、风险档位、收敛措施、评审器评测与落地步骤
* [Claude Code：Code Review](https://code.claude.com/docs/en/code-review) — 四阶段流程、评审强度级别与明确的能力边界
* [读取并请求 PR 评审](https://code.claude.com/docs/en/code-review-pull-requests) — 严重级别、check run 行为与机器可读结论
* [自定义 Code Review](https://code.claude.com/docs/en/code-review-customize) — `REVIEW.md` 与 `CLAUDE.md` 的分工，以及从哪个分支读取规则
* [Bringing Code Review to Claude Code](https://claude.com/resources/articles/code-review) — 厂商自报的预览期数据（16% → 54%、大 PR 命中率、不足 1% 被判错误）
* [Code Review 正式可用](https://claude.com/resources/articles/code-review-is-now-generally-available) — Quick／Standard／Deep 三档与更快的评审


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.