Agent Harness 的工程化与 Eval 驱动迭代方法论

从 Claude.ai 复刻实践出发——一份面向独立开发者的实战白皮书。

摘要

本白皮书源于一次具体的工程实践:作者在自身 Claude 账号被封禁后,基于个人使用体验,用两到三天时间手工复刻了 Claude.ai 的 agent 体验,实现了采访卡片、联网搜索、代码运行、长文档生成等核心功能。最终成品虽然达到了可用水平,但与原版相比仍存在显著的体感差距——作者估算大约只复原了 50% 的体验。

这一实践引出了一个核心问题:在 LLM agent 系统中,底座模型与 agent harness(骨架)各自的贡献究竟有多大?Anthropic 的对外营销叙事强调模型本身,但其工程团队在过去一年中密集发布的内容——《Building Effective Agents》《Writing Effective Tools for Agents》《Effective Context Engineering for AI Agents》《Demystifying Evals for AI Agents》——几乎全部围绕 harness 展开。这种叙事张力本身,就是答案的一部分。

本白皮书系统整理了 Claude.ai 与 Claude Code 在 harness 层面的关键设计决策,论证了「模型给你 100% 的潜能,harness 决定能兑现多少」这一观点。在此基础上,我们提出了一套面向独立开发者的、可执行的 eval 驱动迭代方法论,并给出了具体的数据收集方案、对比实验设计、scorer 设计原则与两周内可落地的执行路线。

白皮书的目标读者是:已经动手构建过 agent 系统、但因缺乏方法论而陷入「凭感觉调试」困境的独立开发者与研究者。我们假设读者已经具备基础的 LLM API 使用经验,但尚未建立起 eval-driven development 的工程肌肉。

第一章 引言:一次复刻实践引发的思考

1.1 实践背景

故事的起点很朴素。作者的 Claude 账号被封禁后,凭借此前作为 Claude.ai 重度用户的使用记忆,尝试通过 Anthropic API 自行搭建一个类似的 agent 体验。在两到三天的密集开发中,实现了以下核心功能:

• 采访卡片(交互式信息收集组件)
• 联网搜索(web search 工具集成)
• 代码运行(代码执行沙箱)
• 长文档生成(结构化输出与 artifact 机制)

成品在功能维度上覆盖了 Claude.ai 的主要能力。然而,在实际使用中,作者发现一个反直觉的现象:即便使用完全相同的底座模型,自建版本与官方 Claude.ai 在体验上仍然存在明显差距。作者主观估算这一差距约为 50%——也就是说,纯 API 加上一个手工 harness,只兑现了官方产品体验的一半左右。

1.2 核心疑问

这一观察直接挑战了一个流行的认知:既然底座模型是相同的,为什么外在体验差距如此显著?这一观察衍生出三个层层递进的问题:

1. 认知层面:在 LLM agent 系统中,底座模型与 harness 各自贡献多少?
2. 工程层面:Anthropic 究竟在 harness 中做了哪些设计,使其能「压榨」出模型剩余的 50%?
3. 方法论层面:作为独立开发者,如何系统性地测量与缩小这一差距?

本白皮书将依次回应这三个问题。读者将看到,前两个问题的答案最终都指向第三个问题——eval 驱动的工程方法论。没有这套方法论,任何关于 harness 优化的讨论都停留在「凭感觉」的层面。

1.3 一个值得分享的反思

本白皮书的另一位「作者」——本文协同作者——分享了一段更早的相关经历。在毕业设计期间,他曾尝试构建一个 multi-agent 系统。彼时的他「完全是个半吊子,没看过什么论文,也没看过什么代码,只是用 Cursor 凭感觉调试修改,甚至没有做很多实验看效果」。结果是「一地鸡毛」。事后回顾,他说:「要是再来一次,我一定砍掉复杂的系统,做更多实验,用数据说话。」

这段反思具有典型性。绝大多数 agent 项目的失败,根因不是模型不够强,也不是开发者不够聪明,而是缺少一个能「用数据说话」的反馈回路。本白皮书的下半部分,将围绕如何建立这个回路展开。

