Claude Code 源码分析：被 99% 用户低估的 Agent 编排平台

✍ ZhouZhou·AI🕐 2026-04-01📦 22.2 KB 🟢 已读 𝕏 文章列表

文章深度解析了 Claude Code 的源码架构，指出大多数用户仅将其作为简单的对话工具，忽略了其作为 Agent 编排平台的强大功能。核心发现包括：CLAUDE.md 的每轮重载机制、Subagents 并行化共享 Prompt Cache 的低成本特性、基于配置的权限系统、5 种上下文压缩策略、25+ 生命周期 Hook 系统以及可恢复的 Session 机制。

# Claude Code 源码曝光：最值钱的功能，99% 用户一次都没用过 **作者**: ZhouZhou·AI **日期**: 2026-03-31T15:41:29.000Z **来源**: [https://x.com/boniusex/status/2039005167031644239](https://x.com/boniusex/status/2039005167031644239) --- ![Image](/doc/96/image/img_ef27a07d2cd7.jpg) 翻译原文链接：https://x.com/mal_shaik/status/2038918662489510273?s=20 作者：@mal_shaik 大多数人打开 Claude Code，输入一个 prompt，等它回复，再输入下一个 prompt。这就像买了一辆法拉利，却永远只挂一档开。我想搞明白，为什么有些人用 Claude Code 的产出，明显比别人高 10 倍。所以我做了任何一个理性人都会做的事：我把它的整个源码都读了一遍。（这里说的“我”，当然指的是 Claude Code 自己。） 11 层架构。成千上万行代码。它表面上像一个终端聊天工具，本质上其实是一个 agent 编排平台。下面就是源码真正揭示的：你到底该怎么用这东西。 CLAUDE.md 会在每一轮都被加载。每。一。轮。这是你能做的最高杠杆动作，但几乎没人认真做。大多数人要么根本没有 CLAUDE.md，要么往里面塞进整本圣经。源码显示，Claude Code 会在每一次 query iteration 中重新读取你的 CLAUDE.md 文件，不是在 session 开始时读一次，而是每一轮都重新读。这意味着每次你发一条新消息，它都会重新加载你的指令。它有一整套层级： - ~/.claude/CLAUDE.md：全局层（你的编码风格、偏好） - ./CLAUDE.md：项目层（架构决策、约定） - .claude/rules/*.md：模块化规则 - CLAUDE.local.md：私有笔记（通常 gitignore）你有 40,000 个字符可以用。真的很多。大多数人可能只用了 200 个字。把你的架构决策写进去。把文件命名规则写进去。把测试模式写进去。把“绝对不要这么做”的规则写进去。模型每一轮都会重新读它们。这就是 Claude Code 只是一个通用助手，和 Claude Code 真正成为一个懂你代码库、懂你习惯、懂你规则的“你的助手”之间的区别。如果你看完这篇只做一件事，那就是这件事。 Subagents 共享 prompt cache（并行几乎是免费的）这是最让我震惊的一点。当 Claude Code fork 一个 subagent 时，它会创建一个和父上下文字节级一致的拷贝。API 会对这个做缓存。所以你同时拉起 5 个 agent 去处理代码库不同部分，成本几乎不比 1 个 agent 串行干活高多少。再读一遍。 5 个 agent。成本几乎等于 1 个。因为它们都命中了 prompt cache。大多数人用 Claude Code 的方式像个单线程工人：一次做一件事，等它结束，再给下一个任务。但源码里实际上有三种 subagent 执行模型： - fork：继承父上下文，针对缓存优化 - teammate：单独 pane，运行在 tmux 或 iTerm 里，通过文件邮箱通信 - worktree：每个 agent 拿到独立 git worktree，每个 agent 一个独立分支你完全可以让 Claude Code 一次拉起 5 个 agent：一个做安全审计，一个重构 auth 模块，一个写测试，一个更新文档，一个修 bug。全部同时执行，全部共享缓存。它的架构就是为此而设计的。把它当单线程工具用，简直是一种浪费。权限系统本来就是给你“配置”的，不是给你一直点确认的每次 Claude Code 问你一句 “allow this action?”，然后你去点“yes”，这其实是配置失败，而不是一个 feature。源码揭示了一个 5 层设置级联： policy > flag > local > project > user 你可以在 ~/.claude/settings.json 里配置 glob 规则，让某些操作永远自动允许： { "permissions": { "allow": [ "Bash(npm *)", "Bash(git *)", "Edit(src/**)", "Write(src/**)" ] } } 有三种权限模式： - bypass：完全不做权限检查（危险但快） - allowEdits：自动允许工作目录内文件编辑 - auto：这是新的模式，会用一个 LLM classifier 来判断每次操作是否允许，这是最甜蜜的平衡点 auto 模式也有自己的 allow/deny 列表可以配。源码显示它会并行 race 多个 resolver：用户点击、hook classifier、bridge，谁先返回谁赢。你每停下来点一次“allow”，本质上都是在浪费时间。配置一次，以后就别再点了。有 5 种 compaction 策略。上下文压力是个真正的大问题源码里有 5 种不同的上下文压缩方式，用来处理会话过长的问题： microcompact：基于时间清理旧工具结果 context collapse：总结一段对话跨度 session memory：把关键上下文提取到文件 full compact：总结整个历史 PTL truncation：丢掉最早的一组消息这说明了一个非常重要的事实：上下文溢出是工程师们花了大量精力解决的核心问题。这对你的实际意义是： - 主动用 /compact。别等系统自动压缩，到那时它可能已经把你真正关心的上下文压没了。 - 默认窗口是 200K tokens。但你可以通过 [1m] 模型后缀切到 1M tokens。做跨很多文件的大型重构时，这非常重要。 - 长会话会累积 session memory，包括任务规格、文件列表、工作流状态、错误、经验等结构化摘要。所以恢复一个 session，比重新开一个新的更有价值。 - 大型工具输出会被落盘，而只把一个 8KB preview 发给模型。如果你一次粘了个超大文件，模型看到的可能只是很小一部分，所以输入要尽量聚焦。真正把 Claude Code 用出高产出的人，会把 /compact 当成游戏里的手动存档点。保留重要内容，清掉无关内容，继续推进。 Hook 系统才是真正的扩展 API（25+ 生命周期事件）这是一个几乎没人知道的高级功能。源码里暴露了 25 个以上的生命周期事件可以 hook： - PreToolUse：任何工具执行前触发 - PostToolUse：任何工具执行后触发 - UserPromptSubmit：你发消息时触发 - SessionStart / SessionEnd：会话生命周期 - 以及另外 20 多个同时它支持 5 种 hook 类型： - command：运行 shell 命令 - prompt：通过 LLM 注入上下文 - agent：运行完整 agent 验证循环 - HTTP：调用 webhook - function：运行 JS 你能做的事包括： - 在每次写文件前自动跑 lint - 每次编辑后自动跑测试 - 自动把相关文档注入到每次 prompt - 任务完成时发 Slack 通知 - 在代码落地前验证安全模式是否被遵循其中 UserPromptSubmit hook 最离谱。你可以在每次发消息时自动注入 additionalContext。想象一下：你不用手动说明，就能让每条 prompt 自动带上测试输出、最近 git diff、项目状态。这才是你在 Claude Code 之上搭建“自定义开发环境”的方式。不是靠写更好的 prompt，而是直接钩入系统本身。 Session 是持久化、可恢复的（不要老是从零开始）每个对话都会被保存成 JSONL 文件，路径在： ~/.claude/projects/{hash}/{sessionId}.jsonl 源码支持： - --continue：恢复最近一次 session - --resume：恢复某个指定历史 session - --fork-session：从历史对话分叉出一个新 session（这个我个人非常喜欢） session memory 会在 compaction 过程中保留关键上下文：任务规格、文件列表、工作流状态、错误、经验。大多数人每次打开 Claude Code 都重新开一个 session。这就像你每过一小时就把 IDE 关掉，再从零打开。之前做了什么、哪里失败了、学到了什么，全丢了。用 --continue。永远都用。让上下文积累。让 session memory 在时间中不断沉淀经验。源码都已经把这套基础设施做好了，你就该用起来。工具体系支持 60+ 工具，而且带智能批处理 Claude Code 内置了 60 多个工具。但真正有意思的是，它是怎么调度这些工具的。源码会把工具调用分成两类： - concurrent：只读操作，比如读文件、搜索、glob，会并行执行 - serial：有副作用的操作，比如编辑、写入、bash 命令，会串行执行这意味着，当 Claude Code 需要读 10 个文件来理解你的代码库时，它会同时读 10 个。但当它需要改 3 个文件时，它会一个一个改，避免冲突。在这些内置工具之外，你还可以接入 MCP servers，为系统增加更多工具。源码采用了 deferred loading，也就是 MCP 工具只有在真正需要时才会加载，所以即使你接了 5 个 MCP server，也不会拖慢每一次请求。还有 ToolSearch，可以延迟发现 agent 还不知道的工具。实际上的结论就是：如果你的工作流涉及外部系统，比如数据库、云服务、CI/CD，那就接 MCP servers。架构已经替你处理了复杂性，你只会得到更多能力。流式架构意味着“打断”几乎没有成本整个管线都基于 async generators，逐个 event 流式产出。按 Escape 可以干净地中止当前流，而不会丢掉之前的上下文。这看起来像小事，但实际上会改变你使用 Claude Code 的方式。如果你已经知道它的回答在跑偏，就不要傻等。立刻打断，然后重定向。源码本来就是这么设计的。你的前置上下文会被保留，打断掉的那次回复会被干净丢弃，没有任何额外惩罚。把它想成 pair programming。如果你的搭档开始往错误方向走，你不会等他把错事做完，而是会立刻说：“停，换条路走。” 同样的逻辑。 Retry 系统比你想象的复杂得多源码里实现了这些机制： - 最多 10 次重试，指数退避 + jitter，基础退避 500ms - 当遇到 401/403 时自动刷新 OAuth token - 模型 fallback：如果 Opus 连续 3 次因为 529 失败，会自动切到 Sonnet - 流式输出有 90 秒空闲 watchdog，如果 streaming 卡住，会退回 non-streaming - persistent mode 下是无限重试，最大回退 5 分钟这意味着，Claude Code 本来就是按“可以挂在后台一直跑”的思路设计的。它能优雅处理 API 抖动、限流和暂时性故障。你不需要一直盯着它。让它在后台跑，回来直接看结果就行。 TL;DR：从源码里能提炼出的最高杠杆动作 - 写一个真正有内容的 CLAUDE.md 每一轮都会加载。40K 字符。杠杆最高。 - 用 subagents 并行化 fork 模式共享 prompt cache。5 个 agent 的成本约等于 1 个。 - 在 settings.json 里配权限永久消灭点“allow”的疲劳。 - 主动用 /compact 之所以有 5 种 compaction 策略，是因为上下文压力是真问题。 - 把 hooks 配起来 25+ 个事件、5 种类型。这才是真正的扩展 API。 - 永远用 --continue Reconnecting... 2/5 已处理 1m 8s 我把 Claude Code 的源码读了一遍，所以你不用读了。大多数人打开 Claude Code，输入一个提示词，等回复，再输入下一个提示词。这就像买了一辆法拉利，却永远只挂一档开。我想知道，为什么有些人用 Claude Code 的效率看起来比别人高 10 倍。于是我做了一件任何理性人都会做的事：我把整个源码都读了一遍（当我说“我”，其实当然是 Claude Code 自己读的）。 11 层架构。几千行代码。一个伪装成终端聊天工具的 agent 编排平台。下面是源码真正揭示出来的：到底该怎么用这个东西。 CLAUDE.md 会在每一轮都被加载每一轮。这是你能做的最高杠杆操作，但几乎没人真正用对。大多数人要么根本没有 CLAUDE.md，要么在里面写了一整本圣经。源码显示，Claude Code 会在每一次查询迭代里重新读取你的 CLAUDE.md 文件。不是只在 session 开始时读一次，而是每一轮都会重新读。也就是说，每次你发送一条消息，它都会重新读一遍你的指令。而且它还有完整层级： - ~/.claude/CLAUDE.md：全局层，放你的编码风格和偏好 - ./CLAUDE.md：项目层，放架构决策和约定 - .claude/rules/*.md：模块化规则 - CLAUDE.local.md：私有备注，通常会 gitignore 你有 4 万字符可以用。这非常多。绝大多数人可能只用了 200 个字符。把你的架构决策放进去。把你的文件约定放进去。把测试模式放进去。把“永远不要这样做”的规则放进去。模型每一轮都会重新读它们。这就是 Claude Code 是“一个普通助手”，还是“一个真正懂你的代码库、像你自己团队成员一样工作的助手”之间的差别。如果你读完这篇只做一件事，那就做这个。子代理共享 prompt cache，所以并行几乎是免费的这是最让我震惊的一点。当 Claude Code fork 一个 subagent 时，它会创建一个与父上下文字节级完全一致的副本。API 会缓存这一份上下文。因此同时拉起 5 个 agent 去处理代码库不同部分，成本几乎和 1 个 agent 顺序执行差不多。再读一遍。 5 个 agent。成本接近 1 个。因为它们都命中了 prompt cache。大多数人用 Claude Code 的方式，像是在用一个单线程工人：一次做一个任务，等它结束，再给下一个。但源码里其实内建了三种 subagent 执行模型： - fork：继承父上下文，缓存最友好 - teammate：在 tmux 或 iTerm 的独立 pane 里运行，通过文件邮箱通信 - worktree：给每个 agent 分配自己的 git worktree 和独立分支你完全可以让 Claude Code 同时拉起 5 个 agent： - 一个做安全审计 - 一个重构 auth 模块 - 一个补测试 - 一个更新文档 - 一个修 bug 全部同时跑，而且共享缓存。这套架构从底层就是为并行而设计的。你如果还把它当单线程工具来用，简直是在浪费。权限系统是拿来配置的，不是拿来不停点确认的每次 Claude Code 问你一句 “allow this action?”，你还手动点一次“允许”，这本质上不是功能，而是配置失败。源码揭示了一个 5 层设置优先级链： policy > flag > local > project > user 在 ~/.claude/settings.json 里，你可以用 glob 规则配置哪些操作永远允许： { "permissions": { "allow": [ "Bash(npm *)", "Bash(git *)", "Edit(src/**)", "Write(src/**)" ] } } 它还有三种权限模式： - bypass：完全不检查权限，危险但极快 - allowEdits：自动允许工作目录内的文件编辑 - auto：这是新的，会用一个 LLM classifier 来判断每次操作。这个是最甜点的位置 auto 模式还支持自己的 allow / deny 列表。源码显示，它会并行启动多个 resolver 竞争响应：用户点击、hook classifier、bridge，谁先返回就听谁的。每次你因为点“allow”停下来一次，都是纯浪费时间。一次配置好，以后别再点了。有 5 种 compaction 策略。上下文压力是个真问题源码里有 5 种不同方式来压缩过长的对话： microcompact：基于时间清理旧工具结果 context collapse：总结一段对话跨度 session memory：提取关键上下文写入文件 full compact：总结整段历史 PTL truncation：丢弃最旧的一组消息这说明了一个很重要的事实：上下文溢出是核心问题，工程师们在这件事上花了很多时间。这对你意味着什么？ - 主动使用 /compact。不要等系统自动压缩，把你在意的上下文也一起丢掉。 - 默认窗口是 200K tokens。但你可以通过 [1m] 模型后缀切到 1M tokens。做跨很多文件的大型重构时，这很重要。 - 长 session 会积累 “session memory”，也就是结构化摘要：任务规格、文件列表、工作流状态、错误和经验。这也是为什么恢复一个旧 session 往往比重开一个新 session 更好。 - 大型工具输出会被写到磁盘，发给模型的只有一个 8KB 预览。所以如果你贴了一个超大文件，模型可能只看到了其中一小部分。输入要尽量聚焦。真正用得最猛的人，把 /compact 当成视频游戏里的手动存档点：保留关键上下文，清掉不必要的，然后继续往前推。 Hook 系统才是真正的扩展 API（25+ 生命周期事件）这是几乎没人知道的高级功能。源码显示，Claude Code 有 25 个以上的生命周期事件可以挂 hook： - PreToolUse：任意工具执行前触发 - PostToolUse：任意工具执行后触发 - UserPromptSubmit：你发送消息时触发 - SessionStart / SessionEnd：会话开始 / 结束 - 以及另外二十多个事件它支持 5 类 hook： - command：运行 shell 命令 - prompt：通过 LLM 注入上下文 - agent：运行完整 agent 验证循环 - HTTP：调用 webhook - function：运行 JS 你可以做的事情包括： - 每次写文件前自动跑 lint - 每次编辑后自动跑测试 - 自动把相关文档注入到每次 prompt - 任务完成时发 Slack 通知 - 在代码提交前校验安全规则是否被遵守其中 UserPromptSubmit 这个 hook 最夸张。你可以在每次消息发送时自动注入 additionalContext。想象一下：你每次发 prompt，不用自己手动贴测试结果、最近 git diff 或项目状态，这些都能自动带上。这才是你在 Claude Code 上搭建“自定义开发环境”的方式。不是靠“写更好的 prompt”，而是直接 hook 进系统。 Session 是持久化且可恢复的（别老是从头开始）每一次对话都会以 JSONL 存在： ~/.claude/projects/{hash}/{sessionId}.jsonl 源码支持这些能力： - --continue：恢复上一次 session - --resume：恢复指定过去的 session - --fork-session：从一个旧对话分叉一个新会话（我个人特别喜欢这个） session memory 会在 compaction 之间保留关键上下文：任务规格、文件列表、工作流状态、错误和经验。大多数人每次打开 Claude Code 都新建一个会话。这就像你每隔一小时就关掉 IDE，再从头重开一次。你刚才在做什么、哪里失败了、学到了什么，这些上下文全没了。所以请用 --continue。一直用。让上下文积累。让 session memory 持续长出经验。源码里已经为此写好了整套基础设施，用它。工具系统会智能批处理 60+ 个工具 Claude Code 内建了 60 多个工具。但更有意思的是，它怎么运行这些工具。源码会把工具调用分成两类： - concurrent：只读操作，比如读文件、搜索、glob，会并行跑 - serial：有副作用的操作，比如编辑、写文件、bash 命令，会串行跑，避免冲突也就是说，当 Claude Code 需要读 10 个文件来理解你的代码库时，它会 10 个一起读。但如果它要改 3 个文件，它会一个一个改。除了内建工具外，你还可以接 MCP servers，给它加更多工具。而且源码用了 deferred loading，也就是说 MCP 工具只有在需要时才加载。你连 5 个 MCP server，不会让每次请求都变慢。它甚至还有 ToolSearch，用于延迟发现 agent 还不知道的新工具。实际上的启示是：如果你的工作流涉及外部系统，比如数据库、云服务、CI/CD，就把对应的 MCP server 接进去。底层架构已经替你处理了复杂性，你只会得到更多能力。流式架构意味着“打断”几乎没有成本整个处理链都是基于 async generator 的，会逐个产出事件。按下 Escape 会干净地中止当前流，而不会丢失之前的上下文。这看起来像个小细节，但它会直接改变你该怎么用 Claude Code。如果你已经看出来它要走偏了，不要等它完整回复完。立刻打断，重新引导。源码就是为这种用法设计的。之前的上下文会保留。错误方向的那段响应会被干净地丢弃。几乎没有惩罚。这和结对编程是一样的：如果你的搭档开始往错误方向走，你不会等他把整套方案都写完才说“哎不对”。你会马上打断他说“换这条路”。 Claude Code 也是一样的用法。它的 retry 系统比你想得更复杂源码里包括： - 10 次重试，指数退避 + 抖动（500ms 基础） - 遇到 401/403 自动刷新 OAuth token - 模型 fallback：如果 Opus 连续 3 次因为 529 错误失败，就自动降到 Sonnet - 90 秒 idle watchdog：如果流式输出卡住，就回退到非流式 - 持久模式下是无限重试，最大退避 5 分钟这意味着 Claude Code 是被设计成可以放心放在那里跑的。它会优雅处理 API 抖动、速率限制和短时故障。你不需要全程 babysit。让它在后台跑，过一会回来拿结果就行。 TL;DR：从源码看，杠杆最高的动作是什么？ - 写一个真正有内容的 CLAUDE.md 它每一轮都会被重新加载。4 万字符可用。这是最高杠杆配置。 - 用 subagents 并行 fork 模式共享 prompt cache。5 个 agent 的成本接近 1 个。 - 在 settings.json 里配置权限永远告别不停点允许。 - 主动使用 /compact 有 5 种压缩策略，说明上下文压力是真问题。 - 设置 hooks 25+ 个事件、5 类 hook。这才是真正的扩展 API。 - 始终用 --continue JSONL 持久化 + session memory = 会随着时间积累的上下文。 - 接上 MCP servers 延迟加载意味着不用时几乎没有成本。 - 大胆打断 async generator 架构意味着重定向几乎没有惩罚。最终结论： Claude Code 根本不是一个“带终端界面的聊天工具”。它是一个披着终端 UI 外衣的 agent orchestration platform。那些从 Claude Code 身上压榨出 10 倍生产力的人，并不是更会写 prompt。他们只是： - 配好了它 - 并行化了它 - 给它挂了 hook - 让上下文跨 session 持续积累源码把这些都写得明明白白。现在你也知道，它底层到底是怎么工作的了。 ## 相关链接 - [ZhouZhou·AI](https://x.com/boniusex) - [@boniusex](https://x.com/boniusex) - [3.4K](https://x.com/boniusex/status/2039005167031644239/analytics) - [https://x.com/mal_shaik/status/2038918662489510273?s=20](https://x.com/mal_shaik/status/2038918662489510273?s=20) - [@mal_shaik](https://x.com/mal_shaik) - [Upgrade to Premium](https://x.com/i/premium_sign_up) - [11:41 PM · Mar 31, 2026](https://x.com/boniusex/status/2039005167031644239) - [3,470 Views](https://x.com/boniusex/status/2039005167031644239/analytics) --- *导出时间: 2026/4/1 11:30:15*

🔗 相关文档