Claude Code 源码深度解析：10 分钟读懂 Claude Code：深度解析当前最成功的 AI 编程 Agent 架构

10 分钟读懂 Claude Code：深度解析当前最成功的 AI 编程 Agent 架构

声明：📝 作者：甜城瑞庄的核桃（ZMJ）
原创学习笔记，欢迎分享，但请保留作者信息及原文链接哦～

文章定位：本文是 Claude Code 开源源码分析的浓缩技术版，面向 AI 应用开发工程师、Agent 系统设计者。核心聚焦于"工程决策"——那些让 Claude Code 从"能用"变成"好用"的关键设计选择。

参考来源：https://diwang.info/how-claude-code-works

源码规模：512,000+ 行 TypeScript，1884 个文件，66+ 内置工具

目录

• 一、Claude Code 是什么
• 二、核心架构全景图
• 三、Agent Loop：系统的灵魂
• 四、上下文工程：血液循环系统
• 五、工具系统：与真实世界交互的手
• 六、代码编辑策略：最核心的能力设计
• 七、权限与安全：7 层纵深防御
• 八、Hooks 与可扩展性
• 九、多 Agent 架构：突破单 Agent 瓶颈
• 十、记忆与技能系统：跨会话学习能力
• 十一、Plan 模式：结构化任务规划
• 十二、任务管理系统：多 Agent 协作的基础设施
• 十三、最小实现 vs 生产级实现
• 十四、系统提示词设计哲学
• 十五、关键数据与文件索引
• 总结

一、Claude Code 是什么

Claude Code 是 Anthropic 发布的CLI 编程 Agent。它不是代码补全工具（GitHub Copilot 那种路线），而是一个受控工具循环 Agent——能理解代码库、编辑文件、执行 Shell 命令、管理 git 的自主编程助手。

1.1 核心解决的工程挑战

1.2 技术栈选型

• 运行时：Bun（更快的 Node.js 替代品，启动速度更快）
• UI 框架：React + Ink（终端 UI 渲染，支持 Flexbox 布局）
• 数据验证：Zod（运行时 Schema 校验，Type-safe）
• 解析工具：tree-sitter（Shell 命令的 AST 级语法分析）
• 语言：TypeScript（1884 个 .ts 文件）

二、核心架构全景图

Claude Code 的整体架构可以用以下层次结构来描述：

┌─────────────────────────────────────────────────────┐ │ 用户输入（REPL 终端 UI） │ └─────────────────────┬───────────────────────────────┘ │ ┌─────────────────────▼───────────────────────────────┐ │ QueryEngine（会话管理层） │ │ • 持久化对话历史 • Token 预算管理 • 用户中断处理 │ └─────────────────────┬───────────────────────────────┘ │ ┌─────────────────────▼───────────────────────────────┐ │ query() 主循环（async generator） │ │ • API 流式调用 • 工具执行 • 错误恢复 │ └──────┬──────────────┬──────────────┬────────────────┘ │ │ │ ┌──────▼──────┐ ┌─────▼──────┐ ┌────▼─────────────────┐ │ 上下文工程 │ │ 工具执行引擎 │ │ 安全权限系统 │ │ • 系统提示词 │ │ • 66+ 工具 │ │ • 规则匹配 │ │ • 4级压缩 │ │ • MCP 集成 │ │ • Bash AST 分析 │ │ • 提示词缓存 │ │ • 并发控制 │ │ • 用户确认 │ └──────┬──────┘ └─────┬──────┘ └────┬─────────────────┘ │ │ │ ┌──────▼──────────────▼──────────────▼─────────────────┐ │ 支撑系统 │ │ • 记忆系统（4种类型+语义召回） │ │ • 技能系统（6层优先级+懒加载） │ │ • Hook 系统（25种事件+4种类型） │ │ • 多 Agent 架构（子 Agent / 协调器 / Swarm） │ └──────────────────────────────────────────────────────┘

