好的评估能让团队更有底气地把 AI agent 发出去。没有评估，团队很容易陷进反应式的循环：问题只在生产环境里暴露，修好一个又冒出一个。评估让问题和行为变化在影响用户之前就可见，而且它的价值会在 agent 的整个生命周期里不断累积。
正如我们在《Building effective agents》里说过的，agent 会跨很多轮工作：调用工具、改动状态、根据中间结果调整策略。让 AI agent 变得有用的那些特性——自主性、智能、灵活性——同时也让它更难被评估。
通过内部实践，以及和处在 agent 开发前沿的客户合作，我们摸出了一些更严谨、也更有用的评估设计方法。下面这些做法，在多种 agent 架构和真实部署场景里都验证过。
评估（eval）就是给 AI 系统做的一次测试：给它一个输入，然后用评分逻辑给输出打分，衡量是否成功。本文讨论的是自动化评估——不需要真实用户，在开发过程中就能跑。
单轮评估很直白：一个提示词、一个回答、一套评分逻辑。早期的 LLM 主要用单轮、非 agent 的评估。随着能力提升，多轮评估变得越来越常见。
Agent 评估还要更复杂。agent 会跨多轮使用工具，一边改环境状态一边调整策略——这意味着错误会传播、会叠加。前沿模型还能找到超出静态评估想象的解法。比如 Opus 4.5 在做 𝜏2-bench 的一道订票题时，发现了政策里的一个漏洞：按题面它算「失败」了，但实际上它给出了对用户更好的方案。
构建 agent 评估时，我们用下面这套定义：
团队刚开始做 agent 时，靠手动测试、自己吃自己的狗粮、加上直觉，往往能走得比想象中远。更严谨的评估看起来像是拖慢交付的额外开销。但过了原型阶段、agent 上了生产开始放量之后，没有评估的开发方式就开始崩了。
崩溃点通常出现在这里：用户反馈「改完之后感觉变差了」，而团队完全在瞎飞——除了猜和试，没有任何验证手段。没有评估，调试就是反应式的：等投诉、手动复现、修掉、祈祷别的地方没被弄坏。团队分不清真正的回归和噪声，没法在发布前拿几百个场景自动验证改动，也量不出改进。
这个过程我们见过很多次。Claude Code 起步时，靠 Anthropic 内部员工和外部用户的反馈快速迭代；后来才开始加评估——先是很窄的领域，比如简洁度、文件编辑，再到更复杂的行为，比如过度设计。这些评估帮忙定位问题、指导改进、聚焦研究与产品的协作。再加上生产监控、A/B 测试、用户研究，评估给了 Claude Code 在规模变大时继续改进的信号。
在 agent 生命周期的任何阶段，写评估都有用。早期，评估逼着产品团队把「什么叫成功」说清楚；后期，它帮团队守住一致的质量线。
Descript 的 agent 帮用户剪视频，他们围绕成功剪辑流程的三个维度建了评估：别弄坏东西、按我说的做、做好。评分方式从人工打分演进到 LLM 评分（判据由产品团队定义、定期用人工校准），现在他们常态化跑两套：一套做质量基准，一套做回归测试。Bolt 的 AI 团队起步更晚，那时他们的 agent 已经有大量用户；三个月里，他们搭出了一套评估系统：跑 agent、用静态分析给输出打分、用浏览器 agent 测应用、用 LLM 裁判评「是否遵循指令」这类行为。
有的团队在开发之初就建评估，有的等到上规模、评估成了改进瓶颈时才补。评估在开发早期尤其有用：它把期望的行为显式写下来。两个工程师读同一份初始 spec，对「AI 该怎么处理边界情况」可能理解不同，一套评估用例就能消除这种歧义。无论什么时候建，评估都能加速开发。
评估也决定你能多快换上新模型。更强的模型出来时，没有评估的团队要花几周测试，而有评估的对手几天内就能摸清新的强弱、调好提示词、完成升级。
一旦有了评估，等于免费获得基线和回归测试：延迟、token 用量、单任务成本、错误率，都可以在一组固定任务上持续跟踪。评估还能成为产品团队和研究团队之间带宽最高的沟通渠道，定义出研究员可以优化的指标。评估的好处远不止盯回归——只是它的成本在前、收益在后，复利效应容易被忽略。
今天大规模部署的 agent 主要有几类：编码 agent、研究 agent、计算机操作 agent、对话 agent。类型之间行业差异很大，但评估技术可以通用。你不需要从零发明一套评估方法——下面几节讲的是各类 agent 上验证过的做法，可以直接当作地基，再扩展到你的领域。
agent 评估通常混合三种评分器：基于代码的、基于模型的、人工的。每种评分器评的是轨迹或结果的一部分。有效评估设计的关键之一，是为活选对评分器。
| 评分器 | 方法 | 优势 | 局限 |
|---|---|---|---|
| 基于代码 | 字符串匹配（精确、正则、模糊等）；二元测试（fail-to-pass、pass-to-pass）；静态分析（lint、类型、安全）；结果校验；工具调用校验（用了哪些工具、参数对不对）；轨迹分析（轮数、token 用量） | 快；便宜；客观；可复现；容易调试；能验证特定条件 | 对「与预期不完全一致的合理变体」很脆；缺乏细微度；不太适合评估偏主观的任务 |
| 基于模型 | 按评分量表打分；自然语言断言；两两对比；参照式评估；多裁判共识 | 灵活；可扩展；能捕捉细微差别；能处理开放式任务；能处理自由格式输出 | 不确定；比代码贵；要和人工评分对齐校准，才谈得上准确 |
| 人工 | 领域专家评审；众包判断；抽样抽查；A/B 测试；标注者一致性 | 金标准质量；贴近专家用户的判断；用来校准模型评分器 | 贵；慢；通常需要能规模化触达的人类专家 |
每个任务的计分方式可以是加权的（多个评分器得分合起来要过阈值）、二元的（所有评分器都必须通过），或者混合的。
能力型（质量型）评估问的是「这个 agent 能把什么做好」。它应该从很低的通过率开始，瞄准 agent 还做不好的任务，给团队一座要爬的山。
回归型评估问的是「它原来会做的那些事，现在还做得好吗」，通过率应该接近 100%。它防止倒退：分数掉了，就说明有东西坏了、需要修。团队在能力型评估上往上爬的时候，一定要同时跑回归型评估，确保改动没有在别处闯祸。
agent 上线并调优之后，那些通过率已经很高的能力型评估可以「毕业」，变成持续运行的回归套件，用来发现漂移。曾经衡量「我们到底能不能做到」的任务，这时衡量的是「我们能不能稳定地做到」。
编码 agent写代码、跑测试、调 bug，像人类开发者一样在代码库里穿行、执行命令。对现代编码 agent 有效的评估，通常依赖任务描述清晰、测试环境稳定、对生成代码的测试足够全面。
确定性评分器天然适合编码 agent，因为软件好不好评是很直白的：代码跑不跑得起来、测试过不过。两个被广泛使用的基准就走的这条路：SWE-bench Verified 把热门 Python 仓库的 GitHub issue 交给 agent，用跑测试套件的方式打分——修好失败的测试、同时不弄坏已有测试，才算通过。一年之内，LLM 在这个评估上的成绩从 40% 涨到了 80% 以上。Terminal-Bench 走另一条线：测端到端的技术任务，比如从源码编译 Linux 内核、训练一个 ML 模型。
当你手上有一组能判断编码任务关键结果的通过/失败测试之后，通常还值得把轨迹也评一遍。比如基于启发式规则的代码质量检查，可以依据「测试通过」之外的东西来评价生成的代码；带清晰评分量表的模型评分器，可以评 agent 怎么调工具、怎么和用户互动。
示例：一个编码 agent 的理论评估
设想一个任务：agent 要修掉一个认证绕过漏洞。下面这份示意性的 YAML 展示了如何用多个评分器和指标来评估它。
yamltask:
id: "fix-auth-bypass_1"
desc: "Fix authentication bypass when password field is empty and ..."
graders:
- type: deterministic_tests
required: [test_empty_pw_rejected.py, test_null_pw_rejected.py]
- type: llm_rubric
rubric: prompts/code_quality.md
- type: static_analysis
commands: [ruff, mypy, bandit]
- type: state_check
expect:
security_logs: {event_type: "auth_blocked"}
- type: tool_calls
required:
- {tool: read_file, params: {path: "src/auth/*"}}
- {tool: edit_file}
- {tool: run_tests}
tracked_metrics:
- type: transcript
metrics:
- n_turns
- n_toolcalls
- n_total_tokens
- type: latency
metrics:
- time_to_first_token
- output_tokens_per_sec
- time_to_last_token
注意，这个例子把可用的评分器铺满，是为了演示。实践中，编码评估通常靠单元测试验正确性、靠一个 LLM 评分量表评整体代码质量，其余评分器和指标按需再加。
对话 agent在客服、销售、教练这类领域与用户交流。和传统聊天机器人不同，它们维护状态、调用工具、在对话中途执行动作。编码和研究 agent 同样会与用户多轮交互，但对话 agent 有个独特的挑战：交互本身的质量就是你要评的东西之一。有效的评估通常依赖可验证的终态结果，加上能同时反映任务完成度和交互质量的评分量表。和大多数评估不同，它们往往需要第二个 LLM 来扮演用户。
对对话 agent 来说，成功可以是多维的：工单解决了吗（状态检查）？十轮之内完成了吗（轨迹约束）？语气合适吗（LLM 评分量表）？𝜏-Bench 和它的后继者 τ2-Bench 就体现了这种多维性：它们在零售客服、机票预订等领域模拟多轮交互，一个模型扮演用户人设，另一个 agent 在贴近真实的场景里应对。
示例：一个对话 agent 的理论评估
设想一个客服任务：agent 要处理一位不满意客户的退款。
yamlgraders:
- type: llm_rubric
rubric: prompts/support_quality.md
assertions:
- "Agent showed empathy for customer's frustration"
- "Resolution was clearly explained"
- "Agent's response grounded in fetch_policy tool results"
- type: state_check
expect:
tickets: {status: resolved}
refunds: {status: processed}
- type: tool_calls
required:
- {tool: verify_identity}
- {tool: process_refund, params: {amount: "<=100"}}
- {tool: send_confirmation}
- type: transcript
max_turns: 10
tracked_metrics:
- type: transcript
metrics:
- n_turns
- n_toolcalls
- n_total_tokens
- type: latency
metrics:
- time_to_first_token
- output_tokens_per_sec
- time_to_last_token
同样，这个任务铺开多种评分器是为了演示。实践中，对话 agent 评估通常用基于模型的评分器同时评沟通质量和目标达成度，因为很多任务——比如回答一个问题——本来就可能有多个「正确」答案。
研究 agent收集、综合、分析信息，产出答案或报告。编码 agent 有单元测试给出二元信号，研究质量却只能相对任务来判。什么算「全面」「来源可靠」，甚至「正确」，都取决于场景：市场扫描、并购尽调、科研报告，标准各不相同。
研究评估有它特有的难点：专家之间对「综合得够不够全」可能就有分歧；随着参考内容变化，真值本身也在漂移；输出越长越开放，出错的空间也越大。像 BrowseComp 这样的基准，测的是 AI agent 能不能在开放网络里大海捞针——题目被设计成容易验证、极难解出。
一个可行的思路是组合多种评分器：有据可依检查论断是否有检索到的来源支撑；覆盖度检查一个好的答案必须包含哪些关键事实；来源质量检查引用的来源是否权威，而不是「第一个检索到的」。对客观题（「X 公司 Q3 营收多少」），精确匹配就够。LLM 可以标出没有支撑的论断和覆盖缺口，也能评估开放式综述的连贯性和完整性。
鉴于研究质量的主观性，基于 LLM 的评分量表应该经常用人类专家的判断来校准，才谈得上有效。
计算机操作 agent通过和人类相同的界面与软件交互——截图、点击、键盘输入、滚动——而不是走 API 或执行代码。它们能用任何带图形界面的应用，从设计工具到老式企业软件。评估要求在真实或沙箱环境里把 agent 跑起来，让它操作软件，然后检查是否达成了预期结果。WebArena 就用 URL 和页面状态检查来验证 agent 是否走对了路径，对会改数据的任务再加一层后端状态验证（确认订单真的下了，而不只是出现了确认页）。OSWorld 把范围扩到整个操作系统：任务完成后用脚本检查各种产物——文件系统状态、应用配置、数据库内容、UI 元素属性。
浏览器 agent 要在 token 效率和延迟之间取舍。基于 DOM 的交互执行快，但很吃 token；基于截图的交互慢，但更省 token。比如让 Claude 总结维基百科，从 DOM 里提文本更高效；而在 Amazon 上找一个笔记本内胆包，截图更高效（把整个 DOM 提取出来太贵）。在 Claude for Chrome 里，我们建了评估来检查 agent 是否为每个场景选了合适的工具，这让浏览器任务跑得更快也更准。
无论哪类 agent，行为每次运行都不一样，这让结果比表面上更难解读。每个任务有自己的成功率——这个任务 90%，那个 50%——这次通过的任务下次可能就挂了。有时候我们真正想量的是：agent 在一个任务上成功的比例。
两个指标能刻画这件事：
pass@k 衡量 agent 在 k 次尝试里至少蒙对一次的概率。k 越大，pass@k 越高：射门次数多，至少进一个的机会就大。pass@1 为 50%，意思是模型第一次尝试就解出了一半任务。编码场景里我们通常最关心第一次就解出来——pass@1。另一些场景里，只要有一个方案能用，提很多方案也没问题。
pass^k 衡量 k 次试验全部成功的概率。k 越大，pass^k 越低，因为要求更多次都保持一致是更难的门槛。假设单次成功率 75%，跑 3 次全过的概率是 0.75³ ≈ 42%。对面客的 agent，这个指标尤其重要——用户期待每次都是可靠的。
两个指标都有用，用哪个取决于产品要求：一次成功就够用的工具看 pass@k，一致性至关重要的 agent 看 pass^k。
这一节是我们从「没有评估」走到「评估可信」的实践经验。可以把它当成评估驱动开发的路线图：早点定义成功，把它量清楚，然后持续迭代。
第 0 步：尽早开始。我们看到很多团队迟迟不建评估，因为他们觉得需要几百个任务。实际上，从真实失败里挑 20 到 50 个简单任务就是很好的开始。毕竟在 agent 开发早期，系统每一次改动往往效果都很明显，效应量大，样本小也够用。更成熟的 agent 才需要更大、更难的评估套件来检测更小的效应，但一开始最好走 80/20。评估这事拖得越久越难建：早期产品需求天然就能翻译成测试用例；拖久了，你就是在从一个已经跑起来的系统里反推成功标准。
第 1 步：从你已经在手工测的东西开始。先把你开发时手动的检查搬过来——每次发版前会验的行为、用户常试的任务。如果已经在生产环境，就翻 bug 跟踪器和客服队列。把用户报的失败变成测试用例，能保证套件反映真实使用；按影响面排序，能把力气花在刀刃上。
第 2 步：写无歧义的任务，并配参考解。任务质量比看上去难把握。一个好的任务，是两位领域专家独立判断会得出一致通过/失败结论的任务。他们自己能做出来吗？做不出来，任务就得改。任务描述里的歧义，最后都会变成指标里的噪声。给模型评分器写判据同理：含糊的评分量表只会产出前后矛盾的判断。
每个任务都应该是「一个正确遵循指令的 agent 能通过」的。这一点很微妙。比如审计 Terminal-Bench 时发现：如果任务让 agent 写脚本但没指定路径，而测试假定了某个特定路径，agent 就可能因为不是自己的错而失败。评分器要检查的一切，都应该在任务描述里说清楚；agent 不该因为规格含糊而失败。对前沿模型来说，在大量试验上通过率为 0（也就是 pass@100 为 0），通常说明任务坏了，而不是 agent 不行——这时该回头检查任务描述和评分器。为每个任务准备一个参考解（一份能通过所有评分器的已知可用输出）很有用：它证明任务可解，也验证了评分器配置是否正确。
第 3 步：构建均衡的问题集。行为该出现的场景和不该出现的场景都要测。单边的评估只会带来单边的优化。比如你只测「该搜索时是否搜索」，最后可能得到一个什么都去搜的 agent。尽量避免类别不平衡的评估。这一点我们是在给 Claude.ai 做网页搜索评估时亲身体会的：难点在于既不让模型在不该搜的时候去搜，又保住它在合适时机做深入调研的能力。团队从两个方向都建了用例：该搜的查询（比如查天气），和该靠已有知识回答的查询（比如「苹果公司是谁创办的」）。在「该搜不搜」和「不该搜乱搜」之间找平衡很难，提示词和评估都迭代了很多轮。随着新例子出现，我们持续往里加用例来扩大覆盖。
第 4 步：搭一个稳健的评估脚手架和稳定的环境。评估里的 agent 必须和生产里的 agent 行为大致一致，环境本身也不能引入额外噪声。每次试验都应该从干净环境开始，做到「隔离」。运行之间不必要的共享状态（残留文件、缓存、资源耗尽）会让失败彼此相关——那是基础设施不稳，不是 agent 表现。共享状态也可能虚高成绩：在某些内部评估里，我们观察到 Claude 通过翻看前几次试验留下的 git 历史，在某些任务上获得了不公平的优势。如果多个不同的试验因为同一个环境限制（比如 CPU 内存不足）而失败，它们就不是独立的，评估结果也就不可信。
第 5 步：认真设计评分器。如前所述，好的评估设计就是为 agent 和任务挑对评分器。我们建议：能用确定性评分器就用；需要灵活性或做不到时用 LLM 评分器；人工评分器留作补充验证，用得克制。
有一种常见的冲动：检查 agent 是否按非常具体的步骤走，比如按顺序调用一串工具。我们发现这种做法太僵硬，会造出很脆的测试——agent 经常能找到评估设计者没想到的合理路径。为了不无谓地惩罚创造力，更好的做法通常是评 agent 产出了什么，而不是它走了哪条路。
对多组件的任务，要设置部分得分。一个正确识别了问题、验证了客户身份、但没能完成退款的客服 agent，明显好过一个一上来就失败的。把这种成功程度的连续谱反映到结果里很重要。
模型评分往往需要仔细迭代才能保证准确。LLM 裁判要跟人类专家紧密校准，你才能确信人工打分和模型打分的分歧很小。为了避免幻觉，给 LLM 一条退路——比如指示它在信息不足时返回「Unknown」。给任务的每个维度写清晰、结构化的评分量表，然后用彼此独立的 LLM 裁判分别评每个维度，而不是让一个裁判评所有维度，也会更有帮助。系统稳健之后，偶尔用人工复核就足够了。
有些评估存在隐蔽的失效模式：即使 agent 表现很好，分数依然很低——因为评分器的 bug、脚手架的约束或任务歧义让 agent 做不出来。再成熟的团队也可能漏掉这些。比如 Opus 4.5 在 CORE-Bench 上最初只有 42%，直到一位 Anthropic 研究员找出了多个问题：评分过于死板（期望「96.124991…」时把「96.12」判为错）、任务描述含糊、以及本来就不可能精确复现的随机性任务。修掉这些 bug、换用限制更少的脚手架之后，分数跳到了 95%。类似地，METR 在他们的时间跨度基准里发现若干配置错误的题目：题目让 agent 优化到某个明确分数阈值，但评分要求超过这个阈值——结果像 Claude 这样照指令做的模型被扣分，而无视目标的模型反而得分更高。仔细复核任务和评分器，能避免这类问题。
让评分器抗绕过、抗作弊。agent 不该能轻易「骗过」评估；任务和评分器应该设计成：通过真的意味着解决了问题，而不是钻了没预料到的空子。
第 6 步：读轨迹。不读的话，你不会知道评分器到底好不好用。在 Anthropic，我们投入做了查看评估轨迹的工具，并会定期花时间读。任务失败时，轨迹能告诉你：是 agent 真做错了，还是评分器拒绝了一个合理方案。它往往还会暴露出关于 agent 和评估行为的关键细节。
失败应该是「讲得通」的：agent 错在哪、为什么错，都很清楚。分数上不去时，我们需要确信那是 agent 表现的问题，而不是评估的问题。读轨迹是验证「评估测的东西是否真的重要」的方式，也是开发 agent 的一项关键技能。
第 7 步：盯住能力型评估的饱和。一个 100% 通过的评估只能盯回归，提供不了改进信号。评估饱和指的是 agent 把所有可解任务都做对了，没留下改进空间。比如 SWE-Bench Verified 今年年初还是 30%，现在前沿模型已经逼近饱和，超过 80%。接近饱和时进展也会变慢，因为只剩最难的题目——这会让结果产生误导：能力的大幅提升，在分数上只表现为小幅上涨。代码审查创业公司 Qodo 起初对 Opus 4.5 无感，因为他们的单次编码评估捕捉不到在更长、更复杂任务上的收益；后来他们做了一套新的 agent 评估框架，才看清进步。
我们的原则是：在有人深入看过评估细节、读过一些轨迹之前，不把分数当作定论。如果评分不公平、任务有歧义、合理方案被扣分、或者脚手架限制住了模型，评估就该重做。
第 8 步：靠开放共建和长期维护让套件保持健康。评估套件是活的资产，需要持续投入和明确的责任人，才有用。
在 Anthropic，我们试过多种维护方式。最有效的是：设立专门的评估团队负责核心基础设施，而领域专家和产品团队贡献大部分任务，并自己跑评估。
对 AI 产品团队来说，拥有并迭代评估，应该像维护单元测试一样日常。团队可能在一个 AI 功能上浪费好几周：早期测试里「能用」，却没满足那些没被说出口的期待——而一套设计良好的评估本可以早早暴露它们。定义评估任务，也是检验「产品需求是否具体到可以开工」的最好方式之一。
我们建议实践评估驱动开发：在 agent 还做不到之前，先用评估定义计划中的能力，然后迭代到做得好为止。内部很多功能今天只是「够用」，本质是在赌模型几个月后的能力；从低通过率起步的能力型评估让这件事变得可见。新模型一发布，跑一遍套件就能看出哪些赌注兑现了。
最贴近产品需求和用户的人，最适合定义成功。以现在的模型能力，产品经理、客户成功、销售都可以用 Claude Code 以 PR 的形式贡献一条评估任务——让他们来，甚至更好地，主动创造条件让他们能来。
自动化评估可以在不上生产、不影响真实用户的前提下，让 agent 跑上千个任务。但这只是理解 agent 表现的众多方式之一。完整的图景还包括生产监控、用户反馈、A/B 测试、人工读轨迹和系统化的人工研究。
| 方法 | 优点 | 局限 |
|---|---|---|
| 自动化评估 不用真实用户，用程序跑测试 |
迭代快；完全可复现；不影响用户；每次提交都能跑；不用发版就能测大量场景 | 前期投入大；产品和模型演进时要持续维护，否则会漂移；如果与真实用法脱节，会造成虚假的信心 |
| 生产监控 跟踪线上指标与错误 |
能反映大规模下的真实用户行为；抓到合成评估漏掉的问题；给出 agent 真实表现的基准事实 | 被动：问题先到用户那里你才知道；信号噪声大；要做埋点投入；缺少用于评分的真值 |
| A/B 测试 用真实流量比较变体 |
衡量真实用户结果（留存、任务完成）；能控制混淆因素；可扩展、系统化 | 慢，要几天到几周才能显著，且需要足够流量；只能测你发布的改动；不深读轨迹的话，很难知道指标变化的「为什么」 |
| 用户反馈 点踩、bug 报告这类显式信号 |
能暴露你没想到的问题；自带真实用户的例子；往往和产品目标相关 | 稀疏且自选择；偏向严重问题；用户很少解释为什么失败；不自动；主要靠用户发现问题，会对用户造成负面影响 |
| 人工读轨迹 人去看 agent 的对话 |
培养对失败模式的直觉；能抓到自动检查漏掉的细微质量问题；帮助校准「好」长什么样、把握细节 | 耗时；不可扩展；覆盖不一致；审阅者疲劳或不同审阅者会影响信号质量；通常只给质性的信号，没有清晰量化 |
| 系统化人工研究 受训评分者对输出做结构化打分 |
多位人类评分者给出的金标准判断；能处理主观或含糊的任务；为改进模型评分器提供信号 | 相对贵、周期长；难以高频进行；评分者之间分歧需要调和；法律、金融、医疗这类复杂领域需要人类专家来主持 |
这些方法对应 agent 开发的不同阶段。自动化评估在发布前和 CI/CD 里最有用，每次 agent 改动和模型升级都跑一遍，是质量问题第一道防线。生产监控在上线后接管，用来发现分布漂移和意料之外的真实世界失败。A/B 测试在你有了足够流量之后，验证重大改动。用户反馈和读轨迹是日常工夫，用来填空：持续分类反馈，每周抽样读轨迹，需要时再深挖。系统化的人工研究留给两件事：校准 LLM 评分器，以及评估那些以人类共识为参照的主观输出。
最有效的团队会把这些方法组合起来：自动化评估负责快速迭代，生产监控提供真值，定期人工复核做校准。
没有评估的团队会陷在反应式循环里：修掉一个失败，又造出另一个，还分不清真正的回归和噪声。早早投入的团队恰恰相反：失败变成用例，用例挡住回归，指标取代猜测，开发反而更快。评估给整个团队一座看得见的山，把「感觉变差了」变成可执行的东西。它的价值会复利——但前提是你把评估当成核心部件，而不是事后补丁。
具体做法随 agent 类型不同而变，但底层原则不变：尽早开始，别等一套完美的套件；从你看到的失败里收集真实任务；写出无歧义、稳健的成功标准；认真设计评分器并组合多种类型；确保题目对模型来说足够难；持续迭代评估以提升信噪比；然后，读轨迹。
AI agent 评估仍是一个年轻、快速演进的领域。随着 agent 承担更长的任务、在多 agent 系统里协作、处理越来越主观的工作，方法也得跟着变。学到新东西，我们会继续分享。
一些开源和商业框架能帮团队不必从零搭基础设施。怎么选取决于 agent 类型、现有技术栈，以及你需要离线评估、生产可观测，还是两者都要。
autoevals 库内置了事实性、相关性等常用打分器。很多团队会混用多个工具、自研评估框架，或者就从简单脚本起步。我们的体会是：框架能加速、能统一，但它的价值取决于你喂进去的任务。更划算的做法通常是先快速选一个贴合工作流的框架，然后把精力花在评估本身——持续打磨高质量用例和评分器。
作者：Mikaela Grace、Jeremy Hadfield、Rodrigo Olivares、Jiri De Jonghe。感谢 David Hershey、Gian Segato、Mike Merrill、Alex Shaw、Nicholas Carlini、Ethan Dixon、Pedram Navid、Jake Eaton、Alyssa Baum、Lina Tawfik、Karen Zhou、Alexander Bricken、Sam Kennedy、Robert Ying 等人的贡献。特别感谢在评估合作中让我们学到很多的客户与伙伴。
]]>Claude Code 是一个 agentic 的编码环境。它不像聊天机器人那样答完就等：它可以读你的文件、跑命令、改代码，自行把问题推进下去——你可以盯着看、随时介入，也可以干脆走开。
这改变了你的工作方式。你不再是自己写完代码让 Claude 来审，而是描述想要什么，由 Claude 想清楚怎么建：它探索、计划、实现。
但这种自主性有学习曲线。Claude 工作在若干约束之下，你需要理解它们。
这份指南整理了在 Anthropic 内部团队，以及各种代码库、语言、环境里的工程师身上反复奏效的做法。
大多数最佳实践都源自同一个约束：Claude 的上下文窗口填满得很快，而一旦填满，表现就会下降。
上下文窗口装着你整段对话：每条消息、Claude 读过的每个文件、每条命令输出。一次调试或一次代码库探索，就可能产生并消耗几万个 token。
这很重要，因为模型的表现会随上下文填满而下滑。接近上限时，Claude 可能开始「忘记」早先的指令，或者犯更多错。上下文窗口是你最需要管理的资源。
给 Claude 一个它能跑的检查：测试、构建、一张用来对比的截图。这决定了你是要一直盯着这个会话，还是能放心走开。
Claude 在「看起来做完了」的时候会停下。如果没有它能执行的检查，「看起来做完了」就是唯一可用的信号，于是你成了验证环路本身：每一个错误都要等你去发现。给它一个能产出通过或失败的东西，这个环路就自己闭合了——Claude 干活、跑检查、读结果，一直迭代到检查通过。
所谓检查，是任何能在对话里给 Claude 一个可读信号的东西：一套测试、构建的退出码、一个 linter、一个把输出与基准文件做对比的脚本，或者一张与设计稿对比的浏览器截图。在 Claude 的检查通过之后，你自己再跑一遍 /verify，对着运行中的应用确认真的是对的。
| 策略 | 之前 | 之后 |
|---|---|---|
| 给出验证标准 | 「实现一个校验邮箱地址的函数」 | 「写一个 validateEmail 函数。测试用例：user@example.com 为 true，invalid 为 false，user@.com 为 false。实现后跑测试」 |
| 用截图验证 UI 改动 | 「把仪表盘弄好看点」 | 「[贴截图] 按这个设计实现。把结果截图和原图对比，列差异并修掉」 |
| 解决根因而非症状 | 「构建挂了」 | 「构建报了这个错：[贴报错]。修掉它并验证构建通过。解决根因，不要压掉错误」 |
检查存在之后，再决定它多硬地卡住收尾：
/goal 条件。一个独立的评估器在每一轮之后重新检查，Claude 会一直干活直到目标达成。如果 Claude 卡住，Claude Code 最终会带着未达成的目标结束这次运行。每一步都是用配置换注意力。只用提示词的方式今天就能用在任何任务上；/goal 和 Stop hook 才是让无人值守的运行也能正确收尾的东西。
让 Claude 给出证据，而不是宣称成功：测试输出、它跑的命令和返回、或者结果截图。看证据比自己再跑一遍验证更快，而且对你没盯着的会话同样有效。
把调研与计划跟实现分开，避免「解决了错的问题」。
让 Claude 直接开写，很可能写出解决错问题的代码。用 plan mode 把探索和执行分开。
推荐的工作流有四个阶段：
1. 探索
按 Shift+Tab 直到状态栏显示 ⏸ plan mode on 进入 plan mode，或者用 claude --permission-mode plan 启动会话。Claude 会读文件、回答问题，但不做任何改动。
claude（plan mode）read /src/auth and understand how we handle sessions and login.
also look at how we manage environment variables for secrets.
2. 计划
让 Claude 产出一份详细的实现计划。
claude（plan mode）I want to add Google OAuth. What files need to change?
What's the session flow? Create a plan.
按 Ctrl+G 把计划在编辑器里打开，直接改完再让 Claude 继续。
3. 实现
批准计划或再按 Shift+Tab 退出 plan mode，让 Claude 照着计划写代码并自行对照检查。
claudeimplement the OAuth flow from your plan. write tests for the
callback handler, run the test suite and fix any failures.
4. 提交
让 Claude 用一条描述清楚的提交信息提交，并开一个 PR。
claudecommit with a descriptive message and open a PR
plan mode 有用，但也有开销。范围清晰、改动很小的事情（改个错字、加一行日志、重命名变量），直接让 Claude 做。
计划最适合这些情况：你对接下来的做法没把握；改动会涉及多个文件；你要改的代码自己不熟。如果你能用一句话描述这次 diff，那就跳过计划。
指令越精确，需要纠正的次数越少。
Claude 能推断意图，但读不了你的心。点名具体文件、说明约束、指出可以参考的现成写法。
| 策略 | 之前 | 之后 |
|---|---|---|
| 圈定范围。说清哪个文件、什么场景、测试偏好。 | 「给 foo.py 加测试」 | 「给 foo.py 写一个测试，覆盖用户已登出的边界情况。不要用 mock」 |
| 指向来源。把 Claude 引到能回答问题的那份材料上。 | 「ExecutionFactory 的 api 怎么这么怪？」 | 「翻一下 ExecutionFactory 的 git 历史，总结它的 api 是怎么变成现在这样的」 |
| 参考已有模式。让 Claude 去看代码库里现成的范例。 | 「加一个日历组件」 | 「看看首页现有组件是怎么写的，HotDogWidget.php 是个好例子。照这个模式实现一个新的日历组件：可以选择月份，也能前后翻页选年份。除了代码库已有的库，不要引入新依赖」 |
| 描述症状。给出症状、可能的位置，以及「修好了」长什么样。 | 「修一下登录的 bug」 | 「用户反馈会话超时后登录失败。检查 src/auth/ 里的认证流程，特别是 token 刷新。先写一个能复现问题的失败测试，再修」 |
模糊的提示也有用——尤其是在探索阶段、你付得起来回纠偏的成本时。像「这个文件你会怎么改？」这样的问题，常常能挖出你原本想不到要问的点。
用 @ 引用文件、直接贴截图，或者把数据管道输进去。
给 Claude 提供资料有几种方式：
@ 引用文件，而不是描述代码在哪。Claude 会在回答前先读那个文件。/permissions 加进白名单。cat error.log | claude -p "explain this error"，把文件内容直接送进去。几个设置动作能让 Claude Code 在你所有会话里都明显更好用。想完整了解各种扩展能力以及各自适合什么场景，见官方文档的 Extend Claude Code。
跑一次 /init，它会根据你当前的项目结构生成一份 CLAUDE.md 草稿，然后慢慢打磨。
CLAUDE.md 是一个特殊文件，Claude 在每次对话开始时都会读它。把 Bash 命令、代码风格、工作流规则写进去，就等于给了 Claude 一份它没法从代码里推断出来的长期上下文。
CLAUDE.md 没有规定格式，但要短、要好读。例如：
CLAUDE.md# Code style
- Use ES modules (import/export) syntax, not CommonJS (require)
- Destructure imports when possible (eg. import { foo } from 'bar')
# Workflow
- Be sure to typecheck when you're done making a series of code changes
- Prefer running single tests, and not the whole test suite, for performance
用 /context 确认 Claude 确实加载了它。CLAUDE.md 每个会话都会加载，所以只写普遍适用的东西。只在某些场景才相关的领域知识或流程，用 skills 更合适——Claude 按需加载，不会把每个会话都撑大。
保持精简。对每一行问一句：删掉它，Claude 会不会犯错？不会就砍掉。臃肿的 CLAUDE.md 会让 Claude 忽略你真正的指令。
| ✅ 该写 | ❌ 不该写 |
|---|---|
| Claude 猜不到的 Bash 命令 | Claude 读代码就能知道的事 |
| 与默认风格不同的代码规范 | 它本来就懂的语言惯例 |
| 测试方式与偏好的测试运行器 | 详细的 API 文档（给链接就好） |
| 仓库约定（分支命名、PR 规范） | 经常变化的信息 |
| 这个项目特有的架构决策 | 长篇解释或教程 |
| 开发环境的坑（必需的环境变量） | 逐个文件描述代码库 |
| 不显然的常见陷阱 | 「写干净的代码」这类自明之理 |
如果明明写了规则，Claude 还是反复做你不想要的事，多半是文件太长、规则被淹没了。如果 Claude 问你一个 CLAUDE.md 里已经回答过的问题，多半是措辞含糊。把 CLAUDE.md 当代码对待：出问题时回看它，定期修剪，改完观察 Claude 的行为是否真的变了。对已经入库的 CLAUDE.md，跑一次 /doctor，Claude 会提议删掉那些它能从代码库推导出来的内容。
如果某一条指令总被跳过，单独给那一行加「IMPORTANT」之类的强调。强调很多行，等于一行都没强调。把 CLAUDE.md 提交进 git，让团队一起补——这个文件的价值会随时间复利增长。
CLAUDE.md 可以用 @path/to/import 语法导入其他文件。导入规则和文件可以放的位置，见官方文档。
想少被问、又不放弃控制权：用 /permissions 预批准你信任的工具，用 /sandbox 让沙箱内的命令免问直接跑。想自己逐条批准改动和命令时，切回 Manual 模式。
在 Claude Code v2.1.283 及以后，auto 模式是交互式终端与 VS Code 会话的内置起始权限模式：由一个独立的分类模型替你审掉大部分动作，只拦看起来有风险的——比如扩大影响范围、不熟悉的基础设施、或被恶意内容驱动的操作。更早的版本里，只有 Pro、Max 和 Team 套餐默认从 auto 模式起步。
Manual 模式下，会改动系统的动作都要先问你：写文件、Bash 命令、MCP 工具。这安全，但累。批准到第十次时，你其实是在点「同意」而不是在审阅。Manual 模式下有两个东西能减少打断，auto 模式下同样生效：
npm run lint 或 git commit让 Claude Code 通过 gh、aws、gcloud、sentry-cli 这类 CLI 去对接外部服务。
CLI 工具是与外部服务交互时最省上下文的方式。你用 GitHub 的话，装个 gh：Claude 知道怎么用它开 issue、提 PR、读评论。没有 gh 它也能走 GitHub API，但未认证的请求很容易撞上频率限制。
Claude 学新 CLI 也很在行。可以这样提示：Use 'foo-cli-tool --help' to learn about foo tool, then use it to solve A, B, C.
用 claude mcp add 加上名字和 URL 或命令，接上 Notion、Figma、你的数据库之类的系统。例如：claude mcp add --transport http notion https://mcp.notion.com/mcp。
接上 MCP server 之后，你可以让 Claude 按 issue 跟踪器实现功能、查数据库、分析监控数据、对接 Figma 设计稿、自动化一些流程。
必须每次都发生、零例外的事，用 hooks。
Hooks 会在 Claude 工作流的特定时点自动跑脚本。CLAUDE.md 里的指令是建议性的，hooks 是确定性的——它保证那件事一定发生。
Hook 也可以让 Claude 来写。可以这样提示：「写一个 hook，每次改完文件都跑 eslint」，或者「写一个 hook，禁止写入 migrations 目录」。手写的话直接改 .claude/settings.json，用 /hooks 查看当前配置了哪些。
在 .claude/skills/ 里放 SKILL.md，给 Claude 领域知识和可复用的工作流。
Skills 用你的项目、团队或领域特有的信息来扩展 Claude 的知识。相关时它会自动用上，你也可以用 /skill-name 直接调用。
在 .claude/skills/ 下建一个目录，放一个 SKILL.md 就是一个 skill：
.claude/skills/api-conventions/SKILL.md---
name: api-conventions
description: REST API design conventions for our services
---
# API Conventions
- Use kebab-case for URL paths
- Use camelCase for JSON properties
- Always include pagination for list endpoints
- Version APIs in the URL path (/v1/, /v2/)
Skills 也能定义你直接调用的重复性流程：
.claude/skills/fix-issue/SKILL.md---
name: fix-issue
description: Fix a GitHub issue
disable-model-invocation: true
---
Analyze and fix the GitHub issue: $ARGUMENTS.
1. Use `gh issue view` to get the issue details
2. Understand the problem described in the issue
3. Search the codebase for relevant files
4. Implement the necessary changes to fix the issue
5. Write and run tests to verify the fix
6. Ensure code passes linting and type checking
7. Create a descriptive commit message
8. Push and create a PR
用 /fix-issue 1234 触发。有副作用、你想手动触发的流程，加上 disable-model-invocation: true。
在 .claude/agents/ 里定义专门的助手，Claude 可以把独立任务交给它们。
Subagent 在自己的上下文里运行，带着自己那套允许使用的工具。适合要读很多文件、或者需要专门视角又不想弄脏主对话的任务。
.claude/agents/security-reviewer.md---
name: security-reviewer
description: Reviews code for security vulnerabilities
tools: Read, Grep, Glob, Bash
model: opus
---
You are a senior security engineer. Review code for:
- Injection vulnerabilities (SQL, XSS, command injection)
- Authentication and authorization flaws
- Secrets or credentials in code
- Insecure data handling
Provide specific line references and suggested fixes.
要明确告诉 Claude 用 subagent：「用 subagent 审一下这段代码的安全问题」。
用 /plugin 逛市场。插件把 skills、工具和集成打包好，装上就能用，不需要配置。
插件把 skills、hooks、subagent 和 MCP server 打包成一个可安装单元，来自社区和 Anthropic。如果你用带类型的语言，装一个代码智能插件，能让 Claude 精确跳转符号，并在改动后自动发现错误。
在 skills、subagent、hooks、MCP 之间怎么选，见官方文档的 Extend Claude Code。
像问另一位工程师那样问 Claude；功能比较大时，先让 Claude 反过来采访你、写出一份 spec，再开始实现。
把 Claude 当资深工程师来问。
接手新代码库时，用 Claude Code 来学习和探索。你可以问那些本来要问同事的问题：
foo.rs 第 134 行的 async move { ... } 是干什么的？CustomerOnboardingFlowImpl 处理了哪些边界情况？foo() 而不是 bar()？这样用 Claude Code 是很有效的上手方式：缩短爬坡时间，也减轻其他工程师的负担。不需要什么特殊提示，直接问就行。
功能比较大时，先让 Claude 采访你。用一句很小的提示开头，让它用 AskUserQuestion 工具来问你。
Claude 会问到你还没想到的地方：技术实现、界面与交互、边界情况、取舍。发送前把 [简述] 换成你的功能。
claudeI want to build [brief description]. Interview me in detail using the AskUserQuestion tool.
Ask about technical implementation, UI/UX, edge cases, concerns, and tradeoffs. Don't ask obvious questions, dig into the hard parts I might not have considered.
Keep interviewing until we've covered everything, then write a complete spec to SPEC.md.
spec 写完之后，开一个全新的会话去执行它。新会话的上下文是干净的，全部用于实现；而你手上有一份写好的 spec 可以对照。
最有用的 spec 是自包含的：点名涉及的文件和接口，写明什么不在范围内，最后给一个端到端的验证步骤，证明这个功能确实能用。花在把 spec 写精确上的时间，回报高于花在盯着实现上的时间。
对话是持久的，也是可回退的。把这两点用起来。
发现它跑偏就立刻纠正。
最好的结果来自紧凑的反馈环路。Claude 偶尔一次就做对，但多数时候，快速纠正能更快得到更好的方案。
Esc：中断 Claude 正在做的事。上下文会保留，你可以就地改方向。Esc + Esc 或 /rewind：打开回退菜单，恢复之前的对话与代码状态，或者从某条消息开始做总结。/clear：在互不相关的任务之间重置上下文。带着无关内容的长会话会降低表现。如果同一个问题在一个会话里纠正了两次以上，上下文里已经堆满了失败的尝试。跑 /clear，带着你学到的东西写一条更具体的提示重新开始。干净的会话加更好的提示，几乎总是胜过带着一堆纠正的长会话。
互不相关的任务之间跑 /clear 重置上下文。
接近上限时 Claude Code 会自动压缩对话历史：保留重要的代码和决策，腾出空间。
长会话里，上下文窗口会塞满无关的对话、文件内容和命令，既降低表现，有时还会让 Claude 分心。
/clear，彻底重置上下文窗口/compact <指令>，比如 /compact Focus on the API changesEsc + Esc 或 /rewind 选一个消息检查点，然后选择「从这里开始总结」或「总结到这里」：前者压缩该点之后的若干消息、保留早先的上下文；后者压缩早先的消息、完整保留近期内容/btw：答案不会进入对话历史，查个细节而不撑大上下文用「用 subagent 调研 X」把研究交出去。它们在独立的上下文里探索，主对话留给实现。
既然上下文是根本约束，就把研究挪出主上下文。Claude 调研一个代码库要读大量文件，全都消耗你的上下文。Subagent 在独立的上下文窗口里跑，只把摘要报回来：
claudeUse subagents to investigate how our authentication system handles token
refresh, and whether we have any existing OAuth utilities I should reuse.
Claude 实现完之后，也可以用 subagent 来做验证。
每一次会开启新一轮的提示都会创建一个 checkpoint。你可以把对话、代码或两者恢复到任何之前的检查点。
Claude 在每次改动前会自动给文件做快照，checkpoint 就是靠它恢复。双击 Escape 或跑 /rewind 打开回退菜单：可以只恢复对话、只恢复代码、两者都恢复，或者从选中的消息开始总结。
于是你不必每一步都精心规划：可以让 Claude 试一个冒险的做法，不行就退回来换一条路。Checkpoint 跟对话一起保存，关掉终端、之后恢复会话，仍然能回退。
Checkpoint 只跟踪通过 Claude 的文件编辑工具做的改动。通过 Bash 命令或外部进程改的东西不会被记录。它不是 git 的替代品。
用 /rename 给会话命名，像对待分支一样：每条工作线都有自己的持久上下文。
Claude Code 把对话保存在本地，所以一个任务跨几天也不用重新解释背景。跑 claude --continue 接着上一次，或者 claude --resume 从列表里挑。给会话起描述性名字，比如 oauth-migration，之后好找。
把单个 Claude 用顺之后，用并行会话、非交互模式和扇出模式把产出放大。
在 CI、pre-commit hook 或脚本里用 claude -p "prompt"。加 --output-format stream-json --verbose 得到流式 JSON。
claude -p "your prompt" 让 Claude 非交互地跑，不需要人应答。除非你传 --no-session-persistence，这次运行仍会创建一个可恢复的会话。非交互模式是把 Claude 接进 CI 流水线、pre-commit hook 或任何自动化流程的方式。输出格式让结果可以程序化解析：纯文本、JSON 或流式 JSON。
bash# One-off queries
claude -p "Explain what this project does"
# Structured output for scripts
claude -p "List all API endpoints" --output-format json
# Streaming for real-time processing
claude -p "Analyze this log file" --output-format stream-json --verbose
第一条打印纯文本。json 格式返回一个带 result 字段的 JSON 对象。stream-json 每行打印一个 JSON 对象，以一个 init 事件开头。
并行开多个 Claude 会话，加快开发、跑互不干扰的实验，或者启动复杂的工作流。
按你愿意投入多少协调成本来选并行方式；需要在会话之间传递发现时，再加上消息机制：
claude agents 派发在后台持续运行的会话，在一个界面里看除了并行干活，多会话还能支撑偏向质量的工作流。全新的上下文能让代码审查更有效，因为 Claude 不会偏袒自己刚写的代码。
比如 Writer / Reviewer 模式：
| 会话 A（作者） | 会话 B（审查者） |
|---|---|
| 「给我们的 API 端点实现一个限流器」 | |
「审一下 @src/middleware/rateLimiter.ts 里的限流实现。看边界情况、竞态，以及和现有中间件写法的一致性」 | |
| 「这是审查意见：[会话 B 的输出]。把这些都改掉」 |
测试也能这么玩：让一个 Claude 写测试，另一个写代码去通过它们。
循环调用 claude -p 逐个处理任务。批量操作时用 --allowedTools 预批准工具。
大迁移或大分析，可以把工作分摊到许多并行的 Claude 调用上。跑 /batch <指令>，Claude 会把改动拆给 5 到 30 个 subagent，每个在自己的 worktree 里干活。想用自己的脚本驱动扇出，就循环调用 claude -p：
1. 生成任务清单
让 Claude 把需要迁移的文件列表写成文件，下一步的循环就能读它。提示例如：list all 2,000 Python files that need migrating and save the list to files.txt
2. 写个脚本遍历这个清单
bashfor file in $(cat files.txt); do
claude -p "Migrate $file from Python 2 to Python 3. Return OK or FAIL." \
--allowedTools "Edit,Bash(git commit *)" \
--permission-mode dontAsk
done
3. 先在几个文件上试，再全量跑
根据前两三个文件出的问题改进提示词，然后跑全量。--allowedTools 预批准了迁移需要的工具；--permission-mode dontAsk 会拒绝其他任何需要批准的调用——无人值守时这一点很重要，不过你安装的 mod 仍可能批准其中一些调用。
也可以把 Claude 接进已有的数据处理流水线：
bashclaude -p "<your prompt>" --output-format json | your_command
想要不被打断、同时后台还有安全检查，用 auto 模式。一个分类模型在命令执行前审查，拦下扩大影响范围、不熟悉的基础设施、被恶意内容驱动的操作，其余常规工作直接放行。
bashclaude --permission-mode auto -p "fix all lint errors"
在带 -p 的非交互运行里，如果分类器反复拦截某些操作，Claude Code 不会因此终止这次运行。
在把任务当作完成之前，让一个 subagent 在全新上下文里审这份 diff，报告缺口。
Claude 无人值守跑得越久，独立检查就越重要。审查者跑在全新的 subagent 上下文里，只看到 diff 和你给的判据，看不到产生这次改动的推理过程，因此它会按自己的理解评估结果。
想查正确性，跑内置的 /code-review skill：它在全新的 subagent 里审查当前 diff 找 bug，把发现送回会话。想对照计划检查，就自己写审查提示——点名要检查的东西、对照的计划，以及什么算一条发现：
claudeUse a subagent to review the rate limiter diff against PLAN.md. Check that
every requirement is implemented, the listed edge cases have tests, and
nothing outside the task's scope changed. Report gaps, not style preferences.
因为审查者以 subagent 运行，实现它的那个会话能直接收到这些缺口，自己修完再重审，不需要你在窗口之间复制粘贴。
被要求「找缺口」的审查者，通常总能报告出一些，即使实现本身是好的——它被要求做的就是这个。追着每一条发现改，会滑向过度设计：多余抽象层、防御性代码、为不可能发生的情况写测试。告诉审查者只报影响正确性或明确需求的缺口，其余当作可选项。
这些都是常见的坑，早点认出来能省很多时间：
/clear。/clear，把学到的东西写进一条更好的初始提示。这份指南里的做法不是铁律。它们是普遍好用的起点，但不一定适合每种情况。
有时你就该让上下文累积——你正深陷一个复杂问题，历史很有价值。有时你该跳过计划，让 Claude 自己摸——因为任务是探索性的。有时模糊的提示恰好最合适——因为在约束它之前，你想先看看它怎么理解这个问题。
留意什么管用。当 Claude 产出很好，回想你做了什么：提示词的结构、你给的上下文、你当时在哪个模式。当它卡住，问一句为什么：上下文太吵？提示太模糊？任务太大，一次做不完？
慢慢地，你会养出任何指南都写不下来的直觉：什么时候该具体，什么时候该开放；什么时候该计划，什么时候该探索；什么时候该清空上下文，什么时候该让它累积。
我们之前说过，Claude Code 自身约 90% 的代码是 Claude 写的。那么，在我们这样的产出速度下，代码是怎么被审查的？现在还有人在读代码吗？如果真的出了问题，又是谁发现的？
这篇文章讲的是 Claude Code 团队的代码审查流程，以及它是如何演进的。从 6 月到 9 月，合并进 Claude Code 代码库的 pull request 数量增长了一倍多，而其中不得不回滚的比例下降了超过 40%。
我们并没有取消审查。但我们把大部分「阅读」工作交给了机器，围绕人的时间和注意力做优化，并在「让错误能被快速、轻松地撤销」这件事上投入了大量精力。
当写代码的是 agent，变更数量会迅速上升。在 Anthropic 的 monorepo 中，每天落地的变更从今年 5 月的约 2,500 个增长到 9 月的 30,000 多个。
Claude Code 住在自己的仓库里，与 monorepo 分离，但它同样承受着巨大压力。以这样的速度交付时，逐行的人工代码审查即使并非不可能，也极其困难。
代码审查承担两项职责：
本文主要聚焦第一项，但最后我们会回到第二项。
我们认为，「有没有人类读过这段代码？」只是「这次变更可能出什么问题，以及应该由哪道检查——自动的还是人工的——来抓住它？」这个问题的一个并不精确的替代指标。
问出这个问题，也改变了审查发生的时间。以前，审查是放在最后的一道关卡：写代码、开 PR、等同事来看。
现在，审查是持续进行的，更像是你写作时的拼写检查。大多数变更在被要求人来看之前，已经至少被 Claude 审过、修过一遍。这拦住了大部分常规错误，也把团队注意力留给了更高层的问题与更细致的审视。
我们希望把人的时间和注意力保留给只有人才能解决的问题，并确保其余部分由自动化检查兜住。以我们当前的变更速度，人类仍有大量工作要做，团队几乎每天都会遇到新的、前所未有的挑战。
人的时间涵盖审查成本的两端：人们花在审查上的时间，以及人们花在修复烂代码造成的破坏上的时间。如果削减了前者，时间却在后者身上冒出来，那就没有意义。
因此我们的目标是：Claude Code 各仓库（CLI、桌面端与 Web 应用、移动端应用）中的绝大多数 pull request，在最多只有一个人参与的情况下完成合并——这个人可以是作者本人——同时回滚率和事故率不上升。为了衡量人的时间，我们跟踪每个 PR 的人工批准次数（中位数与 95 分位）、人工评论数量，以及一个 PR 等待某个人所花的时间。回滚率和事故率则是护栏：如果它们上升，我们就并没有节省人的时间，只是把时间挪了个位置。
一次典型的变更，从工程师的笔记本电脑（或 Slack 里的一个 Claude 会话）出发，会经过多层代码审查。
左右滑动，查看完整图表 →
左右滑动，查看完整图表 →
如今大多数审查发生在 PR 存在之前。我们会给 Claude 一些它可以运行的东西——比如测试、构建，或一张可与设计稿对比的截图——并要求它展示输出，而不是只说「做完了」。随后，一个 subagent 会以全新的上下文审查这份 diff。这两个习惯都来自我们的最佳实践指南。
在开 PR 之前，我们中很多人还会跑几个内部 skill：一个专门找 bug，一个负责简化 diff，还有一个端到端地检查行为。UI 变更还会对照我们的设计规范再检查一遍。
Claude Code 的创造者 Boris Cherny 曾说，给 Claude 一种验证自己工作的方式，大概是最重要的一件事。他估计这能让最终结果好上两到三倍，并写道：「验证在每个领域长得都不一样。它可能只是跑一条 bash 命令，或者跑一套测试，或者在浏览器或手机模拟器里把应用试一遍。」
当自动审查者反复指出同一个问题时，我们会从源头修掉它：改 skill、加一条 lint 规则，或者更新这类指导性文件：
CLAUDE.md 告诉 Claude 这个项目是什么：技术栈、约定、目标与非目标。每次审查都会加载它，所以在大型代码库里我们保持它简短，并从那里指向其他文档。审查者也会标出违反其中约定的代码，以及那些让其中某句话过时的变更。REVIEW.md 由代码所有者编写，告诉审查者在他们负责的那部分代码里什么才是重要的。我们会单独检查审查者是否真的遵循了它。写得好的都很短。它们会说明在那个仓库里失败长什么样（对文档来说是「它在说谎」，对配置来说是「它把流量路由错了」），限制吹毛求疵的数量，列出需要跳过的路径，并要求以文件和行号作为证据，而不是凭名字猜。它们还会要求审查结论以数字开头，并在没有需要修的东西时直说。在有人看之前，每个 pull request 都会先得到一次 Claude 审查。它把 diff 放在整个仓库和这个 PR 声明的意图之下来读，并追问：这个变更是解决了它自己的问题，还是契合系统，又或者破坏了别的东西？
在 bug 修复上，它会去找根因。公开版本 Code Review for Claude Code 现已在 Team 和 Enterprise 套餐上正式可用，而在本地跑 /code-review 会得到更轻量的版本。
在我们推出研究预览版时，获得实质性审查意见的内部 PR 占比从 16% 上升到了 54%。超过 1,000 行的 PR 大多能被发现问题，而大多数小 PR 会干净通过。管理员可以为每个仓库设置为 Quick、Standard 或 Deep。在「漏掉一个 bug 的代价高于多花的审查时间」的地方，Deep 是值得的。
在人来审之前，发现的问题会先由其他 agent 验证。多个 agent 同时找 bug。随后另一组 agent 对每条发现投票，只有足够多的 agent 认为它是真的，它才会被发布出来。只涉及风格、诊断信息或清理工作的发现会被丢弃。我们在自己的 PR 上对这些过滤器做过 A/B 测试，才决定保留它们。剩下的以按严重程度排序的行内评论呈现。每条都标注为 Important、Nit 或 Pre-existing，这样不是这个 PR 引入的 bug，看起来就不会像是作者的责任。
每条发现都必须被回应。要么修掉它，要么带着理由把讨论串标记为已解决。通常会有 agent 在夜里接手修复，于是作者第二天回来时，PR 已经又过了一轮。
安全有它自己的自动审查。只要 bug 审查或安全审查还有任何未关闭的发现，PR 就不能合并。你要么修掉它，要么用一句简短的理由关掉讨论串——这也是清除误报的方式。
如果后续的提交修复了问题，那条发现会自动清除。你也可以用开源的安全审查 GitHub Action 或 /security-review 命令搭建同样的机制。搭建方式见 Claude Code 中的自动化安全审查。
就是那些常规项：lint、类型检查、各平台上的测试，以及构建。（我们写过一篇关于如何为这种体量扩展 CI 的文章，见这里。）一个典型的 CLI pull request 在有人看之前可能会跑几十项检查。PR 模板会问这个变更是怎么测的、怎么撤销。Claude 可以把它填好，但提出这个变更需求的人要对它签字确认。
一次文档修复和一次自动更新器的改动，风险并不相同，所以它们得到的审查也不同。
| 风险 | 示例 | 人工批准 |
|---|---|---|
| 低 | 文档、文案、仅内部使用的功能、开关后面的增量变更 | 自动审查与安全检查全绿后，无需人工批准 |
| 中 | 普通的产品变更，以及对敏感区域的变更，例如缓存、自动更新器或系统提示词 | 一人 |
| 高 | 风险最高的代码，以及一小批始终需要两人的路径 | 两人 |
分级由变更决定，而不是由作者决定。一个分类器读取变更内容，判定它的风险层级。第二个分类器则追问：即使这个层级本不需要，这次变更是否仍需另一个人参与。有些路径永远需要人，包括所有者列为敏感的任何东西，以及任何 CI workflow 文件。
只有受信任的作者才能走更轻的路径。只有在仓库受信任名单上的作者才能走更轻的路径，而名单上主要是拥有这个仓库的团队。其他人都需要第二个人来批准。agent 的批准也永远不能算作人的批准。自动审查可以放行一个低风险变更，但它不能填补一个需要人来的位置。
谁提出的变更，谁就要为它负责。在一个由 agent 写出的 PR 上，指挥这个 agent 的人算作必需的审查者之一，就如同这些代码是他亲手敲的一样。
一次批准只覆盖一个特定的 commit。如果之后落入了系统无法担保的新 commit——比如 agent 推送的，或某人手工解决的合并——批准就必须重新给出。
合并队列会在应用了该变更的基础上，对 main 重新跑所有检查，所以两个各自通过的 PR 不可能组合出一个坏掉的 main。新行为通常会先放在开关后面，先发给 Anthropic 内部员工；我们自己的重度使用，往往能在用户之前暴露出回归。公开发布先走 latest 通道，stable 通道随后跟进。
总还会有一些错误漏过去，所以最后一层是尽快抓住它们。开关可以不用部署就能关掉。Claude Code 有每周轮值的 on-call，事故复盘会追问本应由哪一层抓住这个问题。
发现一次糟糕的合并，仍然依赖作者、on-call，以及回滚和事故看板。我们目前还没有能在这些指标变动时收紧审批的熔断机制；在更多代码转向「零人工合并」之前，工程师们希望先有它。
一位同事说过，慢下来确实会降低出错率，但那主要是因为你在所有事情上都做得更少。我们更愿意在「更快地发现并修复问题」上变得更强。
我们的代码审查流程在一个循环中不断改进。
任何事故现在都是一份 eval。团队收集了过去引发事故的 PR，连同它们的 fix-forward 和回滚，并请熟悉那部分代码的工程师确认每一个 bug 以及它所在的位置。审查者每天都会在这个集合上跑一遍。
左右滑动，查看完整图表 →
我们通过观察人们如何对待评论来衡量噪声。如果你不在意误报很多，想多抓 bug 是很容易的，所以我们需要对这一点加以检查。我们会按 PR 上那个人的反应给审查者留下的每条评论分类：他修了它、他说它错了、他说这个行为是有意为之，或者他认为它无关紧要。我们还会把审查者跑在一些我们已知是干净的 PR 上，统计它报告出的、会让人做出有害改动的问题有多频繁。我们写下来的优先级是：先抓真 bug，其次减少审查轮次。
当作者是 agent 时，噪声的代价更高。一个人可以在几秒内把一个 nit 挥手带过。而 agent 会去修它，这意味着又一次提交和又一轮审查。
审查必须收敛。一个 agent 作者和一个 agent 审查者可以让彼此无限忙碌下去。有一个 CLI PR 在一夜之间经历了五十多轮审查与修复，最后是作者叫停了它。
当我们对审查者反复指出的内容跑 git blame 时，大约 59% 是审查者第一轮就已经存在的代码。审查者很少在发现新 bug，它只是在每一轮里多发现几个旧 bug。
这是我们自己搞出来的。我们已经习惯默认跑好几轮，因为每一轮都会抓到一点新东西。这在一次高风险变更上也许值得，但不该在每一个 PR 上都如此。团队现在把「过审轮次」和召回率放在一起跟踪，并修改了重审策略：
审查 agent 还会每晚在既有代码上跑一遍，帮我们在旧 bug 冒到别处之前抓住它们。
左右滑动，查看完整图表 →
把一位资深工程师从深度工作中拉出来，只为抓一个常规错误，代价远高于一次自动审查。团队里的人仍然要对这些事情负责：
代码审查的第二项职责，一直是传播对代码库的理解。读一位同事的 diff，是你了解发生了什么变化、各部分如何拼在一起的方式。如果大部分阅读都由机器完成，人们又怎么学习代码？
我们没有为此设立正式流程。团队里没有人脑中保留着 Claude Code 的完整心智模型，我们也认为没这个必要。当有人想理解代码库的某一部分时，他们会请 Claude 针对那一个切片写一份讲解。几分钟就能出来，而且反映的是当下的代码。
我们中的一些人还会更进一步，让 Claude 做一个小产物，把那部分代码可视化，并按这个人喜欢的学习方式来讲解。
如果目标是把人的注意力花好，这比逐行阅读琐碎的 diff 强得多。一处一行的文案改动几乎什么都教不了你。为你即将改动的模块写一份讲解，能教你很多。我们「默认在公开 Slack 频道里工作」的文化也有帮助，因为别人在构建东西时，你能看见他们在构建什么。
如果你合入了一个小或中等规模的变更，而事情仍然出了问题，团队规范是通常由你来修。有几件事让它不至于变得糟糕：
责任也是共享的。团队大部分人都在公开频道里工作，任何人都能看到别人在构建什么、接手一个讨论串，或者把一个 Claude 指向某处空白；反馈也来自那些并不拥有这段代码的人。这种开放性是质量能保持在高位、而不必对每一行都设关卡的重要原因。
agent 让开始一件事变得很便宜，所以有些工作不该落地。通常是频道里有人问一句为什么、指出一个更早的决定，或者提出一条更简单的路径，然后作者关闭或重塑这个 PR。
既然代码写得很快，关掉这个 PR 并不让人觉得是损失。诀窍在于尽早在这个讨论串里提出另一个方向，而不是把它作为一条阻塞性评论，留在一个已经完成的 PR 上。
和你的团队一起做这件事所需的大部分组件，今天都已经存在了。
CLAUDE.md 里，再加上运行格式化和 linter 的 hook。/code-review 和 /security-review，或者跑一次全新上下文的 subagent 审查。REVIEW.md，把重复出现的审查意见搬进去。REVIEW.md，然后再铺开。Code Review 的公告说，批准一个 pull request 仍然由人决定；产品发布的是发现，而不是批准。我们自己的仓库走得更远，让所有者决定哪些低风险变更可以仅凭自动化检查就合并，而这条线还在不断移动。
当一次审查漏掉了什么，我们会问：模型当时手上缺了什么？然后把修复写进 CLAUDE.md、一个 skill 或一项新检查。目标没有变：每个变更花更少的人类时间，同时回滚不比以前更多。
如果你的团队让 agent 开 pull request，我们很想听听你们自动化了哪些检查、哪些仍然需要人，以及你认为我们哪里搞错了。
感谢 Emma Webb、Michael Segner 和 Amie Rotherham 的审阅。
]]>