Harness 与 Claude Code：从零理解，再深入拆解
Harness and Claude Code — From First Principles to a Deep Dive
引子：为什么模型选对了，agent 还是不好用？
很多人第一次搭 AI agent，都会陷入同一个执念：选模型。GPT 还是 Claude？Opus 还是 Sonnet？要不要等下一代？仿佛只要模型够强，agent 就会自动变好。
然后现实给了一记耳光：同样的模型，别人搭出来稳如老狗，自己搭出来动不动跑偏、死循环、改一个文件碰坏三个。问题出在哪？
答案是一个很多人没听过、但决定成败的东西——harness（框架 / 脚手架）。这篇文章就讲清楚两件事：harness 到底是什么、为什么重要；以及 Claude Code 作为一个具体的 harness，好在哪、边界在哪、该怎么学。
第一部分：建立直觉（写给初学者）
什么是 harness？
先说一个最关键、也最容易被搞混的概念：
大语言模型（LLM）本身不是 agent。 模型只会做一件事——给它一段文字，它接着往下生成一段文字。它不会自己读文件、不会自己跑命令、不会自己调 API、更不会”先想想再动手”。
那 agent 那些”会自己干活”的能力从哪来？来自包在模型外面的那层软件——这层软件就叫 harness。它负责：
- 把你的需求组织成 prompt 喂给模型；
- 解析模型”我想调用某个工具”的意图，真的去执行；
- 把执行结果再喂回给模型；
- 管理一轮轮对话的上下文，不让它爆掉；
- 出错了怎么重试、怎么回退、什么时候该停下来问你。
打个比方：模型是发动机，harness 是整辆车。 发动机决定了这辆车的性能上限，但你能不能开着它顺利到达目的地，取决于方向盘、变速箱、刹车、导航——也就是 harness。一台 F1 发动机装在没有刹车和方向盘的架子上，还不如一辆设计良好的家用车能跑。
什么是 Claude Code？
这里要纠正第二个常见误解：很多人以为”harness”和”Claude Code”是两个并列的东西，可以二选一。
不是。Claude Code 本身就是一个 harness——它是 Anthropic 做好的、针对编程和智能体任务高度调优的一个具体 harness 实现。
Claude Code 是一个跑在终端里的 AI agent（现在也有 VS Code、JetBrains、桌面 App、网页版和 iOS 版）。你用大白话告诉它想要什么，它自己决定怎么做：读你的代码、跑 shell 命令、改文件、管理 git、调外部服务。换句话说，Anthropic 把上面说的那一整套”车”——方向盘、刹车、变速箱——都给你造好了，你直接上车开就行。
所以正确的对比不是”harness vs Claude Code”，而是：
用 Anthropic 造好的现成 harness（Claude Code） vs 自己造 / 用别的通用框架（LangGraph、AutoGen、CrewAI、OpenHands）
记住这个框架，后面就不会乱。
第二部分：那个反直觉的核心发现
如果这篇文章你只记住一句话，请记住这句：
harness 对 agent 实际表现的影响，常常比换模型还大。
这不是观点，是过去几个月一连串实验反复验证出来的结论。下面都是模型权重完全不变、只改 harness 得到的结果：
| 来源 | 发现 |
|---|---|
| 斯坦福 & 清华研究 | 同一底层模型，因 harness 设计不同，复杂多步任务上出现最高 6 倍的性能差距 |
| Pi Research（Grok Code Fast 1） | 仅改了编辑工具的格式，SWE-bench 从 6.7% 跃升到 68.3%，模型没动 |
| Vercel | 删掉 80% 的工具后，成功率从 80% 升到 100%，token 减半，延迟从 724 秒降到 141 秒 |
| LangChain | 仅改 harness，Terminal-Bench 2.0 从 52.8% 升到 66.5%（从倒数冲进前五） |
| Princeton CORE-Bench | 同一模型，一个 scaffold 得 42%，换一个得 78% |
| SWE-bench Pro | scaffold 质量可在相同权重上造成 22 分的摆动——好 harness 的中端模型能打败差 harness 的前沿模型 |
| Terminal-Bench 2.0 | 同一模型在不同 harness（Claude Code vs OpenHands vs 自研循环）下摆动 30 到 50 个百分点 |
学术界已经把这件事提到了新高度。Preprints.org 上一篇综述《Agent Harness for Large Language Model Agents: A Survey》（系统梳理 110+ 篇论文）直接断言：随着 agent 任务变长变复杂，任务可靠性越来越不取决于底层模型的能力，而取决于包在它外面的执行 harness——harness，而非模型，才是真实世界 agent 系统性能的约束瓶颈。
一句最精炼的总结来自 SWE-bench Pro 的分析：
模型代表性能天花板，harness 决定你能多接近那个天花板。
对初学者的启示很简单：别再纠结”用哪个模型”这一个旋钮了。你手上还有一个影响更大、却几乎没人优化的旋钮——harness。
第三部分：harness 由什么组成
理解了”harness 很重要”，下一个问题是：它具体在哪些地方影响 agent？把它拆开，主要是这几个机制。
1. 工具设计
工具的数量、描述质量、参数格式。反直觉的是——工具不是越多越好。Vercel 的案例就说明，工具太多反而让模型在选择间犹豫、误选；删减后反而更稳。工具描述写得好不好，本身就能造成任务完成率的可测差异。少而清晰，胜过多而模糊。
2. 循环与规划结构
agent 是不是有一个结构化的”规划 → 执行 → 观察”循环。研究显示，加入结构化规划循环带来的提升，比升级到更贵的模型还大。
3. 上下文管理
长会话里如何压缩、保留、检索历史信息。这是一个 agent 能不能撑过 4 小时会话、还是中途”失忆”的关键。
4. 失败处理与重试
出错了能不能捕捉、回退、换条路走。一个会”撞墙就停、换个思路”的 agent，远比”一条道走到黑”的强。
5. 输出校验
真正的 scaffold 会管理上下文、处理失败、校验输出；而只是个”wrapper”（薄薄包一层）的，会浪费掉模型大部分能力。
这五点合起来，就是为什么同一个模型能差出 6 倍。
第四部分：深入拆解 Claude Code 这个 harness（写给实践者）
现在把镜头对准 Claude Code，看 Anthropic 是怎么把上面这套东西做成开箱即用的。它的护城河其实不只是模型质量，而是模型周围的编排面：项目记忆、工具访问、子智能体、自动化钩子，以及一套已经贴合开发者真实工作流的 loop。
Claude Code 把能力分成五个层次，每一层的”上下文成本”不同——这是它设计的核心逻辑：
| 层 | 是什么 | 何时加载 | 用来放什么 |
|---|---|---|---|
| CLAUDE.md | 项目规则 / 记忆 | 始终加载 | 每一轮都必须为真的规则（“跑完测试再说完成”） |
| Skills | 可复用工作流（SKILL.md 文件夹） | 调用时才加载 body | 偶尔才需要的流程（部署清单、调试 playbook） |
| MCP servers | 接外部工具和数据 | 按需连接 | 内部 API、数据库、第三方服务 |
| Subagents | 隔离上下文的子智能体 | 派生时获得独立上下文 | 嘈杂的研究 / 审查工作 |
| Hooks | 生命周期事件上的确定性脚本 | 工具调用前后、会话起止时触发 | 安全检查、强制规则 |
这个分层有个朴素但好用的判断法则：如果一条指令必须对每一轮都成立，放进 CLAUDE.md；如果是只是偶尔需要的流程，做成 skill；如果是必须强制执行的脚本，做成 hook。
几个值得实践者重点关注的点：
Hooks：确定性 vs 概率性的分界线。
这是 Claude Code 一个很有哲学意味的设计。Hooks 是事件驱动的确定性脚本，不像依赖模型”理解”的 prompt——它们不会幻觉。没有 hooks，你的每一道安全防线都依赖模型听懂你的话；有了 hooks，你在系统层强制执行规则（比如在 rm -rf 真正执行之前就拦截掉）。该交给模型判断的交给模型，该用代码兜底的用代码兜底——这是搭生产级 agent 的核心心法。
Subagents 与 Agent Teams：编排的下沉。 Agent Teams 是由一个主 agent 协调的一群专门化子智能体，每个子 agent 有自己独立的上下文窗口、prompt 和工具权限。主 agent 负责规划与整合，专门 agent 各管一摊有边界的活——代码审查、跑测试、前端 QA、安全扫描。这恰好和 Claude Opus 4.8 的 Dynamic Workflows（可并行启动大量子 agent）是配套的：过去要你自己实现的多 agent 编排，现在变成了框架原生能力。
Plugins：团队复用的单位。 Plugin 把 skills、subagents、slash commands、hooks、MCP server 定义打包成一个可安装单元，是团队之间共享 Claude Code 扩展的规范方式。对带团队的人来说，这是把”个人最佳实践”变成”团队标准”的关键。
一句话概括 Claude Code 的设计哲学：loop 是本地且具体的，subagents、MCP、hooks、skills 都是在扩展这个 loop，而不是替代它。
第五部分：Claude Code vs 自建 / 通用 harness
回到那个正确的对比框架。两条路各有取舍：
| 维度 | Claude Code（现成 harness） | 自建 / LangGraph / AutoGen / CrewAI |
|---|---|---|
| 上手成本 | 极低，装好即用，loop 已调优 | 高，循环、上下文、重试都要自己设计 |
| 模型绑定 | 锁定 Claude 系列 | 模型无关，可接开源模型 / 本地部署 |
| 控制粒度 | 中——开放扩展点，但 loop 本身是黑盒 | 完全——每一步状态、分支、回退都可编程 |
| 可观测 / 定制 | 受限于官方暴露的接口 | 任意插桩、任意持久化、任意编排拓扑 |
| 编码场景 | 成熟度极高 | 取决于你的投入 |
| 非编码 / 业务场景 | 偏编码，做业务 agent 需要绕 | 通用，天然适配任意领域 |
| 生产部署 | 可无 TTY 一次性运行（适合 CI/CD） | 运行时自己掌控，但要自己搭 |
怎么选？一个实用的分界：
- 你是在写代码、调系统、做开发——Claude Code 几乎是当前最强的现成 harness，直接用。
- 你是在做一个面向最终用户的业务 agent（比如语音助手、客服、领域 workflow）——Claude Code 不是合适的运行时 harness，它是给开发者在终端用的，不是给终端用户跑业务用的。这时你需要 LangGraph / Dify 这类通用编排，或者自建。
关键是：这两者不冲突，是不同的层。 你完全可以用 Claude Code 来开发那个最终跑在 LangGraph 上的业务 agent。开发期的 harness 和运行期的 harness，可以是两个东西。
第六部分：重要的反面——harness 不是万能的
这一节很关键，因为前面的数据太亮眼，容易让人走向另一个极端：“模型不重要了，全靠 harness”。这是错的。
两种效应都真实，只是在不同场景下主导：
一方面，harness 改动确实能带来巨大提升（Vercel、LangChain、Harvey 法律 agent 准确率翻倍）。但另一方面：Scale AI 的 SWE-Atlas 发现，对某些模型族，harness 的选择落在误差范围之内；METR 的基准也显示，Claude Code 和 Codex 并不总能稳定胜过一个基础 scaffold。
规律是：harness 的边际收益，在”任务长、多步、易失败”的场景最大；在短任务、定义清晰的场景里，模型能力本身就够用，harness 的差异被淹没。
还有一个对所有人都该警醒的发现，来自 METR：通过基准测试的 PR，比真实可被合并进主干的 PR，人工合并率低了 24.2 个百分点，而且这个差距还在以每年 9.6 个百分点的速度扩大。 翻译成人话：
benchmark 跑得漂亮，不等于真能落地。
所以无论你最后选哪条路，都要记住：在你自己的真实任务上测，而不是看排行榜。 赢了你的 benchmark 的那个配置，未必赢得了你的周二上午。
第七部分：技术人员该学什么
最后落到行动。学习路径分两条——一条是”harness 这件事的本质”（可迁移，换任何工具都有用），一条是”Claude Code 这个具体工具”（立竿见影的杠杆）。
学 harness 的本质（给所有人，尤其想走深的人）
- 上下文工程，而非 prompt 工程。 学会在长会话里压缩、保留、检索状态。这比背 prompt 模板重要一个量级。
- 工具设计的”少即是多”。 学会写清晰的工具描述、控制工具数量、设计好参数 schema。记住 Vercel 那个”删 80% 反而更好”。
- 失败处理与控制流。 重试、回退、何时停下来问。这是 LangGraph 这类图式 harness 的真正价值。
- 确定性 vs 概率性的边界。 哪些事交给模型判断，哪些事用确定性代码（hook）兜底。
- 评测的有效性。 记住 METR 那个数据——永远在真实 loop 里验证。
学 Claude Code 的杠杆（给实践者）
业界和资深用户的共识是：掌握五个核心系统就能解锁生产力倍增——配置层级、权限、hooks、MCP、subagents；并且一条铁律是：需要永远执行的事，用 hooks，而不是 prompt。
建议的上手顺序：
- 先 CLAUDE.md + 权限——把项目规则和安全边界立起来。
- 再 MCP——把你的内部系统、数据库、私有 API 接进来。
- 再 subagents + hooks——把代码审查、跑测试、安全扫描做成专门 agent 和确定性钩子。
- 最后 Plugins——把这套打包，在团队里复用，变成团队标准。
一个比读十篇文章更有用的练习
如果你既想搞懂理论、又想形成自己的判断，做一次刻意的横向实验：
选同一个真实任务，分别用 Claude Code 的 subagents、用 LangGraph、用 CrewAI 各跑一遍。记录四个维度：token 消耗、轮次、可靠性、可调试性。
一次这样的实验，胜过读十篇对比文章。它会让你对”harness 选型如何影响 agent”这件事，从”听说”变成”知道”。
结语
AI agent 这两年的故事，正在从”模型竞赛”悄悄转向”系统竞赛”。模型的能力上限固然重要，但决定你能不能真正用上这份能力的，是那层常被忽略的脚手架。
对初学者：别再只盯着模型的旋钮，认识到 harness 这个更大的旋钮的存在，你就已经领先大多数人了。
对实践者：Claude Code 给了你一辆造工精良的车，但真正的功力，在于你懂得它的方向盘、刹车和变速箱各自该在什么时候用——以及，知道什么时候这辆车并不适合你要走的路。
模型决定你能走多远，harness 决定你能不能走到。
💬展开评论 / Show comments