架构关键特点：

• QueryEngine（外层）负责会话生命周期，query()（内层）负责单次查询循环
• 两层分离使各自职责清晰，避免交叉污染
• 所有工具统一接口，安全检查、权限控制、并发管理一视同仁

三、Agent Loop：系统的灵魂

Agent Loop 是 Claude Code 最核心的设计模式，理解了它就理解了所有 Coding Agent 的核心运转逻辑。

3.1 基本控制流

Agent Loop 本质是一个带状态机的while(true)循环：

用户输入 │ ▼ 组装上下文（系统提示词 + Git状态 + 消息历史） │ ▼ 调用 Anthropic API（流式输出） │ ▼ 解析响应 ├─── 有工具调用？ ──→ 执行工具 ──→ 注入结果 ──→ 继续循环 │ └─── 仅文本响应？ ──→ 流式输出给用户 ──→ 结束本轮

实际示例：用户输入"重构这个文件里的所有函数名为 snake_case"

1. 模型决策：先读取文件（→ 工具调用：FileReadTool）
2. 读取完成，结果注入上下文
3. 模型分析当前命名风格（→ 文本推理）
4. 逐个编辑函数名（→ 多次 FileEditTool 调用）
5. 验证是否有遗漏（→ 继续循环）
6. 确认全部完成 → 返回最终结果

整个过程可能循环十几次，但对用户来说只是一条指令的等待。

3.2 双层架构设计

┌──────────────────────────────────────────────────────┐ │ QueryEngine（外层） │ │ 职责：会话生命周期管理 │ │ • 对话持久化（跨请求保存） │ │ • Token 预算检查（防止无限循环消耗） │ │ • 用户中断处理（Ctrl+C 优雅退出） │ │ • 会话级状态管理 │ │ │ │ ┌────────────────────────────────────────────────┐ │ │ │ query()（内层） │ │ │ │ 职责：单次循环执行 │ │ │ │ • Anthropic API 流式调用 │ │ │ │ • 响应解析（文本 vs 工具调用） │ │ │ │ • 工具执行与结果回注 │ │ │ │ • 7 种 Continue Sites 错误恢复 │ │ │ └────────────────────────────────────────────────┘ │ └──────────────────────────────────────────────────────┘

为什么要分两层？

会话层关注的问题（用户中断、Token 耗尽、持久化）与查询层关注的问题（API 调用、工具执行、结果拼装）完全不同。分层让每一层逻辑保持单一职责，降低维护复杂度。

3.3 7 种 Continue Sites（自动错误恢复）

这是 Claude Code 用起来"很少报错"的核心原因：

核心设计原则：错误扣留（Error Containment）——可恢复的错误不暴露给调用者，自动修复后继续执行。

3.4 流式并行执行优化

工具预执行（Prefetch Execution）：

时间轴： 0s ─── 模型开始生成输出 3s ─── 解析到工具调用请求（模型仍在生成中） 3s ─── 立即开始执行工具（不等模型输出完成） 8s ─── 模型输出完成 8s ─── 工具执行结果已就绪 8s ─── 直接进入下一轮循环（省去约 1s 工具等待）

用户感受到的是工具"瞬间完成"，实际上是利用了模型生成的 5-30 秒窗口并行执行工具。

StreamingToolExecutor（流式并发执行器）：

• 只读工具（isReadOnly() = true）：自动并行执行
• 写入工具：严格串行，防止文件冲突
• 同时读三个文件 → 三个 FileReadTool 并发执行，总耗时 = 单个文件读取时间

四、上下文工程：血液循环系统

上下文工程是 Claude Code 工程复杂度最高的部分之一。大模型的能力完全取决于"看到什么"——上下文质量直接决定输出质量。

4.1 上下文三层结构

每次 API 调用的上下文由三层组成，稳定性依次降低：

┌─────────────────────────────────────────────────┐ │