Claude Code实战:Harness工程之道电子书

版 权

内 容 提 要

前 言

资源与支持

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

1.1 从命令行助手到Agent框架

1.2 四层架构模型

1.2.1 记忆层——CLAUDE.md

1.2.2 扩展层——四大组件

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

1.2.4 编程层——Agent SDK

1.2.5 底层视角：Harness与Agentic Loop

1.3 组件关系与协作

1.3.1 触发机制对比

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

1.3.3 Plugins：组合的打包与分发

1.4 技术选型指南

本章小结

思考题

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

2.1 为什么AI需要“记忆”

2.2 五层记忆体系

2.3 CLAUDE.md写作范式

2.4 条件化规则系统

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

2.5.1 React前端项目配置

2.5.2 Node.js后端项目配置

2.5.3 Python数据项目配置

本章小结

思考题

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

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

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

3.2.1 目录结构

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

3.3 渐进式披露：知识的投资回报率

3.3.1 图书馆模型

3.3.2 description的预算机制

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

3.4.1 双通道激活机制

3.4.2 description——Skills的灵魂

3.4.3 防止过触发与欠触发

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

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

3.5.1 路由器思维

3.5.2 契约式引用

3.5.3 500行法则

3.6 allowed-tools：知识约束行动

3.6.1 权限设计模板

3.6.2 Bash的精细控制语法

3.7 参数传递与动态注入

3.7.1 $ARGUMENTS和位置参数

3.7.2 动态上下文注入

3.8 作用域与优先级

3.9 实战：从零构建3类Skill

3.9.1 参考型Skill：代码审查

3.9.2 任务型 Skill：智能提交

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

3.10 Skills的4种设计模式

3.11 测试与迭代

3.12 从软件工程看Skills

本章小结

思考题

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

4.1 上下文窗口的困境

4.2 子智能体的本质

4.3 子智能体的定义与配置

4.4 5种子智能体模式

4.4.1 只读型：安全的观察者

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

4.4.3 并行型：多专家工作流

4.4.4 流水线型：串行处理链

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

4.5 子智能体与Skills的协作

4.6 Token经济学

4.7 从软件工程看子智能体

4.8 实战注意事项

本章小结

思考题

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

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

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

5.2.1 会话级事件

5.2.2 工具调用事件

5.2.3 子智能体事件

5.2.4 完成事件

5.2.5 较新的事件类型

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

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

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

5.4.1 command类型：确定性规则

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

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

5.5 hookSpecificOutput：与Claude交流的协议

5.6 工程实战一：安全防护体系

5.6.1 PreToolUse：危险命令拦截

5.6.2 PreToolUse：敏感文件保护

5.6.3 PostToolUse：全量操作审计

5.6.4 完整配置

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

5.7.1 PostToolUse：自动格式化

5.7.2 PostToolUse：Lint反馈循环

5.7.3 Stop Hook：测试质量门控

5.8 子智能体Hooks：精准的上下文管理

5.8.1 全局与Frontmatter：精度问题

5.8.2 SubagentStart：自动注入上下文

5.8.3 SubagentStop：验证输出质量

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

5.10 环境变量与调试

5.10.1 Hooks可用的环境变量

5.10.2 调试“三板斧”

5.10.3 常见陷阱

5.11 工程设计方法论

本章小结

思考题

第6章 海纳百川：MCP

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

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

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

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

6.4.1 CLI快速配置

6.4.2 .mcp.json 配置文件

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

6.5 实战一：连接数据库

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

6.7 常用MCP服务器生态

6.7.1 官方MCP服务器

6.7.2 热门第三方MCP服务器

6.7.3 实用配置组合

6.8 安全机制：信任的边界

6.8.1 三层纵深安全机制

6.8.2 安全风险与防护

6.9 MCP+Skills：厨房与菜谱

6.10 企业级部署

6.11 调试与故障排除

6.11.1 常用调试手段

6.11.2 MCP工具输出的Token管理

