Claude Code 源码架构概览：51万行代码的模块地图

维元码簿
3 阅读9分钟

系列开篇 | Claude Code 源码架构概览：51万行代码的模块地图

Hi，大家好，欢迎来到维元码簿。

这是一个关于 Claude Code 源码学习的系列。

Claude Code 是当前业界 Coding Agent 的 SOTA 实现。能接触到这样一个工业级系统的完整源码，是难得的学习机会。所以我决定用 Coding Agent 帮我读懂 Claude Code，同时把这个学习过程完整记录下来。

51 万行代码，体量庞大。一篇长文放不下，于是有了这个系列。

作为开篇，本文的任务是画地图——不急着深入细节，而是先搞明白：

  • Claude Code 是什么？有多少核心代码，多少支撑代码？
  • 可以拆成哪些模块？它们如何协作？
  • 学习路径是什么？从哪里开始读？

搞明白了这些，后面的学习就可以有条不紊地进行下去。

Claude Code 到底是什么？

01-claude code理解思路.png

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% 的代码在做“支撑”。但“支撑”不是一个模糊的大筐子，它有具体的结构，每个模块之间也有明确的协作关系。

01-模块全景协作关系.png

模块优先级占比二级话题
Agent 执行内核P01.6%
  • query.ts 主循环结构
  • turn-by-turn 执行逻辑
  • 停止条件判断
  • QueryEngine.ts 消息管理与流式输出
上下文系统P0–P15.6%
  • System Prompt 注入
  • 会话记忆管理（memdir / MEMORY.md）
  • 上下文压缩（microcompact / contextCollapse / autocompact）
工具与扩展系统P0–P217.3%
  • 工具注册与发现（30+ 内置工具 + MCP 接入）
  • 并发调度（只读并行 / 写操作串行）
  • MCP 协议实现
控制面与安全P1–P211.5%
  • 权限模型（allow / deny / confirm 三级决策）
  • Feature Gate 灰度机制
模型与云服务P1–P34.2%
  • Claude API 调用
  • 流式响应处理
  • 模型选择与降级策略
产品外壳与交互P235.9%
  • CLI 命令行（101 子命令）
  • React 终端 UI（389 组件）
  • 命令 / 钩子 / 主题系统
多 Agent 协作P33.7%
  • AgentTool 子任务分发
  • swarm 编排
远程与非 CLI 形态P33.2%
  • Bridge 协议
  • VSCode / IDE 集成
  • 远程控制
基础设施与底座P417.0%
  • 通用工具函数
  • 类型定义
  • 原生模块绑定

P0 = 内核运转 · P1 = 能力边界 · P2 = 产品化 · P3–，P4 = 扩展底座

这些模块在一次请求中是如何协作的

转存失败，建议直接上传图片文件 执行链路拆解：

① 输入入口 → 产品外壳与交互
CLI 接收用户指令，解析参数，启动主循环

② 安全检查 → 控制面与安全
权限校验、Feature Gate 检查、危险操作拦截

③ 上下文拼装 → 上下文系统
System Prompt 注入 → 历史会话加载 → 微压缩合并冗余消息 → 上下文折叠（可选） → 自动压缩（超限时生成摘要）

④ 模型调用 → 模型与云服务
调用 Claude API，流式返回响应（文本或 tool_use）

⑤ 工具调度与执行 → 工具与扩展系统
匹配工具实现 → 内置 30+ 工具执行 → MCP 外部服务接入 → 结果写回消息数组 → 只读工具并行，写操作串行

⑥ 循环与停止 → Agent 执行内核
检查停止条件（轮次上限、Token 预算、用户退出）→ 不满足则回到 ③ 继续循环

每个模块在代码里在哪？体量多大？

知道有哪些模块还不够，我们还需要知道它们在源码里对应哪些文件，规模是多大，以及从哪几个文件下手。

01-源码模块路径.png

模块对应目录文件数代码行核心入口文件
Agent 执行内核src/ 根目录230.8万query.ts、QueryEngine.ts、Task.ts
上下文系统constants/、services/compact/、memdir/962.9万constants/prompts.ts、services/compact/
工具与扩展系统tools/、services/mcp/、skills/、plugins/2758.9万Tool.ts、tools.ts、services/mcp/
控制面与安全bootstrap/、utils/permissions/1765.9万bootstrap/state.ts、utils/permissions/
模型与云服务services/api/、utils/model/692.2万services/api/client.ts
产品外壳与交互cli/、commands/、components/、hooks/、ink/87818.5万main.tsx、cli/
多 Agent 协作tools/AgentTool/、utils/swarm/551.9万tools/AgentTool/
远程与非 CLI 形态bridge/、remote/471.7万bridge/bridgeMain.ts
基础设施与底座utils/、types/、native-ts/3048.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 源码有自己独特的理解，或者发现文中有不准确的地方，欢迎留言交流~

avatar
文章
阅读
粉丝