第二章 认知校正:harness 不是「外壳」,是产品本身

2.1 一个被误导的二元框架

在公众讨论中,「模型 vs. 外壳」是一个常见的二元对立。这种叙事将模型描绘为「内核」,而将围绕模型的工程实现降格为「补充层」或「封装层」。Anthropic 的对外营销也部分助长了这一印象——其产品宣传始终把焦点放在模型能力的代际跃升上。

然而,Anthropic 工程团队的内部语言完全不同。在《Demystifying evals》一文中,Anthropic 明确写道:

「当我们评估一个 agent 时,我们评估的是 harness 和 model 一起工作的效果。」

注意这句话的措辞:agent 不是 model,agent 是 harness + model。在 Anthropic 内部的工程语言里,Claude.ai 和 Claude Code 从来就不是「模型加一个 UI 套壳」,而是「模型 + harness 共同构成的产品」。harness 的质量直接决定了模型能力的兑现率。

2.2 harness 作为可复用资产

一个更强的证据来自 Anthropic 自身的产品决策。2026 年初,Anthropic 将 Claude Code SDK 正式更名为 Claude Agent SDK,理由是:

「Claude Code 已经远不止是编码工具。我们用它做深度研究、视频创作、记笔记……它在驱动我们几乎所有主要的 agent loop。换句话说,驱动 Claude Code 的 agent harness 也能驱动很多其他类型的 agent。」

这一更名背后的工程含义是:harness 被 Anthropic 视为可以独立于具体任务复用的核心资产。其价值至少不低于、甚至高于「为某个垂直场景专门微调模型」。这与公众认知中「模型是核心,壳子可以随便换」的图像完全相反。

2.3 一个更准确的表述

基于上述讨论,我们建议将「模型 vs. 外壳」这一二元框架,替换为以下表述:

模型给你 100% 的潜能,harness 决定能兑现多少。

这一表述有几个重要含义:

第一,harness 不会让模型「超出」自身能力上限。一个 1B 参数的小模型,无论 harness 设计得多么精妙,都无法解决需要复杂推理的任务。

第二,harness 决定了模型在具体场景下能「用出」多少能力。一个 SOTA 模型,如果挂在劣质 harness 上,实际表现可能比中等模型 + 优质 harness 更差。

第三,这意味着 harness 的工程价值具有「杠杆」特性——它放大或抑制底层模型的能力。

作者的复刻实践之所以只能兑现 50% 的体验,根因不是模型不够强(模型是同一个),而是手搓的 harness 截留了模型一半的能力。这种「截留」是隐性的、不易察觉的,但其累积效应在用户体感上极为明显。

第三章 Claude.ai 与 Claude Code 的核心架构设计

本章系统整理 Anthropic 公开的工程内容,提炼出五个最关键的 harness 设计维度。这些维度构成了官方产品与手搓复刻之间的核心差距。

3.1 Context Engineering:上下文工程

3.1.1 概念定义

Context Engineering 是 Anthropic 在 2025 年下半年正式提出的工程概念,定位为 prompt engineering 的进化版。其核心论点是:模型存在「attention budget」(注意力预算)——context 越长,性能越差。这一现象被称为 context rot(上下文腐坏)。

因此,好的 agent 不是把所有相关信息塞进 context,而是——用 Anthropic 的原话——

「找到能最大化目标达成概率的最小高信号 token 集合。」

这与许多开发者的直觉相反。常见的错误是:既然模型支持 200k context,就把所有可能相关的资料、所有工具描述、所有历史对话全部塞进去。结果是模型在长 context 下出现注意力涣散、关键信息被淹没、推理质量下降。

3.1.2 三个核心技术

Context Engineering 包含三个具体技术,分别应对不同场景:

Compaction(压缩):当对话接近 context 上限时,把历史总结成新窗口,保留目标、决策、未决问题,丢弃冗余细节。Claude Code 的长时间运行能力即依赖此机制。压缩的难点在于平衡 recall(召回所有相关信息)与 precision(去除噪声),需要专门设计的压缩 prompt。

