> ## Content Index
> Fetch the complete content index at: https://www.hubwiz.com/blog/llms.txt
> Use this file to discover other available public pages before exploring further.

# Claude Code架构深度剖析
- URL: https://www.hubwiz.com/blog/inside-claude-code-a-deep-dive-into-architecture/
- Published: 2026-04-12T11:22:31.000Z
- Updated: 2026-04-12T11:22:31.000Z
- Description: 一个语言模型、一个工具层、一个反馈循环，以及严谨的工程实践如何组合成一个行为如同开发者的系统。
- Author: admin
- Tags: AGENT, CLAUDE CODE, #Import 2026-10-14 14:41

大多数使用 Claude Code 的人从来不会去想它底层到底在做什么。

你输入一个目标，AI 进行调查、编辑文件、运行测试，然后汇报结果。一切看起来毫不费力。

**但在终端提示符之下，是一个精心设计的系统：** 一个推理模型、一个工具执行层、一个上下文管理管道、一个权限模型，以及一个持续运行直到任务完成的反馈循环。

本文是对 Claude Code 实际工作方式的完整架构解析。不是浅尝辄止的概览。

**而是真实的架构。**

如果你从事软件开发、与 AI 系统打交道，或者只是想真正理解"智能体 AI"在实践中意味着什么，这篇深度解析值得你一读。

### 1、Claude Code 到底是什么

