本书系统介绍了Claude Code的技术架构与工程化实践。全书从“软件工程”视角，解析了从命令行助手到可编程Agent的演进路径，并围绕Claude Code的四层架构模型展开，深入探讨了记忆系统（CLAUDE.md）、技能（Skills）、子智能体（SubAgents）、事件钩子（Hooks）与MCP等核心机制的设计哲学与协同原理。书中不仅提供了翔实的技术选型指南、组件配置方法和触发机制对比，更通过大量实战案例，展示了如何构建*、*、可维护的AI辅助编程工作流，涵盖从个人开发到团队协作，再到与CI/CD流水线集成的企业级部署全流程。

本书适合具备一定编程基础，并希望将Claude Code深度集成*日常开发与团队流程中的*、全栈工程师和技术团队负责人等阅读。

黄佳，笔名咖哥，新加坡科研机构AI研究员，深耕大模型、Agent系统及工程化应用领域。

技术作者、工程化思考者，专注于将复杂的AI能力转化为可设计、可复用、可交付的系统架构。

著有《Agent 设计模式 图解可复用智能体架构》《大模型应用开发 RAG 实战课》《大模型应用开发 动手做 AI Agent》等多部技术图书。

目前聚焦于Agent设计模式、MCP/A2A协议与Agent Skills的工程化构建，致力于推动AI从“能力展示”迈向“工程系统化”实践。

目录

前言

第 1章 登高望远：Claude Code技术架构全景 1

1.1 从命令行助手到Agent框架 2

1.2 四层架构模型 4

1.2.1 记忆层——CLAUDE.md 6

1.2.2 扩展层——四大组件 8

1.2.3 集成层——连接外部世界 11

1.2.4 编程层——Agent SDK 13

1.2.5 底层视角：Harness与Agentic Loop 15

1.3 组件关系与协作 17

1.3.1 触发机制对比 17

1.3.2 数据流：一个请求的旅程 18

1.3.3 Plugins：组合的打包与分发 20

1.4 技术选型指南 21

本章小结 23

思考题 24

第 2章 温故知新：记忆系统工程实践 25

2.1 为什么AI需要“记忆” 26

2.2 五层记忆体系 28

2.3 CLAUDE.md写作范式 32

2.4 条件化规则系统 38

2.5 实战：3种典型项目配置 40

2.5.1 React前端项目配置 41

2.5.2 Node.js后端项目配置 42

2.5.3 Python数据项目配置 43

本章小结 44

思考题 46

第3章 授人以渔：Skills工程实践 47

3.1 从CLAUDE.md到Skills：知识的两个维度 48

3.2 解剖一个Skill：骨骼与纹理 50

3.2.1 目录结构 51

3.2.2 YAML前置元数据：Skill的“身份证” 52

3.3 渐进式披露：知识的*率 54

3.3.1 图书馆模型 55

3.3.2 description的预算机制 56

3.4 触发机制：Claude Code如何抉择Skills的调用 58

3.4.1 双通道*机制 58

3.4.2 description——Skills的灵魂 59

3.4.3 防止过触发与欠触发 61

3.4.4 参考型Skill与任务型Skill：两种Skill哲学 62

3.5 SKILL.md正文：是路由器，不是仓库 64

3.5.1 路由器思维 64

3.5.2 契约式引用 65

3.5.3 500行法则 66

3.6 allowed-tools：知识约束行动 66

3.6.1 权限设计模板 67

3.6.2 Bash的精细控制语法 67

3.7 参数传递与动态注入 69

3.7.1 $ARGUMENTS和位置参数 69

3.7.2 动态上下文注入 70

3.8 作用域与优先级 71

3.9 实战：从*构建3类Skill 72

3.9.1 参考型Skill：代码审查 73

3.9.2 任务型 Skill：智能提交 75

3.9.3 复合型Skill：财务分析（渐进式披露完整案例） 77

3.10 Skills的4种设计模式 80

3.11 测试与迭代 81

3.12 从软件工程看Skills 82

本章小结 84

思考题 85

第4章 分而治之：子智能体与任务委派的艺术 86

4.1 上下文窗口的困境 87

4.2 子智能体的本质 88

4.3 子智能体的定义与配置 91

4.4 5种子智能体模式 96

4.4.1 只读型：*的观察者 96

4.4.2 执行型：高噪声任务处理器 97

4.4.3 并行型：多*工作流 98

4.4.4 流水线型：串行处理链 100

4.4.5 团队型：自组织协作机制 105

4.5 子智能体与Skills的协作 108

4.6 Token经济学 114

