从Claude Code源码分析,理解Harness的设计思想

如果只看模型排行榜，我们很容易产生一种错觉：谁拥有更强的模型，谁就能做出更强的AI Agent。

但真正使用过Claude Code、Codex的人会发现，同一个模型放进不同的运行环境，最终表现可能截然不同。

有的系统只会给出一段代码建议；有的系统却能进入项目、搜索代码、修改文件、运行测试、发现错误、继续修复，最后交付一个可以验收的结果。

两者之间的差距，并不完全来自模型，而是来自模型外面的Harness。

Claude Code恰好是理解Harness设计思想的优秀样本。本文将从它与Harness的关系出发，结合Anthropic官方文档和社区公开的源码研究项目，拆解一个成熟Coding Agent究竟由哪些部分组成。

一、Claude Code和Harness是什么关系？

Claude Code不是模型，而是围绕Claude模型构建的Agent系统

Claude是Anthropic旗下的AI产品与模型家族；Claude Code则是一套主要由Claude模型驱动的Agentic Coding系统。它把模型与文件系统、终端、工具、权限、上下文管理和执行循环结合起来，让模型能够在真实代码库中持续完成任务。

模型可以理解代码、分析问题和生成文本，但模型本身不会自动知道：

当前项目位于哪个目录；
哪些文件允许读取；
应该使用搜索、编辑还是终端工具；
一条Shell命令是否危险；
修改后应该运行哪些测试；
上下文快用完时应该保留什么；
任务完成后应该返回哪些证据。

这些问题都需要模型之外的软件系统解决。

Claude Code就是Anthropic围绕Claude模型构建的一套Agentic Coding环境。官方将它描述为能够理解代码库、编辑文件、运行命令并处理开发工作流的编码Agent。Claude Code官方仓库

如果用一个简化公式表达：

Claude模型＋Harness＝Claude Code的核心Agent能力

等号左边除模型以外的部分，基本都属于Harness。

Harness不是一个功能，而是一套控制系统

Harness经常被翻译成“智能体框架”或“智能体运行时”。但更准确地说，它是一套把不确定的模型推理，约束成可执行工作流程的控制系统。

一个Coding Harness至少要回答六个问题：

给模型看什么？
给模型哪些工具？
工具在什么权限下运行？
工具执行结果怎样返回模型？
长任务如何管理上下文、状态和失败？
系统如何判断任务可以结束？

Anthropic公开的Agent Loop文档展示了Claude Code背后的基本循环：模型接收上下文，决定调用工具；Harness执行工具并返回结果；模型观察结果，再决定继续调用工具还是输出最终答案。Claude Code Agent Loop

这看起来只是一个简单的循环：

用户提出任务

↓

模型分析并选择工具

↓

Harness检查权限

↓

执行工具并返回结果

↓

模型观察结果

↓

继续执行或结束任务

但真正的产品差异，恰恰藏在这个循环的每一个细节中。

Claude Code并不是“Claude模型加一个终端”。它本质上是Anthropic对以下问题给出的完整工程答案：如何向模型提供环境，如何约束模型行动，以及如何让模型在真实软件项目中持续工作。

二、Claude Code源码分析：一个成熟Harness有哪些层次？

我们分析的是哪一份源码？

目前较系统的中文研究项目是xiaonancs/claude-code-source-analysis。该项目声明，其研究基于逆向还原的Claude Code v2.1.88快照，整理了约1884个TypeScript/TSX文件，并将系统划分为三个层次：

Foundations：启动、状态、System Prompt、主循环、上下文、记忆和缓存；
Execution：工具、权限、配置、Agent、任务、MCP和Hooks；
Infrastructure：API适配、特性开关、终端渲染和设计系统。

另一个项目luzhenqian/claude-harness则将大量源码整理成可搜索的模块、架构文章和交互式代码浏览器。

这些项目不是Anthropic官方源码仓库，而是社区研究材料。因此，适合用来理解结构和设计模式，不适合将具体函数名、文件数量或内部实现视为长期稳定的官方承诺。

