Claude Code 架构精读

注：本文是早期总览，后续拆分为 5 篇模块精读。如需最新架构分析，请参阅 总架构（五层架构、queryLoop）及其余模块文档。两者内容有交叉但侧重点不同——本文偏全景概览，模块精读偏实现细节。

项目定位

Claude Code 是 Anthropic 官方的 AI 编程助手，以 CLI 为核心形态，同时支持桌面应用、Web 端（claude.ai/code）和 IDE 扩展（VS Code / JetBrains）。它不是一个简单的”带工具的聊天机器人”，而是一个完整的 AI 辅助软件开发操作系统。

技术栈：Bun runtime + TypeScript + React/Ink（终端 UI）+ Commander.js（CLI 解析）+ Zod v4（schema 校验）+ MCP/LSP 协议

规模：约 1,900 个 TypeScript 文件，512,000+ 行代码，44 个 feature flags 控制未发布功能。

源码泄露事件：2026-03-31，Anthropic 在发布 npm 包 v2.1.88 时未排除 .map（source map）文件，Bun 打包器默认生成的 source map 随生产包发布，任何人下载后可一键还原完整 TypeScript 源码。

五层架构模型

学术论文 arXiv:2604.14228（”Dive into Claude Code”）揭示了一个关键数据：仅 1.6% 的代码是 AI 决策逻辑，98.4% 是确定性基础设施。这意味着 Claude Code 的核心竞争力不在模型本身，而在围绕模型构建的 harness（运行外壳）。

┌─────────────────────────────────────────────────────────────┐
│  Layer 5: 表现层 (Presentation)                              │
│  React/Ink 终端 UI · Vim 模式 · 主题系统 · 进度动画          │
├─────────────────────────────────────────────────────────────┤
│  Layer 4: 意图层 (Intent)                                    │
│  ~80 斜杠命令 · Skill 系统 · Plugin 架构 · 输入路由          │
├─────────────────────────────────────────────────────────────┤
│  Layer 3: 规划层 (Planning)                                  │
│  QueryEngine 核心循环 · System Prompt 组装 · 上下文压缩       │
├─────────────────────────────────────────────────────────────┤
│  Layer 2: 执行层 (Execution)                                 │
│  43+ 工具 · 7 阶段 dispatch pipeline · 流式工具执行器         │
├─────────────────────────────────────────────────────────────┤
│  Layer 1: 基础设施层 (Infrastructure)                        │
│  权限系统 · MCP 生态 · Bridge(IDE) · 会话管理 · 记忆系统     │
└─────────────────────────────────────────────────────────────┘

核心引擎：QueryEngine

QueryEngine 是 Claude Code 的心脏，驱动完整的 LLM 对话循环：

// 简化的核心循环（实际约 1300 行）
class QueryEngine {
  async *submitMessage(): AsyncGenerator<SDKMessage> {
    // 1. 构造 system prompt（含 coordinator 上下文）
    // 2. processUserInput（预处理用户输入）
    // 3. 调用 API（流式）
    // 4. 处理流式响应
    // 5. 管理 tool calls（并行/串行分区）
    // 6. 循环直到模型不再调用工具
  }
}

关键机制：

任务类型系统

Task.ts 定义了 7 种异步任务类型，直接揭示了架构的全部工作模式：

每个任务有统一的状态机：pending → running → completed/failed/killed

工具系统概览

Claude Code 拥有 43+ 个工具，按功能域分组：

文件操作：FileRead、FileWrite、FileEdit、GlobTool、GrepTool、NotebookEdit

Shell 执行：BashTool、PowerShell、REPLTool

Agent/任务管理：AgentTool、TaskCreate/Get/List/Output/Stop/Update、TeamCreate/TeamDelete、SendMessage、TodoWrite

Web：WebFetchTool、WebSearchTool

MCP 集成：MCPTool、McpAuth、ListMcpResources、ReadMcpResource

模式切换：EnterPlanMode/ExitPlanMode、EnterWorktree/ExitWorktree

调度：ScheduleCron(Create/Delete/List)、RemoteTrigger、SleepTool

