1. 项目概述：为什么我们要拆解 Claude Code 的 50 万行源码？

如果你是一名开发者，最近半年肯定没少听说或者用过 Claude Code。它可能是目前市面上最“聪明”也最“好用”的 AI 编程助手，能理解你的整个代码仓库，自主执行复杂的多步任务，甚至安全地在你本地运行 Shell 命令。但你是否想过，这个看似流畅、智能的 Agent 背后，究竟是如何运作的？当 Anthropic 开源了其核心代码后，我们面对的是一个超过 50 万行 TypeScript 的庞然大物。直接阅读？几乎不可能。这正是我们启动 how-claude-code-works 这个项目的初衷：我们决定和 Claude Code 一起，去阅读它自己的源码，并将这个深度解析的过程和成果，系统地、毫无保留地分享出来。

这不是一篇简单的功能介绍或 API 文档翻译。我们将带你穿透表象，直抵 Claude Code 作为一个 生产级、日活百万的 AI Agent 系统 的核心工程架构。你会发现，它的设计远不止是“调用大模型 API”那么简单。它要解决的是真实世界中的硬核问题：如何处理动辄百万 token 的对话上下文而不崩溃？如何让 66 个工具协同工作而不混乱？如何在模型推理需要几十秒的情况下，让用户感觉“响应飞快”？更重要的是，如何让一个拥有 Shell 执行权限的 AI 既强大又安全，不会一不小心把你的项目目录给 rm -rf 了？

这些问题的答案，都精巧地编织在那 50 万行代码之中。通过这个系列，你将看到的不是一个 demo 级别的玩具框架，而是一个经过大规模实战检验的、充满工程智慧的复杂系统设计。无论你是想从头构建自己的 AI Agent，还是想深度定制 Claude Code 以满足团队需求，抑或是单纯对顶尖的 AI 工程实践感到好奇，这份由代码本身“口述”的架构指南，都将是你最短的路径。

2. 核心架构全景：一个生产级 AI Agent 的骨架

要理解 Claude Code，不能只看它和用户交互的那一层界面。我们需要像做 CT 扫描一样，层层透视其内部结构。整个系统的核心，是一个精心设计的多层流水线，它确保了从用户输入到 AI 思考，再到工具执行和结果呈现的整个流程，既高效又可靠。

2.1 核心循环：Agent 的“心脏”如何跳动？

Claude Code 的核心是一个双层循环结构，我称之为“思考-执行”循环。外层是 QueryEngine 管理的会话生命周期，内层是处理单次用户查询（ query ）的主循环。这个设计巧妙地将长对话的上下文管理（外层职责）与单次推理和工具执行的原子操作（内层职责）解耦。

当用户提出一个问题，比如“帮我在 src/utils 目录下找一个处理日期的函数并优化它”，主循环便开始工作。它并非一次性让模型生成所有答案，而是采用了 流式（Streaming） 的方式。模型每思考并生成一个 token（可能是文字，也可能是一个工具调用的指令），这个 token 就会立刻通过流水线传递到前端界面展示给用户。这就是为什么你感觉 Claude Code 的“思考”过程是连续、实时的，而不是漫长的等待后突然蹦出一大段文字。

更精妙的是 工具预执行（Tool Pre-execution） 机制。当模型在生成“我要读取 src/utils/date.js 文件”这段指令时，系统并不会傻等指令完全生成完毕。它会在后台并行地解析已生成的 token 流，一旦识别出工具调用的意图和关键参数（如文件路径），就会提前发起文件读取操作。这样，当模型终于“想完”并正式发出工具调用请求时，文件内容可能已经躺在缓存里了。这大约 1 秒的 I/O 延迟，就被完美地隐藏在了模型几十秒的“思考时间”窗口内。这是让用户体验感觉“快”的关键魔法之一。

2.2 上下文工程：如何驾驭百万 Token 的“记忆”？

AI 模型的上下文窗口是有限的，而编程对话动辄涉及成千上万个文件片段和历史消息。Claude Code 没有采用粗暴的“截断丢弃”策略，而是设计了一套 四级渐进式压缩流水线 。这就像给你的对话记忆装上了一套智能的垃圾回收和内存整理系统。

