Claude Code实战：Harness工程之道

说实话刚翻开《Claude Code实战》的时候我看得懵懵的，一堆工程化概念砸过来，总觉得这是给资深开发者、技术团队看的书，我就是好奇打开的，好像用不上这么复杂的东西。 慢慢啃下来才有点开窍的感觉——以前我印象里Claude Code就是个更会写代码的聊天工具。 反正我用DeepSeek每次开新对话都要重说一遍我是谁它是谁要让它干啥，改个需求还要从头铺垫半天，时灵时不灵的，还总怪模型不够聪明。慢慢就不爱用了。 看这书才知道根本就是我不会用而已。 书里把Skills、子智能体、Hooks这些组件拆得明明白白，虽然具体的配置细节我还没完全摸透，而且我暂时也用不上，但核心逻辑一下就通了：就像搭积木，把重复的工作流程、固定的项目规则、需要把关的环节都拆成独立的模块，不用每次都跟AI碎碎念。 这种就是更智能一点的智能体用法吧？常用的操作做成技能，它自己就会按流程走；怕出错的地方用钩子拦住，不用每次都提心吊胆；复杂任务拆给子智能体分头干，还不占主对话的上下文。 虽然到现在还有不少技术细节一知半解，但整个思路是彻底打开了。原来用AI提效从来不是比谁提示词写得更花哨，是搭一套可复用、能沉淀的体系。 慢慢摸索着把自己常用的流程、规则都攒成模块，AI才能从“一问一答的工具”，变成真的能搭把手干活的搭档，这才是AI编程真正的打开方式吧。我其实一直想要AI帮我编个程，等我研究研究。

本书系统讲解了Claude Code的完整技术栈与工程化实践。适合具备一定编程基础，希望将 Claude Code 引入日常开发与团队流程的开发者和想了解 AI Agent 工程化落地方法的全栈工程师与技术团队负责人阅读。

1. CLAUDE.md 的「删减测试」（最反直觉，也最有用） 作者明确反对「规则越写越长」：「如果删去某条规则后，Claude 依然能做出正确的行为，那么这条规则不该出现在 CLAUDE.md 中。」再配合「Not For 排除范围」（写清楚不覆盖什么、禁止做什么）和「具体性优先」（矛盾时具体规则覆盖通用规则）。这三条直接治好了我 CLAUDE.md 越写越烂的毛病。 2. Skill 是路由器，不是仓库 「SKILL.md 正文：是路由器，不是仓库。」Skill 的本质是知识的按需投放——常驻上下文里只放 description 这一个「唯一触发信号」，低频知识引而不发。超过约 500 行就该拆分或下沉。一句话：别把 SKILL.md 当垃圾桶。 3. 子智能体的核心是「上下文隔离」 「子智能体旨在解决一个更深层次的瓶颈：上下文窗口的有限性。」关键是它拥有独立上下文，绝不回流主对话。最有价值的是对抗性设计：让一个子智能体当「魔鬼代言人」挑另一个方案的刺，专治思维盲点。 4. Hooks 把纪律变成不可绕过的制度 「在特定事件发生时，自动执行预设逻辑」——把个人经验沉淀为组织规范。关键认知是事件的「能否阻止」：PreToolUse 能阻断危险操作（比如 rm -rf），PostToolUse 只能事后反馈，Stop 做完成前门控。作者一句忠告：能用确定性脚本就别调模型。 5. 最小权限 + 具体性优先贯穿全栈 从 CLAUDE.md 的 Not For，到 Skill 的 allowed-tools，再到 Hook 的拦截边界，作者反复强调同一件事：先定义禁区，再谈能力。

黄佳这本书讲透了Claude Code的整套工程架构，从记忆模块到团队CI/CD落地都有实操案例，点透了配套工程体系才是拉开效率的关键，个人记忆规整到团队流水线落地，让我这种新手也能避开不少踩坑误区。

