第 1 章:认识 Claude Code

Claude Code 的 Agentic Loop 全拆解

一、什么是 Agentic Loop

Agentic Loop(智能体循环)是 AI Agent 系统的核心执行范式。它描述了一个自主系统如何持续地与环境交互、做出决策并执行动作,直到完成目标。这个概念的根源可以追溯到控制论中的反馈循环,但在 LLM 时代被赋予了全新的形态。

1.1 通用模型:观察-规划-行动-反思

学术界对 Agentic Loop 的通用定义通常包含四个阶段:

┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   观察      │────▶│   规划      │────▶│   行动      │────▶│   反思      │
│  (Observe)  │     │  (Plan)     │     │  (Act)      │     │ (Reflect)   │
└─────────────┘     └─────────────┘     └─────────────┘     └──────┬──────┘
                                                                    │
◀───────────────────────────────────────────────────────────────────┘
                              循环反馈
  • 观察(Observe):感知环境状态,收集信息。对 Claude Code 而言,就是读取文件、执行命令、搜索代码库。
  • 规划(Plan):基于观察结果,制定达成目标的策略。Claude Code 会生成 TODO 列表、多步计划。
  • 行动(Act):执行计划中的具体步骤。包括编辑文件、运行测试、调用外部工具。
  • 反思(Reflect):评估行动结果,判断是否达成目标,或需要调整策略。Claude Code 通过测试输出、错误信息来验证。

这个循环持续运行,直到任务完成或达到终止条件。

1.2 从 ReAct 到 Claude Code

2022 年,Yao 等人提出了 ReAct(Reasoning + Acting) 框架,首次将推理与行动显式地交织在一个循环中。ReAct 的核心洞见是:LLM 不应该一次性生成完整答案,而应该通过"思考-行动-观察"的迭代过程逐步逼近目标。

ReAct 循环:
  Thought  →  Action  →  Observation
     ↑                        │
     └────────────────────────┘

Claude Code 的 Agentic Loop 是 ReAct 的工程化实现,但做了关键性的扩展:

维度ReAct(论文)Claude Code(工程实现)
工具数量2-3 个简单工具30+ 内置工具 + MCP 扩展
上下文管理五层 Compaction 管道
安全机制七模式权限系统 + ML 分类器
并行能力单线程子代理并行 + 后台任务
持久化Session 存储 + 检查点
人机协作实时干预 + Plan Mode

正如 Anthropic 官方文档所述:"Claude Code serves as the agentic harness around Claude: it provides the tools, context management, and execution environment that turn a language model into a capable coding agent."1


二、Claude Code 的执行流程全景

2.1 核心架构:三层系统

Claude Code 的架构可以抽象为三个层次:

┌─────────────────────────────────────────────────────────────┐
│                    用户交互层                                │
│         (CLI / VS Code / IDE / Web / Desktop)               │
├─────────────────────────────────────────────────────────────┤
│                    Agent 核心调度层                          │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────────┐   │
│  │ StreamGen│  │ToolEngine│  │Scheduler│  │Compressor   │   │
│  │(流输出)  │  │(工具执行)│  │(查询队列)│  │wU2(压缩)    │   │
│  └─────────┘  └─────────┘  └─────────┘  └─────────────┘   │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │           主循环引擎 nO (Master Agent Loop)          │   │
│  │     while(tool_call) → execute → feed → repeat      │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │         异步双缓冲队列 h2A (实时干预)                 │   │
│  │    支持暂停/恢复,用户可在执行中注入新指令            │   │
│  └─────────────────────────────────────────────────────┘   │
├─────────────────────────────────────────────────────────────┤
│                    工具执行层                                │
│  ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌────────┐  │
│  │ Read │ │ Edit │ │ Bash │ │ Grep │ │ Glob │ │  MCP   │  │
│  │ Write│ │ Skill│ │ Agent│ │ Todo │ │ Web  │ │ ...    │  │
│  └──────┘ └──────┘ └──────┘ └──────┘ └──────┘ └────────┘  │
└─────────────────────────────────────────────────────────────┘

这个架构的核心设计哲学是**"做简单的事优先"**——选择正则表达式而非向量数据库进行搜索,选择 Markdown 文件而非数据库进行记忆存储。PromptLayer 的分析文章指出:"The thesis is straightforward: a simple, single-threaded master loop combined with disciplined tools and planning delivers controllable autonomy."2

