逆向深扒Claude Code源码：12层渐进式包装如何炼成工业级智能体

DK_Allen

452人浏览 · 2026-04-02 09:08:43

DK_Allen · 2026-04-02 09:08:43 发布

逆向深扒Claude Code源码：12层渐进式包装如何炼成工业级智能体

Claude Code自发布以来，凭借其强大的自主编码能力迅速成为开发者手中的“王牌AI助手”。它究竟做对了什么？近日，一份基于GitHub泄露源码（v2.1.88，约1884个TypeScript文件、51万行代码）的逆向分析报告在技术圈引发热议。本文提炼报告核心发现，为你揭示Claude Code背后的工程哲学与12层渐进式包装机制。

一、核心洞察：不是模型更强，而是包装更厚

Claude Code之所以优秀，不在于单一技术突破，而在于**12层渐进式包装（Progressive Harness）**将一个最小Agent Loop逐层升级为工业级自主编码代理。其核心竞争力可归结为三个维度：

维度	核心洞察	竞品差距
🏗️ 工程化	编译时DCE + 分层Prompt Cache + 会话持久化 + 流式执行	多数竞品还在单文件Prompt阶段
🤖 Agent架构	多模态子代理 + Fork隔离 + Swarm协调 + Worktree并行	竞品大多只有单层Agent
⚡ Skills系统	按需注入 + CLAUDE.md惰性加载 + 远程Skill搜索	竞品大多是静态Prompt注入

核心文件：query.ts（约785KB）是整个Agent Loop的心脏，所有流式处理、工具调度、上下文压缩、子代理管理都在这个文件中协调。这种“胖核心”设计是刻意的：保持核心循环的原子性，避免分散到多个模块导致的协调复杂度。

二、核心Agent Loop：极简主义的力量

Claude Code的核心是一个极其简洁的while-true循环：

while (true) {
  const response = await api.sendMessage(messages);
  const toolUses = response.filter(block => block.type === 'tool_use');
  if (toolUses.length === 0) break;
  for (const tool of toolUses) {
    const result = await executeTool(tool);
    messages.append({ role: 'user', content: [result] });
  }
}

这就是全部。这个循环的简洁性是Claude Code架构优雅的根本原因。为什么这么简单就够了？因为复杂性被推到了两个地方：

工具层：每个工具自己处理输入验证、权限检查、并发安全性、渲染等
包装层（Harness）：12层机制在这个循环外部叠加production特性

核心循环本身从不改变。添加一个新功能 = 添加一个新工具或一个新的包装层。这是经典的开闭原则在Agent系统中的完美实践。

三、12层渐进式包装机制

这是Claude Code最核心的工程洞察：一个生产级AI Agent需要在基础循环之上叠加12层机制，每一层都建立在前一层之上。在这里插入图片描述

层级	机制	关键源码	工程洞察
s01	Agent Loop	`query.ts`	while-true + tool_use检查 + append
s02	Tool Dispatch	`Tool.ts` + `tools.ts`	`buildTool()`工厂 + 统一注册表
s03	Planning	`EnterPlanModeTool` / `TodoWriteTool`	先列步骤再执行，完成率翻倍
s04	Sub-Agents	`AgentTool` + `forkSubagent.ts`	子代理获得全新messages[]，保持主对话干净
s05	Knowledge On Demand	`SkillTool` + `memdir/`	通过tool_result注入，不污染system prompt
s06	Context Compression	`services/compact/`	三层策略：autoCompact + snipCompact + contextCollapse
s07	Persistent Tasks	`TaskCreate/Update/Get/List`	基于文件的任务图，带状态追踪和依赖关系
s08	Background Tasks	`DreamTask` + `LocalShellTask`	守护线程运行命令，完成时注入通知
s09	Agent Teams	`TeamCreate/Delete` + `InProcessTeammateTask`	持久化队友 + 异步邮箱
s10	Team Protocols	`SendMessageTool`	一个请求-响应模式驱动所有代理间协商
s11	Autonomous Agents	`coordinator/coordinatorMode.ts`	空闲周期 + 自动认领，无需lead逐个分配
s12	Worktree Isolation	`EnterWorktreeTool` / `ExitWorktreeTool`	任务管理目标，worktree管理目录，通过ID绑定

s03 Planning的回报率惊人：从源码注释看，仅仅添加“先列步骤再执行”的机制就使任务完成率翻倍。这与学术界Plan-and-Execute Agent的研究结论一致。

四、工具系统：安全默认与并行执行

4.1 安全默认的设计哲学

每个工具通过buildTool()工厂函数创建，实现统一的生命周期接口。最值得学习的是fail-closed默认值：

const TOOL_DEFAULTS = {
  isEnabled: () => true,
  isConcurrencySafe: () => false,     // 默认：不安全 → 串行执行
  isReadOnly: () => false,             // 默认：有写入 → 需要权限
  isDestructive: () => false,
  checkPermissions: () => 'allow',     // 默认：交给通用权限系统
  toAutoClassifierInput: () => '',     // 默认：跳过安全分类器
};

这意味着：

