# 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 页上下，不虚胖，也不单薄。 ## 八、写作方法：基于源码，但超脱源码 每一章都建议用同一个结构： 1. 先讲工程问题 2. 再讲 Claude Code 如何解决 3. 再讲这种设计的代价和局限 4. 最后提炼成可迁移的原则 比如讲 compact，不应该上来就列函数名，而应该先讲：为什么一个上下文窗口足够大的系统，仍然必须压缩上下文。因为问题从来不只是“装不装得下”，还有“还看不看得清”。等这个问题说清楚，再回到实现，源码就成了证据，不再是叙事本身。 ## 九、文风说明 用户要求“以王小波的口吻”。这件事要做得谨慎。更稳妥的办法，是借用那种写法里的三个气质，不直接模仿句法和段落节奏： - 对技术幻觉保持清醒 - 对工程现实保持诚实 - 对一切装腔作势的说法保持一点不耐烦 所以这本书的语言可以有一点反讽，但不能油滑；可以有判断，但不能端着；可以偶尔说一句锋利的话，但不能靠花活撑门面。 例如类似下面这样的句子是合适的： > 一个会调用 shell 的模型，若想安全完成工程任务，需要的是一整套约束，而不只是多一点聪明。 但不必刻意把每段都写成文学练习。技术书首先要让人看明白，不需要把重点放在作者笔法上。 ## 十、可以立刻开写的内容 如果按这个提案推进，下一步最适合写的是： - 序言 - 第 1 章全文 - 第 2 章全文 - 第 3 章前半部分 原因很简单：这几章先把问题、立场和骨架立住，后面的运行时、工具、compact、verification 才不会写成散装事实。 ## 十一、序言开头样稿 可以这样起： > 这些年，人们喜欢把会写代码的模型叫作智能体。这个称呼不能说错，但也不能说很准。因为多数时候，它既不稳定，也不可靠，只是恰好能在足够多的上下文里，说出一些看上去像样的话。要是把它直接放进文件系统、shell、Git 仓库和权限体系里，它很快就会向你证明，概率分布并不天然适合掌管生产资料。于是问题就落到一件更实际的事上：如何让它成为一个守规矩的系统。Harness Engineering 讲的，就是这件事。 ## 十二、结论 这本 80 页的小书，最适合写成一本短而硬的设计指南。它不追求百科全书式覆盖，而追求把关键判断说清楚，把可迁移原则留下来。只要这点做到了，它就不会依赖 Claude Code 的某个具体版本生存；即使源码以后改了很多，书里最有价值的部分仍然成立。