《Claude Code 设计指南》读书笔记（第 1 章 - 第 9 章）

章节关系图

第 1 章 为什么需要 Harness Engineering

章节总结

这一章先把问题定准了：真正需要治理的不是“模型会不会说”, 而是“一个会说又会执行的模型接入终端、文件系统和网络之后，怎样才不会把现场带偏”。作者把 Harness Engineering 定义为一套制度化控制平面，它的前提不是赞美模型，而是明确承认模型并不天然值得信任。

围绕 Claude Code 的源码，作者把 harness 的骨架概括成五层：受约束的会话系统、持续循环、工具调度、细粒度权限和错误恢复。也就是说，工程秩序不是在结果页补一句提醒，而是在系统入口、执行过程和异常分支里逐层落地。

内在联系

本章相当于全书总论。第二章会把“约束”具体化为 prompt 作为控制面的一部分，第三章到第六章则分别展开连续性、工具、上下文和恢复的治理方式，最后在第九章收束为十条原则。

常见疑问

为什么要专门提出 Harness Engineering, 难道直接给模型更多能力不行吗？不行。能力越强，误操作成本越高；没有受管执行框架，模型越聪明反而越容易放大事故半径。

现实启发

做 AI 编程系统时，第一设计动作不该是“再接一个工具”, 而该是先回答三件事：谁给权限，谁处理中断，谁在失败后把叙事接回来。

第 2 章 Prompt 不是人格

章节总结

作者反对把 system prompt 理解成“人设文案”。对聊天产品来说，这种理解或许够用; 但对要读文件、调工具、长期执行的代理系统来说，prompt 的角色更接近运行时协议。它决定的不是系统“像谁”, 而是系统能做什么、按什么优先级做、冲突时听谁的。

这一章最关键的判断是：Claude Code 的 prompt 从一开始就是分层拼装的。身份定义、系统级约束、工程纪律、记忆来源和缓存成本都被纳入控制面。于是 prompt 的价值不在文字风格，而在它与 memory、tool schema、上下文压缩机制共同构成行为宪法。

内在联系

第一章只说明“要有规矩”, 本章则回答“规矩住在哪里”。它也为第五章的上下文治理做铺垫，因为 prompt 在这里不是孤立文案，而是会和长期记忆及局部规则共同形成控制面。

常见疑问

既然 prompt 可以被用户覆盖，那系统规则是不是不稳？作者的答案是否定的。用户可以追加任务意图，但不能绕过系统已经定义好的结构层级，否则整个 harness 就会退化成口头约定。

现实启发

团队写 agent prompt 时，不要只追求“听起来像资深工程师说的话”，更要明确来源、边界和覆盖顺序。真正难的不是措辞，而是冲突治理。

第 3 章 Query Loop

章节总结

本章把 query loop 提到代理系统心跳的位置。作者认为，一个系统是否成熟，首先看它是不是把连续执行当作主业务：输入如何被治理，模型调用只是循环中的哪一段，工具结果如何回填，中断和恢复如何进入下一轮，停止条件又如何区分“完成”与“失败”。

Claude Code 的关键不是有一个 query() 入口，而是有一段有状态的 queryLoop() 维持生命周期。状态在这里不是包袱，而是代理能连续工作的前提。谁把状态当附属品，最后就会在长任务里失去上下文和节奏，也无从审计。

内在联系

如果第二章讲的是“控制面的宪法”, 本章讲的就是“执行层的行政系统”。后面的工具权限、上下文压缩和错误恢复都要依附于这个心跳，否则只会变成零散补丁。

常见疑问

为什么不能把 agent 理解成“支持工具调用的多轮问答”? 因为真正困难的不在单次调用，而在跨轮状态如何维持。没有 loop, 就没有严格意义上的连续性。

现实启发

评估一个 agent 原型时，不要先看 demo 漂不漂亮，先看它有没有明确的状态结构、停止条件和恢复分支。没有这些，长任务迟早塌。

第 4 章 工具、权限与中断

章节总结

