Claude Code源码全拆解：55个目录、331个模块，最强Agent架构长什么样

Anthropic 的 Claude Code 源码被扒了个干干净净。55 个目录、331 个模块、目前业界最经受实战检验的 Agent 架构——全部暴露在 .map 文件里。

一个叫 Rohit 的独立开发者花了大量时间把每一个文件都拆开看了。每一个架构决策、每一条重试路径、每一个压缩策略、每一层权限管道——然后写了一篇万字长文：这不是拆解，这是蓝图。

Rohit 的原文标题：Building Harness——从 Claude Code 源码中提取 Agent 架构蓝图

我读完之后最大的感受是：大部分人在聊"怎么用好大模型"的时候，Anthropic 在解一个完全不同的问题——怎么让一个 Agent 在生产环境里跑几百轮不崩。答案不在模型本身，而在模型周围那一圈精密的工程系统。这篇文章信息密度极高，我把最核心的设计决策提炼出来，一个一个讲清楚。

01 不是三层，是四层

业界一直在说 Agent 有三层：模型权重（frozen intelligence）、上下文（prompt + 对话历史）、外壳（工具、循环、错误处理）。每个教程都这么教，每个框架 README 都这么写。

普林斯顿 NLP 的 SWE-agent 论文证明了这个方向是对的：同一个 GPT-4，只改交互界面设计，SWE-bench 成绩提升了 64%。模型没变，任务没变，只有环境变了。性能提升藏在第 2、3 层里。

然后你打开 Claude Code 的源码，发现 Anthropic 在做的事情比这三层都多。

里面有什么？四级 CLAUDE.md 层级结构让企业管理员通过 MDM 执行策略；基于磁盘的任务列表加文件锁让并行子 Agent 不会互相踩数据；Git worktree 隔离让五个 Agent 在同一个仓库的五个分支上同时工作零冲突；权限管道从企业级到项目级到用户级到会话级层层传递拒绝规则。

这些都不是"外壳"。这是基础设施：多租户、角色权限控制、资源隔离、状态持久化、分布式协调。Rohit 因此提出了第四层架构：

大部分团队只讨论前三层，因为前三层有趣、好讲、好写论文。第四层没人讨论，因为第四层全是脏活累活——你需要想清楚权限怎么分层、状态跨会话怎么存、多个 Agent 同时写同一个仓库怎么不打架。

但恰恰是第四层，决定了你的 Agent 是一个酷炫的 Demo，还是一个每天有人用的产品。

02 核心循环

Claude Code 的心脏在 query.ts，1,729 行 TypeScript。最关键的设计决策藏在函数签名里——它用的是 async generator，不是 while 循环。

别小看这个选择，区别巨大。大部分教程教你的 Agent 循环长这样：while (needsMoreWork) { result = await callModel(); }。教程里跑得通。生产里五个问题会同时爆炸：

1. 没有流式输出。用户盯着空白屏幕等 10-30 秒。Claude Code 的 generator 一边生成一边 yield StreamEvent，用户逐字看到模型在工作。能看到过程的用户更信任 Agent，信任带来自主执行度，而自主性正是 Agent 处理复杂任务的关键。

2. 没有取消机制。While 循环里按 Ctrl+C 需要从外部接入中止机制。Generator 天然支持——调用方停止调用 .next()，finally 块运行，清理完成。

3. 没有背压控制。模型生成速度快于终端渲染速度时，while 循环把所有内容缓存在内存里。Generator 在消费者停止拉取时自动暂停生产。长会话里，这个差异决定了内存是保持稳定还是涨到进程崩溃。

4. 循环内没有错误恢复。这才是最要命的。

Claude Code 每一轮迭代经过五个阶段：Setup（准备：应用 token 预算、压缩策略）→ Model Invocation（模型调用：流式执行，工具边生成边跑）→ Error Recovery（错误恢复：prompt 太长就压缩重试，输出 token 不够就从 32K 升到 64K）→ Tool Execution（工具执行：未完成的工具在此运行）→ Continuation Decision（继续判断：还有工具要调用吗？到 maxTurns 了吗？）。

错误恢复活在循环内部，不是外面包一层 try-catch。每个阶段都知道什么可能出错，并且有专门的恢复路径。这就是"Agent 遇到速率限制就崩溃"和"Agent 自动退避、重试、切换模型、继续工作"之间的差距。

03 工具并发

Claude Code 内置了 45+ 工具。数量不重要，执行方式才重要。

大部分 Agent 框架要么顺序执行（安全但慢），要么全部并行（快但危险——两个并行写操作写同一个文件会导致数据损坏）。Claude Code 的做法是按并发行为分类每个工具：

工具并发分类代码：QueryDeps 接口定义了依赖注入的模型调用和压缩方法

编排层（toolOrchestration.ts）把工具调用分批执行：只读工具（Glob、Grep、Read、WebFetch）最多 10 个并行跑；写操作工具（Bash 写入、Edit、Write）串行跑。搜索五个文件并行，编辑一个文件串行。并行的速度 + 串行的安全性，同时享受。多工具回合提速 2-5 倍，累积到整个会话就是分钟级别的节省。