6.11.3 常见问题

本章小结

思考题

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

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

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

7.2.1 输出格式控制

7.2.2 成本护栏

7.2.3 安全边界：工具权限

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

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

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

7.4.1 采用官方Action

7.4.2 直接调用CLI

7.5 实战二：多阶段CI管道

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

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

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

7.8.1 必须设置的环境变量

7.8.2 性能调优参数

7.8.3 GitHub Actions中的完整配置模板

7.8.4 MCP服务器在CI中的配置

7.9 跨平台CI/CD集成

7.9.1 GitLab CI/CD配置

7.9.2 JenkinsPipeline集成配置

7.9.3 本地自动化脚本

7.10 安全原则与最佳实践

7.10.1 最小权限原则

7.10.2 Secrets管理

7.10.3 容器隔离

7.10.4 成本防护

7.10.5 审计日志

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

7.12 渐进式落地策略

本章小结

思考题

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

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

8.2 核心API：query函数

8.2.1 Python版本

8.2.2 TypeScript版本

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

8.3.1 system/init——会话初始化

8.3.2 assistant——Claude的响应

8.3.3 user——工具执行结果

8.3.4 result——任务完成

8.4 ClaudeAgentOptions：精细的行为控制

8.4.1 权限模式详解

8.4.2 工具权限的模式匹配

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

8.5.1 基于session_id的会话延续

8.5.2 会话分叉

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

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

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

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

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

8.7.1 PreToolUse：执行前拦截

8.7.2 PostToolUse：执行后处理

8.7.3 Agent SDK Hooks与Shell Hooks的关系

8.8 4道安全防线

8.9 结构化输出：强制JSON Schema

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

8.11 Agent SDK与Headless CLI：如何选型

本章小结

思考题

第9章 集腋成裘：Plugins生态

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

9.2 Plugin的物理结构

9.2.1 plugin.json：Plugin的“身份证”

9.2.2 组件的具体格式

9.3 安装与生命周期管理

9.3.1 安装来源

9.3.2 日常管理

9.3.3 本地开发与测试

9.3.4 存储位置

9.4 命名空间：多Plugin共存

9.5 实战：构建团队能力包

9.5.1 完整目录结构

9.5.2 plugin.json

9.5.3 安全扫描子智能体

9.5.4 Hooks：安全检查脚本

9.5.5 发布流程

9.6 私有市场与企业管理

9.6.1 构建私有市场

9.6.2 使用私有市场

9.6.3 组织级Plugin管理

9.7 Plugin设计原则

9.7.1 单一职责

9.7.2 渐进式迭代

9.7.3 最小权限

9.7.4 文档是必需品

9.8 何时将能力打包为Plugin

9.9 LSP支持与未来演进

本章小结

思考题

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

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

10.1.1 理解定价结构

10.1.2 模型选择策略

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

10.1.4 Prompt缓存

10.1.5 成本监控

10.2 调试：打开黑盒

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

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

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

10.2.4 会话存档与断点调试

10.2.5 Claude异常行为的诊断思路

10.3 安全准则：最小权限是底线

10.3.1 权限模式：第一道防线

10.3.2 工具权限：精细化控制

10.3.3 .claudeignore与文件访问控制

10.3.4 Hook安全扫描

10.3.5 MCP服务器的信任评估

10.3.6 API 密钥的生命周期管理

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

10.4.1 层次化CLAUDE.md

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

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

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

10.5 指令：写好CLAUDE.md与Prompt

10.5.1 CLAUDE.md编写原则

10.5.2 精准表达技巧

10.5.3 分步确认

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

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

10.6.2 CLAUDE.md的治理规范

10.6.3 组织级策略管理

10.6.4 渐进式能力建设路线图

10.6.5 新人Claude Code培训计划

10.7 SDD生态与工作流的融合

10.7.1 SDD四层生态架构

10.7.2 工作流推荐组合方案

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

本章小结

思考题

后记 庖丁解牛，游刃有余