2.2 主循环引擎 nO

Claude Code 的心脏是一个极简的 while(tool_call) 循环,内部代号 nO(nO 和 h2A 均为源码 minify 后的标识符,已被多个独立逆向工程分析公开使用)。其伪代码如下:

// 伪代码示意,非源码真实函数名(基于源码分析)
while (true) {
  // 1. 接收当前状态:系统提示 + 对话历史 + 工具定义
  const state = buildContext();

  // 2. 调用 Claude 模型进行推理
  const response = await anthropic.messages.create({ ...state });

  // 3. 解析响应:可能包含文本 + 工具调用请求
  const { text, toolCalls } = parseResponse(response);

  // 4. 如果没有工具调用,循环终止,返回最终结果
  if (toolCalls.length === 0) {
    yield ResultMessage({ text, cost, usage, sessionId });
    break;
  }

  // 5. 执行工具调用(只读工具可并行,写入工具串行)
  const results = await executeTools(toolCalls);

  // 6. 将结果反馈给模型,进入下一轮
  appendToHistory(toolCalls, results);
}

这个循环的优雅之处在于其约束驱动设计

  • 单线程:维护一个扁平的消息历史列表,没有复杂的多线程竞争
  • 最多一个子代理分支:防止代理无限增殖导致的混乱
  • 流式优先:API 响应以 Server-Sent Events 形式增量到达,工具调用在流中即被检测并触发执行

2.3 实时干预机制 h2A

h2A 是一个异步双缓冲队列,它的特殊之处在于支持暂停/恢复,并能在任务执行中无缝融入用户的临时指令。

假设 Claude 正在进行一个复杂重构,你突然意识到需要添加一个约束条件。在传统批处理模式下,你需要停止一切重新开始。但 h2A 允许你将新指令注入队列,Claude 会动态调整计划继续执行。

"This queue cooperates with nO to create truly interactive, streaming conversations. Rather than waiting for one massive completion, users experience a dynamic back-and-forth where they can guide, correct, or enhance Claude's work in real-time."2


三、六步拆解:从用户输入到最终交付

让我们追踪一次完整的 Claude Code 会话,拆解每个步骤的内部机制。

3.1 步骤一:读取代码库(上下文构建)

当用户输入一个任务(如"修复 auth 模块的测试失败"),Claude Code 首先进入上下文收集阶段

文件选择策略

Claude Code 不会一次性读取整个代码库。它采用按需发现策略:

  1. 初始扫描:使用 Glob 工具获取项目结构概览
  2. 关键词搜索:使用 Grep 工具搜索与任务相关的代码片段
  3. 定向读取:使用 Read 工具深入阅读关键文件

值得注意的是,业界曾推测 Anthropic 可能利用其投资的 Voyage AI 进行语义搜索实验,但最终产品采用了基于 ripgrep 的代理式搜索。原因很务实:Claude 已经深刻理解代码结构,能够构造复杂的正则表达式,维护向量索引的复杂性和开销并不值得。

上下文窗口的构成

在 Claude 做任何推理之前,以下信息已经被加载到上下文中:

来源加载时机影响
系统提示每次请求固定小成本,始终存在
CLAUDE.mdSession 启动完整内容(但 prompt-cached)
工具定义每次请求每个工具增加 schema 开销
对话历史跨轮次累积持续增长
Skill 描述Session 启动短摘要,使用时加载完整内容
Auto MemorySession 启动前 200 行或 25KB

据第三方逆向工程分析,"System prompts, tool definitions, MCP schemas, and memory files consume 30,000-40,000 tokens before you type anything. Performance starts degrading around 147K tokens, not 200K."3(非官方确认数据)

3.2 步骤二:规划(思维链与多步计划)

在理解代码库后,Claude 进入规划阶段。这一阶段的核心输出是:

TODO 列表

Claude Code 会调用 TodoWrite 工具创建一个结构化的 JSON 任务列表,包含 ID、内容、状态和优先级。这不仅是内部记账——UI 会将这些渲染为交互式检查清单,让用户看到 Claude 的计划过程。