Structured note-taking / Agentic memory(结构化笔记 / Agent 记忆):让 agent 把笔记写在 context 之外的持久化存储中,需要时再读回 context。Claude Code 的 CLAUDE.md、TODO 列表、文件系统中转都是这一思路的具象化。这种「外置记忆」避免了反复在 context 中重复同样的信息。

Just-in-time retrieval(即时检索):不预先把整个知识库 embedding 后扔进 context,而是只保留「轻量标识符」(文件路径、查询语句、URL),执行时再用工具动态加载具体内容。这是 Claude Code 与裸 API 调用最大的体感差异——Claude Code 不是「我已经知道你的代码库」,而是「我有 grep、ls、view 工具,需要时去看」。

3.1.3 对手搓 agent 的启示

如果你的复刻版只是把搜索结果、工具返回值一股脑往 context 里堆,模型几乎必然会出现 context rot,表现明显下降。这非常可能就是体感差距的最主要来源。

3.2 工具设计:agent 与确定性系统之间的契约

3.2.1 一个被忽略的洞察

Anthropic 在《Writing effective tools for agents》中给出了一个被很多人忽略的洞察:

「工具是确定性系统与非确定性 agent 之间的契约——和传统 API 完全不同,必须考虑 agent 会幻觉、会误解用途、会错误调用。」

这意味着:为人类开发者设计的 REST API,直接挂给 agent 用,大概率是失败的。工具描述、参数命名、错误信息、返回格式,都需要为 agent 的「非确定性消费」重新设计。

3.2.2 五个具体设计点

工具响应的 token 预算。Claude Code 默认把工具响应限制在 25,000 token 以内,并鼓励 agent 做多次小范围、有针对性的搜索,而不是一次大而全。如果你的工具(比如网页 fetch)动辄返回几万 token 的 HTML 原文,context 立刻就被污染。

工具描述本身就是 prompt。工具描述和参数规格被加载进 agent 的 context,会集体引导 agent 的工具调用行为。写工具描述时,应当采用「给新员工写说明」的标准,把你隐性带入的上下文显式化:特定的查询格式、术语定义、资源间关系。

参数命名要无歧义。用 user_id 而不是 user。用 created_after_utc 而不是 created_after。歧义的参数名会导致 agent 产生看似合理但错误的调用。

错误信息要可执行。报错不能是 Python traceback。要写成「你应该怎么改」的形式。例如:「参数 date 格式错误,期望 YYYY-MM-DD,收到 2026/5/11,请改用连字符分隔。」

工具数量要克制。Claude Code 内部采用三层结构(build-time 消除 + 条件激活 + feature flag)动态管理工具集。太多工具会让系统提示词膨胀、token 成本上升、agent 在选择时混乱;太少则能力受限。不同任务下,Claude 看到的工具集是不同的——这意味着 Claude.ai 实际上是按场景动态裁剪工具的。

3.3 单线程主循环 + 受控并行

3.3.1 反直觉的架构选择

Claude Code 的架构是反直觉的——它故意不搞复杂的多 agent 编排。研究者反向工程后发现,Claude Code 的核心就是一个单线程主循环(代号 nO),配合实时 steering、扁平的消息历史、基于 TODO 的规划、diff-based workflow,以及通过有限的 sub-agent 派生实现受控并行。

其核心思想是:

简单的单线程主循环 + 自律的工具 + 规划 = 可控的自主性。

可调试性和透明度优先于「看起来很厉害的多 agent swarm」。这一选择与许多开源项目中的多 agent 编排框架形成鲜明对比。

3.3.2 何时使用 sub-agent

sub-agent 只在特定场景才被启用:当需要「复杂探索 vs. 主线综合」的隔离时——例如深度研究。sub-agent 各自带着独立的 context 探索,只把短摘要回传给主 agent。这种模式实现了:

• 关注点分离:主 agent 不需要承载所有探索细节
• context 隔离:探索过程产生的大量中间内容不污染主 context
• 并行加速:多个 sub-agent 可以同时工作

但这种模式有明确的代价:可调试性下降、行为可预测性下降、token 消耗上升。因此 Anthropic 的建议是:在前述基础功能没有打磨好之前,不要引入 sub-agent。