4.7 从软件工程看子智能体 117

4.8 实战注意事项 119

本章小结 121

思考题 122

第5章 防微杜渐：Hooks事件驱动自动化 123

5.1 Hooks在Claude扩展体系中的定位 124

5.2 事件生命周期：17个事件 125

5.2.1 会话级事件 125

5.2.2 工具调用事件 126

5.2.3 子智能体事件 128

5.2.4 完成事件 128

5.2.5 较新的事件类型 129

5.2.6 “能否阻止”：*关键的维度 129

5.3 配置体系：6个位置，6种用途 130

5.4 3种处理器类型：确定性的阶梯 132

5.4.1 command类型：确定性规则 132

5.4.2 prompt类型：单次大模型评估 133

5.4.3 agent类型：多轮子智能体验证 133

5.5 hookSpeci.cOutput：与Claude交流的协议 134

5.6 工程实战一：*防护体系 136

5.6.1 PreToolUse：危险命令拦截 136

5.6.2 PreToolUse：敏感文件保护 137

5.6.3 PostToolUse：全量操作审计 140

5.6.4 完整配置 140

5.7 工程实战二：代码质量自动化 141

5.7.1 PostToolUse：自动格式化 141

5.7.2 PostToolUse：Lint反馈循环 143

5.7.3 Stop Hook：测试质量门控 144

5.8 子智能体Hooks：*的上下文管理 146

5.8.1 全局与Frontmatter：精度问题 146

5.8.2 SubagentStart：自动注入上下文 147

5.8.3 SubagentStop：验证输出质量 148

5.9 异步Hooks：后台执行不阻塞 149

5.10 环境变量与调试 150

5.10.1 Hooks可用的环境变量 150

5.10.2 调试“三板斧” 150

5.10.3 常见陷阱 151

5.11 工程设计方法论 151

本章小结 152

思考题 154

第6章 海纳百川：MCP 155

6.1 从M×N到M+N：标准化的力量 156

6.2 架构：客户端–服务器与JSON-RPC 157

6.3 传输方式：连接的3种形态 159

6.4 配置详解：从CLI到配置文件 160

6.4.1 CLI快速配置 160

6.4.2 .mcp.json 配置文件 160

6.4.3 配置文件的位置与作用域 161

6.5 实战一：连接数据库 162

6.6 实战二：构建自定义MCP服务器 163

6.7 常用MCP服务器生态 167

6.7.1 官方MCP服务器 167

6.7.2 热门第三方MCP服务器 167

6.7.3 实用配置组合 168

6.8 *机制：信任的边界 169

6.8.1 三层纵深*机制 169

6.8.2 *风险与防护 170

6.9 MCP+Skills：厨房与菜谱 171

6.10 企业级部署 172

6.11 调试与故障排除 173

6.11.1 常用调试手段 173

6.11.2 MCP工具输出的Token管理 173

6.11.3 常见问题 174

本章小结 174

思考题 175

第7章 无为而治：Headless模式与CI/CD集成 176

7.1 从人机交互到无人值守：一次关键的架构演进 177

7.2 核心参数体系：4个维度的控制 178

7.2.1 输出格式控制 179

7.2.2 成本护栏 181

7.2.3 *边界：工具权限 182

7.2.4 执行控制：模型、Prompt、结构化输出 183

7.3 Unix管道：将Claude融入命令行工作流 185

7.4 实战一：GitHub Actions自动代码审查 186

7.4.1 采用官方Action 187

7.4.2 直接调用CLI 189

7.5 实战二：多阶段CI管道 192

7.6 流式输出：实时监控长耗时任务 194

7.7 会话管理：跨步骤维持上下文 196

7.8 CI 环境配置：生产级清单 197

7.8.1 *须设置的环境变量 197

7.8.2 性能调优参数 198

7.8.3 GitHub Actions中的完整配置模板 198

7.8.4 MCP服务器在CI中的配置 199

7.9 跨平台CI/CD集成 199

7.9.1 GitLab CI/CD配置 200

7.9.2 JenkinsPipeline集成配置 200

7.9.3 本地自动化脚本 201

7.10 *原则与*实践 203

7.10.1 *小权限原则 203

7.10.2 Secrets管理 204

7.10.3 容器隔离 204

7.10.4 成本防护 205

7.10.5 审计日志 205

7.11 从CLI到Agent SDK：Headless模式的编程接口 206

7.12 渐进式落地策略 208

本章小结 209

思考题 210

第8章 器以载道：Agent SDK智能体开发套件211

8.1 Agent SDK的定位：从工具到组件 211

8.2 核心API：query函数 212