1. 裁剪（Truncation） ：第一道防线。系统会优先识别并截断历史消息中那些体积庞大但可能已不再关键的“旧工具输出”，比如很久之前一次 git log 命令返回的几百行结果。
2. 去重（Deduplication） ：几乎零成本的操作。自动识别并合并对话中完全重复的代码片段或描述文本。
3. 折叠（Folding） ：一个非常聪明的设计。对于一段时间内不活跃的对话段落（例如，10 分钟前讨论的另一个无关模块），系统不会删除它们，而是将其“折叠”成一个摘要性的标题。用户看不到详细内容，模型在上下文中也只会看到一个标记，但如有需要，可以随时“展开”恢复完整内容。这平衡了空间节省和信息保留。
4. 摘要（Summarization） ：最后的手段。当以上方法都无法释放足够空间时，系统会启动一个轻量级的“子 Agent”，专门对整段历史对话进行智能摘要，然后用摘要替换掉原始的长篇内容。

这个流水线是“渐进式”的，意味着系统会逐级尝试，一旦某一级释放了足够空间，后面的压缩步骤就不会执行。此外，系统在压缩后还有一个“后悔药”机制： 自动恢复最近编辑的 5 个文件的最新内容 。这确保了 AI 不会在压缩后“失忆”，忘记刚刚正在修改的代码，保证了编程任务上下文的核心连续性。

2.3 工具系统：66个“手和脚”如何协同？

Claude Code 内置了超过 66 个工具，从读文件、写文件、执行 Shell，到搜索代码、调用外部 MCP（Model Context Protocol）服务。管理这么多工具的关键在于 统一的接口规范 和 智能的并发控制 。

所有工具，无论是内置的还是通过 MCP 集成的第三方工具，都遵循同一套 Tool 接口。这意味着它们走的是完全相同的注册、发现、调用和执行流水线，也享受同样的安全检查和权限控制。这种设计极大地提升了系统的可扩展性和一致性。

在并发方面，系统做了自动化的优化： 只读操作（如 read_file , search ）会被自动并行执行 ，以最大化 I/O 效率；而 写操作（如 edit_file , run_shell ）则被强制串行化 ，以防止多个并发的修改导致文件状态混乱或冲突。对于工具产生的大体积输出（超过 100K 字符），系统会自动将其写入临时文件，在上下文中只传递给模型一个文件路径和摘要。当模型确实需要查看全文时，再按需读取。这种“懒加载”策略有效控制了上下文 token 的消耗。

2.4 安全沙箱：五层纵深防御体系

让 AI 在本地自由运行命令，听起来就像在服务器上运行未知脚本一样危险。Claude Code 的安全设计不是靠简单的弹窗确认，而是构建了一个堪称教科书级别的 五层纵深防御体系 。

防御层	核心机制	拦截示例
1. 权限模式	用户预设的信任级别（如“受限”、“正常”、“完全”），从根源上划定 AI 的操作范围。	在“受限”模式下，直接禁止执行任何 Shell 命令。
2. 规则匹配	基于正则表达式或模式的白名单/黑名单规则。	规则 deny: rm -rf 会拦截该命令。
3. Bash AST 深度分析	使用 tree-sitter 解析 Bash 命令生成抽象语法树（AST），进行 23 项语义级安全检查。	分析出 curl $(cat /etc/passwd) 存在命令注入风险；检测 echo $SECRET_KEY 可能泄露环境变量。
4. 用户确认	对于高风险操作，弹出需要用户手动点击的确认对话框。	首次尝试修改 package.json 等核心文件时会请求确认。
5. Hook 校验	开放给开发者的终极扩展层，可以动态审查、修改甚至阻止任何工具调用。	自定义 Hook 给所有 rm 命令自动加上 --dry-run 参数先试运行。

这五层防御是“与”的关系，任何一层成功拦截，命令都不会被执行。其中最硬核的是第三层——Bash AST 分析。它超越了简单的字符串匹配，能理解命令的 真实意图 。例如，它能识别出 sudo 提权、管道符 | 和重定向 > 的数据流、变量替换带来的注入风险等。这种深度的静态分析，是防止新型、变种攻击的关键。