3.4 渐进式披露的系统提示词

3.4.1 模块化的 system prompt

有人通过反向工程 Claude.ai 的 generative UI 功能,发现 Anthropic 使用了一个非常聪明的做法——每个 UI 模块返回不同的设计规范:chart 模块给 Chart.js 模式,art 给插画规则,mockup 给 UI 组件 tokens。研究者将其描述为:

「这是一个懒加载的文档系统——不是预先把整套设计系统塞进 context(每条消息都要付昂贵的 token 成本),而是按需加载相关子集。」

这其实是 progressive disclosure(渐进式披露)原则在 system prompt 上的应用。基础 prompt 保持精简,专门知识在任务触发时才加载。SKILL.md 机制是这一原则的另一个具象化:每个 skill 是一个独立的文档,只在需要时被读入。

3.4.2 对手搓 agent 的启示

如果你的版本是把整个超长 system prompt 一次性塞进每轮请求,不仅烧 token,还会触发 context rot。一个更好的设计是:

• 基础 system prompt 极简,只包含 agent 的身份、最核心的行为准则、工具列表
• 专项知识(代码风格、绘图规范、文档模板)做成独立的模块文件
• 提供一个 read_module 或类似工具,让 agent 在需要时主动加载

这种设计同时降低了 token 成本和 context 污染

3.5 Eval 驱动的迭代闭环

3.5.1 一个关键的方法论

这一点最容易被独立开发者忽略,但其实是 Anthropic 工程能力的核心来源。Anthropic 的工程文章明确给出了启动建议:

「20-50 个从真实失败中抽取的简单任务就是很好的起点……早期 agent 开发中,每个改动都有显著影响,大效果意味着小样本就够用。」

Anthropic 内部用 eval 驱动 harness 的迭代——改一个工具描述,跑 30 个 case,看 pass rate 变化。手搓项目两三天做出来、凭体感调整,迭代速度被自己拖住——这不是「做得不够好」,而是「没有反馈回路所以无法变好」。

3.5.2 eval 驱动的核心价值

eval 驱动开发(Eval-Driven Development, EDD)的核心价值不在于「测出当前分数」,而在于:

• 提供了客观的迭代反馈,避免开发者陷入「自我说服」的循环
• 使得回归测试成为可能——每次改动都能验证「哪些好了、哪些坏了」
• 将「经验」转化为「资产」——失败 case 一旦进入 eval set,就永久保留
• 使团队协作成为可能——多人改动可以用同一套基准评估

这一方法论将贯穿白皮书的后半部分。

第四章 公开 Agent Eval 数据集全景

在进入方法论之前,我们先盘点当前业界主流的公开 agent eval 数据集。这些数据集是构建自己的 task suite 时的重要参考素材,但需要注意:它们多数测的是「模型 + harness 整体能力上限」,而非「在固定模型下不同 harness 的差异」——这两者是不同的问题,我们将在第五章详细辨析。

4.1 软件工程与代码

SWE-bench Verified。事实上的代码 agent 评测标准。任务来自真实 GitHub issue,通过运行测试集判定。其 outcome validity 问题(不正确的补丁也可能通过测试)被论文专门点名,但仍是目前最权威的代码 agent 基准。

SWE-Lancer。从 Upwork 抽取的真实自由职业任务,共 100 万美元总价值。比 SWE-bench 更贴近真实软件工程的多样性。

4.2 通用助手与多步推理

GAIA。测试「通用助手能力」——多步推理、网页浏览、工具使用、基础多模态理解。其设计哲学是「看似简单的提问需要一系列非平凡操作才能正确完成」,刻意抵抗投机取巧。在 Hugging Face 上维护活跃 leaderboard。

4.3 工具调用与客服式交互

τ-bench(Sierra 出品)。双 LLM 模拟用户与 agent 的对话,通过比较数据库最终状态判定成功。它引入了一个非常关键的指标 pass^k:同一题跑 k 次都通过才算通过,测的是可靠性。其实验显示即使是 SOTA 工具调用 agent,在零售场景下 pass^8 也低于 25%。这个数字非常震撼——说明大家的 agent 是脆的,只是被单次成功的 pass@1 掩盖了。

