Claude Code 架构图解:从源码看懂顶级 AI 编程 Agent 的系统设计

关于 Claude Code，最近最热的话题当然是“源码”。

但真正值得写的，不是把注意力放在猎奇式的“隐藏指令”上，而是：当你真的沿着源码结构、模块分层和运行链路去看，你会发现 Claude Code 已经不是一个普通 AI 编码工具，而是一套非常完整的 Agent 系统。

它最厉害的地方，不是某个 prompt，不是某个功能按钮，而是它把这些东西统一做成了一套平台：

• • 有内核
• • 有工具总线
• • 有安全边界
• • 有任务和记忆
• • 有子 Agent 协作
• • 有 IDE 桥接和协议扩展

这篇我就不聊八卦，直接用架构图 + 关键文件导览的方式，带你看懂 Claude Code 到底是怎么搭起来的。

如果你不想一上来就淹死在大仓库里，我建议先把它理解成下面这个结构：

┌──────────────────────────────────────────────┐
│                交互入口层                    │
│ CLI / Terminal UI / IDE Bridge / Remote     │
└──────────────────────────────────────────────┘
                     ↓
┌──────────────────────────────────────────────┐
│                Agent Runtime                 │
│ QueryEngine / Context / Cost / Tool Loop     │
└──────────────────────────────────────────────┘
                     ↓
┌──────────────────────────────────────────────┐
│                能力编排层                    │
│ Tools / Commands / Skills / Tasks / Memory   │
└──────────────────────────────────────────────┘
                     ↓
┌──────────────────────────────────────────────┐
│                基础设施层                    │
│ Auth / MCP / LSP / Analytics / Policy        │
└──────────────────────────────────────────────┘
                     ↓
┌──────────────────────────────────────────────┐
│                外部系统与环境                │
│ Files / Shell / Git / Web / IDE / Services   │
└──────────────────────────────────────────────┘

就按这张图理解，很多东西会一下子顺起来。

因为 Claude Code 并不是把所有能力揉成一锅，而是明显分成：

• • 谁负责入口
• • 谁负责运行时
• • 谁负责能力调用
• • 谁负责底层支撑
• • 谁负责连接外部世界

这就是它的工程感来源。

二、为什么 main.tsx 不是“普通入口文件”，而是整套系统的装配台？

很多人看源码时，会下意识跳过入口文件，直奔大模块。

但 Claude Code 这种大型 CLI，不建议这么看。

从公开资料看，src/main.tsx 不是一个简单的启动器，它更像整个系统的装配台：

• • 启动 Commander.js 命令解析
• • 初始化 React + Ink 终端界面
• • 触发配置读取
• • 并行做部分预取动作
• • 为后续 Query Engine、commands、tools 和状态系统搭桥

也就是说，main.tsx 决定了 Claude Code 不是“脚本式 CLI”，而是“应用式 CLI”。

这点很重要。

因为脚本式 CLI 的思维是：

• • 启动
• • 跑完
• • 退出

而 Claude Code 的思维明显是：

• • 启动一个长期运行的交互系统
• • 管理 UI、状态、会话、能力、工具、审批与扩展协议

你看到这里就会知道，为什么它会有那么重的目录结构——因为它根本不是把自己当“小工具”做的。

三、真正的中枢：QueryEngine.ts 为什么几乎决定了上限？

如果整套系统只能挑一个最关键文件，那基本就是：

• • src/QueryEngine.ts

它的重要性，相当于 Agent Runtime 的中枢神经。

你可以把它理解成下面这张运行图：

用户输入
   ↓
上下文收集（context / memory / config）
   ↓
系统提示与控制层拼装
   ↓
调用模型
   ↓
模型决定：直接回答 or 调工具
   ↓
工具执行并返回结果
   ↓
QueryEngine 接回结果继续推理
   ↓
输出流式渲染 / 会话续航 / 成本统计

这条链路听上去简单，但真正难的地方全藏在细节里：

• • 上下文怎么拼接才稳
• • 工具结果怎么回注
• • 流式输出怎么处理中间态
• • 长会话怎么压缩
• • 模型失败怎么重试
• • 成本怎么控
• • 不同模式怎么切换

所以 Query Engine 的大，不是“写得臃肿”，而是因为它承载了一个真正产品级 Agent 的大量复杂度。

很多“仿 Claude Code”的项目，最大的问题不是功能不够，而是没有这一层真正成熟的运行时内核。

四、工具系统为什么不是附属模块，而是 Claude Code 的“执行总线”？

这一点非常值得所有做 Agent 的团队认真看。

Claude Code 的工具体系，不像很多项目那样是“顺手挂几个函数”。

从公开分析看，它的工具能力覆盖了几个核心域：

1）文件域

• • 读取文件
• • 写文件
• • 局部编辑
• • Notebook 编辑

2）搜索域

• • glob
• • grep
• • web search
• • web fetch

3）执行域

• • bash
• • skill
• • MCP tool
• • LSP tool

4）协作域

• • sub-agent
• • send message
• • team 管理
• • task 管理

5）模式域

• • plan mode
• • worktree mode
• • cron / sleep / remote trigger
• • structured output

你把这些工具放在一起看，会发现它已经不是“工具箱”，而是一个受控执行层。

换句话说：

模型并不是直接碰文件、Shell、Git、Web、子 Agent。
它是通过工具协议，间接地、有边界地触达这些能力。

这和操作系统里的系统调用非常像。

所以 Claude Code 的工具系统更准确的说法不是“tools”，而是：

Agent 的执行总线。

五、权限与安全：为什么这是 Claude Code 最有含金量的部分之一？

