学 Harness 工程，最好的教材不是论文，是生产中跑着的系统。
Claude Code 是目前公开信息最多、架构最透明的终端 AI Agent 之一。更关键的是：它本身就是按照 Harness 设计哲学构建的。Anthropic 的工程团队在写 Claude Code 的同时，也在写关于 Harness 工程的技术博客------两者互为注脚。
把它拆开，你能看到一个真实的、经过生产验证的 Harness 长什么样。
一、一个前提：Claude Code 本身就是一个 Harness
这句话值得停一下想清楚。
大多数人用 Claude Code 的方式是：打开终端，写需求，等它干活。这是用户视角。
工程师视角看是另一回事：Claude Code 是一套包裹着 Claude 模型的基础设施。它负责管理文件系统访问、派遣子 Agent、编排工具调用、维护跨会话记忆、处理权限控制、在上下文接近限制时自动压缩......
这些全是 Harness 的职责。
Claude Code 不是一个「聪明的聊天框」，是一个以 Claude 为核心的 Agent 操作系统。前 8 篇我们讨论的所有 Harness 组件------上下文工程、工具设计、长时执行、安全护栏、评估框架------在 Claude Code 里都有对应的实现。
这就是为什么解剖它有价值：你不是在学一个产品怎么用，是在读一份 Anthropic 写给工程师的参考实现。
二、记忆系统：CLAUDE.md 不是配置文件
很多人把 CLAUDE.md 理解成「项目说明书」，告诉 AI 这个项目是干什么的。这理解只对了一半。
CLAUDE.md 是 Claude Code Harness 的长期记忆接口。
从 Harness 角度看，记忆有四个层级：
2.1 工作记忆------当前会话的上下文窗口。有限，会消耗，会被压缩。
2.2 情节记忆 ------会话历史。Claude Code 支持 --continue 和 --resume，但跨会话后历史是压缩的，不是完整保留的。
2.3 语义记忆------这就是 CLAUDE.md 的位置。它在每次会话启动时被加载进上下文，相当于把「关于这个项目你需要永久记住的事」写死在 Harness 层。无论会话怎么轮换，这部分记忆不会丢。
2.4 程序记忆 ------Skills 系统。把可复用的操作模式封装成 .md 文件，按需注入上下文。
CLAUDE.md 的设计有一个微妙之处：它不在模型权重里，也不在数据库里，是纯文本写在 git 仓库里的。这个选择本身就是一种工程判断------透明、可版本控制、可团队协作，代价是每次都要占用上下文窗口。
Anthropic 的权衡是：长期记忆的可靠性 > 上下文窗口的节省。
有了 Prompt Caching，CLAUDE.md的token开销实际上很低------缓存命中后成本降到原来的 10%。这让这个设计变得更合理。
三、上下文管理：Compaction 是怎么工作的
上下文窗口满了怎么办？这是所有长时运行 Agent 都要面对的问题。
Claude Code 的答案是 Compaction：在上下文接近限制时，自动调用一次对话总结，把完整历史压缩成摘要，清空旧上下文，然后继续执行。
听起来简单，难点在细节：
3.1 压缩时机：不能太早（浪费现有上下文），不能太晚（被截断）。Claude Code 在大约 70-80% 使用率时触发，留出足够的余量给下一轮操作。
3.2 压缩策略 ：/compact 命令支持附带指令------你可以告诉它「压缩时重点保留关于认证模块的讨论」。这是主题聚焦的 Compaction，比无差别压缩更精准。
3.3 信息保真度：压缩必然有损失。Claude Code 的系统提示里明确训练了模型在压缩时保留「决策和原因」而非「操作细节」。这是 Harness 层面的记忆管理策略，而不是模型自己决定的。
对比一下你自己可能的实现：很多工程师在上下文快满时直接截断历史，或者从第一条消息开始删。这两种方式都会在某个点导致模型失去关键上下文，任务中断。
Compaction 的核心思路是：不截断，而是压缩。保留语义，丢弃细节。
四、工具系统：Read/Edit/Bash 的设计哲学
Claude Code 的工具集看起来很小：Read、Edit、Write、Bash、Grep、Glob、WebFetch......十几个工具。
这不是因为能力有限，是刻意的设计选择。
Anthropic 在 Harness 工程博客里明确写过：工具集越大，模型选错工具的概率越高，规划能力越弱。他们在内部实验中发现，给模型 50 个工具，整体任务完成率反而低于给 15 个精心设计的工具。
Claude Code 的工具设计有几个值得注意的模式：
4.1 读写分离：Read 和 Edit/Write 是两类工具，权限策略不同。Read 是默认允许的，Edit 和 Write 需要确认（或在 auto-accept 模式下自动通过）。这不只是 UX 决策，是安全架构------只读操作不会造成不可逆影响。
4.2 精确编辑优先：Edit 工具做的是字符串替换，不是重写整个文件。这降低了大文件操作时的错误率，也让 diff 更清晰可审查。
4.3 Bash 是逃生舱：当其他工具都不够用时，Bash 可以做任何事。但它也是最危险的工具，因此有最严格的权限控制------Claude Code 维护了一个命令黑名单（curl、wget 等），以及基于前缀的白名单规则。
4.4 工具失败是信号，不是终止：Claude Code 的工具调用失败时，会把错误信息返回给模型，让模型决定下一步。这是 Harness 层面的容错设计------工具层面的失败不等于任务失败。
五、子 Agent 系统：独立上下文的并行执行
Claude Code 的子 Agent（Subagent）机制是 Harness 多层级编排的典型实现。
它的工作方式是：主 Agent 可以派遣子 Agent 去完成独立子任务，子 Agent 有自己独立的上下文窗口，完成后把结果返回给主 Agent。
这个设计解决了两个问题：
5.1 上下文隔离：子 Agent 的操作不会污染主 Agent 的上下文。你让子 Agent 去读一个 10 万行的日志文件，分析结果，主 Agent 只看到最终分析，不会把整个日志内容塞进自己的窗口。
5.2 并行执行：Claude Code 支持多个子 Agent 同时运行，配合 Git Worktree 隔离工作区。实践中的模式是：主 Agent 拆解任务，多个子 Agent 并行处理不同模块，主 Agent 汇总结果。一个人推进多个功能分支同时开发。
但子 Agent 有一个刻意的限制：子 Agent 不能再派遣子 Agent。Claude Code 的架构是两层，不是无限递归的树。
这是为什么？Anthropic 在博客里解释过：无限递归的 Agent 树在实践中会产生指数级的调试复杂度。你不知道任务在哪一层出错了，错误的根因追踪变得极其困难。两层架构保持了可观测性------你总能知道是主 Agent 的问题还是某个具体子 Agent 的问题。
这是一个以架构约束换取可调试性的工程决策。
六、权限与 Hooks：Harness 的安全护栏
Claude Code 的权限系统是第 7 篇安全护栏的真实参照物，值得再单独看一次。
四种权限模式对应不同的信任级别：
default：首次使用每个工具时需要确认acceptEdits：自动接受文件编辑，命令执行仍需确认plan：只分析，不执行任何写操作bypassPermissions：跳过所有确认（CI 环境使用）
权限规则支持精细配置：Bash(npm run test:*) 允许所有以 npm run test: 开头的命令，Read(./.env) 禁止读取 .env 文件。这是基于规则的动态策略，而不是静态白名单。
Hooks 系统是更有意思的部分。它让 Harness 的行为可以被外部逻辑钩入：
PreToolUse：工具执行前，可以检查、修改、甚至阻止PostToolUse：工具执行后，可以触发格式化、日志记录、通知Stop：主 Agent 完成响应时触发
不改 Claude Code 核心，就能把团队的质量门控接进来------每次文件编辑后自动跑 lint，每次提交前强制跑测试。
Hooks 把 Claude Code 从一个封闭产品变成了一个可扩展的 Harness 基础设施。
七、与 Codex CLI 的对比：两种 Harness 哲学
上一篇 Codex 系列刚起步，正好在这里做一次横向对比。
| Claude Code | Codex CLI | |
|---|---|---|
| 部署方式 | 闭源产品 | 完全开源 |
| 记忆系统 | CLAUDE.md（项目级）+ 会话压缩 | AGENTS.md（项目级）+ 无跨会话记忆 |
| 工具编排 | 内置工具集 + MCP 扩展 | 内置工具集 + 任意 OpenAI 兼容模型 |
| 沙箱机制 | DevContainer / 权限规则 | 原生 sandbox-exec / Docker |
| 子 Agent | 两层架构，内置 Subagent 系统 | 无原生多 Agent，依赖脚本化 |
| 可观测性 | Analytics Dashboard + OpenTelemetry | 本地 JSON 日志 |
| Hooks | 9 种生命周期事件 | 无 |
两种产品代表了两种 Harness 哲学：
Claude Code 的哲学是深度集成。Harness 和模型深度耦合，换来的是极致的用户体验和开箱即用的工程能力，代价是你只能用 Claude，无法迁移。
Codex CLI 的哲学是开放替换。Harness 是开源的，模型是可替换的，沙箱是系统原生的。代价是 Harness 本身相对薄，你需要自己补更多工程层。
我自己的判断是：如果你是在一个产品团队里交付，Claude Code 的体验优势是真实的，Hooks 和 Subagent 系统省掉了大量基础设施搭建。但如果你是平台工程师，需要把 Agent 能力嵌进自己的系统里，Codex CLI 的开源架构更值得研究------你能看清楚它每一层在做什么。
八、从 Claude Code 学什么
读完 Claude Code 的 Harness 实现，我整理了五条觉得最值得带走的东西------不是理论，是可以直接在下个项目里用的判断：
8.1 长期记忆用文本，不用数据库。CLAUDE.md 的存在证明，把项目上下文写成纯文本放在 git 里，效果不比向量检索差。很多人上来就想搭一个 RAG 系统，但 Anthropic 自己的答案是一个 markdown 文件。先从这里开始。
8.2 工具集越小越好，不是越全越好。内部实验数据：50 个工具 vs 15 个工具，任务完成率反而是后者更高。每次想加一个工具，先想想能不能用现有工具组合出来。
8.3 上下文快满时，压缩，不要截断。保留「为什么」，丢掉「怎么做了」。决策比操作细节更值钱。
8.4 Agent 架构保持两层。主 Agent 规划，子 Agent 执行。不要做递归树，每加一层，调试成本就指数级上升。
Hooks 这个设计最值得学。把扩展点留在生命周期里，而不是把所有逻辑都塞进核心。这是 Claude Code 能在不修改自身的情况下支持几十种团队工作流的原因。
Claude Code 是 Anthropic 花了两年时间、用自己的工具测试自己的理论得出的答案。不是完美的，但是真实生产里跑过的。这种参考实现的价值，比一百篇 Harness 设计文章都实在。
参考文献：