7张图搞懂Claude Code的Harness架构设计
57MB源码，既呈现了企业级通用Agent架构，又蕴藏了Coding Agent外溢的方向布局，适合每个做Agent的团队研究。
分享下我是如何与AI一起解析Claude Code源码，获取Agent设计要领：
包含Harness架构、Agent Loop、状态管理、记忆系统、工具系统…
1. 整体概述
众所周知，Claude Code不仅仅是Coding产品，更是一个通用的终端Agent：能循环思考、调度工具、治理权限、恢复上下文、稳定长会话…
如何研读项目源码呢？
首先，我让AI帮着梳理了下目录架构和模块职责，对项目工程架构有个整体认知。
代码结构先有个大概认知就可以，重要的是学习以下各模块的设计哲学。
2. Harness架构设计
Claude Code的Harness 是一套「入口适配 + 会话成型 + 运行桥接」编排。
设计本质是：把多入口、多模式、多运行位置，收敛成一套统一的agent turn执行模型。
Harness负责将不同入口来的请求，统一成同一种 agent 运行方式。
在架构上可以拆成三层：
第一层：入口与分流
负责接住用户不同的使用方式，如命令行、交互界面、SDK调用、assistant模式、远端链接等。
先经过main.tsx做参数解析、模式判断和路由分发。
第二层：Harness会话编排
这是整个架构核心，可以理解为标准化处理层，负责把三种不同形态（交互会话、无界面会话、远端接入）的请求整理成统一的turn契约。
此外，把工具能力、扩展接入、状态与持久化一起接进来。
这样在真正执行前，就已经把一次会话需要的输入、能力和状态组织完整了。
第三层：Runtime与支撑层
对于本地路径，进入本地Runtime执行完整的Agent Loop，需要调用模型或执行工具时，再继续落到模型与工具执行层。
对于远端路径，转入远端会话宿主，由remote / bridge / server这套机制承载实际执行。
3. Agent Loop设计
Harness 解决了请求从哪里来、交给谁，Agent Loop解答了另一个核心问题：这条链路如何运行？
Claude Code的Agent Loop是一种TAOR 循环：Tink-Act-Observe-Repeat。
这种架构编排足够简单，其背后的哲学是「将智能下沉给模型，释放智能自主权」。
如图所示，Claude Code在将一次turn拆成了几个稳定步骤：
预处理上下文 → 流式采样 thinking → 执行工具 → 拼接toolResult → 判断是否回流到下一轮。
模型负责生成意图，工具负责和外部世界交互，系统再把结果补回上下文，决定要不要进入下一轮。
这不是一个简单的问答回合，而是一套可持续推进任务的执行循环，这也是Claude Code能支撑复杂长任务的核心基础。
4. 状态管理
Claude Code有两套状态系统，采用「会话运行态 + 全局会话态 + 持久化层」分层协同管理架构。
AppState 会话态
当前会话运行实时状态，包括REPL/TUI 里的任务、MCP、插件、权限、通知和远端连接等实时状态，服务于交互体验和当前turn的运行过程。
bootstrap/state 全局态
负责管理当前会话的全局运行信息，包括项目位置、会话标识、成本与预算、模型与功能开关、通道与遥测等，是整个runtime的公共配置底座。
sessionStorage 持久化层
负责把会话记录和恢复信息写入磁盘，保存的是对话轨迹、续接数据和历史快照，供resume、历史读取和会话恢复使用。
这三层架构，由ToolUseContext串起来：它既把当前会话状态暴露给query、tools、tasks，也把turn内上下文带进Agent Loop。
5. 记忆管理
Claude Code的记忆管理比OpenClaw更加成熟完善。
有策略层、指令层、记忆层三套机制，构成「策略约束 + 指令注入 + 分层记忆召回」的组合式上下文系统。
策略层：企业或组织下发的开关与限制，用来约束系统能做什么；
指令层：包括CLAUDE.md、用户级和项目级规则文件，告诉模型如何工作；
记忆层：当前会话沉淀、项目与团队范围的记忆、面向特定Agent的专属记忆，以及每轮按相关性动态注入的动态记忆。
重点看下记忆层，按进入turn的来源，在runtime中是如何筛选、注入和回写：
如图可见，claude code记忆加载链路是：记忆文件 -> 相关性筛选 -> 附件注入 -> 进入下一轮 turn。
最核心的是筛选与装配，在合适的时机，筛选出“本轮最相关”的记忆。
与OpenClaw典型的RAG 语义检索路线不同，Claude Code的记忆筛选机制是LLM 驱动的文件级记忆选择。
筛选机制如下：
- 候选集来自磁盘记忆文件
- 选择依据是文件名、描述、query 语义匹配
- 选择器是模型，不是embedding similarity
- 结果是挑文件，不是查向量库 top-k chunk
另外，动态记忆nested memory也不是检索，而是按路径触发补充。
总之，Claude Code记忆系统「按作用域分层、按时机写入、按相关性召回、按预算约束展示」的完整机制，能够让用户感知到，这个系统越来越懂上下文，而不是“强行回忆”。
6. 工具系统
Claude Code的能力供给系统，分成三层：能力定义、能力装配、能力执行。
如图所示，给模型的能力扩展，先定义了一套统一的能力契约，再按场景把真正可用的能力动态装配出来，最后以运行时上下文的形式交给 agent loop 使用。
可以理解为一条能力供给链：上游扩展能力来源，中间统一筛选和装配，下游按回合决策调用并把tool_result 回流到下一轮上下文。
这条链路既能不断接入新能力，又能保持运行时的一致性、可控性和可扩展性。
对用户来说，内建工具、MCP外部能力、skills / plugins扩展能力，在运行时都表现为统一能力，体验上能力很多，使用方式一致。
7. 隐藏功能
通过代码中很多未完成的代码可见，Anthropic内部组织分化在做多方面探索，将Coding Agent外溢到各行各业，覆盖更多人群。
**通过这些功能可见，Claude Code的演进方向是打造成一个：兼具主动协作、长时记忆、远端运行与会话资产管理能力的Agent工作平台。**
整体来看，Claude Code非常重视恢复能力、权限模型、上下文压缩和长会话稳定性，也在持续补齐远端协作、记忆沉淀、会话资产化等更强自主性的Agent能力。
技术栈和架构形态也许可以相似，但真正拉开差距的，往往是细节是否被打磨到了足够扎实。
Claude Code 这套 Harness 范式提供的是一个「下限可控、上限可拓」的基础框架，如何做到卓越，很多track依然要从代码细节中挖掘，再结合业务打造差异化。