4.4 Web 与计算机操作

WebArena。812 个长程任务,在真实网页环境中测试 agent 的 web 自主性。

OSWorld。扩展到全 OS 控制,测试 agent 对图形界面软件的操作能力。

Mind2Web。聚焦于跨网站的复杂任务流。

4.5 MCP 工具使用

MCPAgentBench。2025 年末新出,与现代 agent 开发场景高度相关。包含真实 841 个任务和超过 20,000 个 MCP 工具,采用带 distractor(干扰项)的动态沙箱环境,测试 agent 的工具选择与辨别能力。这对手搓 agent 尤为有参考价值,因为它专门测「在一堆工具里选对的」。

4.6 长程工作流

WorfBench(ICLR 2025)。使用子序列和子图匹配算法量化 agent 的工作流生成能力。研究发现即使是 GPT-4 在序列规划和图规划能力之间也有约 15% 的差距,说明 linear 任务和 DAG 任务对 agent 的要求显著不同。

4.7 评测框架推荐:Inspect AI

如果要在工程实践中真正使用上述 benchmark,我们强烈推荐 UK AI Security Institute 开源的 Inspect AI 框架(MIT 协议)。其优势:

• 已被 Anthropic、DeepMind、xAI 等顶级 AI lab 采纳为首选评测框架
• 配套的 inspect_evals 仓库已经把 GAIA、SWE-bench、Cybench、GDM CTF 等大部分主流 benchmark 统一封装
• 内置 ReAct agent、多 agent 原语、bash/python/web_search/computer 等工具
• 支持运行任意外部 agent(Claude Code、Codex CLI、Gemini CLI 等),便于横向对比
• 有 web 版 log viewer,trace 可视化非常清晰

第五章 Eval 方法论:模型 eval vs. Harness eval

5.1 一个关键区分

大部分公开 benchmark 数据集解决的是「模型能力比较」问题——即「固定 harness,比较不同模型」。但对于一个正在迭代自己 agent 的独立开发者,真正需要的是相反的问题——「固定模型,比较不同 harness」。这两个问题在实验设计、指标选择、迭代节奏上都完全不同。

5.2 实验设计的核心原则

基于上述区分,harness eval 的实验设计应当遵循以下原则:

原则一:模型作为常量,版本对齐。所有对比组都使用同一模型(精确到版本号),避免「模型能力差异」污染「harness 能力差异」。

原则二:至少三个对比组。Minimal baseline(裸 ReAct loop)、你的 harness、参考上限(如 Claude.ai 官方)。只跑自己的 agent 没有解读空间。

原则三:同一 task 集横向对比。三组在同一组 task 上跑,看绝对差距与失败模式的分布。

原则四:关注 delta,不追绝对分数。「v0.3 比 v0.2 在这 30 题上 +5 题通过」——这个信号比「我现在 65%」有用得多。绝对分数受 task 难度分布影响,delta 才反映你 harness 改动的真实价值。

原则五:trajectory metric 与 outcome metric 并重。两个 agent 都拿到正确答案,一个用了 3 个工具调用,一个用了 15 个——后者其实是失败的。

第六章 数据收集的分层方案

本章提供一个完整的、可执行的数据收集方案,分为四层。每一层服务于不同的目的,合在一起构成 harness eval 的完整闭环。

6.1 第一层:从公开数据集「借 task」(冷启动)

目标:用最少的题快速建立 baseline 对比能力。规模:30-50 题。

不要整个数据集拉下来——agent benchmark 跑一次几小时几十美元,你不需要那个规模。目的是借用 task 的设计,不借用其上的 metric 结论。

6.1.1 推荐的混合配比

6.1.2 抽样建议

• GAIA:Level 1 的 10 题 + Level 2 的 5-10 题。Level 3 太难,baseline 全 fail 反而没区分度。
• τ-bench:retail 域全部 task 约 115 道,抽前 10-15 道即可。每题用 k=4 跑(同题跑 4 次都过才算过)。
• SWE-bench Verified:挑标注难度小于 15min 的简单题 5-10 道。