下图把Claude Code的三个主要层次放在同一张架构图中：Claude模型位于Harness边界之外，负责推理和决策；基础层中的Agent Loop负责组织上下文、发起模型请求并维护循环；执行层把模型返回的工具调用转化为受权限约束的现实行动；基础设施层提供模型连接、状态、界面和可观察性，最终连接到本地文件系统、Shell、Git、网络与外部服务。

图：Claude Code Harness 分层架构与反馈闭环

这三层并不是简单的单向调用关系。反馈循环才是Harness的核心：Agent Loop向外部模型发起请求，模型返回推理结果或工具调用；执行层完成权限检查与调用，工具结果再通过会话和上下文返回Agent Loop，由它组织下一轮模型请求，直到任务结束。

第一层：入口与运行时——先建立环境，再调用模型

Claude Code启动后，不会立即把用户输入发给模型。Harness首先需要完成一系列环境准备：

解析命令行参数；
确定当前工作目录；
加载用户级和项目级配置；
读取CLAUDE.md等持久指令；
恢复会话和自动记忆；
注册内置工具、Skills和MCP工具；
初始化权限、沙箱和终端界面；
选择模型及推理参数。

这体现了Harness的第一个思想：

模型调用只是运行时的一部分，环境构建才是Agent行为一致性的起点。

没有稳定的配置加载顺序，同一个任务可能在不同电脑上表现完全不同；没有项目级规则，模型每次都要重新猜测团队规范。

第二层：System Prompt——不是一段提示词，而是动态装配的运行合同

普通聊天产品的System Prompt往往可以被理解为一段固定文字，但Coding Agent的系统提示要复杂得多。

它需要根据当前环境动态加入：

Agent身份与基本行为原则；
当前操作系统和工作目录；
可用工具及调用规则；
项目中的CLAUDE.md；
权限模式；
已加载的Skills；
Git状态和任务上下文；
输出格式与安全约束。

因此，成熟Harness不会把所有要求写进一个不断膨胀的超级Prompt，而是把提示上下文拆成不同来源，在适当的生命周期中加载。

这带来两个好处：一是不同项目可以复用同一套Agent；二是稳定前缀更容易利用Prompt Cache，降低成本和延迟。

第三层：Agent Loop——Claude Code真正的发动机舱

Claude Code的核心不是一次模型请求，而是一个可以持续多轮运行的Agent Loop。

一个典型任务可能经历：

理解需求

→ 搜索文件

→ 阅读关键代码

→ 形成修改方案

→ 编辑文件

→ 运行测试

→ 观察错误

→ 继续修改

→ 再次验证

→ 汇总结果

模型负责决定下一步，Harness负责维护循环。

Harness要处理的不只是成功路径，还包括网络失败、工具被拒绝、命令超时、输出过长、用户中途补充要求、模型请求取消，以及上下文压缩后的继续执行。

这说明Agent产品的可靠性并不等于模型每一步都正确，而在于：

系统能否让模型观察错误、保留状态，并在可控边界内继续尝试。

第四层：工具系统——把模型的语言变成现实行动

Claude Code的内置工具覆盖文件读取、搜索、编辑、Shell执行、网络访问和任务编排。官方工具文档列出了Read、Edit、Write、Glob、Grep、Bash、Agent和Skill等工具。Claude Code工具参考

工具看似只是函数，实际上需要一整条执行管线：

模型生成工具调用

→ 参数校验

→ 权限规则匹配

→ 必要时请求用户确认

→ 在沙箱或本机执行

→ 截断、清洗和结构化输出

→ 将结果写回会话

→ 模型继续推理

好的工具设计，不是给模型尽可能多的能力，而是给它清晰、稳定、容易选择且结果可观察的能力。

工具太少，Agent无法完成复杂任务；工具太多，工具定义会占用上下文，模型的选择准确率也会下降。Claude Code后来引入Tool Search，按需发现并加载工具，正是对这一矛盾的解决。Claude Code Tool Search

