深入解读当前最成功的 AI 编程 Agent 的源码架构
Claude Code 是目前使用最广泛的 AI 编程 Agent，也是我认为最好用的AI编程工具（我使用Claude Code已经一年了）。它能理解整个代码仓库、自主执行多步编程任务、安全地运行命令——而这一切背后是 50 万行 TypeScript 源码中沉淀的工程智慧（可能也是另一种屎山，最近Claude Code Bug也老多了）。
Anthropic 开源（x）了这份源码。但 50 万行代码，从哪里开始读？
这也是我创建这个项目的初衷，我自己也遇到了没有办法阅读这么长的代码项目的问题，我的解决方案是和Claude Code一起读，让他给我写文档配合我读源代码。在此同时，我想把这个过程文档化，就形成了这个项目。
我和Claude Code加班从源码中提炼出 11 篇专题文档，覆盖了从核心循环到安全防护的每一个关键设计决策。不管你是想造自己的 AI Agent，还是想更深入地理解和使用 Claude Code，这里都是最短路径（应该？就算不是最短的，我也会不断更新这个项目）。
- claude-code-from-scratch — 从零实现 Claude Code 核心功能的最小化实现与分步教程（每一步实现都有源码的reference），我和Claude Code用1300行代码实现了一个minimal的Claude Code，遵循了其开源代码中的设计哲学和实现方案，但是又是最小化的。
大多数 AI Agent 框架都是"demo 级别"——跑通一个场景就宣布成功。Claude Code 不同，它是一个日活百万级开发者实际使用的生产系统，需要处理的问题远比 demo 复杂：
- 对话动辄上百万 token，上下文窗口不够用怎么办？（记忆管理、压缩方案是如何设计的超重要）
- 66 个内置工具同时存在，怎么协调？（如果所有工具上下文都给AI，那将直接爆炸）
- 怎么让用户感觉"快"，哪怕模型推理本身就要几十秒？（如何实现流水线设计）
- 用户让 AI 执行
rm -rf /，怎么拦住？（安全护栏很重要）
这些问题的解法，就藏在源码里。
以下内容均来自对源码的实际分析，不是猜测。
它其实做了三件聪明的事：
- 全链路流式输出 — 不是等模型全部想完再显示，而是每生成一个 token 就立刻展示。从 API 调用到终端渲染，整条链路都是流式的。
- 工具预执行 — 模型说"我要读某个文件"的时候，这个文件其实已经在读了。系统在模型还在输出的同时就开始解析和执行工具调用，利用模型生成的 5-30 秒窗口，把约 1 秒的工具延迟藏起来了。
- 9 阶段并行启动 — 启动时把不相关的初始化任务并行执行，关键路径压到约 235ms。
普通程序遇到错误会报错给用户。Claude Code 的策略是：能恢复的错误，用户根本看不到。
比如对话太长超出了上下文窗口，它不会弹个错误框让你手动处理，而是悄悄压缩上下文、自动重试。token 输出达到上限？自动从 4K 升级到 64K 再重试。整个 Agent 循环有 7 种不同的"继续"策略，每种对应一种故障恢复路径。
这就是为什么用 Claude Code 的时候很少遇到报错——不是没有错误，而是大部分都被内部消化了。
这是整个系统中最精妙的设计之一。当上下文快要超限时，不是一刀切地压缩，而是分 4 个级别逐步处理：
- 裁剪 — 先把历史消息中的大块内容（旧的工具输出）截断
- 去重 — 几乎零成本地去除重复内容
- 折叠 — 把不活跃的对话段落折叠起来，但不修改原始内容（可以展开恢复）
- 摘要 — 最后手段，启动一个子 Agent 对整个对话做摘要
每一级都可能释放足够的空间，让后面的级别不需要执行。而且压缩后系统会自动恢复最近编辑的 5 个文件内容，防止模型忘记刚刚在干什么。
Claude Code 让 AI 直接在你电脑上跑命令，安全设计必须过硬。它不是靠一个"你确定吗？"对话框，而是搭建了 5 层防御体系：
- 权限模式 — 不同信任级别，限制可执行的操作范围
- 规则匹配 — 基于命令模式的白名单/黑名单
- Bash 命令深度分析 — 这里最硬核：用语法树分析（不是正则匹配）拆解 Shell 命令的真实意图，包含 23 项安全检查，覆盖命令注入、环境变量泄露、特殊字符攻击等
- 用户确认 — 危险操作弹出确认对话框，但有 200ms 防抖保护，防止键盘连击导致误确认
- Hook 校验 — 允许用户自定义安全规则，甚至可以动态修改工具的输入参数（比如自动给
rm加上--dry-run）
这五层任何一层拦住就不会执行，纵深防御。
所有工具——读文件、写文件、跑命令、搜索、甚至第三方 MCP 工具——都遵循同一套接口规范。这意味着：
- 第三方工具和内置工具走完全相同的执行流水线，享受同样的安全检查和权限控制
- 只读工具自动并行执行，写操作自动串行，不需要手动管理并发
- 工具输出超过 100K 字符时自动落盘，模型只拿到摘要和文件路径，需要时再读取全文
Claude Code 支持三种多 Agent 模式：
- 子 Agent — 主 Agent 分派任务给子 Agent，等结果返回
- 协调器 — 纯指挥官模式，协调器只能分配任务，不能自己读文件、写代码，强制分工
- Swarm — 多个命名 Agent 之间点对点通信，各自独立工作
为了防止多个 Agent 同时改同一个文件产生冲突，系统用 Git Worktree 给每个 Agent 一份独立的代码副本。
graph TB
User[用户输入] --> QE[QueryEngine 会话管理]
QE --> Query[query 主循环]
Query --> API[Claude API 调用]
API --> Parse{解析响应}
Parse -->|文本| Output[流式输出]
Parse -->|工具调用| Tools[工具执行引擎]
Tools --> ReadTool[读文件]
Tools --> EditTool[编辑文件]
Tools --> ShellTool[Shell 执行]
Tools --> SearchTool[搜索工具]
Tools --> MCPTool[MCP 工具]
Tools -->|结果回注| Query
Context[上下文工程] --> Query
Context --> SysPrompt[系统提示词]
Context --> GitStatus[Git 状态]
Context --> ClaudeMD[CLAUDE.md]
Context --> Compact[压缩流水线]
Perm[权限系统] --> Tools
Perm --> Rules[规则层]
Perm --> AST[Bash AST 分析]
Perm --> Confirm[用户确认]
- 10 分钟读懂 Claude Code — 全部内容的浓缩版，适合快速了解
| # | 文档 | 你会了解到 |
|---|---|---|
| 1 | 概述 | Claude Code 解决什么问题、技术选型背后的思考、整体架构 |
| 2 | 系统主循环 | Agent 是怎么"思考-行动-观察"循环的，怎么处理中断和恢复 |
| 3 | 上下文工程 | 怎么在有限的上下文窗口里塞下最有用的信息，压缩策略的全部细节 |
| 4 | 工具系统 | 66 个工具怎么注册、调度、并发控制，怎么接入第三方工具 |
| 5 | 代码编辑策略 | 为什么选择"搜索替换"而不是"整文件重写"，怎么保证编辑安全 |
| 6 | 权限与安全 | 5 层安全体系的完整实现，Bash 命令的 23 项安全检查 |
| 7 | 用户体验设计 | 为什么用 React 写终端 UI，流式输出的实现，终端交互细节 |
| 8 | 最小必要组件 | 造一个 coding agent 最少需要哪些模块，从 500 行到 50 万行的演进路线 |
| 9 | Hooks 与可扩展性 | 23 种 Hook 事件，怎么在不改源码的前提下定制 Claude Code 的行为 |
| 10 | 多 Agent 架构 | 子 Agent、协调器、Swarm 三种模式的设计取舍 |
| 11 | 记忆与技能系统 | AI 怎么"记住"你的偏好和项目上下文，跨会话学习的实现 |
| 你是 | 你能获得 |
|---|---|
| 想做 AI Agent 产品的开发者 | 一个经过百万用户验证的架构参考，少走弯路 |
| Claude Code 用户 | 理解它为什么这样工作，学会用 Hooks 和 CLAUDE.md 深度定制 |
| 对 AI 安全感兴趣的人 | 生产级 AI 系统的安全设计实战，不是论文里的理论 |
| 学生或 AI 研究者 | 大规模工程实践的第一手材料，比任何教科书都真实 |
| 指标 | 数值 |
|---|---|
| 源码总行数 | 512,000+ |
| TypeScript 文件 | 1,884 |
| 内置工具 | 66+ |
| 压缩流水线级数 | 4 级 |
| 权限防御层数 | 5 层 |
只有 10 分钟？ → 读 快速入门
想理解核心原理？ → 按顺序读 主循环 → 上下文工程 → 工具系统
想自己造一个 AI Agent？ → 先读 最小必要组件，再去看 claude-code-from-scratch
想定制 Claude Code？ → 读 Hooks 与可扩展性 + 记忆与技能系统
欢迎提 Issue 和 PR！如果你发现分析有误或有更好的理解角度，非常欢迎讨论。
MIT