以 Claude Code CLI 源码（~1900 文件，512K+ 行）为案例，讲解生产级 AI Agent 的设计与实现。 教程使用伪代码表达，不绑定特定语言。

读者画像: 有编程经验，了解 LLM API 基础用法，想系统理解 Agent 系统的设计。

三个层级的读者都能从这份教程中获得价值：

• 初级：关注每章开头的概念介绍和代码块后的分点总结，理解 AI Agent 的核心概念和基本设计模式。不懂源码也能读懂教程的主干内容
• 中级：关注"实现备注"段落和每章末尾的"源码导读"表格，理解生产级 Agent 的具体实现方式，可对照 Claude Code 源码深入学习
• 高级：关注各章的"设计权衡"和"最佳实践与反模式"段落，理解不同设计方案的取舍、批判性视角，以及选择当前方案的具体原因

配合源码阅读：本教程配合 Claude Code 源码 阅读效果最佳。每章"源码导读"表格列出了关键文件和行号，克隆仓库后可直接定位。

理解这五个原则比记住具体实现更有价值。它们在源码中反复出现，是架构决策背后的真正驱动力。

未声明的属性默认取最安全的值。

buildTool 工厂函数的安全属性默认为 isConcurrencySafe=false, isReadOnly=false。一个新工具如果忘记声明这些属性，系统把它当作"不安全、有写操作"处理——这比默认信任更安全，代价是可能降低执行效率。在未知状态下，选择安全而非便利。

出现章节：第 2 章，第 6 章

多层策略从轻到重，不一次性崩溃。

上下文压缩有五层策略，从无损（磁盘持久化）到低损（移除过期内容）到有损（LLM 摘要）逐步升级。安全检查从正则到 AST 到语义分析层层叠加。每一层都有局限，多层叠加才有效。

出现章节：第 3 章，第 6 章

等待期间持续输出状态，而非阻塞。

withRetry 是 AsyncGenerator，在等待重试的间隙 yield 心跳消息——用户界面可以显示"正在重试..."，CI 环境不会超时终止。这不只是用户体验优化，它解决了分布式系统中的一个真实问题。

出现章节：第 1 章，第 5 章

API 调用的经济账影响架构决策。

User Context（CLAUDE.md 内容）放在 messages 而非 system prompt 中，是为了让 ~200KB 的 system prompt 被跨用户缓存。子 Agent 与父 Agent 使用相同的 system_prompt/tools/model，是为了 prompt cache 命中，把 O(N) 的成本变为 O(1)。

出现章节：第 4 章，第 7 章

安全需要隔离，性能需要共享，关键是划对边界。

子 Agent 共享 system_prompt/tools/model（cache 命中），但隔离 abort_controller/file_state_cache（独立取消和读写追踪）。把 abort_controller 误放入"共享"，取消一个子 Agent 会取消所有；把 tools 误放入"隔离"，cache 立刻失效。

出现章节：第 7 章

序章（问题）
    ↓
第 1 章：循环是基础
    ↓
第 2 章：工具是循环的执行单元
    ↓
第 3 章：上下文是工具运行的环境约束
    ↓
第 4 章：Prompt 塑造上下文
    ↓
第 5 章：流式和容错保障系统在真实环境中可靠运行
    ↓
第 6 章：安全保障系统在不受信任的环境中运行
    ↓
第 7 章：多 Agent 应对更复杂的场景
    ↓
第 8 章：扩展性与未覆盖的前沿方向
    ↓
尾声（路线图）

每一章都回答一个具体问题，解决前一章遗留的限制。