第五层：权限与沙箱——把“模型想做”与“系统允许做”分开

模型可以建议执行某个命令，但是否真正执行，必须由Harness决定。

Claude Code把权限和沙箱设计成互补的两层：

·权限系统决定某个工具调用是否允许、拒绝或需要询问；

·沙箱在操作系统层限制Shell命令可以访问的文件和网络范围。

官方文档明确指出，权限规则适用于Bash、Read、Edit、WebFetch和MCP等工具；沙箱则重点约束Bash及其子进程。Claude Code权限与沙箱

这背后有一个非常重要的Harness原则：

永远不要把安全寄托在模型“自觉不做危险操作”上。

模型负责提出行动，系统负责裁决行动。即使Prompt Injection影响了模型判断，操作系统级边界仍然应该发挥作用。

第六层：上下文管理——上下文不是越大越好，而是要像内存一样管理

在长任务中，System Prompt、对话历史、文件内容、命令输出和工具定义都会持续占用上下文。

如果不管理，上下文很快就会被日志和中间过程填满，模型反而可能忘记最初目标。

Claude Code的处理方式包括：

对稳定的提示前缀使用缓存；
延迟加载Skills和MCP工具定义；
清理过时工具输出；
接近上限时自动压缩会话；
将长期规则放入CLAUDE.md重新注入；
使用子Agent隔离大规模搜索过程。

官方文档说明，自动压缩会总结较早历史，保留最近对话和关键决策；CLAUDE.md中的持久规则会在请求中重新加载。Claude Code上下文管理

这揭示了一个常被忽视的事实：

Harness不仅在管理模型能做什么，也在管理模型能记住什么。

第七层：子Agent——并行只是表象，真正价值是上下文隔离

Claude Code可以把搜索、研究或审查任务交给子Agent。

很多人首先想到的是并行提速，但子Agent更深层的价值是隔离上下文。子Agent拥有独立会话，可以读取大量文件、运行自己的工具循环，最后只把总结返回主Agent。

这样，大量中间日志不会污染主会话，主Agent可以继续保留目标、约束和关键决策。

因此，多Agent架构不只是“多找几个模型同时工作”，而是把复杂任务划分为多个受控的信息边界。

第八层：MCP、Skills和Hooks——三种不同的扩展方向

Claude Code提供了多种扩展机制，但它们解决的问题不同：

MCP：连接外部服务和新工具；
Skills：封装可复用的知识、规则和工作流；
Hooks：在工具执行、权限请求、压缩和会话边界等事件上运行确定性逻辑；
Plugins：将上述能力打包和分发。

官方扩展文档将这些机制放在Agent Loop的不同位置：CLAUDE.md提供持久上下文，Skills按需加载，子Agent在隔离上下文中运行，Hooks响应生命周期事件，MCP连接外部系统。Claude Code扩展机制

这也是成熟Harness的重要特征：

不用一个万能插件接口解决所有问题，而是为知识、能力、自动化和分发分别设计扩展点。

第九层：终端UI——可观察性也是Harness的一部分

Claude Code的终端界面并不只是把模型回复打印出来。

它需要实时呈现：

模型正在思考还是等待；
即将调用什么工具；
哪条命令正在执行；
哪些文件发生了修改；
是否需要权限确认；
子任务处于什么状态；
当前上下文和费用如何变化。

一个可以自主执行命令的Agent，如果没有清晰的状态反馈，用户就无法判断它是在正常工作、陷入循环，还是即将做危险操作。

所以，优秀的Harness不仅要让Agent能行动，还必须让行动可观察、可打断、可解释。

三、从Claude Code提炼出的Harness设计思想

通过以上结构，可以总结出九条具有普遍意义的Harness原则。

1. 模型负责决策，系统负责边界

让模型决定下一步做什么，但不能让模型决定自己拥有什么权限。

能力与授权必须分离。模型可以请求工具，Harness负责校验、审批和执行。