这个设计看似简单，但关键在于分类是在工具定义时就打好标签的，不需要运行时分析。编排层只需要读标签、分批、调度。简洁、可靠、可扩展。

04 流式工具执行

StreamingToolExecutor：模型还在生成下一步描述时，第一个工具已经在跑了

这是 Claude Code 里我觉得最精妙的组件之一。大部分框架等模型完全生成完毕才开始执行工具。Claude Code 在流式传输过程中就开始执行——一个 Grep 调用的输入 JSON 一完整，立刻就开始跑，不用等下一个工具调用开始生成。

一轮包含三个工具调用的操作，能隐藏 2-5 秒的延迟。模型在描述下一步操作时，第一个工具的结果可能已经在等了。

难的是边界情况处理：如果并行批次中某个工具失败，per-tool 的 siblingAbortController 杀掉兄弟进程，但父级查询控制器不受影响，对话继续。如果流式传输失败回退到非流式，执行器丢弃排队的工具，对正在运行中的工具请求生成合成错误响应。结果按原始顺序 yield，即使工具 2 比工具 1 先完成。

每一个细节都是被真实的生产故障教出来的。看上去是"优化"，实际上是一份用户在真实场景里踩过的所有坑的清单——用代码的形式写成了解决方案。

05 提示词即缓存

系统提示词结构：SYSTEM_PROMPT_DYNAMIC_BOUNDARY 标记把提示词分为全局缓存区和动态区

Claude Code 的系统提示词不是一个字符串。它是一个带缓存元数据的结构化数组。

一个 SYSTEM_PROMPT_DYNAMIC_BOUNDARY 标记把提示词分成两个区域。标记以上的部分：所有用户、所有会话完全相同，命中 API 层面的全局 prompt cache。这部分占整个提示词的约 80%——你不需要每次 API 调用都重新 tokenize 577+ 行内容。

标记以下的部分：按会话 memoize（每会话计算一次）或 volatile（每轮重新计算）。Volatile 部分尽量最小化，因为每次变更都会让后面所有内容的缓存失效。

还有一个精妙的设计：用户上下文（git status、CLAUDE.md 内容、当前日期）被注入为第一条用户消息（用 <system-reminder> 标签包裹），而不是放在系统提示词里。原因很实际：这些内容每轮都变，放在系统提示词里会从变更点开始让后面所有内容的缓存失效。放到用户消息里，系统提示词的缓存就能逐轮保持稳定——相当于白嫖了 80% 的 prompt tokenization 成本。

规模化运营时，这个设计决定了你的 Agent 每次对话花 $0.02 还是 $0.20。没有任何一个 Agent 教程、框架文档或技术大会讨论过把提示词按缓存效率来设计。但这可能是整个代码库里杠杆最高的优化。

06 四级压缩

大部分 Agent 框架在撞到上下文限制时要么截断旧消息，要么直接崩溃。Claude Code 支持无限对话长度，靠的是四级压缩策略，从便宜到贵排列：

1. Microcompact——每轮都跑。如果一个工具上次调用后结果没变，用缓存引用替换完整结果。比如反复 Read 同一个文件，能省下数千 token。成本：接近零。

2. Snip Compact——接近 token 上限时触发。删除对话开头的消息，但保留最近几轮的"受保护尾部"。不需要调用模型。有损但快。

3. Auto Compact——Snip 不够时触发。用一次单独的模型调用总结之前的对话，旧消息被总结替换。系统追踪压缩状态，防止"总结的总结的总结"这种循环。

4. Context Collapse——超长会话的最后手段。多阶段分步压缩：先压工具结果，再压思考块，最后压整段内容。最贵的选项，只在连续运行数小时的会话中使用。

核心原则：最便宜的先跑，最贵的最后才用。大部分有压缩功能的框架直接跳到总结。总结在压缩调用和总结本身两个地方都消耗 token。Microcompact 和 Snip 能以零模型调用处理大量案例。而且"受保护尾部"这个概念很关键——压缩运行时，最近几轮的消息永远不会被总结掉。模型始终对刚做过的事情保持完整记忆，哪怕更早的上下文已经被压缩了。这样模型就不会在执行计划的过程中忽然忘了自己刚才在干什么。

07 七级权限

七阶段权限管道：从工具调用请求到最终执行，每一步都有审批或拒绝的机会

大部分 Agent 框架的权限是个二元开关：允许或拒绝。Claude Code 跑的是一个七阶段管道。

规则用类似 glob 的模式匹配工具名和输入："允许所有 bash"太粗——谁都不想让 Agent 跑 rm -rf /。"禁止所有 bash"又让 Agent 变废物。"允许 git 命令和 npm test，其他的都问我"——这才是权限控制的最佳平衡点。

权限模式构建了渐进式信任：新用户从 default 模式开始，每个操作都要批准。熟悉后切到 acceptEdits 或 bypassPermissions。不是安全和速度之间的二选一，而是一个光谱。

Hooks 是最后的逃生口——你的自定义脚本接收工具调用详情，返回 approve 或 block。企业可以搭自定义护栏：阻止破坏性操作、任务完成后发 Slack 通知、每次文件写入后跑 linter。不需要改一行源码。