6.1.3 数据 schema 设计

将三个来源的 task 统一成你自己的 schema:

• id:唯一标识符,如 gaia_001
• source:来源标签,便于按来源分析
• input:用户原始问题
• expected:期望答案或判定函数
• tools_needed:预期会用到的工具(自己标注)
• difficulty:难度(自己标注或沿用原数据集)

关键点:不要直接用各 benchmark 的 runner,把 task 抽出来塞进你自己的 harness 跑。因为你测的是 harness,不是模型。

6.2 第二层:对比组的设计

只跑你自己的 agent 没用——你需要至少两个对比组才能解读数字。

6.2.1 C 组的实操

C 组怎么跑:你不能 API 化 Claude.ai,但可以人肉跑——把 30 题手工贴进 Claude.ai web 界面,记录回答和 trajectory。30 题乘以几分钟一题等于一两个下午能搞定。这个数据非常宝贵,因为它告诉你那 50% 差距具体在哪些题上爆出来的。

6.2.2 A 组的诊断价值

A 组也很重要:如果 A 已经能解决 80% 的题,说明你 harness 的边际价值不大,要么换题(找更难的),要么承认这部分场景上 harness 设计空间小。这种「反向证伪」对避免过度工程化非常关键。

6.3 第三层:生产数据的持续收集

公开数据集是冷启动,真正能让你 harness 越来越好的是生产数据——也就是你和测试用户在真实使用中产生的对话。

6.3.1 第一周就埋点

每次在你的复刻版上发消息,自动记录以下结构化数据:

• session_id:会话标识
• timestamp:时间戳
• user_message:用户原始消息
• system_prompt_version:你的 harness 版本号
• tools_available:当前可用工具列表
• trajectory:完整的工具调用序列与中间消息
• final_response:最终回答
• user_feedback:用户反馈(初始为 null,后续填充)
• tokens_used:token 消耗
• latency_ms:延迟

存成 JSONL 格式,本地文件就行,别一开始就上 Langfuse 或 Phoenix——基础设施先简单。

6.3.2 最低成本的反馈机制

UI 上加两个按钮:点赞 / 点踩。只要这一个信号,后面 90% 的分析都能做。可选加一个 this is interesting 标签,用来标「虽然没失败但值得回看」的 case。

6.3.3 每周的 triage 习惯

每周日花 30 分钟,过一遍这周所有点踩的 case 和随机抽取的 5 个点赞的 case:

• 失败模式聚类:这周的失败主要是哪几类?工具选错?context 爆了?多轮一致性丢失?
• 挑 2-3 个最典型的失败 case,加进你的 task suite
• 每月把 task suite 重新组织一次,删掉过于简单的、保留有区分度的

这个习惯比任何工具都重要。Anthropic 团队也是这么做的,他们称之为 error analysis loop。

6.4 第四层:Scorer 的设计

收集到 task 之后,怎么判定「通过」?给你三档选择,按 ROI 排:

6.4.1 规则判定(占 40%)

用在能精确判定的题上:

• GAIA 大部分题有 exact match 答案
• SWE-bench 跑测试套件
• τ-bench 比较数据库 final state
• 自己的题:能用关键词、正则、结构化输出判定的就用规则

永远优先用规则——便宜可靠,可复现性强。

6.4.2 LLM-as-judge(占 50%)

用在主观题上。写一个判官 prompt,让 Claude(或更便宜的 Haiku)给 trajectory 打分。典型的 judge prompt 结构:

你是一个严格的评测员。给定:用户原始问题、agent 的完整 trajectory、agent 的最终回答。判定以下三个维度,每个 1-5 分:任务完成度、工具使用合理性(是否调用了不必要的工具/漏调用)、回答质量(是否准确、是否啰嗦)。返回 JSON 格式。

关键纪律:LLM judge 必须用人工抽样校准。每 50 次自动评测,人工复核 5 个,看 judge 是否跟你的判断一致。不校准的 LLM judge 是危险的——它可能系统性偏向某种风格(比如更长的回答、更多的工具调用),从而误导你的迭代方向。

