这本书不是什么

在开始之前，我想先把这本书的边界说清楚，避免浪费你的时间。

这本书不是：

• Claude Code 的使用手册；
• 一份完整的 Claude Code 源码导读；
• agent 入门教程；
• 一份「怎么写出更好的 prompt」的经验集。

如果你找的是其中任何一样，这里都不适合你。

这本书是什么

这本书是以 Claude Code 为样本、围绕 harness engineering 展开的一份架构观察笔记。

它做的事情只有一件：

把一个真实、成熟、长期演化中的 agent runtime 拆开，看它把哪些复杂度前置到了架构层，把哪些工作分流到了旁路，又把哪些边界做成了正式的运行时结构——并从中抽取可以迁移到其他系统的工程判断。

最近 harness engineering 这个词越来越多地出现在讨论里。比起「怎么调模型」，它更关心：

• 怎么让模型在一套受控环境里工作
• 怎么定义模型能看到什么、能调用什么、调用失败后怎么办
• 怎么把长期协作所需的基础设施做出来
• 怎么让系统在功能越加越多的同时不塌成一团

Claude Code 恰好是现在少数公开可读、又在这些问题上做得比较认真的样本。这本书就围绕这些问题，把它当成一个值得拆开研究的对象。

写给谁

这本书最适合下面几类读者：

• 想研究 agent runtime 设计的工程师——你会在这里看到 runtime 解构、控制面与数据面分离、side-channel、上下文工程、治理接入这些问题是怎么被解决的。
• 想做自己的 harness / agent 平台的开发者——你会在后面找到可以迁移的设计原则，而不只是「Claude Code 有哪些功能」的描述。
• 对长期协作型 agent 感兴趣的架构师——memory、compact、subagent、恢复机制、任务系统在这里都不是附加功能，而是正式的基础设施。

反过来，下面这几类读者可能更适合别的材料：

• 想学 prompt 技巧的
• 想马上上手 Claude Code 使用的
• 想看 Claude Code 代码文件逐行注释的

这本书的承诺与不承诺

承诺的：

• 尽量基于源码做判断，不做无依据的推测
• 清楚区分「观察到的事实」和「抽象出的原则」
• 保持克制，不神化也不过度解读
• 术语保持前后一致

不承诺的：

• 不承诺覆盖 Claude Code 所有代码路径
• 不承诺每个结论都能在源码里找到完全对应的函数（部分是综合判断）
• 不承诺研究结论随 Claude Code 迭代自动保持最新

这些边界需要提前说清，否则「研究」这个词很容易被当成「总结」。

怎么读

这本书不要求从头到尾顺序阅读。它被组织成四篇：

第一篇 · 基础轮廓（00–07）

答的问题：「开始研究之前，我需要先知道这个系统长什么样」

这一篇是以产品和模块视角，先把 Claude Code 的整体轮廓建立起来：入口、命令、工具、QueryEngine、UI、扩展、配置、构建形态。读完这一篇，你会知道这本书要研究的对象长什么样子。

第二篇 · 工程视角过渡（08–10）

答的问题：「我应该用什么视角继续深入研究它」

这一篇负责把读者从「产品模块」视角切换到「runtime 工程」视角。08 章负责过渡，09 章总结 harness engineering 的观察框架与可迁移经验，10 章专门讨论评测基础设施和受控自改进。

第三篇 · 运行时深挖（13–26）

答的问题：「这个 runtime 的关键结构是怎么工作的」

这是本书最厚的一部分，每章对应一个真实存在的 runtime 子系统：agent loop、skills、hooks、工具编排、memory、recovery、context 装配、治理边界、tool system、streaming、compact、tasks、subagent。

第四篇 · 综合、索引与收束（27–30）

答的问题：「我读完之后，需要一张总图和一套可查的参考」

这一篇不是正文，是参考资料：总体架构图、阅读路径、术语表、最终综合。如果你不准备顺读，可以只用这一篇的入口。

附录

• 附录 A：源码证据索引（按符号组织，用于回溯正文结论）

最小阅读路径

如果你不想全读，下面三条路径会是最常见的：

• 想先建立整体感：前言 → 00 → 03 → 13 → 20 → 27
• 想做自己的 harness：09 → 13 → 15 → 16 → 19 → 20 → 24 → 26 → 30
• 只做速查：27（总图） → 28（索引） → 29（术语）

第 28 章会提供更完整的按问题跳读索引。

一点致谢与诚实声明

这本书的研究对象是开源的 Claude Code 仓库。本书作者不属于 Anthropic，所有对 Claude Code 设计意图的判断都是外部观察，可能有误。任何「Claude Code 这样做是因为……」的表述，更准确的读法都是「从代码看，这种读法是能自洽的」。

如果你在阅读中发现与源码不符的地方，请以源码为准。

愿这本书对你研究和构建自己的 agent runtime 有帮助。