从泄露的源码出发，拆解这个 AI 编程助手背后的
架构理念、设计哲学与工程智慧
Claude Code 是 Anthropic 推出的 AI 编程助手，它直接在你的终端里运行，可以读写文件、执行命令、搜索代码，甚至同时派出多个"分身"并行工作。它不是一个只能回答问题的聊天机器人——它是一个能真正动手干活的 AI 工程师。
当这份源代码意外曝光后，我们终于有机会一窥其内部设计。这份报告将用通俗的语言，为你拆解让 Claude Code 如此强大的核心设计理念。
Claude Code 最核心的设计是一个"循环"——AI 不断地思考、行动、观察结果，然后再思考，直到任务完成。
想象一个人类工程师接到任务后的工作方式：先理解需求，然后打开文件看看代码，试着修改，运行测试，看到报错，再修改……这个过程就是一个循环。Claude Code 把这个人类直觉变成了精密的软件架构。
关键洞察：这个循环没有固定的步数限制。Claude Code 会一直工作，直到它认为任务完成或者需要向你确认。这意味着它可以处理需要几十步才能完成的复杂任务——比如重构一整个模块、修复一个跨越多个文件的 bug，或者从零搭建一个新功能。
在源码中，这个循环由两个关键文件驱动：QueryEngine 负责管理整个对话的生命周期（就像一个项目经理），而 query 则负责执行具体的每一轮对话（就像一线工程师）。它们协作完成：发送消息给 AI → 接收流式回复 → 解析工具调用 → 执行工具 → 把结果反馈给 AI → 重复。
光能"想"还不够，Claude Code 的真正力量在于它能"做"。45 种以上的内置工具让它可以像人类开发者一样操作你的电脑。
读取任何文件——代码、图片、PDF、Jupyter 笔记本。支持按行读取，避免一次性加载巨大文件。
精确替换文件中的指定内容，而非覆盖整个文件。就像人类用"查找替换"一样精确。
用正则表达式在整个项目中搜索代码内容，或按文件名模式查找文件。底层使用极快的 ripgrep。
运行终端命令——安装依赖、运行测试、执行构建、操作 git。这是最强大也最危险的工具。
访问网页获取文档、搜索技术资料。让 AI 能查阅最新的 API 文档和解决方案。
最独特的工具：Claude Code 可以"分裂"出多个独立的子 AI，让它们并行处理不同的子任务。
45+ 个工具如果全部一次性告诉 AI，会浪费宝贵的"思考空间"（上下文窗口）。Claude Code 的解决方案很巧妙：
延迟加载机制（Deferred Tools）：只有最常用的核心工具（读写文件、搜索、执行命令等）在一开始就加载。其余工具（如 MCP 集成、笔记本编辑等）只是告诉 AI "这些工具存在"。当 AI 需要时，它通过 ToolSearch 工具来按需加载具体工具的完整定义。就像手机里的 App——你不需要同时打开所有 App，而是需要的时候再打开。
Claude Code 支持并行工具调用。当 AI 在一次回复中请求多个没有依赖关系的工具（比如同时读取 3 个文件），系统会通过 StreamingToolExecutor 同时执行它们，而不是排队一个一个来。这大幅提升了处理速度。
给 AI 操作电脑的能力，同时确保它不会搞砸事情——这是 Claude Code 最精巧的平衡术。
想象你雇了一个新员工。你不会第一天就给他所有系统的管理员权限，而是根据任务需要，逐步授权。Claude Code 对 AI 的权限管理也是同样的逻辑。
每次 AI 想使用一个工具时，系统都会经历这样的判断链：
安全设计亮点：Claude Code 把工具分成了几个风险等级。读取文件是安全的（只读不写），编辑文件是中等风险，执行 Shell 命令是高风险，删除文件则是破坏性操作。系统默认对高风险操作会弹窗询问，而且你可以用通配符批量授权——比如 Bash(git *) 表示"所有 git 命令都自动通过"。
| 模式 | 行为 | 适用场景 |
|---|---|---|
| 默认模式 | 安全操作自动通过，危险操作弹窗确认 | 日常开发 |
| 计划模式 | 每个操作都需要确认 | 关键操作，需要谨慎 |
| 自动模式 | ML 分类器自动判断是否安全 | 信任度高的环境 |
| 全权委托 | 所有操作直接通过（需明确确认开启） | 自动化流水线 |
AI 的"记忆"（上下文窗口）是有限的。如何在有限的空间里装下最有用的信息，是 Claude Code 最关键的工程挑战之一。
这就像你的办公桌空间是有限的——你不能把所有文件都摊在桌上，需要智能地管理哪些放在手边、哪些存档、哪些可以扔掉。
AI 的"操作手册"——定义了它的角色、可用工具、行为准则。分为可全局缓存的静态部分和每次会话不同的动态部分。
你的"私人备忘录"——从项目根目录到用户主目录逐级搜索，让 AI 了解项目规范和你的偏好。
当前会话的完整对话记录，包括所有工具调用和结果。这是"工作记忆"的核心。
跨对话的长期记忆——记住你的角色、偏好、项目背景。存储在文件系统中，每次对话自动加载。
当对话太长、上下文快满时，Claude Code 不是简单地截断，而是启动自动压缩：
当上下文使用量达到 70% 时，系统发出预警
用 AI 对之前的对话进行精华总结，保留关键决策和结论
摘要后重新注入最近操作的 5 个文件内容（各限 5000 token），确保 AI 不"失忆"
在对话中插入"压缩边界"标记，清晰区分压缩前后的内容
大结果存磁盘：当一个工具返回的结果超过阈值（默认 50,000 字符），系统不会把完整结果塞进上下文，而是把结果保存到磁盘文件，只在上下文中放一个简短摘要和文件路径。AI 需要时可以再去读取。这就像论文里的"详见附录"——正文保持精简，细节随时可查。
Claude Code 最令人惊叹的能力之一：它可以"分裂"出多个独立的 AI 代理，让它们像一个团队一样并行工作。
想象一个项目经理，当面对一个大任务时，他不会自己一步步做完所有事，而是把任务分拆给多个团队成员同时处理。Claude Code 也是这么做的。
| 代理类型 | 特点 | 用途 |
|---|---|---|
| 通用代理 | 拥有全套工具，独立上下文 | 复杂的多步骤任务 |
| 探索代理 (Explore) | 只有只读工具，不能修改代码 | 快速搜索、代码调研 |
| 规划代理 (Plan) | 只读 + 分析，输出实施方案 | 架构设计和方案评估 |
| 自定义代理 | 从 ~/.claude/agents/ 加载自定义配置 | 特定领域的专家代理 |
每个子代理都运行在隔离的上下文中：
实际例子：当你让 Claude Code "给这个项目写单元测试"，它可能会同时派出 3 个子代理：一个探索代理先摸清项目结构，一个分析代理研究现有测试风格，一个通用代理开始写最明显的测试用例。这三个代理并行工作，最终结果汇总回主代理。
每个项目都有自己的规矩——代码风格、提交规范、部署流程。CLAUDE.md 就是你告诉 AI 这些规矩的方式。
这个设计理念非常简单而强大：用一个 Markdown 文件来定义 AI 在这个项目中的行为准则。Claude Code 启动时，会自动搜索并加载这些文件。
系统会从当前工作目录向上逐级搜索，直到文件系统根目录。在每一级目录中，它检查三个位置：CLAUDE.md、.claude/CLAUDE.md、以及 .claude/rules/ 下的所有 Markdown 文件。
@include 指令：CLAUDE.md 支持用 @路径 语法引入其他文件的内容。比如你可以写 @./docs/api-standards.md 来引入 API 规范文档。被引入的文件也会受到相同的大小限制（单个文件最多 40,000 字符），系统会自动检测循环引用。
每次对话结束，AI 的"记忆"就清空了。但 Claude Code 设计了一套文件系统驱动的持久记忆，让 AI 能跨对话保持对你和项目的了解。
关于你的角色、技能、偏好。"这是一位资深 Go 开发者，第一次接触 React。"
你对 AI 行为的修正。"不要在这些测试中 mock 数据库——我们之前因此踩过坑。"
项目的非代码背景信息。"auth 中间件重写是因为法务合规要求，不是技术债。"
外部资源的指引。"pipeline 的 bug 跟踪在 Linear 的 INGEST 项目里。"
每条记忆存储为一个独立的 Markdown 文件，包含结构化的元数据（名称、描述、类型）。所有记忆的索引存在 MEMORY.md 中，每次对话开始时自动加载。
记忆的边界意识：源码中明确规定了记忆系统不应该存什么——代码模式、架构细节、git 历史、调试方案。这些信息可以从代码本身和 git log 获取，存进记忆反而会过时。只有那些不能从代码推断出的非显而易见的信息才值得记忆。这种克制的设计避免了记忆膨胀和过时信息的干扰。
钩子（Hooks）让你可以在 AI 工作流的关键节点插入自定义逻辑——就像在流水线上安装传感器和开关。
这是一个非常强大的扩展机制。你可以用它来：拦截危险的命令、自动格式化代码、记录审计日志、或者与你公司的内部工具集成。
在 AI 使用任何工具之前。可以修改参数、拒绝操作、或追加条件。
在工具执行完毕后。可以审查结果、触发后续动作。
对话刚建立时。用于初始化环境、加载配置。
用户按下回车但消息还未发送时。可以预处理或拦截输入。
钩子以子进程方式执行（Shell 脚本或 Node.js），有超时保护（默认 10 分钟）。它的输出是结构化的 JSON，告诉系统这个操作应该 允许、拒绝 还是 询问 用户。
安全考量：所有钩子的执行都需要通过工作区信任检查。这防止了一个恶意项目通过 .claude/settings.json 中的钩子定义来执行任意代码——只有用户明确信任的工作区才能运行钩子。
MCP（模型上下文协议）是让 Claude Code 能够连接到任何外部服务的标准接口——就像 USB 口让电脑可以连接各种设备。
通过 MCP，你可以把 Slack、GitHub、数据库、内部 API 等任何服务变成 Claude Code 可用的工具。Claude Code 内置了完整的 MCP 客户端。
MCP 工具在 Claude Code 内部被包装成原生工具，命名格式为 mcp__服务名__工具名。默认都是延迟加载的，只在需要时才完整加载定义。MCP 配置支持多层合并——企业策略 → 用户配置 → 项目配置，高优先级覆盖低优先级。
这为什么重要：MCP 让 Claude Code 从一个"本地编程工具"变成了一个"可以与任何系统交互的通用 AI 代理"。你可以让它读 Slack 消息、查 Jira ticket、调用内部微服务——所有这些只需要配置一个 MCP 服务器。
Claude Code 不只是一个终端工具——它通过精巧的"桥接"架构嵌入到 VS Code 和 JetBrains 等 IDE 中。
桥接系统（Bridge）是一个双向通信层，让 IDE 扩展和 Claude Code 核心引擎可以互相通信：
IDE 扩展调用 Bridge API 注册环境，获取唯一标识和密钥
Bridge 持续轮询服务器，等待新的会话请求
收到请求后，Bridge 启动子进程运行 Claude Code 实例
通过 WebSocket 实现实时双向通信——指令下行、结果上行
权限请求转发到 IDE 界面，用户在 IDE 中直接批准或拒绝
这种架构确保了核心逻辑只有一份代码——无论是终端、VS Code 还是 JetBrains，运行的都是同一个 Claude Code 引擎，只是 UI 层不同。
在大型代码库中，响应速度就是生产力。Claude Code 在多个层面进行了极致的性能优化。
启动时同时触发 MDM 配置读取、密钥链访问、特性标志初始化——而不是串行等待，节省 50ms+ 启动时间。
重型模块（OpenTelemetry、gRPC、语音等）只在真正需要时才加载，大幅降低启动内存和时间。
通过 Bun 的 feature flag 系统，未启用的功能在构建时就被完全移除，产物更小更快。
系统提示、文件内容、上下文信息都有 LRU 缓存，配置变更时自动失效。
系统提示分为全局可缓存和会话特定两部分，最大化 API 端的提示缓存命中率，降低延迟和成本。
所有 API 响应和工具执行都是流式的——你不需要等 AI 说完，字一个个出现时就可以开始阅读。
从源码中提炼出的五大设计哲学，解释了为什么 Claude Code 能做到竞品做不到的事。
Claude Code 不是"带 AI 的编辑器"，而是"带编辑器的 AI 代理"。整个架构围绕 Agent Loop 构建——AI 是主角，工具是它的手和眼睛。这意味着用户只需要描述目标，AI 自己规划路径、选择工具、处理错误。
权限系统从不信任开始，逐步授权。你可以从"每步确认"过渡到"自动批准 git 操作"再到"全权委托"。六层权限体系让信任可以精确到单个工具、单条命令。这既保证了安全，又不会把熟练用户烦死。
从 CLAUDE.md 的分级加载、到持久记忆系统、到自动压缩、到工具结果的磁盘存储——每一个设计决策都在回答同一个问题："如何让 AI 在有限的上下文窗口里拥有最丰富、最相关的信息？"
多代理架构不是锦上添花，而是解决复杂问题的核心策略。一个 AI 的上下文窗口不够用？分出子代理，每个有独立的上下文。任务太大？拆成子任务并行处理。这让 Claude Code 可以应对人类工程师也需要团队协作才能完成的大任务。
钩子系统、MCP 协议、自定义代理、自定义技能、插件系统——Claude Code 不试图内置所有功能，而是提供标准化的扩展点。你可以用 MCP 连接 Slack，用钩子添加代码审查规则，用自定义代理创建领域专家。这使得 Claude Code 是一个平台，而不仅仅是一个工具。
从 50 万行源码中，我们看到的不只是精巧的工程实现，更是一种对 AI 辅助编程应该如何工作的深思熟虑。
Claude Code 的设计者显然意识到：让 AI 写代码的关键不在于模型有多聪明，而在于如何让模型在正确的上下文中、用正确的工具、在正确的权限边界内工作。这三个"正确"——上下文管理、工具系统、权限控制——构成了 Claude Code 架构的三大基石。
而多代理架构、钩子系统和 MCP 协议则把这个基石扩展成了一个开放的、可组合的 AI 工程平台。
本报告基于公开泄露的 Claude Code 源码分析撰写，仅作技术研究和教育用途。