系列开篇 | Claude Code 源码架构概览：51万行代码的模块地图
Hi，大家好，欢迎来到维元码簿。
这是一个关于 Claude Code 源码学习的系列。
Claude Code 是当前业界 Coding Agent 的 SOTA 实现。能接触到这样一个工业级系统的完整源码，是难得的学习机会。所以我决定用 Coding Agent 帮我读懂 Claude Code，同时把这个学习过程完整记录下来。
51 万行代码，体量庞大。一篇长文放不下，于是有了这个系列。
作为开篇，本文的任务是画地图------不急着深入细节，而是先搞明白：
- Claude Code 是什么？有多少核心代码，多少支撑代码？
- 可以拆成哪些模块？它们如何协作？
- 学习路径是什么？从哪里开始读？
搞明白了这些，后面的学习就可以有条不紊地进行下去。
Claude Code 到底是什么？
Claude Code 到底是一个什么软件？
大多数人第一次听到 Claude Code，会说："就是一个命令行里面能写代码的 ChatGPT 嘛。"
这个理解不算错，但远远不够。让我带你一层一层地剥开它的外壳。
第一层：CLI 命令行工具（表象）
在最外层，Claude Code 确实是一个 CLI 应用------你输入 claude，它启动交互式会话。
但如果你以为它只是"命令行里能写代码的 ChatGPT"，那就错过了最重要的部分。
横向对比同类产品：Gemini CLI （Google）、Codex CLI （OpenAI）------看起来都是命令行工具。但这里的关键误区是：我们在比较"CLI"，但 CLI 就是个入口交互形态，根本不是重点。
CLI 仅仅只是它交互的产品形态的壳，真正有价值的是里面的 Coding Agent。
光看数字：101 个子命令 、389 个 React 组件------终端 UI 的复杂度堪比中型 Web 应用。
第二层：Agent 核心循环（能力）
剥开 CLI 外壳，里面是一个能自主决策的 Agent。
也许你知道 ReAct Agent 模式 （Reasoning + Acting），Claude Code 的核心也是如此------感知 → 思考 → 行动 → 观察 → 再思考...
但和普通聊天机器人不同，Claude Code 不只是"告诉你怎么做"，而是直接帮你做 。它有30+ 个内置工具：读写文件、执行 Bash、搜索代码，还能通过 MCP 协议接入外部工具。
这个循环让它从"被动的聊天机器人"变成了"主动的任务执行者"。
第三层：Agent Harness 工程（复杂性）
这是 Claude Code 最有价值的部分。
| 部分 | 代码行数 | 占比 |
|---|---|---|
| Agent 核心逻辑 | ~3,000 | < 1% |
| 工程支撑系统 | ~511,000 | > 99% |
Agent 的"大脑"只有不到 3000 行，但让它能稳定运行的"身体"占了 99%。
很多人认为 Claude Code 的能力全部来自于 Claude 模型。但当你深入理解 Harness 之后，你会发现：这是大模型能力的放大器------这部分工程工作至少贡献了一半的效果。
同样的模型，没有好的 Harness 只是玩具，有了完整的 Harness 才能变成生产级工具。想想这些实际问题：
- 对话太长怎么压缩？
- Agent 想执行
rm -rf /谁来拦截？ - API 调用失败怎么重试？
Claude Code 给出了答案：上下文系统 管理记忆，权限系统 控制安全，错误处理保障稳定。
那么，这个占 99% 代码量的"支持系统"到底包含哪些核心模块？让我们拆开看看。
盲人摸象：业界 SOTA AI Coding 软件的模块拆解
如果要我们自己实现一个工业级的 AI Coding 软件，需要搞定哪些模块？
这个问题帮助我们建立全局视角。不是漫无目的地去读代码，而是先问：如果让我来写，我会怎么组织？
带着这个问题，我结合过去做服务端系统的经验，对 Claude Code 源码做了一次"盲人摸象"式的初步阅读。摸完之后，我把这个系统拆成了 9 个一级模块，每个模块标注了优先级。
需要说明的是，这个拆分是我个人的理解，不是官方定义。Claude Code 的源码没有显式的"模块边界"，目录结构也有交叉。我是按照"职责"和"依赖关系"来划分的------同一个目录下的文件可能属于不同模块，同一模块的代码也可能散落在多处。
但这个拆分对我很有帮助，它让 51 万行代码从"一团乱麻"变成了"几个相对独立的命题"。下面三个问题会逐一展开：
- 问题一：这 9 个模块分别是什么？如何协作？
- 问题二：每个模块在代码里对应哪些目录？体量多大？
- 问题三：应该按什么顺序学习？
问题一：这个系统有哪些模块？
99% 的代码在做"支撑"。但"支撑"不是一个模糊的大筐子，它有具体的结构，每个模块之间也有明确的协作关系。
| 模块 | 优先级 | 占比 |
|---|---|---|
| Agent 执行内核 | P0 | 1.6% |
| 上下文系统 | P0--P1 | 5.6% |
| 工具与扩展系统 | P0--P2 | 17.3% |
| 控制面与安全 | P1--P2 | 11.5% |
| 模型与云服务 | P1--P3 | 4.2% |
| 产品外壳与交互 | P2 | 35.9% |
| 多 Agent 协作 | P3 | 3.7% |
| 远程与非 CLI 形态 | P3 | 3.2% |
| 基础设施与底座 | P4 | 17.0% |
P0 = 内核运转 · P1 = 能力边界 · P2 = 产品化 · P3，P4 = 扩展底座
各模块的二级话题：
- Agent 执行内核：query.ts 主循环结构 · turn-by-turn 执行逻辑 · 停止条件判断 · QueryEngine.ts 消息管理与流式输出
- 上下文系统：System Prompt 注入 · 会话记忆管理（memdir / MEMORY.md）· 上下文压缩（microcompact / contextCollapse / autocompact）
- 工具与扩展系统：工具注册与发现（30+ 内置工具 + MCP 接入）· 并发调度（只读并行 / 写操作串行）· MCP 协议实现
- 控制面与安全：权限模型（allow / deny / confirm 三级决策）· Feature Gate 灰度机制
- 模型与云服务：Claude API 调用 · 流式响应处理 · 模型选择与降级策略
- 产品外壳与交互：CLI 命令行（101 子命令）· React 终端 UI（389 组件）· 命令 / 钩子 / 主题系统
- 多 Agent 协作：AgentTool 子任务分发 · swarm 编排
- 远程与非 CLI 形态：Bridge 协议 · VSCode / IDE 集成 · 远程控制
- 基础设施与底座：通用工具函数 · 类型定义 · 原生模块绑定
这 9 个模块在一次请求中是如何协作的？
执行链路拆解：
① 输入入口 → 产品外壳与交互
CLI 接收用户指令，解析参数，启动主循环
② 安全检查 → 控制面与安全
权限校验、Feature Gate 检查、危险操作拦截
③ 上下文拼装 → 上下文系统
System Prompt 注入 → 历史会话加载 → 微压缩合并冗余消息 → 上下文折叠（可选） → 自动压缩（超限时生成摘要）
④ 模型调用 → 模型与云服务
调用 Claude API，流式返回响应（文本或 tool_use）
⑤ 工具调度与执行 → 工具与扩展系统
匹配工具实现 → 内置 30+ 工具执行 → MCP 外部服务接入 → 结果写回消息数组 → 只读工具并行，写操作串行
⑥ 循环与停止 → Agent 执行内核
检查停止条件（轮次上限、Token 预算、用户退出）→ 不满足则回到 ③ 继续循环
问题二：每个模块在代码里在哪？体量多大？
知道有哪些模块还不够，我们还需要知道它们在源码里对应哪些文件，规模是多大，以及从哪几个文件下手。
| 模块 | 对应目录 | 文件数 | 代码行 | 核心入口文件 |
|---|---|---|---|---|
| Agent 执行内核 | src/ 根目录 |
23 | 0.8万 | query.ts、QueryEngine.ts、Task.ts |
| 上下文系统 | constants/、services/compact/、memdir/ |
96 | 2.9万 | constants/prompts.ts、services/compact/ |
| 工具与扩展系统 | tools/、services/mcp/、skills/、plugins/ |
275 | 8.9万 | Tool.ts、tools.ts、services/mcp/ |
| 控制面与安全 | bootstrap/、utils/permissions/ |
176 | 5.9万 | bootstrap/state.ts、utils/permissions/ |
| 模型与云服务 | services/api/、utils/model/ |
69 | 2.2万 | services/api/client.ts |
| 产品外壳与交互 | cli/、commands/、components/、hooks/、ink/ |
878 | 18.5万 | main.tsx、cli/ |
| 多 Agent 协作 | tools/AgentTool/、utils/swarm/ |
55 | 1.9万 | tools/AgentTool/ |
| 远程与非 CLI 形态 | bridge/、remote/ |
47 | 1.7万 | bridge/bridgeMain.ts |
| 基础设施与底座 | utils/、types/、native-ts/ |
304 | 8.7万 | utils/（通用工具） |
核心逻辑极度精简 ------query.ts 约 1700 行，QueryEngine.ts 约 1300 行，两个文件加起来不到 3000 行，比很多业务系统的单个 Service 还小。
问题三：应该按什么顺序学？
光知道有哪些模块、代码在哪还不够，我们需要一条有逻辑的学习路径。
5 步学习路线：
第 1 步：跑通主循环 · Agent 执行内核
- query.ts 主循环结构、turn-by-turn 执行逻辑、停止条件判断
- QueryEngine.ts 消息管理、流式输出、上下文生命周期
第 2 步：读懂上下文 · 上下文系统
- System Prompt 注入机制（工具描述、项目规则、权限状态）
- 会话记忆管理（memdir 历史加载、MEMORY.md 机制）
- 上下文压缩策略（microcompact、contextCollapse、autocompact）
第 3 步：理解工具链 · 工具与扩展系统
- 工具注册与发现（30+ 内置工具、MCP 外部工具接入）
- 工具调度机制（并发分组、只读并行/写操作串行）
- MCP 协议实现（服务端配置、工具发现、结果回传）
第 4 步：搞清安全边界 · 控制面与安全
- 权限模型（allow/deny/confirm 三级决策）
- Feature Gate 机制（实验功能灰度、远程配置下发）
第 5 步：扩展视野 · 多 Agent / 远程形态
- 多 Agent 协作（AgentTool 子任务分发、swarm 编排）
- 远程控制（Bridge 协议、VSCode/IDE 集成）
前三步是 P0 核心三件套，读懂这三个模块就理解了 Agent 的完整工作机制。
从这里开始，我们会按这个顺序逐个模块深入。
系列预告
本文是 Claude Code 源码学习的开篇，目的是画一张"地图"。三个核心结论：
- Claude Code 的价值不在模型，在 Harness --- 99% 代码在做工程支撑
- 9 个模块，P0 核心三件套 --- 执行内核 + 上下文 + 工具，读懂这三个就理解了 Agent
- 学习路径清晰 --- 从内核出发，逐层向外
如果这篇文章对你有帮助，欢迎点赞收藏支持一下。
如果你对 Claude Code 源码有自己独特的理解，或者发现文中有不准确的地方，欢迎留言交流------大家一起把这块拼图拼得更完整。