1. 本书一共10章，把Claude Code分为四层：记忆层、扩展层（command、skill、hooks、subagent）、集成层（Headless、MCP）和编程层（Agent SDK），最后讲述了plugin和工程化，个人以为plugin也可以归类到集成层，Agent SDK也可以归类到工程化； 2. 本书技术细节丰富，比如CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC总开关、MAX_MCP_OUTPUT_TOKENS调整MCP输出上限、strict-mcp-config限制MCP工具、权限规则的评估顺序deny→ask→allow等，有助于全面熟悉Claude Code，也有助于拓宽遇到问题时的解决思路； 3. 作者在最后提出工程化的要义：“让强大却充满不确定性的工具，在秩序井然的系统中可靠地创造价值。”正如发动机本身也是强大却不确定，但在汽车各软件、硬件系统的控制下，使得发动机稳定可靠的驱动汽车行驶在世界各地。LLM是智力发动机，Harness是汽车底盘，LLM联合Harness蕴藏着澎湃动力。

黄佳这本《Claude Code实战：Harness工程之道》今年五月刚出，人民邮电的。作者笔名"咖哥"，之前写过《Agent设计模式》《动手做AI Agent》，这本是他把Agent理论往Claude Code工程化落地的作品。294页，不算厚，但密度不低。 先说清楚这本书在讲什么。很多人对Claude Code的认知停在"更聪明的代码补全"或者"终端里的Copilot"，这本书上来就把这个认知掀了——它说Claude Code不是工具，是Agentic Harness，是裹在LLM外面那套运行时基础设施，管工具调度、上下文工程、安全执行、状态持久化这些事。Harness这个词原意是马具，书里和李宏毅2026春季课里讲的那个"Harness Engineering"是同一个源头：千里马（模型）力气再大，不配马具也白搭，力气传不出来还容易失控。 李宏毅那边把这几年的演进分成三代：第一代Prompt Engineering，在prompt上雕花；第二代Context Engineering，管上下文喂什么；第三代Harness Engineering，给模型搭整套操作系统——控制认知框架、控制能力边界、控制行为流程。这本书站的就是第三代的位置。书里有个判断我很认同：同一模型在不同Harness下的表现差异，远超不同模型在同一Harness下的差距。TerminalBench上验证过，光优化Harness就能让模型代码能力冲进Top5。这话翻译过来就是——别急着追Opus，先把你那副马具配好。 下面按书的"认识→掌握→驾驭"三段走，每章拎一下核心价值观。 ------ 第一段：认识全貌（第1-2章） 第1章 登高望远：Claude Code技术架构全景 四层架构是这章的骨架。记忆层（CLAUDE.md）、扩展层（Skills/Hooks/MCP/子智能体）、集成层（连外部世界）、编程层（Agent SDK）。很多人用Claude Code只发挥了10%效能，原因就是只摸到第一层和第三层的一点边，扩展层那四大件基本没碰。这章最值钱的是把Agentic Loop讲透了——模型不是发一问答一问就完事，它是个持续的执行循环，输入治理、工具调度、恢复分支、停止条件，这套心跳才是Agent。 第2章 温故知新：记忆系统工程实践 AI编程第一大痛点是失忆。每次新会话模型面对的是干净上下文，上次聊的架构决策、技术栈、修过的bug全没了。这章给了个五层记忆体系，核心是CLAUDE.md的写作范式。这里有个容易踩的坑得提：很多人把CLAUDE.md当项目文档写，两百行架构介绍、API清单、数据库设计往上堆，然后奇怪Claude为什么经常无视规则。书里点得很直白——CLAUDE.md的本质是规则层，不是文档层。OpenAI那边AGENTS.md的实践也印证了：太大的规则文件反而起反效果，"所有事都重要"等于"没重要的事"。解法叫渐进式揭露，CLAUDE.md当目录，100行左右，具体知识放结构化docs里，需要的时候再展开。 ------ 第二段：掌握核心（第3-6章，扩展层四大件） 第3章 授人以渔：Skills工程实践 Skills相当于给Claude配专业技能包。这章有几个很实的洞察。一是SKILL.md是路由器不是仓库——500行法则，超过就拆。二是description是Skills的灵魂，有个"预算机制"，description写不好触发就乱，要么过触发要么欠触发。三是参考型Skill和任务型Skill是两种哲学，前者给知识后者给流程。四是allowed-tools做权限约束，知识得绑着行动边界才有意义。最后落到Skills的四种设计模式，从软件工程视角看这块，不是在写prompt而是在设计可复用组件。 第4章 分而治之：子智能体与任务委派的艺术 上下文窗口是有天花板的，大任务塞不进去怎么办？拆给子智能体。这章给五种模式：只读型（安全观察者）、执行型（高噪声任务处理器）、并行型（多专家工作流）、流水线型（串行处理链）、团队型（自组织协作）。只读型和执行型的区分很关键——前者不动代码只调研，后者会改东西，权限和噪声级别完全不同。Token经济学这节也得看，子智能体不是免费拆，每次fork都烧token，得算ROI。这章结尾那句"多代理的真正价值不是更快，而是把不确定性分区"——意思是并行带来的最大好处是职责边界清楚了，验证可以独立，这比提速更重要。 第5章 防微杜渐：Hooks事件驱动自动化 Hooks是Claude扩展体系里最"工程"的一块，17个事件贯穿会话级、工具调用级、子智能体级、完成级。三种处理器类型构成一个确定性阶梯：command（确定规则）→ prompt（单次LLM评估）→ agent（多轮子智能体验证），越往后越贵越聪明。这章两个实战方向值得记：一个是安全防护（PreToolUse拦危险命令、拦敏感文件，PostToolUse全量审计），一个是代码质量自动化（PostToolUse自动格式化、Lint反馈循环、Stop Hook测试门控）。Hooks的精髓是"在关键节点设 checkpoint"，让AI在没失控之前就被拦住。有个坑书里也提了：Stop Hook别塞太多token进去，比如整份测试报告，容易触发prompt-too-long，而prompt-too-long的恢复机制会跳过Stop Hook，死循环。 第6章 海纳百川：MCP MCP这节讲的是从M×N到M+N的标准化力量——N个Agent和M个数据源之间本来要写M×N个适配器，有了MCP就只要M+N。架构是客户端-服务器加JSON-RPC，传输三种形态，配置从CLI到.mcp.json分层。实战两块：连数据库、搭自定义MCP服务器。这章有个比喻我喜欢：MCP是厨房，Skills是菜谱。厨房通了（能取料），菜谱才能用（能炒菜）。安全那段三层纵深（认证授权、数据保护、访问控制）是企业落地的必看项。 ------ 第三段：驾驭工程（第7-10章） 第7章 无为而治：Headless模式与CI/CD集成 这章是从"人机交互"切到"无人值守"的跃迁。Headless模式下Claude Code不喊你确认，按预设规则跑完，适合嵌CI/CD。两个实战：GitHub Actions自动代码审查、多阶段CI管道。核心参数四维控制——输出格式、成本护栏、安全边界、执行控制。Unix管道那段讲怎么把Claude揉进命令行工作流，流式输出做长任务监控，会话管理跨步骤维持上下文。CI环境那节给的是生产级清单：环境变量、性能调优、MCP在CI里的配置、跨平台（GitLab/Jenkins）对照。安全原则五条——最小权限、Secrets管理、容器隔离、成本防护、审计日志，条条都是踩过坑才写得出的。 第8章 器以载道：Agent SDK智能体开发套件 从这章开始从"用Claude Code"转到"基于Claude Code造东西"。Agent SDK把query函数、消息类型（system/init、assistant、user、result）、ClaudeAgentOptions这几块铺开，本质是让你用几行代码就能包一个专属AI应用，底层输出流、权限、会话管理它替你管，你只管工具设计和流程编排。这章实战是搭代码分析Web服务，可以作为SaaS化AI工具的入门模板。 第9章 集腋成裘：Plugins生态与能力打包分发 Plugins解决的是"团队资产沉淀"问题。个人用Claude Code是玩具，团队用得把最佳实践封装成可复用组件——Skills、SubAgent、Hooks打成包，新人拉下来就能用，不用每人重新调一轮。这章实战是"构建团队能力包"。 顺带必须把书里Harness Engineering十条原则的那段揉进来，那是第9章（有些版本附录里）压箱底的东西： • 把模型当不稳定部件，不当同事。同事能担责，模型不能，所以权限、恢复、验证、回滚得自己做。 • Prompt是控制面的一部分，跟runtime、tool schema、memory、hook一起组成控制平面。把prompt当人格设定，最后得到的是个很会表演但不受控的系统。 • Query loop才是代理系统的心跳，没loop的系统能做demo但谈不上运行时。 • 工具是受管执行接口，越危险的工具越不能当普通能力对待。 • 上下文是工作内存，能塞进去不等于应该塞进去，标准是"可治理"不是"够多"。 • 错误路径就是主路径——prompt too long、max output、中断、hook回环、compact失败，这些都是长会话的日常天气，恢复/熔断/限次/防死循环设计时就得有。 • 验证必须独立，不能让系统自己给自己打分。实现者天然相信自己"差不多行了"，模型更是。 • 团队制度比个人技巧重要。一个高手能驯代理，一个团队不行。分层CLAUDE.md、可执行skill、生命周期hook、可追踪transcript、统一验证定义——这些得制度化。 这几条比前面所有操作指南加起来都值钱，是全书真正"工程之道"四个字的落点。 第10章 炉火纯青：工程化实战——从个人到团队 收尾章，六个维度：成本控制（上下文优化、请求优化、模型分级选型）、调试（黑盒诊断的分步/隔离/常见问题三板斧）、大型代码库适配（分区、索引、增量、上下文管理）、团队规范落地（四阶段路线图：个人→团队能力→流程集成→持续优化）、SDD生态融合。附录给了最佳实践清单、CLAUDE.md模板库（React/Node/Python三类）、Skills设计检查、MCP安全 checklist，都是能直接抄的。 ------ 这本笔记看到这儿，说点自己的判断。 这本书不是给AI编程小白看的，0基础拿起来会懵，它默认你已经用过Claude Code/Cursor/Copilot，卡在"聊天式用AI"那层——问一句答一句，上下文一断重来，生成的代码没项目感，团队每个人用法都不一样。它卖的不是操作步骤（虽然294页里操作步骤也不少），卖的是Harness这个认知框架：模型是不可靠部件，系统仍然可以可靠，前提是别把可靠性寄托在模型身上，要做进harness里。 四层架构、Skills、子智能体、Hooks、MCP、Headless、SDK、Plugins——这一整套不是功能清单，是"给模型搭操作系统"的零件箱。书里226个代码片段，配套极客时间那门课（黄佳讲的，平台TOP1）可以一起啃，33讲+书+官方仓库，完整走一遍大概60-90小时。 最实用的是第2章CLAUDE.md范式、第3章Skills的渐进式披露、第5章Hooks的安全门控、第7章Headless的CI集成，这四个拿来就能用。最值得反复嚼的是第9章那十条Harness原则，尤其是"验证独立"和"团队制度比个人技巧重要"这两句——这已经不是Claude Code专属的方法论了，是所有AI Agent工程都能搬过去用的。 如果你已经在用Claude Code但感觉"也就那样"，这本书能让你那匹马多跑出百分之六十的力气。如果你还没开始用，先去把CLI跑通再来翻这本，不然四层架构听着像天书。 要不要我顺着Harness这条线，把李宏毅那套"Prompt→Context→Harness"三代演进再单独拆一版，或者把书里CLAUDE.md/Skills/Hooks三件套按一个真实项目（比如你手头正在跑的那个）给个配置草稿。

