Claude Code 源码解析系列 · 第1篇

整体架构：50万行TypeScript背后是一套怎样的设计？

前言

2026年3月31日，Anthropic 的 Claude Code 在 npm 上发生了一次意外泄露——约 1900 个 TypeScript 源文件、50 多万行代码，通过 .map 文件短暂暴露在公网约 3 小时。

这次泄露让我们第一次有机会完整地、系统地分析目前全球最顶尖的 AI 编程工具的架构设计。本系列将从源码分析者的视角出发，逐模块拆解 Claude Code 的核心设计，不堆砌源码细节，更侧重讲清楚"为什么要这样设计"，以及"这些设计选择背后的工程哲学"。

一、Claude Code 是什么？

Claude Code 是 Anthropic 官方推出的命令行编程助手，发布于 2025 年。它运行在终端里，通过自然语言对话帮你完成写代码、调 bug、跑测试、提交 Git 等开发任务。

核心定位是 Agentic Coding——能够自主规划、自主执行、自主反思的智能体。可以把它理解为：一个在终端里运行的、真正能替你"编程"的 AI。

理解这一定位，有助于我们理解它的架构设计。

二、六层架构总览

Claude Code 的架构分为 6 个层次，自顶向下：

📐 架构层次一览

• ① CLI 与 UI 层
   — 终端交互界面，接收用户输入，渲染输出
• ② Agent 循环引擎
   — 核心调度中心，运行 ReAct 推理-执行循环
• ③ 工具系统
   — 内置 40+ 工具，封装所有外部操作能力
• ④ 记忆系统
   — 三层记忆架构，管理会话上下文
• ⑤ 上下文压缩系统
   — 五级压缩策略，控制 token 消耗
• ⑥ 权限与安全系统
   — 纵深防御，保障操作安全

▲ Claude Code 整体六层架构分层示意图

每层职责清晰，边界明确——典型的分层解耦架构，上层依赖下层，下层对上层无感知，便于独立演进和测试。

三、各层详解

第一层：CLI 与 UI 层

Claude Code 没有用传统的 readline + chalk 方案，而是选择了 React Ink——用 React 开发范式构建终端 UI。

     好处是组件化、状态驱动、热更新。UI 每一块都是独立 React 组件，状态变化驱动渲染，代码结构更接近现代前端开发思路。由于 React 生态成熟，社区有大量可复用组件，降低了开发成本。   

技术选型：ReactInk

第二层：Agent 循环引擎

这是 Claude Code 的大脑。核心是一个 while(true) 无限循环，实现 ReAct 机制（Reasoning + Acting，即推理+执行）：

用户输入 → 推理规划 → 选择工具 → 执行操作 → 观察结果 → 判断是否完成                                                         ↓                                                    未完成则继续循环

▲ ReAct 推理-执行循环机制

每一步都在思考："当前状态是什么？我该做什么？用什么工具？结果符合预期吗？"这和人类开发者"想一想、试一试、看一看"的思维模式高度一致。

循环终止条件：任务完成 / 达到最大迭代次数 / 用户主动中断。

技术关键：ReAct PatternLLM 调度

第三层：工具系统（Tools）

Claude Code 本身不具备读写文件、执行命令的能力——这些全部通过"工具"来实现。目前内置工具超过 40 个，代表性工具：

• 🔧 BashTool — 执行 shell 命令
• 📄 FileReadTool / FileWriteTool — 文件读写
• 🔍 GrepTool — 代码搜索
• 🌐 WebSearchTool — 联网搜索
• 🤖 AgentTool — 调度子 Agent（多 Agent 架构的核心）

工具系统采用 "fail-closed" 策略：默认禁止不安全操作并发执行，高危操作必须获得用户明确授权，防止 Agent 在多步操作中意外破坏关键数据。

第四层：记忆系统（Memory）

Claude Code 的记忆系统分为三层，用温度区分：

🧠 三层记忆架构

• 🔥 热层 → MEMORY.md → 当前会话高频关键信息
• 🌡️ 温层 → Topic 文件 → 当前话题相关上下文
• ❄️ 冷层 → 历史对话 → 已结束的历史会话

▲ 热-温-冷三层记忆架构，温度越高代表访问频率越高

核心思路：信息按使用频率分层，关键信息始终在最近位置，冷数据按需召回。三层记忆是在信息完整度和 token 成本之间找到的工程平衡。

第五层：上下文压缩系统

Claude Code 实现了 五级压缩策略，应对对话越长上下文越膨胀的问题：

• ① Snip — 剪裁当前上下文，去掉低价值信息
• ② Microcompact — 微压缩，保留关键语义
• ③ Context Collapse — 多轮交互折叠为摘要
• ④ Autocompact — 基于阈值自动触发
• ⑤ Reactive Compact — 异常情况下的紧急压缩

这套机制让 Claude Code 能处理超长对话，适用于大型代码库或多轮重构场景。

第六层：权限与安全系统

Claude Code 的安全设计是纵深防御——层层设卡，不寄希望于单一检查点。

▲ 纵深防御安全体系，多层拦截保障操作安全

• 🛡️ 影子 AI 安全审查 — 内部 YOLO Classifier 在危险操作前分类判断
• 🛡️ Bash 命令安全检查 — 所有 shell 命令执行前经安全评估
• 🛡️ 权限分级 — 高危操作需要额外确认

目标：即使 Agent 某一步判断错误，系统仍有机会在更底层拦截危险操作。

四、整体设计哲学

从六层架构可以看出 Claude Code 的几个核心设计原则：

① 分层解耦，每层专注一件事CLI 层不管推理，引擎层不管 UI，工具层不管记忆。清晰边界让每个模块可独立演进。

② 工具是能力的边界Agent 本身不做事，所有能力通过工具封装。系统可预测、可控制、可审计。

③ 安全是设计出来的，不是堵出来的fail-closed 策略到多级安全检查，安全设计贯穿整个架构，而非事后打补丁。

④ 成本感知贯穿始终三层记忆 + 五级压缩，说明团队对 token 成本有极深刻认知。这是架构设计的核心约束之一。

五、小结

Claude Code 的架构设计，展示了一个生产级 AI Agent 应该有的样子——清晰分层、完备工具系统、精细记忆管理，以及从一开始就设计进去的安全思路。

50 万行代码背后，没有某个惊天的"秘密武器"。更多的是工程上的严谨、对细节的极致追求，以及对复杂系统的强大管控能力。

这恰恰是大型系统设计的本质：用优秀的架构，让复杂变得可控。

▲ Claude Code 源码架构全景

预告：下一篇我们将深入解析 Agent 循环引擎的实现细节——ReAct 机制的具体实现、决策流程关键节点，以及多轮对话下的状态管理策略。敬请期待。