6.4.3 人工评测(占 10%)

用在最关键的 ablation 上。每次做大改动(换 prompt 架构、加新工具),从 task suite 抽 10 题,手工打分。慢但绝对可靠,是 LLM judge 的 ground truth 来源。

不要省这一步。LLM judge 的所有可靠性都建立在与人工评测的定期对齐上。

第七章 反直觉的工程建议

跑过几轮 eval 之后,你会发现一些反直觉的事实。我们将这些经验提前告诉你,以节省你掉坑的时间。

7.1 pass@1 会骗你,一定要看 pass^k

同一题跑 4 次,4 次都过才算过。τ-bench 那个数字(SOTA 模型在 pass^8 上跌到 25%)就是这么得出来的。手搓 agent 在 pass^k 上的下降会比 Claude.ai 官方更剧烈——这才是真实差距,而 pass@1 会掩盖它。

更重要的是,pass^k 反映了你的 agent 在生产环境中的真实可用性。一个 pass@1 等于 80% 但 pass^4 只有 30% 的 agent,意味着用户每用 4 次会遇到 2-3 次失败,这种体验是无法接受的。

7.2 一开始 task suite 太小没关系,但要诊断性强

30 题胜过 300 题,如果这 30 题里每一题都能定位一类失败模式。题目要互相区分:测工具选择的题就不要混杂搜索准确性的考察。每加一题前问自己:「这题如果失败,我能立刻知道是哪个环节出问题吗?」

7.3 trajectory metric 跟 outcome metric 一样重要

两个 agent 都拿到正确答案,一个用了 3 个工具调用,一个用了 15 个——后者其实是失败的。把以下指标作为一等公民对待:

• 工具调用次数
• token 消耗
• 是否走回头路(同一工具用相似参数重复调用)
• 是否触发了「无效」的工具调用(参数错误、被拒绝等)
• 延迟

不要只看最终对错。trajectory 才是 harness 优劣的指纹。

7.4 别一开始就追绝对分数,追 delta

「我的 v0.3 比 v0.2 在这 30 题上 +5 题通过」——这个信号比「我现在 65%」有用得多。绝对分数受 task 难度分布影响,delta 才反映你 harness 改动的真实价值。

具体做法:每个 harness 版本号对应一个 eval run,把 run 之间的 diff 作为主要观察对象。

7.5 把 Claude.ai 官方作为持续 baseline

每个月花一下午,把当前 task suite 在 Claude.ai 上重新跑一遍。这告诉你两件事:

1. 你与官方的差距在缩小还是在扩大?
2. Claude.ai 自己有没有偷偷变强?(它会的,Anthropic 后台一直在迭代 system prompt 和 harness。)

没有这个持续对照,你可能在你认为「自己变好了」的时候,实际是 Claude.ai 变得更好。

第八章 两周可执行的落地路线

理论再扎实,如果落不到行动,价值为零。本章给出一个具体的、两周内可执行的路线图,任何具备基础 Python 能力的开发者都可以照做。

8.1 第 1 周:打基础

Day 1-4 的目标是把 eval 基础设施跑通。这一周不要试图改 harness——专注于「建立反馈回路」本身。多数项目失败,就是因为跳过了这一步,直接进入「凭感觉改代码」的循环。

Day 5-6 的对比实验是分水岭。如果 A 和 B 的差距远小于 B 和 C 的差距,说明你的 harness 努力方向偏了——你以为在做的事情,模型本身就能完成大部分。如果 A 和 B 接近 C,说明你做的事情有价值。这两种结论都需要数据才能得出,凭感觉得不到。

8.2 第 2 周:启动迭代飞轮

Day 9-13 是真正的 harness 迭代周。每个改动应当满足:

• 改动前明确假设:「我认为加上 compaction 会让长对话任务 +3 题通过」
• 改动后跑一次完整 eval,看实际 delta
• 假设被证伪也是好结果——这至少排除了一个方向,避免你在错的路上走更远

Day 14 上线埋点,标志着你从「批量 eval」模式进入「持续 eval」模式。从此你不再依赖外部数据集——你的真实用户(包括你自己)就在不断产生新的测试数据。