8.2.1 Python版本 213

8.2.2 TypeScript版本 213

8.3 消息类型：解读Claude的输出流 214

8.3.1 system/init——会话初始化 215

8.3.2 assistant——Claude的响应 215

8.3.3 user——工具执行结果 216

8.3.4 result——任务完成 216

8.4 ClaudeAgentOptions：精细的行为控制 218

8.4.1 权限模式详解 219

8.4.2 工具权限的模式匹配 220

8.5 会话管理：跨调用的上下文延续 221

8.5.1 基于session_id的会话延续 221

8.5.2 会话分叉 222

8.6 自定义工具：扩展Claude的能力边界 223

8.6.1 使用@tool装饰器定义工具 223

8.6.2 在Agent配置中注册并启用自定义工具 225

8.6.3 使用Pydantic模型进行参数验证 225

8.7 Agent SDK中的Hooks：程序化的拦截 226

8.7.1 PreToolUse：执行前拦截 227

8.7.2 PostToolUse：执行后处理 228

8.7.3 Agent SDK Hooks与Shell Hooks的关系 230

8.8 4道*防线 231

8.9 结构化输出：强制JSON Schema 233

8.10 实战：构建代码分析Web服务 235

8.11 Agent SDK与Headless CLI：如何选型 238

本章小结 239

思考题 240

第9章 集腋成裘：Plugins生态 241

9.1 Plugins的定位：能力的封装与分发 242

9.2 Plugin的物理结构 243

9.2.1 plugin.json：Plugin的身份证 244

9.2.2 组件的具体格式 245

9.3 安装与生命周期管理 248

9.3.1 安装来源 248

9.3.2 日常管理 249

9.3.3 本地开发与测试 249

9.3.4 存储位置 249

9.4 命名空间：多Plugin共存 249

9.5 实战：构建团队能力包 250

9.5.1 完整目录结构 250

9.5.2 plugin.json 251

9.5.3 *扫描子智能体 251

9.5.4 Hooks：*检查脚本 252

9.5.5 发布流程 253

9.6 私有市场与企业管理 253

9.6.1 构建私有市场 253

9.6.2 使用私有市场 254

9.6.3 组织级Plugin管理 255

9.7 Plugin设计原则 255

9.7.1 单一职责 255

9.7.2 渐进式迭代 255

9.7.3 *小权限 256

9.7.4 文档是*需品 256

9.8 何时将能力打包为Plugin 257

9.9 LSP支持与未来演进 258

本章小结 258

思考题 259

第 10章 炉火纯青：工程化实战——从个人到团队 260

10.1 成本控制：让Token为你工作，而不是烧钱 261

10.1.1 理解定价结构 261

10.1.2 模型选择策略 262

10.1.3 上下文管理是成本控制的核心 263

10.1.4 Prompt缓存 263

10.1.5 成本监控 264

10.2 调试：打开黑盒 265

10.2.1 --debug模式：执行过程的“X光” 266

10.2.2 stream-json：实时透视“思考流” 267

10.2.3 PostToolUse Hook：构建持久化审计日志 267

10.2.4 会话存档与断点调试 268

10.2.5 Claude异常行为的诊断思路 269

10.3 *准则：*小权限是底线 270

10.3.1 权限模式：第 一道防线 270

10.3.2 工具权限：精细化控制 271

10.3.3 .claudeignore与文件访问控制 272

10.3.4 Hook*扫描 273

10.3.5 MCP服务器的信任评估 273

10.3.6 API 密钥的生命周期管理 274

10.4 大型代码库：在有限上下文窗口中驾驭百万行代码 275

10.4.1 层次化CLAUDE.md 275

10.4.2 引导搜索，而非全量阅读 277

10.4.3 子智能体：构建模块化的上下文边界 277

10.4.4 上下文压缩与精细化管理 278

10.5 指令：写好CLAUDE.md与Prompt 279

10.5.1 CLAUDE.md编写原则 279

10.5.2 *表达技巧 280

10.5.3 分步确认 280

10.6 团队落地：从个人到组织的跃迁 281

10.6.1 共享配置：团队统一的基石 281

10.6.2 CLAUDE.md的治理规范 282

10.6.3 组织级策略管理 283

10.6.4 渐进式能力建设路线图 284

10.6.5 新人Claude Code培训计划 284

10.7 SDD生态与工作流的融合 285

10.7.1 SDD四层生态架构 286

10.7.2 工作流推荐组合方案 287

10.8 全局视图：8种核心机制的协奏 288

本章小结 289

思考题 291

后记 庖丁解牛，游刃有余292