作者在这一章强调，模型一旦开始调工具，问题性质就从“回答质量”变成“真实动作后果”。所以工具系统的核心不是“接得多不多”, 而是执行前已经做了多少治理。Claude Code 用受管执行接口代替模型直接碰世界：工具调用先被分类，并发要过安全判断，权限先于能力，Bash 因为破坏力最大而被施加最细规矩。

这里还有一个重要判断：中断不是附带特性，而是运行时的一等公民。StreamingToolExecutor 的存在说明，执行过程中的取消、拒绝和结果回传必须被正式对待，否则工具层只是在把不稳定性外溢给现实世界。

内在联系

第三章给了“循环骨架”, 本章则把最危险的执行动作纳入骨架管控之内。第六章会继续说明，当工具调用失败或半途被打断时，恢复策略该如何接管。

常见疑问

为什么 Bash 总被单独拿出来看？因为它几乎天然带着跨文件、跨进程、跨环境的破坏力。系统越允许它自由发挥，就越需要更明确的审批和边界语义。

现实启发

设计工具链时，最忌讳把工具能力等同于工具安全。一个“能跑”的 shell 接口，如果没有并发规则、权限模型和中断语义，本质上就是把事故入口产品化。

第 5 章 上下文治理

章节总结

这一章的核心是给“记忆越多越聪明”的朴素想法泼冷水。作者认为，上下文首先是一笔预算，而不是一个无限可堆叠的仓库。Claude Code 用 CLAUDE.md、MEMORY.md、session memory 和 compact 机制说明：长期指令、短期连续性和摘要重建必须分层治理，否则系统会被自己记住的东西拖死。

尤其重要的是，compact 的目标不是单纯压缩字数，而是重建“可继续工作的上下文”。这说明上下文治理的本质不是收藏，而是保留工作语义：哪些约束仍有效、任务进度到哪里、后续动作靠什么承接。

内在联系

第二章谈控制面的层级，本章把这套层级拉到记忆系统里具体化。它也直接服务于第六章，因为很多恢复动作其实都建立在上下文预算和摘要重建之上。

常见疑问

为什么不能简单依赖聊天历史？因为聊天记录会不断膨胀，且混杂长期规则、临时讨论和过时信息。代理系统需要的是可治理的工作内存，不是一份越来越长的流水账。

现实启发

团队做记忆系统时，最值得先定义的是“哪些信息长期有效，哪些只该短期保留，什么时候必须摘要重建”。不做这一步，后面所有 agent 表现都会越来越飘。

第 6 章 错误与恢复

章节总结

作者明确反对“正常情况下”的设计叙事。对代理系统来说，prompt too long、输出被截断、hook 回环、工具中断都不是偶发事故，而是迟早会来的运行周期。成熟系统的标志，不是它从不出错，而是它在出错后能否继续工作。

Claude Code 的恢复思路很清楚：先把可恢复错误从面向用户的报错里暂时扣下，交给恢复系统判断是 compact、续写、重试还是终止; 连恢复动作自己也要受治理，避免 compact 进入死循环。恢复保护的不是面子，而是执行叙事的一致性。

内在联系

第五章提供了预算治理与摘要重建的基础，本章则回答“预算超了怎么办”。第七章的验证分工又进一步说明，恢复之后仍需要独立判断问题是否真的解决。

常见疑问

为什么错误路径要被视为主路径的一部分？因为只要系统在真实环境里持续运行，错误就不是例外。把错误当边角料，等于把真正的系统能力留白。

现实启发

很多 agent PoC 死在“第一次长任务”上，不是因为模型不够强，而是因为系统默认失败后只能重新开始。真正实用的恢复，目标应该是继续推进而不是清零重来。

第 7 章 多代理与验证

章节总结

这一章把多代理从“多开几个 worker”拉回到责任分区问题。作者认为，单代理走到一定复杂度后，真正稀缺的不是再多一点推理，而是把探索、执行、汇总和验证拆开，防止它们在同一条上下文里互相污染。Claude Code 对 forked agent 的第一要求甚至是 cache-safe, 这说明它首先关心的是状态隔离和主循环稳定，不是表面上的并行。