新增工具时忘记声明并发安全性？→ 自动串行执行（安全的默认）
忘记声明只读？→ 自动触发权限检查（安全的默认）
安全相关工具必须显式覆盖toAutoClassifierInput

4.2 并行工具执行

StreamingToolExecutor是性能关键组件。当Claude API返回多个tool_use blocks时，执行器会分区处理：

isConcurrencySafe() == true → 并行执行（Promise.all）
isConcurrencySafe() == false → 串行执行（顺序await）

这解释了为什么Claude Code在文件搜索这类操作上感觉很快——多个GlobTool/GrepTool调用被并行执行。

五、Prompt工程：分层缓存与代码级编程智慧

5.1 分层缓存架构

Claude Code的system prompt被精心分割为静态前缀和动态后缀，这是prompt cache命中率的关键优化：

System Prompt 结构:
┌─────────────────────────────────────────────┐
│  STATIC PREFIX（全局可缓存）                  │
│  ├── Identity + Intro                       │
│  ├── System Rules                           │
│  ├── Doing Tasks Guidelines                 │
│  ├── Actions Safety Section                 │
│  ├── Using Your Tools Section               │
│  ├── Tone & Style                           │
│  └── Output Efficiency                      │
│                                             │
│  ═══ DYNAMIC BOUNDARY MARKER ═══           │
│  __SYSTEM_PROMPT_DYNAMIC_BOUNDARY__         │
│                                             │
│  DYNAMIC SUFFIX（会话特定，不缓存）          │
│  ├── Session-specific Guidance              │
│  ├── Memory (CLAUDE.md)                     │
│  ├── Environment Info                       │
│  ├── Language / Output Style                │
│  ├── MCP Server Instructions                │
│  └── Scratchpad / FRC / Budget              │
└─────────────────────────────────────────────┘

关键约束（源码注释原文）：

WARNING: Do not remove or reorder this marker without updating cache logic in: src/utils/api.ts (splitSysPromptPrefix), src/services/api/claude.ts (buildSystemPromptBlocks)

这意味着Anthropic在API侧对system prompt做了基于Blake2b哈希的前缀缓存。静态部分跨用户/跨会话共享缓存，极大降低了每次API调用的prompt token成本。

5.2 极简主义编码风格指令

从prompts.ts源码中提取的关键prompt engineering技巧：

❌ "Don't add features, refactor code, or make improvements beyond what was asked"
❌ "Don't add error handling for scenarios that can't happen"
❌ "Don't create helpers or abstractions for one-time operations"
❌ "Three similar lines of code is better than a premature abstraction"

这四条规则反映了Anthropic团队从实践中发现的核心问题：LLM天然倾向于过度工程化。Claude Code通过prompt约束来对抗这个倾向。

5.3 安全行为雕塑

CYBER_RISK_INSTRUCTION是整个prompt中的安全基石：

"Assist with authorized security testing, defensive security, CTF challenges"
"Refuse requests for destructive techniques, DoS attacks, mass targeting"
"Dual-use security tools require clear authorization context"

短短一段话，但经过Safeguards团队精心校准和评估。源码注释明确要求修改必须获得专门团队审批。

5.4 行动安全框架

"Carefully consider the reversibility and blast radius of actions"
"The cost of pausing to confirm is low, while the cost of an unwanted action (lost work, unintended messages sent, deleted branches) can be very high"

设计哲学：量两次，切一次。将操作分为三类：

🟢 可自由执行：编辑文件、运行测试等本地可逆操作
🟡 需确认：git push、创建PR、发消息到外部服务
🔴 高度警惕：rm -rf、force-push、删除分支、drop table

六、上下文管理：三层透明压缩

Context Window 预算分配:
┌─────────────────────────────────────────────────────┐
│  System Prompt (tools, permissions, CLAUDE.md)       │
│  ═══════════════════════════════════════════════     │
│                                                      │
│  Conversation History                                │
│  ┌─────────────────────────────────────────────┐     │
│  │ [older messages → 压缩摘要]                  │     │
│  │ ═══════════════════════════════════════════  │     │
│  │ [compact_boundary marker]                    │     │
│  │ ─────────────────────────────────────────── │     │
│  │ [recent messages — 完整保真度]               │     │
│  └─────────────────────────────────────────────┘     │
│                                                      │
│  Current Turn                                        │
└─────────────────────────────────────────────────────┘

策略	触发条件	机制	Feature Flag
autoCompact	token count超过阈值	调用Claude API对旧消息生成摘要	默认启用
snipCompact	僵尸消息堆积	移除无效消息和过期标记	`HISTORY_SNIP`
contextCollapse	上下文结构性低效	重构上下文组织方式	`CONTEXT_COLLAPSE`

对用户的认知：System prompt告诉模型“The conversation has unlimited context through automatic summarization”——用户和模型都认为对话没有长度限制，但实际上是三层压缩在透明地工作。

Function Result Clearing (FRC)：系统prompt还额外提醒模型：

“Write down any important information you might need later in your response, as the original tool result may be cleared later.”

这是一个精妙的设计——让模型在工具结果还新鲜时主动“记笔记”，防止信息在压缩时丢失。

七、子代理与多代理架构