3. 多智能体协作：当 Claude Code 开始“分身”

单个 AI Agent 的能力总有边界。对于复杂的项目，可能需要前端、后端、测试等多个“专家”协同工作。Claude Code 原生支持三种多 Agent 协作模式，每种模式都解决了不同的协同问题。

子 Agent（Sub-agent）模式 是最常见的。主 Agent 可以将一个子任务（如“去写一个单元测试”）分派给一个子 Agent 去执行。子 Agent 拥有独立的思考循环和上下文，执行完毕后将结果返回给主 Agent。这类似于函数调用，但粒度更粗，能力更强。

协调器（Coordinator）模式 则是一种严格的分工。在这个模式下，协调器 Agent 只能分配任务，不能亲自读写文件或执行代码 。它纯粹是一个“指挥官”，负责规划、拆解任务，并指派给其他具有执行权限的 Worker Agent。这种设计强制实现了“规划”与“执行”的分离，有助于生成更清晰、更宏观的项目计划。

最复杂的是 Swarm（蜂群）模式 。多个具有独立名称和身份的 Agent 在一个共享空间中工作，它们可以互相发送消息、分配任务。这模拟了一个小型开发团队的场景。为了防止多个 Agent 同时修改同一个文件导致冲突，系统底层使用了 Git Worktree 机制。每个 Agent 在初始化时，都会获得当前代码仓库的一份独立工作副本（Worktree）。Agent 在自己的副本上修改，只有在完成一个完整阶段或经过协调后，才尝试将变更合并回主分支。这从版本控制层面提供了物理隔离，是解决并发写冲突的优雅方案。

4. 从零到一：如何借鉴 Claude Code 设计自己的 Agent？

阅读庞大源码的目的，最终是为了创造。如果你被 Claude Code 的设计所启发，想动手构建自己的 AI Agent，直接模仿 50 万行的系统无疑是困难的。因此，我们配套创建了 Claude Code From Scratch 项目。

这个项目提供了一个约 4000 行代码的极简实现，剥离了所有生产级的高级特性（如多 Agent、记忆系统、复杂的安全层），只保留最核心的骨架。它清晰地展示了构建一个可工作的 AI 编程 Agent 所必需的 七个最小必要组件 ：

1. 会话管理器 ：管理对话历史和上下文。
2. 流式 API 客户端 ：与大模型（如 Claude）进行流式交互。
3. 工具执行器 ：定义、注册和执行工具（读/写文件，运行命令）。
4. 响应解析器 ：解析模型的流式输出，区分普通文本和工具调用。
5. 上下文构造器 ：将对话历史、系统指令、文件内容等组装成模型所需的提示。
6. 安全护栏 ：一个最基本的安全检查层（例如，禁止某些路径的写入）。
7. 主循环 ：将以上所有组件串联起来的核心逻辑。

通过这个最小实现，你可以快速建立起对 AI Agent 工作流的直观理解。之后，再回过头来看 Claude Code 的源码，你就会明白每一个庞大的模块（如四级压缩、五层安全）都是在解决这个最小系统在规模化和生产化过程中遇到的具体问题。这种“从简到繁”的对照学习，是掌握复杂系统设计的最佳路径。

5. 实战避坑：基于源码分析的开发经验谈

在深度阅读源码和进行配套实践的过程中，我们积累了一些在官方文档中不会提及的“踩坑”经验和设计洞见，这些对于想深度使用或二次开发 Claude Code 的开发者至关重要。

经验一：理解“编辑前强制读取”的防幻觉设计 在 code-editing-strategy.md 中深入分析的“编辑前强制读取”机制，是保证代码编辑准确性的基石。它的实现并非简单调用 read_file 。系统会在模型发出编辑指令时，检查目标文件是否已在当前上下文中。如果没有，它会 中断当前的编辑流程 ，先插入一个 read_file 工具调用，获取文件最新内容后，再让模型基于新内容重新生成编辑。这个设计彻底防止了 AI 基于过时或记忆中的文件内容进行编辑，从而产生幻觉（编辑了不存在的代码行）。在你自定义工具时，如果涉及状态修改，也应考虑类似的“状态前置验证”模式。

