00:00:00
资料库 ② · Anthropic 的 Agent 工程方法
第 21–40 条 · 共 20 条 · 来源：Anthropic Engineering · 时间跨度 2024-12 至 2026 年
选这个来源的理由很直接：Claude Code 是他们写的，agent 相关的工具协议是他们定的。这些文章不是评测也不是转述，是实现者在讲自己怎么做的、踩了什么坑、以及为什么这么选。这一类一手材料的信息密度，比任何"最佳实践汇总"都高。
同时要说清它的局限：这是一家公司在讲自己的产品。涉及能力和效果的数字，读的时候当"厂商自报"看；涉及设计取舍和失败复盘的部分，可信度高得多——没人会编造自己的事故。
按时间排，是因为这条线本身有意义：2024 年底还在讨论"什么算 agent"，2025 年中开始讨论上下文怎么管，2025 年底工具协议成型，2026 年焦点转向 harness 设计和长任务可靠性。看这个顺序，比看单篇更能理解这个领域在往哪走。
关于时效
标了 会过期 的条目，内容和具体的模型版本、API 参数、产品形态绑定，半年后可能已经变了；标了 结构性 的讲的是设计原则，换几轮模型仍然成立。时间紧就先读结构性的那些。
2024 年底—2025 年初：先把「什么是 agent」定清楚
21. Building effective agents
来源：Anthropic Engineering，2024 年 12 月 19 日。结构性
读它解决什么：agent 到底有哪几种做法，什么时候该用哪种，什么时候根本不该用 agent。
要点：
- 区分 workflow（预定义代码路径编排 LLM）和 agent（LLM 自己决定流程和工具调用）
- 给出几个可组合的模式：prompt chaining（拆成串行步骤）、routing（分类后分发）、parallelization（分片并行或多路投票）、orchestrator-workers（主控动态派活）、evaluator-optimizer（生成—评审—改进循环）
- 反复强调的结论：从最简单的方案开始，只在确有必要时才增加复杂度
- 明确说很多场景下单次 LLM 调用加检索就够了，不需要 agent
我的补充：这是整个第二卷的地基，也是我认为过去两年里关于 agent 架构最有用的一篇。 它的价值不在于介绍了什么新技术，而在于给一堆混着说的东西建立了分类。分类清楚了，讨论才能进行。
我在实际项目里最常用到的判断是它那条"最简优先"：
- 任务步骤固定 → 写成 workflow（prompt chaining）。别用 agent——固定流程用 agent 只是把确定性换成了不确定性和额外 token。
- 任务分几类、每类处理方式不同 → routing。这一步用小模型做分类往往就够。
- 任务可以切成互不依赖的片 → parallelization。这是提速最直接的手段，而且比让单个 agent 顺序做更可控。
- 步骤数和路径事先不知道 → 这时才需要 agent。
- 有明确的质量标准且能自动判定 → evaluator-optimizer。注意前提是"能自动判定"，判定不了的时候这个循环会稳定地收敛到"看起来很好"。
最容易被跳过、代价最大的一条：文中提到 agent 适用于"步骤不可预测"的场景，但同时要求你能承受它出错。我见过的失败案例几乎都是这一点没想清楚——用 agent 处理了一个既需要确定性、又没有验证手段的任务。
22. The "think" tool: Enabling Claude to stop and think in complex tool use situations
来源：Anthropic Engineering，2025 年 3 月 20 日。结构性
读它解决什么：在多轮工具调用中，怎么给模型留出"停下来想一下"的空间。
要点：
- 提供一个名为
think的工具，它什么都不做——只是把模型写进去的内容记录下来 - 作用是在工具调用之间创造一个结构化的思考位置：拿到工具结果后先分析，再决定下一步
- 适用场景：需要遵守复杂策略、多步工具链、工具返回结果需要判断的任务
我的补充：这个设计的巧妙之处在于它用工具接口这个已有机制，换来了一个纯粹的思考槽位，不需要改模型也不需要改协议。一个无副作用的空工具，就把"想"变成了流程里的一个显式步骤。
它和现在普遍支持的 extended thinking 不是一回事，区别值得记住：
- extended thinking 发生在响应开始前——此时模型还没看到任何工具结果
think工具发生在工具调用之间——此时它手上有了真实数据
所以这两者互补，不互相替代。 前者用于规划，后者用于"拿到结果后重新评估"。
自己实现 agent 时，这个模式几乎零成本，我建议默认加上。要注意的一点是别让它变成噪音：如果每一步都调 think，上下文会被大量自言自语填满。我的做法是在工具描述里写清"仅在需要权衡多个选项、或工具结果与预期不符时使用"。
23. Claude Code: Best practices for agentic coding
来源：Anthropic Engineering，2025 年 4 月 18 日。部分会过期
读它解决什么：Claude Code 该怎么用，作者团队自己的用法是什么。
要点：
CLAUDE.md：放项目约定、常用命令、代码风格、注意事项，会被自动读进上下文- 工具权限管理：allowlist 常用的安全命令，避免每次都确认
- 推荐工作流：explore → plan → code → commit——先让它读代码理解现状，再让它出方案，然后才写
- 提到让它先写测试、以及给它明确的验证目标
- 多 Claude 协作、用
git worktree并行、以及 headless 模式做自动化
我的补充：这是这一卷里最实用的一条，也是新手唯一必读的一条。 具体命令和参数会变（所以标了会过期），但里面几个做法我用下来是长期有效的：
CLAUDE.md 的收益被严重低估。 它解决的是"每次开新会话都要重复解释项目背景"这个持续成本。我放进去的东西：
- 怎么跑测试、怎么构建、怎么起开发服务器（最高频，收益最大）
- 项目的目录约定和分层规则
- 明确的禁止项（"不要引入新依赖"、"不要改
xxx目录"） - 已知的坑（"这个测试在 Windows 上必须用
--runInBand"）
"explore → plan → code" 里的 plan 一步最容易被跳过，但收益最高。 直接让它写代码，它会基于猜测动手；先让它出方案，你能在几十秒内否掉一个错误方向，而不是在两百行代码之后。
"先写测试"在 agent 场景下的意义和人写代码时不同：测试在这里首先是给 agent 的验证信号，让它能自己判断改对了没有，而不只是回归保护。这一点和第一卷第 7 条（设计 agentic loop）是同一件事的两面。
2025 年中：多 agent 与上下文工程
24. How we built our multi-agent research system
来源：Anthropic Engineering，2025 年 6 月 13 日。结构性
读它解决什么：多 agent 系统在什么情况下真的比单 agent 好，代价是什么。
要点：
- 采用 orchestrator-workers：主 agent 做规划，派生子 agent 并行搜索，各自带回结果
- 核心优势是上下文隔离：每个子 agent 有自己的上下文窗口，可以并行探索不同方向
- 明确指出代价：token 消耗远高于单 agent 对话
- 讨论了工程难点：状态管理、错误累积、以及子 agent 之间的协调
我的补充："上下文隔离"这个收益是多 agent 架构最实在的理由，比"分工"这种说法准确得多。
具体机制值得说清楚：一次大范围代码搜索可能要读几十个文件，这些内容会把主上下文填满，而其中绝大部分是无用的——你只需要结论。交给子 agent 的话，几十个文件的内容留在子 agent 那里被丢掉，主上下文只收到一段摘要。上下文预算的性价比差了一个量级。
所以我用子 agent 的判断标准是：这个任务是不是"读很多、结论很少"？ 是就派出去。反之，如果任务需要频繁和主上下文交互、或者结论本身就很长，那么派出去反而更贵。
它诚实说了 token 成本高，这点值得认真对待。 并行搜索的 token 消耗大致是单 agent 的数倍。对研究型任务这个交换划算——时间是瓶颈；对简单任务就是纯浪费。
还有一个文中提到、我实践中反复验证的坑：子 agent 的任务描述必须足够具体。含糊的指派会让多个子 agent 的工作重叠或者跑偏，然后你要在主 agent 里花更多 token 去调和这些冲突。
25. Writing effective tools for agents — with agents
来源：Anthropic Engineering，2025 年 9 月 11 日。结构性
读它解决什么：给 agent 写工具，怎么写才好用；以及怎么用 agent 自己来改进工具。
要点：
- 工具设计要点：清晰的命名、明确的描述、合适的粒度、token 高效的返回格式
- 强调工具应该按 agent 的实际工作流来设计，而不是照着已有 API 一比一包装
- 提出用 agent 自己去测试和改进工具描述：让它用，看它误用在哪，然后改描述
- 返回内容要考虑上下文成本——不要把整个 JSON 原样丢回去
我的补充："不要照着已有 API 一比一包装"是这篇最重要的一句，也是我见过最普遍的错误。
一个具体例子：如果你的 REST API 有 GET /users、GET /users/{id}、GET /users/{id}/orders，直接包成三个工具，agent 就需要三轮调用才能回答"这个用户最近买了什么"。合并成一个 get_user_with_recent_orders 工具，一轮就完事。 工具的粒度应该匹配"任务的自然单位"，不是"资源的自然单位"。
返回格式的 token 成本经常被完全忽略。 一个 API 返回 50 个字段，agent 需要 3 个，剩下 47 个字段每次调用都在烧你的上下文预算。我的做法：默认返回精简字段，需要详情时用参数显式要求。
"用 agent 测试工具描述"这个方法我实测很有效。 做法是给它一批真实任务，然后看日志里它在哪里选错了工具、传错了参数。误用的地方几乎总是描述不清，不是模型笨。 把误用点写进工具描述的"何时使用/何时不要使用"，误用率会明显下降。
26. A postmortem of three recent issues
来源：Anthropic Engineering，2025 年 9 月 17 日。结构性（作为事故分析的范例）
读它解决什么：2025 年 8—9 月 Claude 质量下降到底是怎么回事。
要点：
- 复盘三个独立的基础设施 bug，它们叠加导致了部分请求的输出质量下降
- 涉及请求路由到错误的上下文窗口配置、输出内容损坏、以及推理栈的编译问题
- 说明了为什么难发现：bug 只影响一部分请求，而且症状表现为"质量下降"而不是"报错"
- 解释了为什么他们最初无法从用户报告中定位问题
我的补充：这一条我推荐的读法是"当成事故分析的教材"，而不是当成关于 Claude 的新闻。 它讲的问题模式在任何 ML 服务里都会出现。
最值得学的一点：当故障表现为"质量下降"而不是"错误"时，常规监控是瞎的。 HTTP 200、延迟正常、错误率为零，但输出变差了。这类故障：
- 传统指标（错误率、延迟、可用性）完全看不到
- 用户能感觉到，但描述不出来——"感觉变笨了"无法转成可查的线索
- A/B 对比困难，因为模型输出本身就有随机性
这直接推出一个工程结论：跑 LLM 服务必须有输出质量的自动化监控，而不只是可用性监控。我的做法是维护一组固定的 golden 请求，定期跑并比对输出特征——不追求逐字相同（不可能），而是看长度分布、格式合规率、关键字段是否出现这类可量化的指标突然偏移。
另一个值得注意的是"多个 bug 叠加"这个模式。 单个 bug 影响 5% 请求可能淹没在噪音里，三个叠起来就出现了明显但难以归因的现象。这也是为什么"用户报告增多"这个信号本身要当成需要调查的输入，即便你手上所有指标都正常。
27. Effective context engineering for AI agents
来源：Anthropic Engineering，2025 年 9 月 29 日。结构性
读它解决什么：上下文窗口该怎么用，为什么"塞满"是错的。
要点：
- 提出 context engineering 这个说法，替代更窄的 "prompt engineering"
- 核心论点：上下文是有限资源，要主动管理，不是能塞多少塞多少
- 讨论的手段包括：compaction（压缩历史）、结构化的 note-taking（把状态写到上下文外面）、子 agent 隔离、及时清理无用内容
- 指出上下文变长会带来注意力分散的问题——信息多不等于表现好
我的补充："上下文是有限资源"这个框架，是我用下来对实际效果影响最大的一个认知转变。 它把一堆看起来无关的技巧统一到了同一个目标下：让上下文里的每个 token 都在起作用。
具体到我自己的做法：
- 长任务把状态写到文件里。 让 agent 维护一个进度文件，而不是靠对话历史记住做到哪了。好处是压缩历史时状态不会丢——这是长任务失败最常见的原因。
- 大范围搜索交给子 agent（第 24 条），主上下文只收结论。
- 重复的约定固化成文件（
CLAUDE.md、Skill），不要每次在对话里重述。 - 注意工具返回的体积。 一个把整个文件内容返回的工具，调用几次就能吃掉小半个窗口。
"信息多不等于表现好"这一点反直觉，但我实测确实如此。 上下文里有大量弱相关内容时，模型会被带偏——比如你早前贴过一段无关代码，它后面可能会去修改那段代码。给 100k token 的完整代码库，效果常常不如给 10k token 的相关部分。 这也解释了为什么"整个仓库塞进去"这种做法效果往往不好。
2025 年底：技能、沙箱与工具协议
28. Equipping agents for the real world with Agent Skills
来源：Anthropic Engineering，2025 年 10 月 16 日。部分会过期
读它解决什么：Agent Skills 是什么，解决什么问题。
要点：
- Skill = 一个文件夹，里面放 Markdown 指令，可以带脚本和资源
- 关键机制是按需加载：只有相关时才把内容读进上下文，不占用平时的窗口
- 目的是把重复的专业知识和流程固化下来，跨会话复用
- 组合性：多个 Skill 可以叠加使用
我的补充：Skill 解决的是一个很具体的成本问题：你有一套流程，每次要用都得重新解释一遍。
"按需加载"是这个设计的关键，也是它和 CLAUDE.md 的本质区别。 CLAUDE.md 是每次会话都进上下文的——所以只该放高频、通用的东西。Skill 是只在需要时才展开的——所以可以放很长、很专的内容而不用担心占窗口。
我的划分标准很简单：
- 每次都用的 →
CLAUDE.md（构建命令、目录约定、禁止项） - 偶尔用但每次都要详细说明的 → Skill（发版流程、特定格式的报告模板、某个复杂子系统的操作手册）
写 Skill 时最容易犯的错是写成文档。 Skill 的读者是 agent，不是人。所以：写明确的步骤和判断条件，不写背景介绍；把"什么情况下用这个 Skill"写在最前面（这决定了它会不会被正确触发）；能用脚本代替说明的就用脚本——一个能跑的脚本比五段描述可靠得多。
对应第一卷第 10 条（Simon Willison 对 Skills 的分析），两条一起读能看到"外部视角"和"设计者视角"的差别。
29. Beyond permission prompts: making Claude Code more secure and autonomous
来源：Anthropic Engineering，2025 年 10 月 20 日。结构性
读它解决什么：每步都问用户"允许吗"不可持续，有没有别的办法。
要点：
- 指出权限确认的困境：问太多会导致用户无脑点同意，问太少则不安全
- 转向操作系统层面的沙箱：文件系统隔离、网络限制
- 思路是在受限环境里给更大的自由度，而不是在开放环境里逐步审批
我的补充："问太多导致无脑同意"这个观察是这篇的核心，它在安全领域有个名字叫 alert fatigue（告警疲劳）。
这个机制值得讲清楚，因为它反直觉：增加确认次数在超过某个阈值后会降低安全性，不是提高。 因为用户看到第 50 个确认框时已经不读内容了，此时第 51 个真正危险的操作也会被批准。所以"多问一句更安全"这个直觉是错的。
沙箱思路的正确性在于它改变了失败模式：
- 权限确认的失败模式是人的判断失误——而人在疲劳时判断力必然下降
- 沙箱的失败模式是边界配置错误——这是一次性的、可以审查的、可以自动化测试的
后者可靠得多，因为它不依赖任何人在第 51 次仍然保持警惕。
实践上，我倾向于两层都要：沙箱作为兜底（哪怕判断失误也不会造成不可逆损害），确认只保留给真正高风险的少数操作（写生产、删数据、发外部请求）。关键是确认框要少到你愿意每次都读。
对应第 32 条（auto mode）是这条思路的产品化。
30. Code execution with MCP: Building more efficient agents
来源：Anthropic Engineering，2025 年 11 月 4 日。会过期
读它解决什么：MCP 工具很多时上下文吃不消，怎么解决。
要点：
- 问题：把所有 MCP 工具定义都放进上下文，工具一多就占掉大量 token
- 方案：把 MCP 服务器暴露成代码 API，让 agent 写代码来调用，而不是走工具调用协议
- 好处包括：只加载需要的部分、可以在代码里做过滤和聚合、中间结果不必进上下文
我的补充：这一条的核心洞察是："让模型写代码调用工具"比"让模型逐个调用工具"在很多场景下效率高一个量级。
原因有三层，逐层递进：
- 工具定义不必全部进上下文——需要哪个查哪个。工具从 5 个涨到 50 个时，这一点从优化变成必需。
- 中间结果可以在代码里处理掉。 "取 1000 条记录，筛出符合条件的 3 条"——走工具调用要把 1000 条塞进上下文再筛；写代码则只有 3 条进上下文。这是差距最大的一点。
- 循环和条件天然可表达。 "对每个用户执行 X" 用代码是三行，用工具调用是 N 轮往返。
代价是明确的：需要一个能执行代码的沙箱，而且这个沙箱现在成了你的攻击面——agent 生成的代码会在里面跑，而 agent 可能被 prompt injection 影响（见第三卷）。所以这条路的前提是沙箱本身足够严格：无网络或严格白名单、文件系统隔离、资源限制、超时。
标了会过期是因为具体的 MCP 接口形态还在变，但"用代码而不是逐个调用"这个思路会留下来。
31. Introducing advanced tool use on the Claude Developer Platform
来源：Anthropic Engineering，2025 年 11 月 24 日。会过期
读它解决什么：平台层面为工具使用提供了哪些新能力。
要点：
- 介绍一组进阶的工具使用特性，方向是减少工具定义对上下文的占用、以及让工具调用更程序化
- 与第 30 条的思路一致：工具数量增长后，"全量加载定义"这个模式撑不住
我的补充：这一条和第 30 条是同一个问题的两种解法——一个在应用层（自己写代码调 MCP），一个在平台层（API 直接支持）。平台层的方案省事，应用层的方案可控且不绑定厂商。
我的选择标准：如果你的工具集稳定且不多（十几个以内），平台方案更省事；如果工具很多、或者需要复杂的中间处理、或者你不想绑在单一厂商上，自己做代码执行那条路更可控。
这条标了会过期，且过期速度可能是这一卷里最快的——具体 API 形态半年内很可能就变了。读它的价值在于理解"工具数量增长带来的上下文压力"这个问题本身，以及各家会往哪个方向解。问题会留下来，这版 API 不一定。
32. Effective harnesses for long-running agents
来源：Anthropic Engineering，2025 年 11 月 26 日。结构性
读它解决什么：让 agent 跑几个小时甚至更久，外围需要什么支撑。
要点：
- harness = 模型外围的那一整套脚手架：上下文管理、工具、状态持久化、错误恢复、进度追踪
- 长任务的核心难点：上下文会超、错误会累积、状态会丢
- 讨论的手段包括 checkpoint、状态外置、以及失败后的恢复策略
我的补充："harness" 这个词值得记住，因为它命名了一个此前没被明确讨论的东西：模型之外的所有工程部分。 而在长任务里，harness 的质量比模型的质量更决定结果——这个判断我实测认同。
长任务失败的三个模式，以及对应的手段：
- 上下文耗尽。 跑了两小时，历史塞满窗口，压缩后丢了关键状态。→ 状态必须写在上下文外面（文件、数据库），上下文只当工作区。
- 错误累积。 第 30 步一个小偏差，第 80 步变成完全跑偏。→ 要有周期性的"对照原始目标检查"，而不是一路顺着自己的输出往下走。
- 不可恢复。 跑了三小时，最后一步失败，全部重来。→ checkpoint。每完成一个可验证的阶段就存档。
第 1 条是最普遍的，第 3 条是最贵的。 我的经验是先解决第 3 条——因为在你调试 harness 的过程中，会反复遇到"跑了很久然后失败"，没有 checkpoint 的话调试成本高得离谱。
一个具体做法：让 agent 维护一个结构化的进度文件（当前阶段、已完成项、待办项、遇到的问题），每步更新。这个文件同时充当 checkpoint 和状态存储，而且人也能读——出问题时你能一眼看出它跑到哪、在想什么。
2026 年：评测、并行与可靠性
33. Demystifying evals for AI agents
来源：Anthropic Engineering，2026 年 1 月 9 日。结构性
读它解决什么：怎么评测一个 agent 系统好不好。
要点：
- 讲 agent 评测和单轮 LLM 评测的区别：路径不唯一、状态有副作用、失败方式更多样
- 强调要评测最终结果而不只是中间步骤
- 讨论怎么设计能真正反映实际任务的评测集
我的补充：没有评测，你对 agent 系统的所有改动都是猜。 这句话听起来老套，但在 agent 场景下比在传统软件里更严重——因为输出有随机性，你无法通过跑一次来判断改动是好是坏。改了 prompt 感觉变好了，可能只是这次运气好。
agent 评测比单轮评测难的具体地方：
- 路径不唯一。 同一个任务可以有五种正确解法，不能按步骤比对，只能看结果。
- 有副作用。 评测跑完可能改了文件、发了请求，下一次跑的环境已经不一样了。所以每次评测都需要干净的初始状态——这是工程量最大的部分。
- 失败方式多。 可能做错、可能死循环、可能中途放弃、可能声称完成但实际没做。"声称完成但没做"是最需要专门检测的一类，因为它在日志里看起来像成功。
我自己的最小可用做法：准备 10–20 个真实任务，每个都有可自动判定的成功标准（测试通过、文件包含某内容、命令返回 0）。改动前后各跑三遍，比通过率。规模小但比"感觉变好了"可靠得多，而且能挡住绝大多数明显的退步。
34. Designing AI-resistant technical evaluations
来源：Anthropic Engineering，2026 年 1 月 21 日。结构性
读它解决什么：AI 能轻松通过大多数技术面试题之后，怎么考察真实能力。
要点：
- 讨论传统技术评估在 AI 辅助下失效的问题
- 方向是考察 AI 不容易替代的部分：判断力、权衡、对现有系统的理解、调试真实问题
我的补充：这一条的适用范围比"招聘"大得多——它其实在回答"人在这套工作流里的价值是什么"，这个问题对你自己的职业规划同样成立。
那些明显失效的题型：写一个排序、实现某个数据结构、LeetCode 中等难度题——这些现在几乎无法区分候选人。
我认为仍然有区分度的方向：
- 给一个有 bug 的真实系统，让他找出并修复。 关键考察点是定位过程而不是修复动作。（对应第一卷讲调试的那些条）
- 让他 review 一段 AI 写的、有微妙问题的代码。 这直接对应实际工作内容，而且**"能不能看出问题"这个能力无法外包给 AI**——因为 AI 就是问题的来源。
- 给一个含糊的需求，看他问什么问题。 提对问题的能力目前仍然稀缺。
- 让他解释一个技术决策的取舍。 不问"用什么"，问"为什么不用另一个"。
共同点是：这些题都要求"判断"，而不是"产出"。 产出正在变便宜，判断没有。这也是我认为个人应该把学习精力放在哪里的答案。
35. Building a C compiler with a team of parallel Claudes
来源：Anthropic Engineering，2026 年 2 月 5 日。结构性
读它解决什么：多个 agent 并行做一个大型、结构复杂的项目，实际怎么组织。
要点：
- 用一组并行的 Claude 实现一个 C 编译器
- 编译器这个选题的特点：规模大、模块边界清晰、正确性可自动验证
- 讲了任务如何切分、并行如何协调
我的补充：选 C 编译器做这个实验非常聪明，理由值得单独说：
- 模块边界天然清晰——词法、语法、语义分析、代码生成，接口定义明确。这是并行的前提。
- 正确性可以自动验证——有现成的测试套件，编译出来的程序跑对了就是对了。这解决了并行最大的难题：怎么知道每个 agent 做对了。
- 规模足够大——单个上下文装不下，必须分工。
- 有明确的规范——C 标准是白纸黑字的，不需要猜需求。
这四个条件恰好是"并行 agent 能work"的完整前提清单。 我认为这比文章的具体结论更有价值：拿到一个任务时，用这四条对一遍，就能判断并行是否合适。
反过来看，不满足这些条件的任务，并行 agent 会很难受：
- 边界不清（比如改一个耦合严重的老系统）→ 多个 agent 改同一片代码，冲突比进展多
- 无法自动验证（比如 UI 好不好看）→ 你要人工审查 N 份产出，审查成本超过并行收益
- 规模不够（几百行的功能）→ 协调开销大于收益，单 agent 更快
配合第一卷第 8 条（并行 coding agent 的实践坑）读，一个讲成功案例的条件，一个讲日常使用的摩擦。
36. Quantifying infrastructure noise in agentic coding evals
来源：Anthropic Engineering，2026 年 2 月 5 日。结构性
读它解决什么：agent 评测的分数波动里，有多少来自基础设施而不是模型。
要点：
- 量化评测环境本身带来的噪音：网络波动、依赖安装失败、超时、环境差异
- 说明这类噪音会污染评测结论
我的补充：这一条和第 33 条是配套的，讲的是评测里那个容易被完全忽略的误差来源。
我踩过的具体坑：一次评测里 agent 的"失败"，事后查是 npm install 因为网络问题超时。模型完全没问题，但分数记成了失败。 这类噪音的麻烦在于它看起来像模型能力问题——日志里就是"任务没完成"。
实践上要做的几件事：
- 区分"环境失败"和"任务失败"。 依赖装不上、网络超时、磁盘满，这些应该标记为无效样本重跑，而不是计入失败率。不区分的话，你的评测在测你的网络。
- 依赖预装或缓存。 别让每次评测都去拉网络。这一步同时提速和降噪。
- 同一改动多跑几次看方差。 如果方差比你想测的差异还大，那这个评测结论没有意义——这是最容易被跳过的一步，也是最能防止自欺的一步。
- 记录足够的诊断信息，让你事后能判断某次失败属于哪一类。
判断标准很简单：如果你的评测噪音是 ±5%，那 3% 的提升是看不出来的。 先降噪，再优化。
37. Eval awareness in Claude Opus 4.6's BrowseComp performance
来源：Anthropic Engineering，2026 年 3 月 6 日。会过期
读它解决什么：模型能察觉自己在被评测，这对评测结果意味着什么。
要点：
- 分析 Claude Opus 4.6 在 BrowseComp 上的表现与"评测意识"（eval awareness）的关系
- 涉及模型识别出测试场景后行为是否改变的问题
我的补充：这是个从评测方法论角度看相当麻烦的问题：如果模型能识别"我在被测试"，那评测测到的可能不是它在真实场景下的行为。
这个现象在社会科学里叫 Hawthorne 效应——被观察者知道自己被观察时，行为会变。 现在它出现在 ML 评测里了。
它带来的具体困难：
- 评测集合成痕迹明显（任务过于工整、没有真实项目的杂乱），模型可能据此识别出测试环境
- 一旦识别，行为可能改变——更谨慎、更冗长、或者更倾向于给"标准答案"
- 于是评测分数和实际部署表现之间出现了系统性偏差，而这个偏差的方向你事先不知道
我能想到的应对方向：让评测任务尽量接近真实（用真实项目的真实 issue，而不是构造的题目）、在真实使用中采样评估而不只依赖离线评测集、以及关注行为一致性（同一任务在"明显是测试"和"看起来是真实"两种包装下表现是否一样）。
标了会过期是因为它绑定具体模型版本。但**"评测意识"这个问题本身会长期存在，而且随模型能力提升会更明显**——这是读它的理由。
38. Harness design for long-running application development
来源：Anthropic Engineering，2026 年 3 月 24 日。结构性
读它解决什么：用 agent 做完整应用开发（不是单个功能）时，harness 该怎么设计。
要点：
- 是第 32 条的延伸，聚焦在"开发一个完整应用"这个场景
- 涉及长周期任务里的状态管理、阶段划分、以及如何保持方向不跑偏
我的补充：从"完成一个任务"到"开发一个应用"，难度增加的地方不在代码量，而在一致性：
- 决策要记住。 第 3 天做的技术选型，第 20 天不能忘。这必须写在上下文外面——写成文档、ADR（架构决策记录），否则一定会丢。
- 风格要统一。 否则你会得到第一卷第 20 条描述的那种概念完整性崩塌：同一个概念四种叫法，五套并行的模式。
- 不能重复造。 第 10 天写的工具函数，第 25 天别再写一个功能相同接口不同的。
- 方向不能漂。 长周期里每一步都"合理"，累积起来可能已经偏离最初目标很远。
我认为最关键的手段是把"项目的当前状态"外置成人和 agent 都能读的文档：架构决策、已有模块和它们的职责、命名约定、待办和已知问题。这份文档是 harness 的核心，不是附属品。
它同时解决两个问题：agent 每次开工先读它，就能接上之前的决策；你想知道项目现状时，读它比读代码快。
配合第一卷第 20 条（概念完整性）读，一个讲问题一个讲手段。
39. How we built Claude Code auto mode: a safer way to skip permissions
来源：Anthropic Engineering，2026 年 3 月 25 日。会过期
读它解决什么：怎么在不逐条确认的前提下保持安全。
要点：
- auto mode 的设计：跳过逐条权限确认，同时通过其他机制保证安全
- 是第 29 条思路的产品化落地
我的补充：这一条是第 29 条那个论点走到产品里的结果——从"每步问你"变成"在受限环境里自主跑"。
我自己用这类模式的判断标准，核心是**"最坏情况可接受吗"**：
- 在能整个丢掉的环境里（容器、worktree、临时目录）→ 放开跑，出问题删掉重来
- 在真实工作目录里 → 至少要有干净的版本控制状态，随时能
git reset - 能碰到生产、能发外部请求、能删数据 → 不放开，无论工具提供什么保障
这个标准不依赖你对工具的信任程度，只依赖"如果它做了最糟的事，我损失什么"。 我认为这是唯一稳的判断方式——因为工具的保障机制你无法完整验证，但"这个目录能不能整个删掉"你自己清楚。
标了会过期因为是具体产品特性。但**"用环境约束替代逐步审批"这个方向是对的，会留下来。**
40. Scaling Managed Agents: Decoupling the brain from the hands
来源：Anthropic Engineering，2026 年 4 月 8 日。结构性
读它解决什么：大规模跑 agent 时，架构上怎么拆。
要点：
- 核心思路是把"决策"和"执行"分开——brain（模型推理）与 hands（工具执行环境）解耦
- 目的是让两部分能独立扩展
我的补充："大脑和手分开"这个架构判断值得记住，理由是这两部分的资源特性完全不同：
- 推理：GPU 密集、无状态、可以任意水平扩展、按 token 计费
- 执行：需要持久化环境（文件系统、进程、安装的依赖）、有状态、需要隔离、按时间和资源计费
混在一起时，你被迫按两者的最大需求配置资源，浪费严重。 拆开之后各自按需扩展：推理层可以是无状态的服务池，执行层可以是容器池，各自的伸缩策略独立。
这也让沙箱隔离更自然（第 29、39 条）：执行环境本来就是独立的进程/容器，隔离是架构的一部分，不是额外加的一层。
一个次要但实在的好处：执行环境可以复用。 同一个 agent 会话的多次工具调用共享一个容器，依赖不用反复安装——这直接对应第 36 条讲的评测噪音问题。
本卷小结：21–23 条是基础认知（第 21 条的 agent 分类学和第 23 条的 Claude Code 实践是必读）；24–27 条是多 agent 与上下文工程（第 27 条上下文工程改变了我的实际做法）；28–32 条是技能、沙箱、工具协议（第 32 条 harness 概念最重要）；33–40 条是 2026 年的评测方法论和架构演进（第 33 条评测是所有优化的前提）。
这一卷里最不会过期的五条：第 21、27、32、33、40 条。 从"agent 有哪几种"到"怎么评测"到"怎么拆架构"，是一条完整的工程线。
上一卷： ← ① Agentic 编程实践 · 总览： 工具资料库 · 下一卷： ③ Agent 安全与 Prompt Injection →