Claude Code架构深度剖析

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

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

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

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

而是真实的架构。

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

1、Claude Code 到底是什么

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

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

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

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

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

2、五层架构

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

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

架构全貌

第一层：模型核心

基础层是一个 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 分开。它覆盖的是即时会话状态，而不仅仅是被追踪的更改。

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 管道，或将操作记录到你自己的系统。

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

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