![](data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="%23D95C41" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"><line x1="12.1" y1="11.9" x2="18.9" y2="8.2" /><line x1="12.1" y1="12.1" x2="20.3" y2="12.9" /><line x1="12.2" y1="12.4" x2="16.6" y2="19.1" /><line x1="11.8" y1="12.4" x2="7.3" y2="19.2" /><line x1="11.9" y1="12.1" x2="3.7" y2="13.3" /><line x1="11.8" y1="11.7" x2="7.8" y2="4.4" /></svg>)
拆解 Claude Code 的 harness 设计
Anthropic 在《Effective harnesses for long-running agents》里明确提出：可靠性的来源是 harness 而不是模型，agent 需要在"模型之外"被约束。Claude Code 就是这个思路的产品化样本，Anthropic 官方也直接把它归入 agentic harness 的范畴。它不是营销话术——Claude Code 可能是目前公开拆解最透彻的 harness：源码公开、社区研究报告详尽，而且它把课程讲义里的几乎所有核心机制（分层记忆、上下文压缩、权限、钩子、子智能体、会话持久化）都做成了完整的产品化实现。
这一篇我们用课程五子系统框架拆 Claude Code，重点看它怎么把"上下文管理""防止提前宣告完成""确定性约束"这些 harness 原教旨概念落地。
一句话定位
Claude Code 的核心是一个简单的 while 循环：调用模型、执行工具、观察结果、再调用模型。但绝大部分代码不在这个循环里，而在围绕这个循环的系统里——权限系统、上下文压缩管线、扩展机制、子智能体编排、会话存储。这就是 harness 的本质：循环是骨架，骨架之外的一切才是决定可靠性的部分。
指令子系统：分层记忆体系
Claude Code 的记忆系统是它对 harness 理论最直接的贡献，对应课程里"仓库即事实来源"和"跨会话上下文连续"两讲。官方文档《How Claude remembers your project》明确说：每次会话都从全新的上下文窗口开始，靠两类机制跨会话携带知识——CLAUDE.md 文件（你写的指令）和 auto memory（Claude 自己写的笔记）。
作用域上，官方把 CLAUDE.md 文件分为四类（按加载顺序从宽到严）：
- 组织策略级：由 IT/DevOps 统一管理（如
/etc/claude-code/CLAUDE.md），公司级规范。 - 用户级
~/.claude/CLAUDE.md：跨项目的个人偏好与规则。 - 项目级
./CLAUDE.md或./.claude/CLAUDE.md：项目级事实来源，工程结构、技术栈、验证命令，随仓库共享。 - 本地级
./CLAUDE.local.md：个人项目内偏好，通常加进.gitignore不提交。
此外还有两条机制：
- 子目录级按需加载：子目录里的 CLAUDE.md 不在启动时加载，而是当 Claude 读取该目录文件时才进入上下文。
- 自动记忆（auto memory）：Claude 根据你的纠正和偏好主动写笔记，按仓库共享、跨 worktree 生效，每会话最多加载前 200 行或 25KB。
这四类作用域构成一个指令层级：官方文档说"越具体的指令越晚进入上下文"（项目指令在用户指令之后出现）。它的价值在于：不是让模型在每次对话开头消化一整篇巨型指令，而是按作用域就近加载。这正是课程第四讲"为什么单个巨型指令文件会失败"的产品化答案。
上下文子系统：五层压缩管线
Claude Code 对上下文的管理是一套五层压缩管线（five-layer compaction pipeline），不是"满了就摘要"这么简单——这一架构细节来自 VILA Lab 的《Dive into Claude Code》源码级拆解。课程第五讲讲"长任务会丢失连续性"，Claude Code 的解法是多级漏斗：先做无损的剪枝（去掉冗余工具结果），再做结构化提炼，最后才动用有损的 LLM 摘要，并配套熔断机制防止过度压缩。
配套的是会话存储的设计：追加式会话存储（append-oriented storage），所有历史都追加写入 history.jsonl，支持 /resume 恢复和 fork 分支。这保证了"每次会话结束前都做好交接"——不是因为记性好，而是因为存储层是追加的、可重放的。
工具子系统：四种扩展机制
Claude Code 把扩展面切成四类，每一类解决一类问题，这是它设计里最值得抄的部分：
- 技能（Skills）：官方文档定义——
SKILL.md描述的过程性知识，按触发词自动加载，渐进式披露。适合"如何做某件事"的领域知识。 - MCP：官方文档里的 JSON-RPC 协议连接外部系统，是"模型的手够到外部世界"的标准接口。
- 钩子（Hooks）：官方文档挂在
PreToolUse、PostToolUse、Stop等生命周期事件上的确定性脚本。 - 插件 / 子智能体（Subagents）：官方文档把复杂任务拆给专门化的 agent 执行。
关键设计是职责分离：CLAUDE.md 管"是什么"，技能管"怎么做"，MCP 管"连到哪"，钩子管"何时强制"。团队如果把这几层混用（比如把 MCP 干的事写进 CLAUDE.md），就会出现课程里说的上下文渗漏。
反馈与验证：确定性约束 + 人机分工
课程第十讲讲"跑通完整流程才算真正验证"，Claude Code 的对应机制是双轨的：
1. 权限系统（确定性约束）。 Claude Code 的权限不是"全都问一遍"，而是七种模式 + 一个基于 ML 的分类器：低风险操作放行，高风险操作按策略询问或拒绝（架构细节见 VILA Lab 拆解）。这是把"给 agent 划清边界"（第七讲）做成了运行时强制，而不是靠提示词恳求。
2. 钩子（防提前宣告完成）。 PostToolUse 钩子可以在工具执行后强制跑检查、把结果写回上下文；Stop 钩子在 agent 宣告完成时介入。这就是"干活的人和检查的人分开"——Anthropic 在 harness 文章里明确观察到 agent 会自信地夸赞自己的工作（"confidently praised their work"），所以用钩子注入确定性的检查，而不是信任模型的自评。
3. 子智能体（隔离上下文）。 每个子智能体的对话记录存在独立的 sidechain 文件里，不会膨胀父智能体的上下文（见 VILA Lab 拆解）。这是"任务边界"和"上下文隔离"的结合：拆分任务的同时，也隔离了上下文污染。
可观测性与会话持久化
Claude Code 的日志是追加式的完整记录（history.jsonl），加上 /compact、/clear、/init 这些显式命令，让你可以主动管理上下文状态，而不是被动等它满。/init 更是把"让 agent 每次工作前先初始化"（第六讲）做成了一条命令——官方文档说它自动分析代码库并生成初始 CLAUDE.md（含构建命令、测试说明、工程约定）。
映射到课程框架
| 子系统 | Claude Code 的实现 | 评价 |
|---|---|---|
| 指令 | 作用域分层（组织/用户/项目/本地）+ 自动记忆 | 分层记忆是标杆实现 |
| 工具 | 技能 + MCP + 钩子 + 子智能体四类扩展 | 职责划分清晰，是核心亮点 |
| 环境 | 项目内设置 + settings.json | 靠用户在 CLAUDE.md 里自描述 |
| 状态 | 追加式会话存储 + 五层压缩 + resume/fork | 极强，长任务连续性的参考实现 |
| 反馈 | 权限分类器 + PostToolUse 钩子强制检查 | 把"防提前宣告完成"变成确定性机制 |
值得借鉴的设计
- 指令按作用域分层，而不是堆在一个文件里。目录级 CLAUDE.md 是"就近加载"的漂亮实现。
- 压缩是分级漏斗：先无损后损，别一上来就全文摘要。
- 用钩子做确定性检查：防提前宣告完成，靠的是运行时强制，不是提示词恳求。
- 子智能体上下文隔离：拆任务的同时拆上下文，别让子任务的结果污染主循环。
- 会话存储追加式 + 可重放：交接不是靠记忆，是靠存储层保证。
参考来源（原文 / 源码）
每条论断都能回溯到下面的原文或源码，避免凭印象转述：
- Claude Code 官方文档 · Memory：每次会话全新上下文、CLAUDE.md 四类作用域、子目录按需加载、auto memory（200 行 / 25KB）、
/init生成 CLAUDE.md。
https://code.claude.com/docs/en/memory - Claude Code 官方文档 · Skills / MCP / Hooks / Sub-agents：四类扩展机制的定义与事件（PreToolUse / PostToolUse / Stop）。
https://code.claude.com/docs/en/skills ｜ https://code.claude.com/docs/en/mcp ｜ https://code.claude.com/docs/en/hooks ｜ https://code.claude.com/docs/en/sub-agents - VILA Lab《Dive into Claude Code》（源码级拆解报告）：五层压缩管线、权限七模式 + ML 分类器、sidechain 子智能体、追加式会话存储 history.jsonl。
https://zhiqiangshen.com/projects/Claude_Code_Report/Claude_Code_Report.pdf - Anthropic《Effective harnesses for long-running agents》："可靠性来自 harness 而非模型"、agent 会自信地夸赞自己的工作、用钩子做验证等观点出处。
https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents - Claude Code Full Stack 导读（社区，CLAUDE.md / Skills / MCP / Subagents / Hooks 分层）：作为扩展机制职责分离的补充阅读。
https://jsmanifest.com/claude-code-full-stack-guide
相关讲义：第三讲 · 让代码仓库成为唯一的事实来源 ｜ 第九讲 · 防止 agent 提前宣告完成 ｜ 第十讲 · 跑通完整流程才算真正验证