同时，验证必须独立成阶段，不能由执行代理顺手给自己打分。多代理真正解决的，是把不确定性按职责分区，再通过协调者与验证环节收口。

内在联系

前六章主要在讲单一代理如何维持秩序，本章开始回答“任务变大后如何避免混乱复制”。第八章会进一步把这种分工提升为团队制度。

常见疑问

为什么“实现完成”不等于“问题解决”? 因为实现代理天然倾向于为自己的完成感背书。没有独立验证，系统很容易把局部产出误判成整体闭环。

现实启发

做多代理系统时，先定义角色边界和收口机制，再谈并发数量。否则你得到的不是分工，而是多份并行失控。

第 8 章 团队落地

章节总结

这一章把问题从个人高手转向组织复制。作者指出，很多 AI 工具在个体手里看起来很好用，是因为高手一直在用背景知识和临场判断兜底。一旦团队推广，这些脑内秩序如果没有被写成规则、审批、hook 和技能切片，系统就会立刻失稳。

Claude Code 值得参考的地方，在于它把高手经验硬化为分层 CLAUDE.md、approval 语义、技能资产、生命周期 hook 以及统一验证定义。团队真正需要复用的，不是某个人怎样盯着模型工作，而是哪些制度能让陌生成员在相同边界下工作。

内在联系

第七章讨论职责分工，本章把这种分工上升为组织治理。它也是第九章十条原则里“团队制度比个人技巧重要”的现实展开。

常见疑问

是不是先多写 skill 就算团队化了？不是。skill 只是制度切片的一部分; 如果规则分层、审批口径、验证标准和审计轨迹都不稳定，再多 skill 也只是在堆现场补丁。

现实启发

推动团队落地时，最先要固化的通常不是“最佳提示词”, 而是禁止做什么、哪些改动必须验证、哪些审批绝不能跳过，以及失败后留下什么可复盘轨迹。

第 9 章 Harness Engineering 十条原则

章节总结

这一章把前面八章压缩成十条判断：把模型当不稳定部件、prompt 是控制面的一部分、query loop 是心跳、工具是受管执行接口、上下文是工作内存、错误路径就是主路径、恢复的目标是继续工作、多代理是对不确定性分区、验证必须独立、团队制度比个人技巧重要。它们不是格言，而是前文所有结构分析的浓缩版本。

这章的价值不在新增细节，而在把零散工程感受压成可复用判断。对团队来说，真正带得走的往往不是某个函数名或某次实现技巧，而是这些足以指导下一轮系统设计的原则。

内在联系

本章是全书总收束。前八章分别从控制面、循环、工具、记忆、恢复、分工和治理铺陈证据，这里则把证据转成设计口径。

常见疑问

既然原则已经总结出来，还需要读前面章节吗？需要。原则给的是压缩判断，前文给的是结构来由。没有来由，原则很容易被误用成口号。

现实启发

做内部 agent 规范时，最有效的写法不是长篇功能说明，而是把这些原则转成可执行清单：哪些必须显式化，哪些必须独立验证，哪些错误必须先恢复再决定是否暴露给用户。

全书脉络小结

《Claude Code 设计指南》真正反复证明的一件事是：可靠性不能寄托在模型身上，只能寄托在 harness 身上。作者从“先承认模型不可靠”起笔，依次展开 prompt 作为控制面、query loop 作为心跳、工具执行的权限纪律、上下文预算治理、错误恢复、多代理分工以及团队制度化，最后把这些压缩成十条原则。

如果把这本书的论证链再缩成一句话，就是：一个 AI 编程系统的成熟度，不看它最顺的时候像不像高手，而看它出错、被打断、上下文爆炸、多人协作时还能不能维持秩序。它讨论的不是“如何把模型调得更会写代码”, 而是“怎样让一个不稳定的模型在工程现场里被制度化地使用”。