🐎 Claude Code 实战
照着《Claude Code 实战》(黄佳 著,人民邮电出版社·异步图书·暮柳 AI,副标题「Harness 工程之道」)做的自学笔记 —— 跟 25 课 Claude Code 橙皮书 不是一件事:那本讲怎么用它写代码(读文件、改文件、跑测试、看报错),这一本讲怎么给它搭架子(规矩放哪、能力怎么拆、什么时候必须由脚本接管、什么情况下它根本不该被叫起来)。全书立在一个比喻上:Claude 是一匹力气很大的马,你为它设计一副合身的马具;马具不让马跑得更快,它让马的力气使在一个方向上。十条主线一章一条:全景 → 记忆 → 技能 → 子智能体 → 钩子 → 协议 → 无人值守 → SDK → 插件 → 工程化;第 1~6 章是「有什么、怎么用」,第 7~9 章是「换个地方怎么用」,第 10 章是「多人怎么管」。三句话是全书的骨头:模型能忘,钩子不会;上下文是有限资源,谁进来谁就得值这个价;从轻往重走容易,从重往轻走要命。逐节一篇,「本章小结」并进章末,合计 91 篇。沙箱里能真跑的都真跑(钩子脚本、目录结构、配置解析、SDK 调用),必须真 Claude Code 的贴教材原样并标注。
内容来自我的 Obsidian 自学笔记 · 全书 10 章 91 篇已全部写完 · 全书完结 🎉
第1章 登高望远:Claude Code 技术架构全景
从命令行助手到 Agent 框架
循环才是分水岭:一问一答与自主干活的差别
四层架构模型
记忆、扩展、集成、编程四层怎么分工
组件关系与协作
谁触发谁,一个请求走哪条路
技术选型指南
先问约束再挑组件,别反着来
第2章 温故知新:记忆系统工程实践
为什么 AI 需要「记忆」
模型本身无状态,记忆全靠外面喂
五层记忆体系
五层各存什么、谁覆盖谁
CLAUDE.md 写作范式
CLAUDE.md 是操作手册,不是项目…
条件化规则系统
按文件路径挂规则,命中才注入
实战:3 种典型项目配置
三种技术栈的配置差在哪
第3章 授人以渔:Skills 工程实践
从 CLAUDE.md 到 Skills:知识的两个维度
常驻知识与按需知识的成本差
解剖一个 Skill:骨骼与纹理
一个 Skill 就是一目录加一份 YA…
渐进式披露:知识的投资回报率
三级披露:先读一行,用到才读全文
触发机制:Claude Code 如何抉择 Skills 的调用
模型自己看 description 决定…
SKILL.md 正文:是路由器,不是仓库
正文是路由表,不是资料仓库
allowed-tools:知识约束行动
权限收窄等于把行动范围钉死
参数传递与动态注入
参数怎么传,上下文怎么预取
作用域与优先级
四层作用域的覆盖顺序
实战:从零构建 3 类 Skill
参考型、任务型、复合型三件套
Skills 的 4 种设计模式
四种设计模式各自的适用面
测试与迭代
用触发率与命中率把 descriptio…
从软件工程看 Skills
单一职责、开闭、契约,一个不少
第4章 分而治之:子智能体与任务委派的艺术
上下文窗口的困境
塞满就忘,越读越贵
子智能体的本质
独立上下文,只回结论不回过程
子智能体的定义与配置
frontmatter 五个字段定死一个…
5 种子智能体模式
五种分工形状,各有各的代价
子智能体与 Skills 的协作
Skill 管能力,子智能体管上下文
Token 经济学
省的是主上下文,不是总 token
从软件工程看子智能体
委派就是接口隔离
实战注意事项
什么时候不该拆
第5章 防微杜渐:Hooks 事件驱动自动化
Hooks 在 Claude 扩展体系中的定位
唯一一处确定会执行的地方
事件生命周期:17 个事件
十七个事件,能不能阻止最关键
配置体系:6 个位置,6 种用途
六个放置位置,六种生效范围
3 种处理器类型:确定性的阶梯
命令、单次评估、多轮验证的阶梯
hookSpecificOutput:与 Claude 交流的协议
用一段 JSON 回话给模型
工程实战一:安全防护体系
拦危险命令、护敏感文件、全量审计
工程实战二:代码质量自动化
格式化、lint 回灌、测试门控
子智能体 Hooks:精准的上下文管理
在子智能体起点注入、终点验收
异步 Hooks:后台执行不阻塞
后台跑,不拖慢主流程
环境变量与调试
环境变量清单与调试三板斧
工程设计方法论
把确定性从模型手里拿回来
第6章 海纳百川:MCP
从 M×N 到 M+N:标准化的力量
M 乘 N 变 M 加 N 的那笔账
架构:客户端-服务器与 JSON-RPC
客户端-服务器加 JSON-RPC 三种…
传输方式:连接的 3 种形态
标准输入输出、SSE、HTTP 三种连接
配置详解:从 CLI 到配置文件
命令行、配置文件、作用域三层配置
实战一:连接数据库
只读账号加表白名单
实战二:构建自定义 MCP 服务器
把自家接口包成 MCP 服务器
常用 MCP 服务器生态
官方与第三方,谁能直接用
安全机制:信任的边界
三层纵深,信任要有边界
MCP+Skills:厨房与菜谱
厨房与菜谱:能力与做法分开
企业级部署
内网、鉴权、审计三件事
调试与故障排除
工具输出最吃 token,先查它
第7章 无为而治:Headless 模式与 CI/CD 集成
从人机交互到无人值守:一次关键的架构演进
一次 prompt 换一次运行,没有来回
核心参数体系:4 个维度的控制
输出、成本、权限、执行四维参数
Unix 管道:将 Claude 融入命令行工作流
标准输入输出就是接口
实战一:GitHub Actions 自动代码审查
官方 Action 与裸调 CLI 的取…
实战二:多阶段 CI 管道
拆成多阶段,省的是重复读上下文
流式输出:实时监控长耗时任务
不流式就没法监工
会话管理:跨步骤维持上下文
多步之间靠会话号续上下文
CI 环境配置:生产级清单
密钥、并发、超时、模板四件套
跨平台 CI/CD 集成
GitLab、Jenkins、本地脚本三…
安全原则与最佳实践
最小权限、密钥、隔离、成本、审计
从 CLI 到 Agent SDK:Headless 模式的编程接口
命令行与 SDK 是同一件事两种写法
渐进式落地策略
先只读后写入,先建议后执行
第8章 器以载道:Agent SDK 智能体开发套件
Agent SDK 的定位:从工具到构造
从调用工具到搭一个会干活的程序
核心 API:query 函数
一个异步生成器吐完整个回合
消息类型:解读 Claude 的输出流
四种消息读懂一轮到底发生了什么
ClaudeAgentOptions:精细的行为控制
权限模式与工具匹配规则
会话管理:跨调用的上下文延续
会话号续接与会话分叉
自定义工具:扩展 Claude 的能力边界
装饰器定义、注册启用、参数校验
Agent SDK 中的 Hooks:程序化的拦截
拦截点搬进代码里
4 道安全防线
权限、工具、沙箱、审计四道防线
结构化输出:强制 JSON Schema
用 schema 把输出钉成结构
实战:构建代码分析 Web 服务
把前面所有零件拼成一个服务
Agent SDK 与 Headless CLI:如何选型
按要不要进程内控制来选
第9章 集腋成裘:Plugins 生态
Plugins 的定位:能力的封装与分发
把一整套能力打成可分发的包
Plugin 的物理结构
一份清单加四个组件目录
安装与生命周期管理
装、更、改、卸四个动作
命名空间:多 Plugin 共存
冲突靠命名空间隔开
实战:构建团队能力包
从零打一个团队能力包
私有市场与企业级管理
私有市场就是一份索引清单
Plugin 设计原则
单一职责到文档齐全
何时将能力打包为 Plugin
什么时候值得打包
LSP 支持与未来演进
语言服务给模型位置感