8.3 后续的长期节奏

两周后,你应当形成以下节奏:

• 每次改动:跑完整 task suite,看 delta(几分钟)
• 每周日:triage 这周的真实使用 case,挑 2-3 个加入 task suite(30 分钟)
• 每月:把当前 task suite 在 Claude.ai 上重跑一次,更新对照基准(1 个下午)
• 每季度:回顾 task suite 整体结构,删除过时的、补充新场景的(1 天)

这个节奏一旦稳定下来,你的 harness 进步速度会肉眼可见。

第九章 结语:从开发 agent 到 agent 工程

9.1 一个 framing 的转变

回到白皮书开篇的故事——作者花两三天复刻 Claude.ai,做出一个 50% 体验的版本。这是绝大多数 agent 项目的真实状态:能跑、有 demo,但离真正「产品级」还有相当距离。

这个差距的本质,不在于你不够聪明,也不在于模型不够强。它在于一个 framing 的差异:

• 开发 agent:目标是「做出一个能用的东西」。指标是「它跑通了」。
• Agent 工程:目标是「持续可量化地提升 agent 质量」。指标是「在哪些维度上、提升了多少」。

从前者到后者的跨越,核心是建立 eval 驱动的反馈回路。这一跨越对个人开发者尤其重要——因为没有团队的「集体经验」做缓冲,你必须用工程方法弥补。

9.2 给独立开发者的几点直白建议

先建反馈回路,再写 harness 代码。你两三天能搭出来的复刻版,如果没有 eval,再迭代一个月也只是在 50% 附近反复横跳。

30 题胜过 300 题。诊断性强、互相区分的小 suite,比庞杂的大集合更有价值。

永远跑对照组。没有 baseline 的数字是没有意义的。

把失败 case 当资产对待。每一个糟糕的对话,如果不被记录、不进入 eval set,就是双重浪费——既糟糕了体验,又没换来任何反馈价值。

克制使用 multi-agent。在 single-agent harness 没打磨好之前,multi-agent 只会让调试更难、可靠性更低。这是 Anthropic 用 Claude Code 的实践反复验证过的。

9.3 一个更深的观察

写完这份白皮书,我们想留下一个更深的观察:

你正在做的事情,不只是搭一个 agent,而是在建立一种工程思维。这种思维一旦形成,会在你未来所有的 AI 项目中持续复利。

τ-bench 那个数字(SOTA 模型在 pass^8 上跌到 25%)的真正启示是:Anthropic 自己的人也是靠 eval 才发现他们的 agent 没那么牛。如果连 Anthropic 都不敢凭感觉迭代,任何个人项目凭感觉迭代都是把自己钉死在 50% 体感天花板上的最快方式。

你已经踩过这个坑了,知道哪里疼。下次不要再踩了——这本身,就是大部分人一辈子也学不会的东西。

附录 A:推荐资源与参考文献

A.1 Anthropic 工程博客(必读)

• Building Effective Agents
• Effective Context Engineering for AI Agents
• Writing Effective Tools for AI Agents
• Demystifying Evals for AI Agents
• Building Agents with the Claude Agent SDK

推荐阅读顺序:Building Effective Agents → Effective Context Engineering → Writing Effective Tools → Demystifying Evals。第二篇最关键,第三篇最被低估。

A.2 评测框架

• Inspect AI(UK AISI 开源,MIT 协议)
• inspect_evals 仓库(预实现的主流 benchmark)
• Langfuse(开源 LLM 可观测性平台)
• Arize Phoenix(开源,基于 OpenTelemetry)
• DeepEval(pytest-native 评测库)

A.3 公开数据集

• GAIA
• τ-bench
• SWE-bench Verified
• WebArena
• OSWorld
• MCPAgentBench(2025 末新出,见对应 arxiv 论文)

A.4 进阶阅读

• Hamel Husain 的 LLM evals 课程笔记
• Establishing Best Practices for Building Rigorous Agentic Benchmarks(arxiv 2507.02825)
• Claude Code 架构反向工程分析(见白皮书中引用的 ZenML、bits-bytes-nn 博客)