how-claude-code-works

深入解析 Claude Code 源码架构：一份填补空白的工程地图

一个 50 万行代码的阅读难题

Claude Code 是目前使用最广泛的 AI 编程 Agent，也是许多开发者公认的"最好用的 AI 编程工具"。它能理解整个代码仓库、自主执行多步编程任务、安全地运行 Shell 命令——这些强大能力背后，是 Anthropic 团队多年积累的工程智慧。

然而，Claude Code 的源码并不开源。社区面对的是一个黑盒：使用体验出色，但内部如何实现，几乎无从得知。直到这个项目的出现。

how-claude-code-works 由作者 Windy3f3f3f3f 发起，联合 Claude Code 本身共同"加班"，从源码中提炼出 15 篇专题文档，覆盖了从核心 Agent 循环到安全防护的每一个关键设计决策。不管你是想造自己的 AI Agent，还是想更深入理解 Claude Code，这套文档都是目前最系统的参考资料。

图1：Claude Code 系统架构全景（来源：项目文档）

---

Claude Code 的三级范式跃迁

在深入架构之前，理解 Claude Code 的定位至关重要。项目文档将 AI 辅助编程划分为三级范式：

第一级：代码补全（如 GitHub Copilot）。模型基于局部上下文预测下一行代码，本质是单次预测问题。用户是驾驶员，模型只是副驾。

第二级：IDE 聊天助手（如 Cursor Chat）。用户用自然语言描述需求，模型生成代码片段或修改建议。但关键限制是：模型不能执行操作——它生成 diff，由用户决定是否 apply，无法自行验证。

第三级：自主 Agent（Claude Code）。模型不仅能生成代码，还能自主执行操作（读写文件、运行命令、搜索代码），形成完整的"思考—行动—验证"闭环。用户退居"监督者"角色。

Claude Code 正是第三级范式的标杆实现。

---

核心架构：双层生成器 + 受控工具循环

项目的核心贡献之一是对 Claude Code 内部架构的系统梳理。根据文档，Claude Code 采用双层生成器架构，核心是 QueryEngine（会话管理层）和 query()（查询执行层）的清晰分离：

• QueryEngine 负责会话管理，接收用户输入，管理上下文状态，控制整个查询的生命周期。
• query() 函数是 Agent Loop 的主体，执行"消息规范化 → API 流式调用 → 工具解析 → 执行 → 结果注入 → 判断继续/终止"的循环，直到模型决定不再调用工具。

这套设计将"会话管理"和"单次查询执行"解耦，职责边界清晰，便于独立测试和演进。

上下文工程是另一个被文档重点着墨的主题。Claude Code 的每次 API 请求，光系统提示词和工具定义就可能占 50-100K token，而真实的编码会话产生的原始文本轻松超过 100 万 token。Claude Code 依赖服务端的前缀缓存（Prefix Caching）来降低成本，但这有一个残酷约束：前缀必须字节级完全一致才能命中缓存。任何字节的变化——换一个请求头、改一个工具的顺序——都会导致整个缓存失效。这使得上下文工程变成一种"带着镣铐跳舞"的设计艺术。

---

工具系统：66+ 内置工具的统一编排

Claude Code 的所有能力——文件读写、Shell 命令、代码搜索、子 Agent 派生、MCP 外部服务调用——都通过统一的工具系统暴露给模型。模型不直接操作文件系统或网络，而是通过调用工具完成一切副作用操作。

文档将这套工具系统分为三层架构：

• 设计层：Tool 泛型接口，定义每个工具的执行逻辑、输入 Schema、安全语义标记（只读/破坏性/并发安全）、权限检查和 UI 渲染。
• 组装层：getAllBaseTools() → getTools() → assembleToolPool()，从编译时裁剪到运行时过滤，将内置工具和 MCP 工具合并为统一工具池。
• 执行层：StreamingToolExecutor，在模型流式输出的同时并发执行工具，处理权限检查、Hook 回调和结果格式化。

这种设计让新增工具只需实现 Tool 接口，无需修改执行流水线或权限系统。安全语义编码为接口方法而非外部配置，确保安全属性与工具实现始终同步。

---

Hook 扩展：27 种事件的插件化机制

Claude Code 提供了一套强大的 Hook 扩展机制，允许用户在不修改源码的前提下，向 Agent Loop 的关键生命周期节点注入自定义逻辑。

项目文档记录了 27 种 Hook 事件，覆盖命令执行、提示词注入、Agent 派生、HTTP 请求等各个阶段。Hook 支持 4 种可配置类型（Command/Prompt/Agent/HTTP）和 2 种编程式类型（Callback/Function），并通过 Matcher 匹配器和 Stop Hook 实现精细的条件控制。

典型用法包括：每次 git push 前自动运行 lint 检查；每次编辑文件后在后台运行测试；将所有工具调用发送到公司审计系统。这套机制与 Git Hooks、Webpack Plugins 的设计理念一脉相承，但面对的问题更复杂——需要处理权限控制、异步长任务、多 Agent 协调等场景。

---

多 Agent 架构：三种协作模式

文档还梳理了 Claude Code 支持的三种多 Agent 协作模式：

1. 子 Agent（AgentTool）：父 Agent 派生子 Agent 执行特定任务，结果返回父 Agent，适合任务分解。
2. 协调器模式（Coordinator）：一个 Agent 只负责分配任务，派生多个 Worker 并行执行，汇总结果，适合大规模并行处理。
3. Swarm 团队模式：多个 Agent 通过信箱通信（mailbox）直接通信，形成去中心化的协作网络，适合复杂的多方协作场景。

---

配套项目：从理解到实现

项目还提供了配套项目 Claude Code From Scratch，约 4000 行 TypeScript 或 Python 双版本，11 章分步教程，从零构建自己的 Claude Code。这意味着读者不仅能理解 Claude Code 的设计思路，还能动手实践，将知识转化为可运行的代码。

---

部署与使用

本项目是一个静态文档站点，使用 docsify 框架构建，无需编译或服务器端渲染。部署极为简单：

• GitHub Pages：Fork 项目后，在仓库 Settings 中启用 GitHub Pages，选择 main 分支的 root 即可，约 1 分钟完成。
• Vercel / Cloudflare Pages：连接 GitHub 仓库后自动部署，支持自定义域名。
• 本地预览：克隆后运行 npx docsify-cli serve . 即可本地浏览。

硬件需求为零，无需 GPU，无需特殊配置，是真正零门槛的知识获取项目。

图2：项目配套的开发者讨论社区

---

局限与思考

项目本身也有一些值得注意的局限：

• 文档而非源码：本项目是对 Claude Code 的逆向分析和文档化，并非源码本身，细节可能因版本迭代而有所出入。
• 没有可运行的代码：这是一个静态文档项目，不是一个可运行的代码库或工具包，无法直接集成到工作流中。
• 依赖英文阅读能力：虽然提供了中文翻译，但核心技术术语和部分内容仍以英文为主。

---

行业意义

在 AI Agent 赛道竞争日益激烈的当下，Claude Code 的工程实践代表了一种值得深入研究的设计范式。how-claude-code-works 的价值不仅在于它提供了多少技术细节，更在于它示范了一种通过 AI 辅助来理解 AI 的方法论——作者借助 Claude Code 本身来分析和解读 Claude Code，这种"用工具理解工具"的循环本身就耐人寻味。

对于 AI 爱好者，这是了解当前最先进 AI 编程工具内部机制的最佳入口；对于 AI 开发者，这是学习 Agent 系统设计、上下文工程、工具编排的最佳教科书。