Claude Code实战 Harness工程之道

前言
第1章 登高望远：Claude Code技术架构全景 1
1.1 从命令行助手到Agent框架 2
1.2 四层架构模型 4
1.2.1 记忆层——CLAUDE.md 6
1.2.2 扩展层——四大组件 8
· · · · · · (更多)

前言
第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
· · · · · · (收起)