{
  "todos": [
    { "id": "1", "content": "运行测试套件定位失败用例", "status": "completed", "priority": "high" },
    { "id": "2", "content": "读取 auth.ts 和 auth.test.ts 理解代码", "status": "in_progress", "priority": "high" },
    { "id": "3", "content": "修复认证逻辑中的边界条件", "status": "pending", "priority": "high" },
    { "id": "4", "content": "重新运行测试验证修复", "status": "pending", "priority": "high" }
  ]
}

"Behind the scenes, the system uses reminders to keep Claude focused: after tool uses, system messages inject the current TODO list state, preventing the model from losing track of its objectives in long conversations."2

Plan Mode

对于复杂任务,用户可以显式进入 Plan Mode(按 Shift+Tab 切换)。在此模式下,Claude 仅使用只读工具(Read、Grep、Glob)分析代码库,生成详细计划供用户审阅后再执行。

Plan Mode 的工作流:

用户请求 ──▶ Plan Mode 分析 ──▶ 生成结构化计划 ──▶ 用户审阅/修改 ──▶ 批准执行 ──▶ 实施变更
                │                                              │
                └────────────── 只读工具 only ──────────────────┘

3.3 步骤三:执行(文件编辑与命令执行)

规划完成后,Claude 进入执行阶段,调用工具进行实际操作。

核心工具集

Claude Code 拥有约 30 个内置工具,分为五大类:

类别工具功能
文件操作Read, Edit, Write读取、修改、创建文件
搜索Glob, Grep按模式查找文件、正则搜索内容
执行Bash, Monitor运行 shell 命令、后台监控
WebWebSearch, WebFetch搜索网页、获取页面内容
编排Agent, Skill, AskUserQuestion子代理、技能、询问用户

每个工具遵循统一的接口模式:

// 基于源码分析的示意性接口定义
interface Tool {
  // 1. 输入 schema(执行前用 Zod 验证)
  inputSchema: z.ZodSchema;

  // 2. 权限检查(返回 allow / deny / ask)
  checkPermissions(params): PermissionResult;

  // 3. 执行逻辑
  execute(params): ToolResult;

  // 4. UI 渲染器(终端显示)
  render(result): UINode;  // UI 渲染节点
}

并行工具执行

当 Claude 在单轮中请求多个工具调用时,SDK 会根据工具类型决定执行策略:

  • 只读工具(Read、Glob、Grep、MCP 只读工具):并行执行
  • 状态修改工具(Edit、Write、Bash):串行执行,避免冲突

3.4 步骤四:评估(测试运行与错误分析)

执行后,Claude 需要验证结果。这通常通过运行测试或检查命令输出来完成。

一个典型的评估循环:

Turn 1: Bash(npm test) ──▶ 3 个测试失败
Turn 2: Read(auth.ts) + Read(auth.test.ts) ──▶ 理解代码逻辑
Turn 3: Edit(auth.ts) 修复边界条件 ──▶ Bash(npm test) 重新运行
Turn 4: 所有测试通过 ──▶ 文本回复:"已修复,3 个测试全部通过"

这个评估-修复循环可能重复多次。Claude 会根据错误输出调整策略,形成自纠错行为

3.5 步骤五:调整(回溯与修正)

当执行结果不符合预期时,Claude Code 具备多种调整机制:

检查点回滚

每次文件编辑前,Claude Code 都会创建文件内容的快照(checkpoint)。如果出现问题,用户可以按 Esc 两次回滚到之前的状态,或要求 Claude 撤销更改。

"Every file edit is reversible. Before Claude edits any file, it snapshots the current contents. If something goes wrong, press Esc twice to rewind to a previous state, or ask Claude to undo."1

用户实时干预

用户可以在任何时候中断 Claude 的执行,提供修正指令。Claude 会立即停止当前操作,根据新输入调整方法。

[Claude 正在 investigating...]

用户:"方向不对,问题在 session handling 里。"

[Claude 调整 approach...]

上下文压缩恢复

在长时间会话中,当上下文窗口接近上限时,Claude Code 会自动压缩对话历史。压缩后会执行恢复操作:重新读取最近访问的文件、恢复 TODO 列表、重新注入技能内容,确保工作连续性。

3.6 步骤六:交付