![](https://www.hubwiz.com/blog/content/images/2026/04/image-169.png)

在讲架构之前，先建立正确的心智模型。

Claude Code **不是**一个更智能的自动补全工具。它**不是**一个包裹着代码编辑器的聊天机器人。正确的心智模型是：它是一个**连接到真实工具的推理引擎，在循环中运行，直到你的任务完成。**

它与传统工具的区别是结构性的：

- 代码自动补全看到你打开的文件，建议接下来该写什么\* 代码聊天助手回答问题，但无法对你的代码库进行操作\* Claude Code 阅读你的整个项目，跨文件进行规划，执行真实命令，观察结果并进行调整

你不再是驾驶员。你变成了设定目的地、审查车辆是否正确到达的那个人。

## 2、五层架构

Claude Code 由五个不同的层构建而成。每一层都有特定的职责。它们共同产生了自主、可靠的编码行为。

以下是完整的架构栈，从底层到顶层。

### 架构全貌

![](https://www.hubwiz.com/blog/content/images/2026/04/image-170.png)

### 第一层：模型核心

基础层是一个 Claude 语言模型，大多数编码任务使用 Sonnet，复杂架构推理使用 Opus。

这一点很重要：**模型本身是无状态的。** 它不会在会话之间记住任何东西。每次对话都从一张白纸开始。模型在会话中知道的一切，都来自于 API 调用之前组装到上下文窗口中的内容。

**模型在一个轮次中做什么：**

- 读取完整的上下文窗口（你的提示 + 所有历史记录 + 工具输出 + 系统指令）
- 决定是回复文本、调用一个或多个工具，还是两者兼有
- 通过服务器发送事件（Server-Sent Events）逐 token 流式传输响应

模型可以在**一个轮次中链式调用多个工具**。它可能在一次爆发中读取三个文件、运行一次 grep、编辑一个函数，然后才产生任何可见的文本输出。这就是为什么 Claude Code 在多步骤工作中感觉很快速：它不需要在每个微操作之间等待人类批准。

**关键洞察：** 当模型产生仅包含文本而没有工具调用的响应时，循环停止。模型不调用工具的决定就是退出条件。

### 第二层：上下文组装管道

每次调用模型时，系统提示会首先被组装。这发生在你的文字发送到 API 之前。

**上下文组装管道加载：**

- **当前日期和时间**\* **Git 状态**：当前分支、最近的提交历史、未提交的更改
- **CLAUDE.md 内容**：你的项目特定指令、约定和持久化上下文
- **自动记忆**：Claude 从之前会话中保存的模式和偏好
- **工具定义**：每个可用工具的名称、描述和 schema
- **对话历史**：本次会话中所有之前的轮次

这个组装好的上下文就是模型实际读取的内容。不仅仅是你发的消息。而是你项目的全景、你的偏好以及你当前工作状态的完整画面。

实际影响：**你放在 CLAUDE.md 中的内容质量直接影响每次输出的质量。** Claude 不知道你的代码库有特定的命名约定，除非你告诉它。它不知道你更喜欢类型化错误，除非你明确说明。所有你在乎的东西都应该放在那个文件里。

### 第三层：上下文窗口与压缩

上下文窗口是 Claude 的工作记忆。它也是有限的，以 token 为单位衡量（大约每 4 个英文字符为 1 个 token）。

**随着会话的推进，窗口会被填满：**

- Claude 从你的文件中读取的所有内容
- 它收到的每个命令输出
- 每个工具调用及其结果
- 不断增长的对话历史

当窗口接近容量时，**压缩系统会在大约 92% 使用率时自动触发。** 它会总结对话历史，保留关键的代码片段和指令，并将长期摘要写入记忆文件。较早的工具输出会首先被清除。你的核心指令会被最后保留。

架构使用一个简单规则：**优先考虑下一次决策所需的内容。** 两小时前的调试输出不如 Claude 当前正在编辑的函数签名重要。

**这对你的意义：**

- 将持久性规则放在 `CLAUDE.md` 中，而不仅仅是对话消息里
- 运行 `/context` 查看什么在消耗空间
- 对于非常长的任务，将它们分段进行并在每段之间验证\* 会话早期的详细指令可能会因压缩而丢失

子智能体（在第五层讨论）是解决这个问题的架构方案：它们拥有自己独立的上下文窗口，因此它们的工作不会增加主会话的上下文成本。

### 第四层：工具层

这是推理变为行动的地方。

没有工具，模型只是一个文本生成器。有了工具，它就变成了一个能观察和改变世界的智能体。Claude Code 内置五类工具，每类代表不同的能动性类型：

**文件操作**

- 读取项目中的任何文件
- 使用精确的基于 diff 的写入编辑文件
- 创建新文件、重命名和重组
- 每次文件编辑在写入前都会创建检查点，使其完全可逆

**搜索**

- 通过 glob 模式在整个代码库中查找文件
- 使用正则表达式搜索内容
- 探索目录结构
- 结果返回时包含路径、行号和匹配上下文

**执行**

- 运行任意 shell 命令
- 执行测试套件和构建系统
- 使用 git（status、diff、commit、push）
- 运行脚本和系统工具
- **这是最强大的类别，也是最严格受权限控制的**

**Web**

- 搜索网络查找文档、错误消息、库 API
- 获取特定 URL 的完整页面内容
- 查阅包的变更日志和发布说明

**代码智能**（安装插件后可用）

- 编辑后查看类型错误和警告
- 跳转到定义和查找引用
- 跨文件符号解析

**工具调度在底层是如何工作的：**

模型在其响应中生成一个 `tool_use` 块，指定工具名称和输入参数。工具调度器接收这个块，检查权限模型，路由到正确的处理器，执行，并返回一个 `tool_result` 块。该结果被追加到对话中，然后再次调用模型。

这个循环是流式优先的。工具调用在流式传输过程中被检测到，并在模型的完整响应甚至还未完成之前就触发执行管道。这就是为什么你在终端中能实时看到工具调用出现，而不是在一段停顿之后。

一个关键细节：**每个工具结果都有一个** **`maxResultSizeChars`** **限制。** 当结果超出这个限制时（一个非常大的文件、一个海量的测试输出），内容会被保存到临时文件，模型收到一个带有文件路径的预览。这可以防止单个大输出淹没上下文窗口并挤掉其他所有内容。

### 第五层：智能体循环

这是将语言模型转变为编码智能体的架构。

这个循环非常简洁：

```
while Claude is calling tools:
    1. Execute the requested tool
    2. Append the result to conversation history
    3. Call the model again with updated context
    4. If model returns text only (no tool calls): exit loop

```

这就是全部。简洁是有意为之的。Anthropic 明确选择了**单线程主循环**以实现可调试性和可靠性。一个扁平的消息列表。没有多个智能体角色争夺控制权。

循环会根据你的请求进行适配：

- 一个事实性问题可能不需要任何工具调用（模型直接回答）
- 一个 bug 修复可能经历读取、编辑、测试、读取错误、再次编辑、再次测试的循环
- 一个重构可能涉及跨 15 个文件的 40 或 50 次工具调用
- 一个大型任务可能运行 45 分钟后才将控制权交还给你

**异步消息队列**使你能够在任务执行过程中中断和引导。你可以在 Claude 积极工作时注入新指令。队列处理暂停/恢复而不需要完全重启。Claude 不会停止一切，而是吸收你的修正并按更新后的计划继续。

在 2025 年 10 月到 2026 年 1 月之间，第 99.9 百分位的轮次持续时间几乎翻倍，从不到 25 分钟增长到超过 45 分钟。团队越来越多地将 Claude Code 用于多小时的自主任务。单线程循环架构使得当出现问题时这些任务可以被调试。

## 3、权限模型：融入架构的安全性

权限不是事后补充的。

它们被编织在工具执行路径中。

**在任何工具运行之前，它会通过一个权限门。权限门有四种操作模式，可通过** **`Shift+Tab`** **切换：**

**模式：** 会发生什么 **默认模式** Claude 在文件编辑和 shell 命令前会询问 **自动接受编辑** 文件编辑自动进行，shell 命令仍需批准 **规划模式** 仅限只读工具；Claude 创建一个你批准后再执行的计划 **自动模式** Claude 通过后台安全检查评估所有操作（研究预览）

你还可以在 `.claude/settings.json` 中将特定命令加入白名单。像 `npm test` 或 `git status` 这样的命令可以无需批准直接运行。影响外部系统的命令（数据库写入、API 调用、部署）每次都需要明确授权。

**检查点**是另一个安全机制。

在编辑任何文件之前，Claude 会对当前内容进行快照。如果编辑产生了错误的结果，按两次 `Esc` 即可回退。这与 git 分开。它覆盖的是即时会话状态，而不仅仅是被追踪的更改。

![](https://www.hubwiz.com/blog/content/images/2026/04/image-171.png)

## 4、记忆架构

Claude Code 有三个不同的记忆系统，理解这三个系统会改变你使用这个工具的方式。

### 4.1 CLAUDE.md（你写的）

项目根目录下的一个 Markdown 文件。**在每次会话开始时加载，在上下文窗口填满之前**。这里放持久化的项目知识：命名约定、架构决策、测试要求，以及你希望 Claude 每次都知道的东西。

**最有效的结构：**

- 项目概述：这是什么、做什么
- 架构：关键模块及其职责
- 约定：如何命名、如何组织代码
- 测试：如何运行测试，通过的标准是什么
- 当前优先级：你正在积极处理什么

### 4.2 自动记忆（Claude 写的）

在你工作的过程中，Claude 会自动保存模式和偏好。比如："这个项目变量使用 camelCase"，"这个开发者更喜欢显式错误处理而非异常捕获"。这个记忆文件的前 200 行或 25KB 在会话开始时加载。

**你应该定期审查和整理这个文件。被保存的错误模式会微妙地影响每一个未来的会话。**

### 4.3 会话 JSONL（完整的审计追踪）

每条消息、工具调用和结果都被写入 `~/.claude/projects/` 下的纯文本 JSONL 文件。这支持三种能力：

- **回退**：撤销到会话中的任何先前状态
- **恢复**：从你上次停下的地方继续（`claude --continue`）
- **分叉**：从历史中的某个节点分支并尝试不同的方法（`--fork-session`）

如果你同时在两个终端中恢复同一个会话，两者都写入同一个文件并交错记录。不会损坏任何东西，但对话会变得不连贯。对于并行工作，始终使用分叉来给每个终端自己的会话 ID。

## 5、子智能体：没有混乱的并行化

子智能体是分解大型任务的架构方案。

当 Claude Code 生成一个子智能体时，它会创建一个**嵌套的智能体循环，拥有自己独立的上下文窗口、自己的工具集和自己的对话历史。** 子智能体独立处理其分配的任务。完成后，它向父智能体返回一个摘要。

关键的架构特性：**子智能体的工作不会消耗父智能体的上下文窗口。** 这就是为什么子智能体有助于处理长会话。它们在独立的上下文中完成工作，并回报一个紧凑的结果。

约束是：**一次最多一个子智能体分支。** Anthropic 刻意防止不受控制的智能体增殖。你可以通过 Teams 实现并行工作流（使用 tmux 实现真正的并行性），但默认的单子智能体限制是一个可靠性选择，而不是限制。

子智能体可以本地运行（进程内）或在远程计算资源上运行。架构支持将繁重的任务卸载到 Anthropic 管理的虚拟机，而你的主会话在本地继续。

## 6、扩展：最上面的那一层

在核心循环之外，三种扩展类型增加了能力：

#### **技能（Skills）**

**Claude 可以引用的预编写工作流文件。**

Claude 在会话开始时看到技能描述，但完整内容只在技能被使用时加载。对于你手动调用的技能，设置 `disable-model-invocation: true` 可以将描述保留在上下文之外直到需要时才加载。技能是可重复的团队工作流的正确选择："我们这里怎么做代码审查"，"我们的部署流程"。

#### **MCP（模型上下文协议）**

**外部服务的集成层。**

将 Claude 连接到数据库、API、文档系统、项目管理工具。MCP 工具定义默认延迟加载，通过工具搜索按需加载，所以只有工具名称会消耗上下文，直到 Claude 真正需要某个特定工具。

#### **钩子（Hooks）**

**围绕 Claude 的操作运行的事件驱动自动化。**

在工具执行之前。在文件编辑之后。在会话结束时。钩子让你可以自动运行代码检查器、强制安全检查、触发 CI 管道，或将操作记录到你自己的系统。

![](https://www.hubwiz.com/blog/content/images/2026/04/image-172.png)

## 7、完整追踪：一个请求发生了什么

以下是一个真实请求的完整执行路径。

**你输入：** "结账流程中有一个关于过期卡片用户的 bug。修复它。"

**实际发生的顺序：**

- 你的消息被追加到对话历史中
- 上下文组装运行：git status、CLAUDE.md、自动记忆、工具定义、完整对话历史被组装
- 完整上下文通过 Anthropic API 发送给 Claude 模型，通过服务器发送事件进行流式传输
- 模型决定搜索。调用 `search` 工具，查询 "checkout card expired"- 工具调度器检查权限。搜索自动批准。处理器执行
- 搜索返回：三个匹配的文件 `checkout.js`、`payments.js`、`card_validation.py`\- 模型对这三个文件调用 `file_read`。结果追加到上下文
- 模型识别出 `checkout.js` 中缺失的错误处理路径
- 模型调用 `file_edit`，附带修复的精确 diff
- 权限门检查：文件编辑在默认模式下需要批准。你看到 diff 并批准
- 文件写入。写入前保存检查点
- 模型调用 `bash` 运行 `npm test` 进行验证
- 测试通过。模型注意到两个与此更改无关的既有失败
- 模型生成纯文本响应：它改了什么以及为什么
- 循环退出。控制权返回给你

总工具调用次数：7。总读取文件数：3。总编辑文件数：1。一个人工批准步骤。

如果你在自动接受模式下运行这个，零次人工干预。整个调查和修复将在无停顿的情况下完成。

## 8、架构在哪里出问题

每个架构都有失败模式。这些是 Claude Code 真正的失败模式。

#### **大型代码库上的上下文溢出**

当一个项目有数百个文件，相关代码分散很广时，Claude 无法同时在上下文中容纳所有内容。它必须选择读取什么，而这些选择会影响其理解的质量。通过一个结构良好的 CLAUDE.md 来缓解这个问题——告诉 Claude 去哪里看，而不仅仅是做什么。

#### **自信的幻觉**

模型可能会以十足的信心生成不能工作的代码，或者描述一个有微妙缺陷的方案。它在陌生领域推理得越多，风险越高。在提交之前务必阅读 diff。务必运行你自己的测试。输出是起点，不是最终答案。

#### **压缩侵蚀早期指令**

长会话中早期的指令可能会被压缩掉。如果你在一个 3 小时会话的开始给了 Claude 一个重要的约束，到第二个小时时它可能已经不在那个约束下操作了。把硬性要求放在 CLAUDE.md 中，不要放在对话里。

#### **长时程任务一致性**

对于非常长的任务（多小时自主运行），模型可能在早期决策和后期决策之间失去一致性。这与其说是模型限制，不如说是上下文管理问题。对于大型任务，将其架构为一系列带检查点的分段，而不是一次连续运行。

#### **不可逆的外部操作**

文件编辑有检查点且可逆。数据库写入、API 调用、部署：这些不是。Claude 默认在这些操作前会询问，但在批准之前审查操作的责任完全在你。

## 9、这个架构在实践中意味着什么

Stripe 在 1,370 名工程师中部署了 Claude Code。一个团队在四天内完成了一个 10,000 行的 Scala 到 Java 的迁移，这项工作原本估计需要十个工程师周。

在 Anthropic，现在大部分代码由 Claude Code 编写。工程师专注于架构、产品思维和编排：设定目标、审查结果、并行管理多个智能体。

这个转变主要不是关于速度，尽管速度是其中的一部分。它是关于人类判断力运作的层级。当执行被自主处理时，人类精力集中在真正需要判断力的决策上：构建什么、如何组织、输出是否正确、下一步做什么。

从 Claude Code 中获益最多的开发者不是那些最巧妙地写提示的人。而是那些清晰地思考了他们的架构、在 CLAUDE.md 中记录了他们的约定、并建立了验证习惯的人：始终阅读 diff，始终运行测试，始终理解改了什么以及为什么。

## 10、结束语

研究 Claude Code 构建方式最重要的洞察：**智能不在模型中。它在循环中。**

一个只响应单次提示的语言模型可以是令人印象深刻的。但让 Claude Code 在质上感觉不同的不是 Claude 更聪明。而是围绕 Claude 的系统赋予了它观察、行动、检查自己的工作并调整的能力。循环就是智能体。

工具给了 Claude 双手。上下文组装给了它记忆。反馈循环给了它纠偏的能力。权限模型给了你保持监督的能力。会话存储给了你撤销任何操作的能力。

这些单独的部分中没有一个是革命性的。连接它们的架构才是。

**理解循环是善用循环的开始。**

---

原文链接: [Inside Claude Code: A Visual Deep Dive into the Architecture That Actually Works](https://medium.com/ai-engineering-simplified/inside-claude-code-a-visual-deep-dive-into-the-architecture-that-actually-works-d9474e1006cd?ref=hubwiz.com)

汇智网翻译整理，转载请标明出处