7.1 四种Spawn模式

模式	实现	隔离级别	使用场景
default	同进程	messages[]共享	简单委派
fork	独立进程	全新messages[]，共享文件缓存	研究性任务、多步实现
worktree	Git Worktree + fork	独立目录 + 全新消息	并行修改不同功能
remote	Bridge to Container	完全隔离	Claude Code Remote

7.2 Fork Agent的精妙之处

源码注释中的设计倡导：

“creates a fork, which runs in the background and keeps its tool output out of your context — so you can keep chatting with the user while it works”

核心价值：Fork代理的工具输出不会回到主代理的上下文窗口。这解决了Agent系统中最常见的问题——上下文污染。主代理可以继续与用户对话，而Fork代理在后台完成研究或实现工作。
在这里插入图片描述

八、Skills系统：按需注入的精髓

8.1 按需注入 vs 预加载

Claude Code的Skills系统最根本的设计决策是：通过tool_result注入知识，而不是通过system prompt预加载。

传统方式（大多数竞品）	Claude Code方式
System Prompt = Base Prompt + ALL Skills + ALL Memory	System Prompt = Base Prompt + Dynamic Boundary + Env Info
每次API调用都携带全部知识	Skills = SkillTool.call() → tool_result → 当需要时注入
浪费token、占据上下文	Memory = CLAUDE.md → 按目录惰性加载
-	知识只在需要时出现在上下文中

8.2 CLAUDE.md惰性记忆系统

~/.claude/CLAUDE.md                  ← 全局级别
<project-root>/CLAUDE.md             ← 项目级别
<project-root>/.claude/CLAUDE.md     ← 项目配置级别
<current-dir>/CLAUDE.md              ← 目录级别

这些文件在loadMemoryPrompt()时被加载到system prompt的动态区域，但只在当前工作目录相关时才被加载。

8.3 Experimental Skill Search

108个缺失模块中最引人注目的是EXPERIMENTAL_SKILL_SEARCH系列，包括远程技能加载器、本地技能搜索、技能预取等。系统prompt中的相关指令：

“Relevant skills are automatically surfaced each turn as ‘Skills relevant to your task:’ reminders. If you’re about to do something those don’t cover, call DiscoverSkillsTool with a specific description.”

这表明Anthropic正在构建一个类似“App Store for Agent Skills”的系统——远程技能可以被动态发现、加载和执行。

九、权限系统：四层防御纵深

Rules：用户定义的权限规则（如Bash(git *)模式匹配）
Hooks：用户编写的shell脚本在工具执行前/后触发
Interactive：会话中临时授权，记住本次会话的授权决定
YOLO模式：bypass permissions，但有独立的安全分类器兜底

十、编译时特征门控

Anthropic使用Bun的feature()编译时内在函数实现Dead Code Elimination：

// 内部构建
feature('DAEMON') → true   → daemon/main.js 保留在bundle中

// 外部构建（npm包）
feature('DAEMON') → false  → daemon/main.js 被DCE移除

已确认的Feature Flags：COORDINATOR_MODE、HISTORY_SNIP、CONTEXT_COLLAPSE、DAEMON、KAIROS、VOICE_MODE、WEB_BROWSER_TOOL、EXPERIMENTAL_SKILL_SEARCH、FORK_SUBAGENT、VERIFICATION_AGENT等。

运行时门控：

process.env.USER_TYPE === 'ant' → Anthropic内部员工功能
GrowthBook feature flags → A/B实验（使用随机词对混淆，如tengu_frond_boric）

十一、未来路线图

11.1 新模型

代号	对应	状态
Numbat（袋食蚁兽）	下一代模型	确认（注释中明确提及）
Opus 4.7	高端模型	开发中
Sonnet 4.8	平衡模型	开发中
Capybara v8	当前Sonnet版本	已服役，有已知问题（29-30%错误声明率）

11.2 KAIROS——全自主代理模式

这是最大的未发布特性。从System Prompt源码：

你正在自主运行。你会收到 <tick> 提示让你保持活跃 — 把它们当作“你醒了，现在要做什么？”多个tick可能被批量放在一条消息中。这很正常——只处理最新的一个。

节奏控制

使用SleepTool控制等待时间。每次唤醒花费一次API调用，但prompt cache在5分钟不活动后过期 — 需要平衡。

偏向行动

Reading files, searching code, making code changes, committing，不需要询问。如果两个合理方案举棋不定，选一个就行。随时可以纠正方向。

十二、对我们的启示

12.1 如果你在构建AI Coding Agent

优先级	行动	Claude Code启发
P0	实现基础Agent Loop + Bash Tool	这就是最小可行产品
P0	添加Planning机制	完成率翻倍的“免费午餐”
P1	实现Sub-Agent + Context Isolation	避免上下文污染
P1	实现三层权限系统	rules + hooks + interactive
P1	按需注入Skills，不要预加载	节省token，提升相关性
P2	实现Context Compression	auto-compact为核心
P2	System Prompt分层缓存	静态/动态分界 → cache命中率
P3	Task Persistence	JSONL append-only日志
P3	Multi-Agent / Swarm	只在单代理证明不够时