书名包含harness 工程之道，但是整本书没有围绕 ClaudeCode 如何基于 harness 工程展开，就书籍末尾的后记里生硬的点了一下。作为一本 ClaudeCode 扫盲书不错，但是想了解学习harness 的，可以直接绕道了。书名里的 harness纯蹭热度

比较空洞，不如直接看官方文档。

这本书不是简单介绍 Claude，而是用“四层架构 + 八大机制”重塑你对 AI 工程的认知。作者先勾勒 Claude Code 从命令行到可编程 Agent 的演进路线，再逐层拆解记忆、Skills、子智能体、Hooks、MCP 等核心组件，给出从个人到团队的落地方法。书中大量真实案例揭示：只有把 Claude 装进记忆系统、用 Skills 固化知识、借子智能体分治、以 Hooks 做安全拦截，才能真正解放开发者生产力。尤其对成本、权限与协作的剖析，让人警醒——AI 并非免费午餐，工程化才是王道。读完此书，你会明白：与其追问“Claude 为什么没理解”，不如反思“我是否搭建了让它成功的架构”。

书里把Claude Code拆成四层——记忆（CLAUDE.md）、技能、子智能体和钩子，说白了就是教我们怎么管理上下文、怎么分工协作、怎么保证安全。 适合想真正把AI编程工具用稳、用进团队流程的朋友，读完我们能从“玩个新鲜”升级到“正经干活”。