2. Agent的核心不是Prompt，而是反馈闭环

Prompt决定模型如何开始，反馈闭环决定任务能否完成。

真正有效的Agent必须能够“行动—观察—修正”，而不是只生成一次看起来正确的答案。

3. 不追求每一步都正确，而要追求错误可恢复

模型会选错文件、写错代码、执行失败。

成熟Harness不会假设错误不存在，而会保留工具结果、测试证据和任务状态，让Agent能够继续修复。

4. 上下文是一种稀缺计算资源

更多上下文并不必然带来更好结果。

工具描述、日志和中间推理都会占用预算。Harness需要决定哪些信息常驻、哪些按需加载、哪些压缩、哪些交给子Agent处理。

5. 确定性规则不能只写进Prompt

“修改后必须运行测试”“禁止访问某个目录”“发布前必须经过审查”这类规则，如果仅依赖模型遵守，就不够可靠。

更稳妥的方式是使用权限、沙箱、Hooks和状态机，让关键约束由代码强制执行。

6. 工具质量比工具数量更重要

模型需要的是边界清晰、输入稳定、输出可解释的工具。

过多工具既消耗上下文，也增加误选概率。按需发现、最小授权和任务专用工具集通常比“把所有工具一次性塞给模型”更有效。

7. 多Agent首先是信息架构，其次才是并发架构

子Agent的核心价值不仅是同时工作，而是隔离上下文、缩小职责、减少主Agent的信息负担。

如果没有清晰的任务边界和结果汇总机制，增加Agent数量只会增加协调成本。

8. 人不是Agent循环外的观察者，而是控制系统的一部分

用户要能够批准、拒绝、补充要求、中断执行和查看证据。

Human-in-the-loop不是Agent“不够自动化”的缺点，而是高风险任务中必要的治理设计。

9. Harness本身需要持续评估和演进

Agent表现不佳，不一定意味着模型不够强，也可能是：

提供了错误的上下文；
工具描述不清；
权限规则导致任务反复中断；
压缩丢失了关键目标；
验证机制无法识别假完成；
子Agent拆分方式不合理。

因此，未来的Agent优化会越来越像系统工程：通过日志、轨迹、失败分类和评测，不断改进Harness。

四、Claude Code真正值得学习的，不只是功能

Claude Code最容易被看到的是功能：它会搜索代码、修改文件、运行命令、调用子Agent。

但这些功能并不是它最重要的护城河。

真正值得学习的是，它把一个具有概率性、可能出错的语言模型，放进了一套具备上下文管理、工具协议、权限边界、失败恢复和人机协作能力的工程系统中。

模型能力决定Agent理论上能走多远，Harness决定它在现实中能否稳定到达。

这也解释了为什么同一个Claude模型，通过普通API调用和通过Claude Code执行同一个软件任务，结果可能差异巨大：

普通API调用得到的是模型的一次回答；Claude Code提供的是一套持续工作的环境。

未来，模型能力可能逐渐商品化，企业也会同时使用多个模型。届时真正形成差异的，可能不再只是模型排行榜上的几分，而是：

谁拥有更好的上下文组织；
谁拥有更可靠的工具和验证机制；
谁能让长任务持续运行；
谁能在自主执行与安全控制之间取得平衡；
谁能把人的经验沉淀成可复用的Skills、Hooks和工作流。

它是一套围绕软件工程重新设计的人机协作系统，也是理解现代Agent Harness最有价值的案例之一。

模型提供智能，工具提供行动，反馈提供修正，权限提供边界，而Harness把这一切组织成可靠的生产力。

这才是Claude Code源码背后最值得理解的设计思想。

参考资料

Anthropic：Claude Code官方仓库

Anthropic：Claude Code如何工作

Anthropic：Agent Loop

Anthropic：工具参考

Anthropic：权限与沙箱

Anthropic：扩展Claude Code

社区研究：Claude Code源码解析

社区研究：Claude Harness

论文：Dive into Claude Code