经验二：善用 Hooks 进行无侵入式定制 Claude Code 的 Hooks 系统是其可扩展性的核心。它提供了超过 23 个关键事件节点，覆盖了从会话开始、工具调用前后，到响应解析、错误处理的完整生命周期。例如，你可以通过 beforeToolCall Hook 来记录所有工具调用的日志；通过 modifyToolParams Hook 动态修改工具参数（比如总是为 find 命令加上 -type f 参数）；甚至通过 permissionRequest Hook 实现一套完全自定义的权限审批流程。关键在于，这些定制 无需修改核心源码 ，通过配置文件或插件即可完成，保证了与上游版本更新的兼容性。

经验三：CLAUDE.md 是项目级的“系统提示词” 很多用户忽略了项目根目录下的 CLAUDE.md 文件。这实际上是 Claude Code 的 项目级上下文配置文件 。系统在初始化会话时，会自动读取该文件的内容，并将其作为高优先级的系统指令注入上下文。你可以在这里定义项目的技术栈规范（如“使用 TypeScript 严格模式”）、目录结构说明、特定的代码风格要求、甚至是需要避免的“反模式”。合理编写 CLAUDE.md ，能极大地提升 AI 对项目背景的理解准确度和输出质量，效果远超在每次对话中重复说明。

经验四：关注“技能（Skills）”的懒加载与预算管理 Claude Code 的技能系统（如何修复 Bug、如何写测试等）来源多样（内置、项目定义、用户自定义）。它采用懒加载机制，并非一次性将所有技能描述塞入上下文。系统会为“技能描述”分配一个独立的 token 预算池，并根据对话的进展和相关性，动态选择加载哪些技能。这提示我们，在设计 AI Agent 的“知识库”或“操作指南”时，不应追求大而全的一次性灌输，而应采用 按需、分块、动态加载 的策略，以节省宝贵的上下文窗口。

经验五：生产级 Agent 必须处理“优雅降级” 在分析主循环时，我们看到了 7 种不同的 ContinueSite （继续策略）。这本质上是 一套完整的故障恢复和优雅降级机制 。网络超时、API 限流、上下文超长、工具执行失败……在百万日活的生产环境中，错误无处不在。Claude Code 的设计哲学是：尽可能在内部消化错误并重试，仅将无法恢复的致命错误暴露给用户。例如，当一次工具调用失败，系统可能会自动重试；当 token 超限，会自动触发压缩流程。在你的 Agent 设计中，必须为每一个可能失败的外部依赖（模型 API、工具执行、网络 I/O）设计明确的回退和重试路径，这是保证系统鲁棒性的关键。

6. 总结与资源指引

Claude Code 的 50 万行源码，是一部关于如何构建生产级 AI Agent 的鲜活教科书。它展示的不仅是功能，更是在面对真实世界的复杂性、安全性和规模挑战时，一系列经过深思熟虑的工程权衡和架构决策。

如果你想继续深入：

• 快速理解核心 ：建议按顺序阅读 主循环 -> 上下文工程 -> 工具系统 这三篇文档，这是支撑整个系统运行的铁三角。
• 专注安全开发 ： 权限与安全 和 代码编辑策略 两章详细拆解了如何给 AI 系上“安全带”。
• 着手定制开发 ： Hooks 与可扩展性 、 记忆系统 、 技能系统 是进行深度定制的入口。
• 动手实现 ：强烈建议配合 Claude Code From Scratch 项目边学边练，从 4000 行代码的最小原型开始，逐步理解每个模块添加的必要性。

最终，研究 Claude Code 的最大价值不在于复制其代码，而在于理解其背后 解决复杂问题的思路 。如何管理状态？如何设计扩展点？如何平衡能力与安全？这些问题的答案，对于任何正在或即将投身于 AI 原生应用开发的工程师来说，都是无比宝贵的经验。希望这份源自代码深处的解读，能成为你探索 AI Agent 工程世界的一幅可靠地图。