我反而觉得，这部分比“隐藏 prompt”更值得研究。

因为一个 AI 编程 Agent 真正进入现实工作流以后，风险很快就会上来：

• • 它可以读文件
• • 它可以改文件
• • 它可以执行 shell
• • 它可以操作 git
• • 它可以连接外部工具
• • 它还可能触发子 Agent

这个时候问题就变成：

谁来定义它的动作边界？谁来批准？哪些动作可自动放行？哪些动作必须拦截？

从公开资料来看，Claude Code 不是把安全当外挂，而是至少做了这几层：

第一层：工具级权限检查

也就是“每次工具调用都检查”，而不是事后追责。

第二层：审批模式

允许不同模式下，使用不同的授权策略。

第三层：风险解释

系统不只是拦，还会解释“为什么这个动作危险”。

第四层：自动分类

通过独立分类逻辑判断哪些请求可自动通过，哪些应该升级到人工确认。

这意味着 Claude Code 的安全架构，不是“怕出事所以限制很多”，而是：

它试图在自动化能力和可控性之间找到系统级平衡。

这点特别像成熟的工程产品，而不像实验室 demo。

六、Prompt 架构真正值得学的，不是“秘密文本”，而是“分层控制思路”

这点我想单独强调一下。

最近很多人对 Claude Code 的 prompt 很感兴趣，但我觉得真正值得学的，不是把某段系统提示抄下来，而是它的Prompt Architecture。

根据公开研究资料，它更像下面这个结构：

静态系统前缀（可缓存）
├─ 身份与行为边界
├─ 安全与风险约束
├─ 工具使用偏好
├─ 输出风格规则
└─ 效率与错误处理原则

动态系统后缀（会话相关）
├─ 当前环境信息
├─ Memory / CLAUDE.md 类内容
├─ Skills / Commands / Tool descriptions
├─ MCP server 指令
├─ 模型覆盖设置
└─ 当前任务上下文

这个结构说明了两件很重要的事：

1）Prompt 在 Claude Code 里是“控制层”，不是“灵感文本”

它承担的是系统行为约束，而不是文学创作。

2）Prompt 和状态系统是联动的

因为 memory、session search、compact、summary、skills、tool descriptions 都会进入这套控制层。

所以 Claude Code 的 prompt 本质上不是“某几句隐藏咒语”，而是：

一个和上下文管理、工具系统、缓存策略、子 Agent 编排深度耦合的控制面。

这才是真正值得抄作业的地方。

七、多 Agent、Bridge、MCP：它为什么明显不是“单终端工具”思维？

当你继续往下读，就会发现 Claude Code 很明显已经不是围绕“当前终端窗口”来设计的。

1）Multi-Agent / Coordinator

有 coordinator/，有 AgentTool，有 team 相关工具。

这说明它不是默认一个 Agent 单线程干到底，而是在为：

• • 子 Agent 探索
• • 分工执行
• • 结果汇总
• • 队伍协作

做准备。

2）Bridge

有专门的 bridge/ 层，用于连接 IDE。

这非常关键。

因为很多产品是“IDE 插件优先”，而 Claude Code 更像是：

先做独立 runtime，再把 runtime 通过桥接能力接到 IDE 里。

这会让它的系统边界更清晰，能力复用更强。

3）MCP / Remote / Server

这些模块说明 Claude Code 已经在往平台协议化方向走。

不是只做一个本地终端工具，而是开始具备：

• • 标准协议接入
• • 远程会话扩展
• • 服务化能力外放

所以从产品视角看，Claude Code 更像：

一个可以跑在终端里的 Agent 平台核心。

八、如果你想读源码，我建议按这条路径走

这类大仓库最怕“到处点，到处晕”。

我建议你按这 4 步读：

Step 1：先读骨架

• • src/main.tsx
• • src/commands.ts
• • src/tools.ts

目的：先搞清楚它是怎么启动、注册和装配的。

Step 2：再读内核

• • src/QueryEngine.ts
• • src/Tool.ts
• • src/context.ts
• • src/cost-tracker.ts

目的：理解 Agent Runtime 如何运转。

Step 3：再读能力域

• • src/tools/
• • src/commands/
• • src/tasks/
• • src/memdir/
• • src/skills/
• • src/plugins/

目的：理解系统真正“能做什么”。

Step 4：最后读平台扩展

• • src/bridge/
• • src/services/mcp/
• • src/remote/
• • src/server/

目的：理解它如何从一个 CLI 走向平台。

这条路线最省脑力。

九、我建议顺手收藏的 GitHub 地址

如果你接下来准备继续研究，可以先收藏这几个：

• • Claude Code 源码镜像与文档整理：
• • https://github.com/777genius/claude-code-source-code-full
• • Claude Code 相关源码/重建项目集合：
• • https://github.com/chauncygu/collection-claude-code-source-code
• • 另一个源码镜像：
• • https://github.com/fyu/claude-code
• • Claude Code prompt 架构研究：
• • https://github.com/noelzappy/claude-code-system-prompts

这些更适合当研究参考入口。

十、最后一句话：Claude Code 最厉害的，不是某个功能，而是“系统感”

如果你让我只用一句话总结 Claude Code 的源码启发，我会这么说：

它不是把模型接进 IDE 或终端，而是把 AI 编程助手做成了一个真正有运行时、有安全边界、有状态系统、有扩展协议的工程平台。

这才是它最值得抄作业的地方。

不是神秘 prompt，
不是彩蛋功能，
也不是某个小技巧。

而是：

Claude Code 已经把“AI Coding Agent”这件事，从功能产品，做成了系统产品。