其他：SkillTool、ConfigTool、BriefTool、LSPTool、ToolSearch、SyntheticOutputTool

每个工具共享统一的 30 方法接口（Tool<Input, Output, P>），包含 inputSchema、checkPermissions、call、prompt、各种 render 方法。

工具执行管道

工具调用经过 7 个阶段：

用户消息 → QueryEngine → API 流式响应
                              ↓
                    StreamingToolExecutor
                    (流完整即启动，隐藏 ~1s 延迟)
                              ↓
                    ┌─────────────────────┐
                    │ 1. 验证 tool name    │
                    │ 2. 推测性分类器      │
                    │ 3. PreToolUse hooks  │
                    │ 4. 权限检查          │
                    │ 5. tool.call()       │
                    │ 6. PostToolUse hooks │
                    │ 7. Analytics event   │
                    └─────────────────────┘
                              ↓
                    并发分区：
                    - isConcurrencySafe=true → Promise.all 并行
                    - isConcurrencySafe=false → 串行执行

流式工具执行器（StreamingToolExecutor）是性能关键：当 API 流式返回多个 tool_use blocks 时，已完整接收的工具立即启动执行，不等待整个响应完成。这隐藏了约 1 秒的工具延迟。

兄弟 abort 机制：如果一个 Bash 工具执行出错，会取消同一轮中尚未启动的兄弟工具调用，避免在错误基础上继续操作。

三层记忆系统

记忆文件使用 frontmatter 格式，支持 [[name]] 双向链接。MEMORY.md 是索引文件，每次会话加载到上下文中。

Feature Flag 系统

Claude Code 通过 GrowthBook + bun:bundle 的 feature() 函数实现死代码消除和渐进式发布：

性能工程

9 阶段并行启动：独立初始化任务并行执行，将启动关键路径压缩到约 235ms。

Prompt Cache 优化：fork 机制通过构建字节一致的 API 请求前缀最大化 cache 命中率。所有 fork 子进程共享相同的请求前缀。

工具延迟隐藏：StreamingToolExecutor 在模型生成期间预解析执行工具，用户感知延迟减少约 1 秒。

懒加载工具：通过 shouldDefer 标记，非常用工具不加载到初始 prompt 中，需要通过 ToolSearch 按需加载，节省 token。

System Prompt 结构

从 system_prompts_leaks 仓库获取的 Claude Code Opus 4.8 系统提示词揭示了完整的 prompt 架构：

<system-reminder>  ← harness 注入的延迟工具列表
  可用但未加载 schema 的工具（需 ToolSearch 激活）
</system-reminder>

<system-reminder>  ← MCP 服务器使用说明
  各 MCP 服务器的工具使用指南
</system-reminder>

<system-reminder>  ← 可用 Skills 列表
  deep-research / update-config / verify / code-review / ...
</system-reminder>

# System Prompt    ← 核心身份和行为规范
  角色定义 + 安全边界 + 输出格式

# Harness          ← 运行环境约束
  工具权限模式 / hook 机制 / 代码引用格式

# Memory           ← 记忆系统规范
  文件格式 / 索引维护 / 去重规则

# Environment      ← 运行时环境信息
  工作目录 / 平台 / 模型版本 / 可用形态

# Context management ← 上下文压缩说明

关键设计洞察

1. Harness > Model：98.4% 确定性代码 + 1.6% AI 决策逻辑。核心竞争力在 harness 而非模型。

2. Fail-closed 安全：权限系统默认拒绝，工具调用必须通过权限检查才能执行。

3. 编排显式化：从 Coordinator 的 prompt 注入到 Dynamic Workflows 的代码化脚本，编排逻辑越来越显式和可审计。

4. 模型即 Runtime：Claude Code 将 LLM 从”对话伙伴”变成了”执行引擎”——模型决定调用什么工具、以什么顺序、是否并行。

5. 渐进式降级：从远程 CCR（最强）→ 本地 Opus（强）→ Haiku 子 agent（快），根据任务复杂度自动选择执行策略。

参考资源