Harness Engineering：Claude Code 设计指南
副标题：从源码抽象出可控 AI 编程系统的工程原则
一、这本书要写什么
这不是一本“Claude Code 源码导读”。
源码导读有一种天然的局限：它容易把代码中直接出现的内容视为最重要的内容。实际情况未必如此。代码只是系统在某个时间点留下的形态，工程原则才是它真正的骨架。要是只沿着函数往下讲，最后很容易写成一本啰嗦的注释集。读者看完以后知道有个 getSystemPrompt()，却不明白为什么一个能写代码的代理系统，最终会长成一个权限很多、状态很多、边界很多、还经常自我打断的系统。
这本书要做的事，是从 Claude Code 这类系统的实现里，提炼出一套更普遍的设计方法。它关心的是为什么必须这样设计，才不至于把一个会写代码的概率机器，误认为是一个可以独立行使判断力的工程师。
更直接地说，这本书讲的是 Harness Engineering。所谓 Harness，就是给模型装上一套约束结构。这个词听起来不浪漫，但它能防止执行能力在工程环境里失控。凡是和 shell、文件系统、Git、权限、网络打过交道的人，通常都会重视这层约束。
二、目标读者
这本书面向三类人：
- 正在做 AI coding agent、IDE agent、CLI agent 的工程师
- 想把“prompt engineering”升级成“runtime engineering”的技术负责人
- 希望为团队建立一套可控、可验证、可复盘的代理式开发规范的人
它不主要写给只想知道某个开关怎么开的用户。那种内容写在帮助文档里就行。书应该写那些短文放不下、源码又不肯主动告诉你的东西。
三、全书定位
目标篇幅：80 页左右
目标风格：
- 专业技术书，不是营销文案
- 基于源码，但不受源码目录结构支配
- 语言尽量清楚，不装神弄鬼
- 允许有一点冷幽默，但不耍滑头
- 写工程常识，也写工程错觉
这本书不应该把 Claude Code 写成某种“越来越像人”的故事，而应该把它写成一个“越来越像系统”的故事。软件一旦进入生产环境，真正决定结果的通常是边界、约束、回滚和验证。
四、核心论点
全书只需要围绕一个核心论点展开：
Prompt 决定它怎么说话，Harness 决定它怎么做事。
再展开一点，可以得到下面几条：
- 模型不是可信执行体，运行时和权限系统才是
- 工具是被约束的执行接口
- 错误属于主路径的一部分
- 上下文越可治理越好
- 自治要求系统在明确边界内持续做事
- 验证属于完成定义的一部分
五、为什么 80 页比 200 页更合适
两百页当然不是不能写，但很容易写出一种技术书里常见的问题：明明只想说十个判断，却扩成三十章，于是中间生出许多过渡性段落。段落一多，书就变厚；书一厚，作者也容易误以为自己讲得更全面。实际情况往往只是把同一件事从不同角度重复了一遍。
八十页正好。它允许我们：
- 讲清楚方法论
- 讲清楚 Claude Code 的关键设计点
- 给出可操作的团队实践
- 留下一点空白，不把书写成 API 清单
这种体量更接近一本短而硬的工程小书。读者不需要请假一周来读它，读完以后也不至于只记住一些空泛术语。
六、建议目录
全书建议 9 章，加一个附录。
第 1 章 为什么需要 Harness Engineering
这一章讨论问题的起点：为什么“会写代码”远远不足以构成一个可用的工程代理。模型看上去像个助手，实质上仍是一团概率分布。它有时候对，有时候错，有时候还会错得很像那么回事。核心问题不在聪明程度，而在稳定性。Harness 的任务，就是把这种不稳定能力约束成可接受的系统行为。
要点：
- 从“智能”到“可控”的差别
- 为什么代码代理天然需要缰绳
- 从 prompt engineering 走向 runtime engineering
第 2 章 Prompt 不是人格，Prompt 是操作系统的一部分
这一章解释 system prompt 在 Claude Code 中的真正角色。它是一层行为协议。它定义任务边界、输出风格、工具使用原则、风险动作准则，以及上下文治理的基本规则。进一步说，真正重要的是 prompt 如何与 runtime、memory、tool schema 一起组成完整的控制平面。
要点：
- 分层 system prompt 的意义
- 默认 prompt、append prompt、agent prompt 的优先级
- 为什么“好 prompt”必须和系统设计配套
第 3 章 Query Loop：代理系统的心跳
这一章讲 Claude Code 的主循环。凡是代理系统，只要它不是一次性问答，就一定有一个心跳结构。一次循环如何装配上下文，何时调用模型，如何消费流式输出，如何决定继续、重试、压缩或返回，这些属于系统设计的主骨架。一个代理是不是成熟，先看它有没有把循环设计明白。
要点：
- Query loop 的最小结构
- 状态机思维
- 为什么“流式”不是表现层问题，而是控制问题
第 4 章 工具不是外挂，而是受控执行面
这一章讨论 tools。很多人会把工具理解成“让模型多长几只手”。这种理解不算错，但太轻了。真正关键的是：工具不是能力装饰，而是执行边界。工具 schema 决定模型能以什么方式接触真实世界；权限策略决定它碰到边界时是停下、询问，还是继续。因此，工具系统本质上是安全设计的一部分。
要点：
- tool schema 的真实作用
- 权限与确认机制
- shell、文件、网络、Git 为什么必须区别对待
第 5 章 上下文不是越多越好，而是越可治理越好
这一章讨论 memory、summarization、compaction。上下文窗口变大，不意味着问题自动解决。上下文一旦失控，模型就会开始在无关信息里打转，把真正重要的约束淹没掉。Claude Code 的很多设计，本质上是在做上下文预算管理。预算管理做不好，再大的窗口也只是更大的垃圾桶。
要点：
- context window 不是容量竞赛
- compact 的作用与代价
- memory 应该保存什么，不该保存什么
第 6 章 错误不是异常分支，错误就是主路径
传统软件里，人们总爱把成功路径写得很漂亮，失败路径只是补丁。代理系统对此更敏感：失败路径没设计好，成功路径迟早也会失去可信度。Claude Code 这类系统的价值，在于出错以后还能恢复、还能交代、还能保持上下文连续，不会只用一句“出了点问题”把一切模糊带过。
要点：
- retry、recovery、reactive compact
- max_output_tokens 与 prompt-too-long 的不同处理
- “忠实汇报”为什么是架构要求
第 7 章 多代理不是分身术，验证也不是自证清白
这一章讨论 subagent、fork、verification agent 等机制。很多人看见多代理，就容易联想到“并行更快”。速度只是附带收益，更重要的是职责分离。执行代理负责推进工作，验证代理负责挑刺。要是让同一个代理既干活又验收，最后往往会出现自我背书的问题。
要点：
- subagent 的边界
- explore、execute、verify 的分工
- 为什么验证必须独立
第 8 章 团队落地：如何把一个聪明工具变成可用制度
到了团队里，问题就不再是“这个代理会不会做事”，而是“它做事的方式是否稳定，团队是否能承受，出了问题谁能复盘”。这一章不谈玄学，只谈落地：怎么写 CLAUDE.md，怎么设计 skill，怎么制定 policy，怎么区分可自动执行与必须先问人的动作。
要点：
- 团队 CLAUDE.md 设计原则
- 技能系统和工具边界
- 审批、审计、可逆性原则
第 9 章 Harness Engineering 十条原则
最后一章给出归纳。一本技术书写到结尾仍不敢下判断，通常说明作者自己也没有想清楚。这里应该明确列出十条原则，作为全文总结，也作为团队实践的检查清单。
建议包括：
- 把模型当不稳定部件，而不是同事
- 先设计回滚，再设计自治
- 把错误路径当主路径来写
- 把权限当产品能力来设计
- 把验证写进完成定义
- 把上下文当资源而不是垃圾桶
附录 关键图与清单
附录可以收这些材料：
- Query loop 状态机
- Tool execution 状态机
- Compact / retry 状态机
- CLAUDE.md 编写清单
- Tool 设计清单
- Verification 清单
七、80 页的篇幅分配
建议这样分：
- 第 1 章：8 页
- 第 2 章：8 页
- 第 3 章：12 页
- 第 4 章：12 页
- 第 5 章：12 页
- 第 6 章：10 页
- 第 7 章：8 页
- 第 8 章：6 页
- 第 9 章：4 页
附录：若干图表和清单，约 5 到 8 页
这样总量在 80 页上下，不虚胖，也不单薄。
八、写作方法：基于源码，但超脱源码
每一章都建议用同一个结构：
- 先讲工程问题
- 再讲 Claude Code 如何解决
- 再讲这种设计的代价和局限
- 最后提炼成可迁移的原则
比如讲 compact，不应该上来就列函数名，而应该先讲：为什么一个上下文窗口足够大的系统，仍然必须压缩上下文。因为问题从来不只是“装不装得下”，还有“还看不看得清”。等这个问题说清楚，再回到实现，源码就成了证据，不再是叙事本身。
九、文风说明
用户要求“以王小波的口吻”。这件事要做得谨慎。更稳妥的办法，是借用那种写法里的三个气质，不直接模仿句法和段落节奏：
- 对技术幻觉保持清醒
- 对工程现实保持诚实
- 对一切装腔作势的说法保持一点不耐烦
所以这本书的语言可以有一点反讽，但不能油滑；可以有判断，但不能端着；可以偶尔说一句锋利的话，但不能靠花活撑门面。
例如类似下面这样的句子是合适的：
一个会调用 shell 的模型，若想安全完成工程任务，需要的是一整套约束，而不只是多一点聪明。
但不必刻意把每段都写成文学练习。技术书首先要让人看明白，不需要把重点放在作者笔法上。
十、可以立刻开写的内容
如果按这个提案推进，下一步最适合写的是：
- 序言
- 第 1 章全文
- 第 2 章全文
- 第 3 章前半部分
原因很简单：这几章先把问题、立场和骨架立住，后面的运行时、工具、compact、verification 才不会写成散装事实。
十一、序言开头样稿
可以这样起：
这些年，人们喜欢把会写代码的模型叫作智能体。这个称呼不能说错，但也不能说很准。因为多数时候，它既不稳定，也不可靠，只是恰好能在足够多的上下文里，说出一些看上去像样的话。要是把它直接放进文件系统、shell、Git 仓库和权限体系里，它很快就会向你证明，概率分布并不天然适合掌管生产资料。于是问题就落到一件更实际的事上：如何让它成为一个守规矩的系统。Harness Engineering 讲的，就是这件事。
十二、结论
这本 80 页的小书，最适合写成一本短而硬的设计指南。它不追求百科全书式覆盖，而追求把关键判断说清楚，把可迁移原则留下来。只要这点做到了，它就不会依赖 Claude Code 的某个具体版本生存；即使源码以后改了很多，书里最有价值的部分仍然成立。