一组围绕 Claude Code CLI 源码展开的中文架构拆解文章。
这个仓库不是功能手册，也不是 Claude Code 的使用教程。
它更像一份持续展开的源码研究笔记，核心目标是三件事：
- 讲清楚 Claude Code 解决了哪些真实的 Agent 工程问题。
- 解释它为什么这么设计，而不是只罗列“它有什么能力”。
- 把这些设计迁移成我们自己做 Agent、Coding Agent、AI CLI、AI IDE 时可复用的工程经验。
如果你关心的是下面这些问题，这个仓库会比较对路：
- Agent 为什么一旦产品化，复杂度会突然上升
- 工具调用、权限系统、上下文压缩、会话恢复应该如何一起设计
- 复杂 CLI 为什么最后会长成一个“运行时系统”，而不只是一个命令入口
- 系列总目录：README.md
- 第 1 篇：拆开 Claude Code，我才看清 Agent 不是一个“会调模型的 CLI”
- 第 2 篇：启动链路拆解：Claude Code 为什么能在大系统里把冷启动压下来？
- 第 3 篇：QueryEngine 与 query.ts：为什么 Agent 运行时要分“会话层”和“轮次层”？
- 第 4 篇：工具系统与安全边界：Claude Code 如何把能力暴露给模型，又不让它失控？
- 第 5 篇：上下文与恢复：Claude Code 如何让长任务在压缩、中断之后仍然接得上？
| 篇次 | 文章 | 核心问题 |
|---|---|---|
| 01 | 拆开 Claude Code，我才看清 Agent 不是一个“会调模型的 CLI” | 为什么它值得逐层拆开 |
| 02 | 启动链路拆解：Claude Code 为什么能在大系统里把冷启动压下来？ | 启动优化到底在优化什么 |
| 03 | QueryEngine 与 query.ts：为什么 Agent 运行时要分“会话层”和“轮次层”？ | 为什么不能一个大循环全做完 |
| 04 | 工具系统与安全边界：Claude Code 如何把能力暴露给模型，又不让它失控？ | 工具协议与运行时治理如何一起成立 |
| 05 | 上下文与恢复：Claude Code 如何让长任务在压缩、中断之后仍然接得上？ | 长任务为什么不能只靠塞更多 prompt 来维持连续性 |
| 06 | 权限系统内核：Claude Code 如何把 trust、mode、classifier 和 approval 串成一条决策链（规划中） | 同一条工具请求为什么会经过多层判断 |
| 07 | 终端 UI 架构：Claude Code 为什么不用 readline，而要用 React 加 Ink（规划中） | 复杂 CLI 为什么会演化成终端里的前端应用 |
| 08 | Hooks、Skills、Plugins：Claude Code 怎样在可扩展和可控之间找到平衡（规划中） | 扩展系统如何既开放又不失控 |
当前这组文章围绕同一个问题展开：
当 Agent 从“能调模型的原型”走向“要长期运行的产品”时，哪些复杂度必须被工程化？
Claude Code 给出的答案包括：
- 启动编排
- 会话层与轮次层拆分
- 工具协议与调度
- 权限边界与信任模型
- 上下文压缩与恢复语义
- 终端 UI 运行时
- 受控的扩展机制
- 文章默认使用中文写作。
- 文中的源码引用会尽量附上 GitHub 可点击链接，方便对照阅读。
- 全系列文章默认将源码链接固定到具体 commit 快照，避免后续仓库更新导致引用漂移、正文分析和读者看到的代码错位。
- 每篇文章都优先回答“为什么这么设计”，而不是只做代码翻译。
- 本仓库主要用于学习、研究与架构分析。
- Claude Code 为 Anthropic 的产品名称，相关权利归原项目方所有。
- 如果文章中有理解偏差，欢迎提 Issue 或 PR 一起修正。