我觉得这个权限设计最聪明的地方在于：它把"信任"变成了一个可以被量化和调节的参数，而不是一个要么全给要么全不给的二元选择。这对企业落地 AI 编程助手来说至关重要——安全团队能接受的底线和开发者想要的自由度之间，终于有了一个合理的折中方案。

08 823 行重试

withRetry.ts 有 823 行。每一行的存在都因为一次生产事故。

429（速率限制）：检查 Retry-After 头。低于 20 秒？重试，保持快速模式。超过 20 秒？进入 30 分钟冷却。检测到 overage-disabled 头？永久禁用快速模式，并解释原因。

529（服务器过载）：追踪连续 529 计数。连续三次且有备选模型？切换模型。后台任务？直接放弃防止级联。前台任务？指数退避重试。

400（上下文溢出）：解析错误消息提取实际 token 数和限制值。重新计算：可用 = 限制 - 输入 - 1000 安全缓冲。设置 3,000 的最低输出下限。调整预算后重试。

退避公式：delay = min(500ms × 2^attempt, 32s) + random(0, 0.25 × baseDelay)

对于无人值守会话（CI/CD 流水线、后台 Agent），系统进入持久重试模式：429 和 529 错误无限重试，最大退避 5 分钟，6 小时硬重置上限，每 30 秒发一次心跳防止被 idle kill。

流式传输层还有自己的可靠性机制：90 秒无数据超时看门狗（45 秒时预警）、连续两个数据块间隔超过 30 秒的停顿检测、流式失败自动回退非流式且保持连续 529 计数不被重复统计。

在 fetch 外面套三次重试不是生产级可靠性。一个理解每种错误语义、并为每种错误提供专门恢复路径的状态机，才是。

09 子 Agent 隔离

子 Agent 获得独立上下文：appState 设置器变为空操作，文件状态缓存被克隆

Claude Code 能生成子 Agent——独立的 Agent 循环实例，各自有自己的上下文、工具和工作目录。终止父 Agent 会级联终止所有子 Agent。但子 Agent 不能修改父 Agent 的状态：appState 的 setter 变成了空操作，文件状态缓存是克隆的。

修改代码的子 Agent 还会获得自己的 Git worktree——一个 Agent 一个工作树，各自在自己的分支上操作。并行 Agent 共享工作区会制造冲突，worktree 隔离让每个 Agent 独立工作，验证通过后再合并。node_modules 做符号链接防止磁盘膨胀——五个并行 Agent 不需要五份依赖副本。

任务协调用的是基于磁盘的任务列表 + 文件锁（指数退避，30 次重试，5-100ms 间隔）。高水位标记防止 reset 后任务 ID 重复。三种执行后端可选：进程内（最快，共享内存）、tmux 面板（终端隔离，每个 Agent 有自己的标签页）、远程（完全机器隔离）。

这些不是什么 AI 黑科技。这就是正经的分布式系统工程——锁、协调、隔离、状态管理、访问控制、资源共享。以前是后端架构师的工作，现在变成了 Agent 开发者的必修课。

10 对我们意味着什么

Rohit 这篇文章给我的最大冲击不是某个具体技巧，而是一个认知升级：模型是商品，环境决定成败。

同一个模型，更好的环境，64% 的性能提升。大部分行业在优化第一层：更大的模型、更高的基准分数。赢家在投资第三层和第四层。

1. Agent 循环用 async generator，不是 while。流式输出、取消、可组合性、背压控制——全部内置于抽象本身。While 循环留了四个缺口。

2. 工具按并发行为分类。只读并行、写入串行。定义时打标签，编排层自动处理分批。2-5 倍提速，零竞态条件。

3. 系统提示词按缓存边界设计。静态内容在前，动态内容在后，边界显式标记。规模化运营时最高杠杆的成本优化。

4. 压缩用层级策略，不是单一方案。便宜的先跑，贵的最后用。只在便宜策略全部失败时才花 token 做总结。

5. 第一天就设计第四层。状态跨会话怎么存？权限怎么扩展到团队？加了并行之后协调怎么做？事后补基础设施比一开始就设计难十倍。

Claude Code 就是证据——一个 55 个目录、331 个模块的 TypeScript 应用，把同一个驱动聊天界面的 Claude 模型变成了一个能无人值守运行数小时、从 API 故障中自动恢复、在千轮会话中管理自身上下文、并协调多个并行子 Agent 在同一个代码库上工作的编程 Agent。

源码就在那里。模式已经被记录。决策清晰可读。

如果你正在搭自己的 Agent 系统，不要从"哪个模型好"开始想。从"我的循环会在第几轮崩"、"我的上下文窗口在第几百条消息时溢出"、"两个 Agent 同时写同一个文件怎么办"这些问题开始想。先搭外壳，再搭基础设施。这才是 Claude Code 真正教会我们的事。

相关链接：

•  原文：https://x.com/rohit4verse/status/2041548810804211936

•  SWE-agent 论文：https://arxiv.org/abs/2405.15793

文章来自于"深思SenseAI"，作者 "深思SenseAI"。