任务完成后,Claude 会:

  1. 生成总结:说明做了什么变更、为什么做、测试结果如何
  2. 展示差异:以彩色 diff 形式展示所有修改,便于审阅
  3. 可选提交:如果用户要求,可以执行 git commit(需要权限批准)
  4. 会话持久化:对话历史保存到 ~/.claude/projects/,支持 /resume 恢复

四、安全机制在 Loop 中的位置

Claude Code 的安全不是单层防护,而是一个五道关卡的权限门控系统,每个工具调用都要经过完整的审批流程:

工具调用 ──▶ [1] 工具级 checkPermissions()
              │    └─ Bash 检查危险命令,Write 检查文件路径
              │
              ▼ [2] Settings 允许/拒绝列表
              │    └─ glob 模式如 Bash(npm run *)、Read(~/project/**)
              │
              ▼ [3] 沙箱策略
              │    └─ 托管限制:路径、命令、网络访问
              │
              ▼ [4] 活动权限模式
              │    └─ default / acceptEdits / plan / auto / dontAsk / bypassPermissions
              │
              ▼ [5] Hook 覆盖
                   └─ PreToolUse hooks 可批准、阻止或修改调用

4.1 权限模式

根据 arXiv 论文和 Anthropic 官方文档,Claude Code 的权限系统包含以下模式:

模式行为适用场景
default首次使用每个工具时请求许可新代码库探索
acceptEdits自动接受文件编辑和常见文件系统命令日常开发
plan只读分析,生成计划供批准复杂重构前
autoML 分类器评估每个动作的风险,自动批准低风险操作研究预览
dontAsk除非预批准,否则自动拒绝严格环境
bypassPermissions跳过所有权限提示(除受保护目录外)CI/容器

注:arXiv 论文提到"seven modes",但官方文档目前公开上述六种。第 7 种可能为实验性模式,具体名称待官方确认。

4.2 ML 权限分类器(Auto Mode)

Auto Mode 的核心是一个ML-based 分类器,它实时评估每个工具调用的风险等级。分类器考虑以下因素:

  • 动作类型:读取文件 vs 运行 bash 命令,基线风险不同
  • 具体参数:写入临时目录 vs 写入生产配置文件
  • 可逆性:操作是否可以撤销
  • 影响范围(Blast Radius):单文件重命名 vs rm -rf
  • 对话上下文:当前任务是否与该操作匹配

基于评估结果,每个动作被路由到三个结果之一:自动批准请求确认完全阻止

"The permission classifier is designed to prevent mistakes, not adversarial attacks. If you're working in an environment where security is a hard requirement, infrastructure-level controls are still necessary."4

4.3 安全机制在 Loop 中的嵌入位置

┌─────────────────────────────────────────────────────────────────┐
│                        Agentic Loop                              │
│                                                                  │
│  用户输入 ──▶ 规划 ──▶ [权限检查] ──▶ 执行 ──▶ 评估 ──▶ 调整   │
│                          │                                       │
│                    分类器评估                                    │
│                    / 模式判断                                    │
│                    / Hook 拦截                                   │
│                          │                                       │
│                    允许 / 询问 / 阻止                            │
└─────────────────────────────────────────────────────────────────┘

权限检查发生在每次工具调用之前,是 Loop 的必经关卡。即使是 Auto Mode 中自动批准的操作,分类器仍然进行了评估——只是没有向用户展示确认对话框。


五、与通用 Agent 框架的对比

5.1 ReAct vs Claude Code

维度ReActClaude Code
推理显式性Thought 显式输出Thinking blocks(可折叠)
工具生态论文中 2-3 个30+ 内置 + MCP 无限扩展
上下文管理截断旧消息五层 Compaction 管道
安全七层权限 + ML 分类器
人机协作实时干预 + Plan Mode
持久化无状态Session 存储 + 检查点

ReAct 是理论框架,Claude Code 是工程实现。Claude Code 保留了 ReAct "思考-行动-观察"的核心循环,但围绕它构建了完整的生产级基础设施。

5.2 Reflexion vs Claude Code

Reflexion 框架引入了自我反思机制:Agent 分析过去的行动和结果,识别错误并提炼策略,将反思文本保存以指导未来决策。

Claude Code 的反思机制体现在:

  • 测试驱动反馈:运行测试,根据失败信息调整代码
  • 错误分析:读取错误输出,定位问题根源
  • Session Memory:后台进程持续维护结构化笔记,积累跨会话经验

但 Claude Code 没有显式的"反思步骤"——反思被内化在 Loop 的评估阶段,是每次工具执行后的自然行为,而非独立的反思环节。

5.3 设计哲学差异

需要强调的是,LangChain 和 LlamaIndex 是面向开发者的构建框架,而 Claude Code 是面向终端用户的应用工具。两者定位完全不同,以下对比的是不同产品形态的设计选择,而非优劣评判:

通用 Agent 框架(LangChain/LlamaIndex)          Claude Code
─────────────────────────────────────        ─────────────
追求通用性、可组合性                          追求简单性、可控性
多代理 swarm、DAG 编排                        单线程主循环 + 受控子代理
复杂的状态管理(数据库/向量存储)              扁平消息历史 + Markdown 记忆
插件化、可扩展至上                            工具化、安全至上

"While competitors chase multi-agent swarms and complex orchestration, Anthropic built a single-threaded loop that does one thing obsessively well—think, act, observe, repeat."2


六、五层上下文压缩管道(Compaction Pipeline)

长时间会话不可避免地会触及上下文窗口上限。Claude Code 的解决方案不是简单的" summarization",而是一个分层降级的压缩管道。

6.1 设计原则

核心思想:能拖则拖,能省则省,逐级升级。从最便宜的操作开始,只在必要时才调用 LLM 进行总结。

成本
^ │  * Full Compact ($$$, LLM 总结)
│ │
│ │  * Session Memory ($0, 增量笔记)
│ │
│ │  * Time-Based MC ($0, 内容清理)
│ │
│ │  * Cached MC (~$0, 缓存编辑 API)
│ │
│ │  * Persist Large ($0, 磁盘存储)
│ └────────────────────────────────────▶ 压缩质量

6.2 五层详解

Layer 0:大结果持久化到磁盘

在压缩发生之前,Claude Code 先在源头控制数据量。当工具返回超过 50K 字符时,完整结果写入磁盘文件,上下文中只保留约 2KB 的预览 + 文件路径。

"Read tool explicitly sets its threshold to Infinity, exempting itself from the persistence mechanism. Persisting Read's output to a file and then having the model Read that file creates a circular dependency."5

Layer 1:缓存微压缩(Cached Microcompact)

据第三方源码分析推测,系统可能利用 Anthropic API 的缓存能力,直接在服务端缓存中删除旧的工具结果,不修改本地消息。这是最高效的压缩方式——零成本、零信息损失(结果仍在磁盘上可读取)。(注:cache_edits API 名称及具体机制为社区推测,非官方确认。)

API Server Cache
+------------------+
| system prompt    │ ◀── cached prefix (保留)
| tools            │
| msg[0]: user     │
| msg[1]: asst     │
| msg[2]: user/tr  │ ◀── cache_edits: delete this
| ...              │
+------------------+

Layer 2:时间微压缩(Time-Based Microcompact)

据第三方分析,当用户离开超过一定时间后,服务端缓存可能已过期。此时清理旧工具结果的代价极低——因为整个前缀都需要重写。系统将保留最近的 N 个工具结果,其余替换为占位符。(注:具体 TTL 时长为社区推测,非官方确认。)

Layer 3:会话记忆压缩(Session Memory Compact)

这是整个系统中最精妙的设计。Session Memory 是一个后台进程,持续维护一个结构化的 Markdown 笔记文件。当需要压缩时,直接使用这些笔记作为总结——无需额外的 LLM 调用

笔记模板包含:当前状态、任务规格、重要文件、工作流、错误与修正、学习总结等。据第三方源码分析推测,后台提取进程可能以独立代理进程运行,与主会话共享 prompt cache prefix。(注:具体实现细节为社区推测,非官方确认。)

"It essentially amortizes the expensive operation of understanding session content across the entire session lifecycle, performing small incremental extractions at regular intervals, so that when compaction is finally needed, the payoff is a free summary."5

Layer 4:完整压缩(Full Compact)

当 Session Memory 不可用或压缩后仍超阈值时,系统回退到完整的 LLM 总结。据第三方分析,这可能通过独立代理进程完成,核心目的是共享主会话的 prompt cache prefix——这样大部分输入命中现有缓存,只需为压缩指令和输出付费。(注:具体实现为社区推测,非官方确认。)

压缩提示采用两阶段结构:先让模型追溯对话时间线(analysis block),再生成结构化总结(summary block)。analysis block 在提取后被剥离,仅作为提高总结质量的草稿纸。

6.3 压缩后的恢复

压缩不是终点。压缩后,Claude Code 会执行恢复操作

  1. 边界标记:标记压缩点
  2. 总结消息:压缩后的工作状态
  3. 重新读取最近文件:最多 5 个,共 50K tokens
  4. 恢复 TODO 列表:保留任务状态
  5. 重新注入技能:按最近使用排序,每技能 5K tokens
  6. 继续指令:告诉 Claude 从何处继续,不再询问用户
This session is being continued from a previous conversation that ran out
of context. The summary below covers the earlier portion of the conversation.

[SUMMARY]

Please continue the conversation from where we left it off without asking
the user any further questions. Continue with the last task that you were
asked to work on.

七、实际案例:追踪一次完整的会话

以下为一个基于典型行为的示意性会话追踪:用户要求"修复 auth 模块中过期卡片用户的结账流程 bug"。

7.1 会话时间线

Turn 1 ──▶ 用户输入:"修复 auth 模块中过期卡片用户的结账流程 bug"
           │
           ▼ 上下文构建
           ├── 加载 CLAUDE.md(项目规则)
           ├── 加载 Auto Memory(过往学习)
           ├── 加载系统提示 + 工具定义
           └── 当前对话历史(空)
           │
Turn 2 ──▶ Claude 规划:创建 TODO 列表
           │  TodoWrite({
           │    "1": "运行测试定位失败用例",
           │    "2": "读取相关源码理解逻辑",
           │    "3": "修复边界条件",
           │    "4": "验证修复"
           │  })
           │
Turn 3 ──▶ Bash(npm test) ──▶ 3 个失败
           │  [权限检查:Bash 工具 → acceptEdits 模式自动批准测试命令]
           │
Turn 4 ──▶ Read(auth.ts) + Read(payments/checkout.ts) + Grep("expired card")
           │  [并行执行:Read 和 Grep 都是只读工具]
           │  [权限检查:Read 无需批准,Grep 无需批准]
           │
Turn 5 ──▶ 分析:发现 token 刷新逻辑在卡片过期时返回 null,
           │        但下游代码未处理 null 情况
           │
Turn 6 ──▶ Edit(auth.ts:45) 添加 null 检查
           │  [权限检查:Edit 工具 → 快照原文件 → 请求用户批准]
           │  [用户点击"Yes"]
           │  [执行:应用 diff,显示彩色差异]
           │
Turn 7 ──▶ Bash(npm test) ──▶ 2 个通过,1 个仍失败
           │
Turn 8 ──▶ Read(auth.test.ts) ──▶ 发现测试用例期望抛出特定错误
           │
Turn 9 ──▶ Edit(auth.ts:45) 修改 null 检查为抛出自定义错误
           │  [权限检查:再次请求批准]
           │
Turn 10 ──▶ Bash(npm test) ──▶ 全部通过
           │
Turn 11 ──▶ 文本回复(无工具调用):"已修复 auth 模块的过期卡片处理
            bug。问题根源:token 刷新在卡片过期时返回 null,下游未处理。
            修改:在 auth.ts:45 添加 CardExpiredError 抛出。所有 3 个测试
            现已通过。"
            │
            ▼ Loop 终止(无工具调用)
            └── 返回 ResultMessage

7.2 关键决策点分析

时刻决策机制
Turn 2创建 TODOTodoWrite 工具 + 系统提醒注入
Turn 3先运行测试模型推理:"先观察再行动"
Turn 4并行读取多个文件只读工具可并行执行
Turn 6请求编辑权限五层权限门控生效
Turn 7-10迭代修复评估-调整循环
Turn 11终止循环响应中无 tool_use 块

八、源码级洞察

2026 年 3 月 31 日,Anthropic 意外通过 npm registry 的 source map 泄露了 Claude Code 的完整 TypeScript 源码(约 1,900 个文件、512,000 行代码)。该事件由安全研究员 Chaofan Shou(@Fried_rice)发现,涉及 npm 版本 v2.1.88,泄露途径为 source map 文件上传至 R2 存储桶。社区镜像仓库(如 soufianebouaddis/claude-code-doc)对源码进行了备份和分析。以下是社区分析揭示的关键实现细节:

8.1 核心循环的实现

源码证实了 PromptLayer 的分析:核心确实是一个简单的 while(tool_call) 循环,没有 DAG、没有分类器、没有 RAG。模型决定一切。

8.2 搜索策略的演进

源码显示早期版本确实实验了基于 Voyage 嵌入的语义搜索,但后来切换为 ripgrep。这验证了 Anthropic "做简单的事优先"的设计哲学。

8.3 44 个隐藏功能标志

源码分析社区报道了若干未发布的功能标志,包括:

  • Agent Teams(多代理协作系统)
  • 后台守护进程(Background Daemons)
  • 高级沙箱模式
  • 实验性模型支持

(注:具体数量和功能名称以社区分析为准,不同来源的统计可能存在差异。)

8.4 五层 Compaction 的工程实现

arxiv 论文《Dive into Claude Code》对 compaction 管道进行了系统性分析:

"Most of the code, however, lives in the systems around this loop: a permission system with seven modes and an ML-based classifier, a five-layer compaction pipeline for context management, four extensibility mechanisms (MCP, plugins, skills, and hooks), a subagent delegation and orchestration mechanism, and append-oriented session storage."6

(注:论文提到"seven modes",但正文未明确指出第 7 种模式的具体名称。)


九、总结:为什么 Claude Code 的 Loop 有效

Claude Code 的 Agentic Loop 之所以有效,不是因为某个单一的技术突破,而是因为系统性的工程约束

  1. 简单循环,复杂周边:核心循环极简(while(tool_call)),但围绕它的权限系统、压缩管道、扩展机制、记忆系统构成了完整的生产级基础设施
  2. 约束驱动设计:单线程、最多一个子代理分支、扁平消息历史——这些约束不是为了限制能力,而是为了保证可调试性和可靠性
  3. 人机协作优先:h2A 队列允许实时干预,Plan Mode 允许先审阅再执行,检查点允许随时回滚——用户始终处于控制地位
  4. 成本意识:五层压缩管道从"零成本磁盘存储"到"免费 Session Memory"再到"付费 LLM 总结",每一步都体现了对 token 成本的精打细算
  5. 安全分层:五层权限门控不是过度工程,而是防御纵深——任何单层都可能被绕过,但五层同时失效的概率极低

正如 PromptLayer 文章的结语:

"The power comes from its radical simplicity. While competitors chase multi-agent swarms and complex orchestration, Anthropic built a single-threaded loop that does one thing obsessively well—think, act, observe, repeat. The same pattern that powers a CS101 while loop now drives an agent capable of refactoring entire codebases. Elegant engineering + constraint-driven design."2


参考来源

Footnotes

  1. Anthropic. "How Claude Code works." Claude Code Docs, 2026. https://code.claude.com/docs/en/how-claude-code-works 2
  2. PromptLayer. "Claude Code: Behind-the-scenes of the master agent loop." PromptLayer Blog, 2025. https://blog.promptlayer.com/claude-code-behind-the-scenes-of-the-master-agent-loop/ 2 3 4 5
  3. MorphLLM. "Claude Code Context Window: Limits, Compaction & Management Guide." 2026. https://www.morphllm.com/claude-code-context-window
  4. MindStudio. "What Is Claude Code Auto Mode? How the Permission Classifier Works." 2026. https://www.mindstudio.ai/blog/what-is-claude-code-auto-mode-permission-classifier
  5. Finisky. "Context Compaction in Claude Code: A Five-Layer Cascade and the Art of Free Summaries." 2026. https://finisky.github.io/en/claude-code-context-compaction/ 2
  6. Liu, Jiacheng, et al. "Dive into Claude Code: The Design Space of Today's and Future AI Agent Systems." arXiv:2604.14228, 2026. https://arxiv.org/html/2604.14228v1