Claude Code 源码架构解析：揭秘六个内置 Agent 与对抗性验证设计

前几天，Claude Code 的源码在社区流传开来。为了探究其内部设计，我花了不少时间进行梳理和分析。

首先，我基于泄露的代码实现了一个本地 CLI 工具，它能够调用基本的 Skills 和 MCP（Model Context Protocol）工具，运行起来有模有样。

在梳理过程中，我整理出多份分析材料，例如下面这份关于其内部多Agent协作机制的图示，它清晰地展示了任务如何被分发给不同的智能体并行处理。

当然，最吸引我的还是其源码中体现的工程思想与架构设计。下面，就为大家深入剖析我从这次Claude Code源码分析中学到的关键内容。

01、源码概览与核心模块

从目录结构来看，项目清晰地划分了功能边界：

• tools/: 工具集，提供各种原子能力。
• commands/: 命令系统，处理用户输入。
• skills/: 技能模块，封装复杂行为。
• hooks/: 钩子机制，用于扩展和自定义。

其中几个核心文件的大小揭示了其复杂性：

• main.tsx: 803KB，应该是编译打包后的主入口文件。
• AgentTool.tsx: 233KB，Agent 工具的核心实现。
• insights.ts: 115KB，洞察与分析模块。
• QueryEngine.ts: 46KB，查询引擎核心。
• Tool.ts: 29KB，所有工具的基类。

tools 目录下包含了超过 40 种工具，涵盖了 Bash 执行、文件读写、代码搜索、Web 访问、MCP 集成、远程触发等几乎你能想到的所有操作场景。每一个工具都是一个独立的、可被主 Agent 按需调用的能力单元。

skills/bundled 目录则包含了 17 个内置技能，例如 remember（记忆）、stuck（卡顿诊断）、loop（循环）、batch（批处理）、debug（调试）等。

而 tools/AgentTool/built-in 目录中的 6 个内置 Agent，则是本次分析的重点。

02、六个各司其职的内置 Agent

这 6 个内置 Agent 并非通用，而是各有专精，职责边界非常清晰。

通用目的 Agent

这是一个处理大多数常规任务的“多面手”。其代码非常简洁，只有几十行，定位是处理那些不太复杂、无需特殊专业技能的任务。当遇到超出其能力范围的复杂任务时，它会被调度给更专业的 Agent 处理。

探索 Agent

这是一个只读的探索型 Agent，专门用于在代码库中搜索信息。它的设计哲学非常明确：严禁任何形式的文件修改。

其系统提示词中明确写道：

This is a READ-ONLY exploration task. You are STRICTLY PROHIBITED from:
- Creating new files (no Write, touch, or file creation of any kind)
- Modifying existing files (no Edit operations)
- Deleting files (no rm or deletion)
- Moving or copying files (no mv or cp)

这是一个只读探索任务。你被严格禁止执行以下操作：
• 创建新文件（禁止使用 Write、touch 或任何形式的文件创建）
• 修改现有文件（禁止进行任何 Edit 操作）
• 删除文件（禁止使用 rm 或任何删除行为）
• 移动或复制文件（禁止使用 mv 或 cp）

这种设计将“探索代码”和“修改代码”两种完全不同的心智模式分离开来，既避免了探索过程中的误操作风险，也让 Agent 能更专注地执行搜索任务。

规划 Agent

这是一个架构规划型 Agent，用于设计实现方案。它同样采用只读模式，但其核心任务是理解复杂需求、分析现有架构、并输出可行的实施计划。

它的系统提示词开篇即阐明身份：

You are a software architect and planning specialist for Claude Code.
Your role is to explore the codebase and design implementation plans.

你是 Claude Code 的软件架构师和方案规划专家。
你的职责是对代码库进行探索，并设计实现方案。

验证 Agent

这是我个人在整个源码中最欣赏的部分。这个 Agent 的定位不是去“确认代码能工作”，而是想方设法去“破坏”它。

其系统提示词直截了当：

You are a verification specialist. Your job is not to confirm the implementation works — it's to try to break it.

你是一名验证专家。你的任务不是确认实现是否正常工作，而是想方设法找出它的问题、尝试把它“搞崩”。

更有意思的是，它甚至对自己容易犯的“错误模式”有清醒的认知：

You have two documented failure patterns. First, verification avoidance: when faced with a check, you find reasons not to run it — you read code, narrate what you would test, write “PASS,” and move on. Second, being seduced by the first 80%: you see a polished UI or a passing test suite and feel inclined to pass it, not noticing half the buttons do nothing...

你已经出现过两种典型的失败模式。
第一种是“逃避验证”：当需要进行检查时，你会找各种理由不去真正执行验证，比如只读代码、描述自己“本来会怎么测”，写个“PASS”，然后就结束了。
第二种是“被前 80% 迷惑”：当看到一个看起来很完善的 UI，或者测试用例跑通时，你很容易就给出通过结论，却忽略了其实还有一半的按钮根本没有任何作用……

这种在AI系统中罕见的“自我认知”非常关键。它知道作为LLM的Agent容易偷懒和轻信表面现象，因此在提示词中直接警告：“别偷懒，我知道你会怎么偷懒”。

Claude Code 指南 Agent

这是一个指导型 Agent，专门帮助用户学习如何使用 Claude Code 本身，类似于一个内置的、交互式的帮助系统。当你输入 /help 命令时，背后回应你的很可能就是它。

状态栏设置 Agent

负责配置和更新 IDE 状态栏显示的 Agent。虽然看起来不起眼，但它是 Claude Code 深度集成到开发者IDE环境中的关键一环，直接影响用户体验。

03、Anthropic 的内部特权与差异化设计

在翻阅源码时，我发现了一个有趣的模式：很多内置技能和 Agent 都包含一个特殊的条件判断。

if (process.env.USER_TYPE !== ‘ant’) {
  return
}

这里的 ‘ant’ 是 Anthropic 内部员工的标识。这意味着部分高级功能是内部专享的。

例如，管理自动记忆系统的 remember 技能，以及用于诊断并尝试修复卡死会话的 stuck 技能，都设置了上述检查，仅供内部使用。

另一个差异化设计的例子体现在模型选择上。探索 Agent 的配置中有一行：

// Ants get inherit to use the main agent‘s model; external users get haiku for speed
model: process.env.USER_TYPE === ‘ant‘ ? ‘inherit‘ : ‘haiku‘

内部用户可以继承主 Agent 的模型（通常是能力更强的 Sonnet 或更高阶模型），而外部用户则统一使用更轻量、更快的 Haiku 模型。

这种设计说明 Anthropic 在工程上做了深思熟虑的权衡：对于“探索代码”这种任务，顶级模型带来的边际收益有限，而快速的响应体验更为重要。当然，这也暗示了内部员工在处理更复杂任务时，确实在使用更强大的模型。

04、深入解析验证 Agent：一种对抗性测试思维

验证 Agent 值得单独探讨，因为它代表了一种与传统测试完全不同的思维模式。

传统测试的思路是：设计用例，验证功能是否符合预期。而验证 Agent 的思路是：穷尽一切可能的手段，去证明这段代码存在缺陷。

它的系统提示词中包含一个专门的“对抗性探测”章节：

=== ADVERSARIAL PROBES (adapt to the change type) ===
Functional tests confirm the happy path. Also try to break it:
- **Concurrency** (servers/APIs): parallel requests to create-if-not-exists paths
- **Boundary values**: 0, -1, empty string, very long strings, unicode, MAX_INT
- **Idempotency**: same mutating request twice — duplicate created?
- **Orphan operations**: delete/reference IDs that don‘t exist

=== 对抗式探测项（根据变更类型灵活调整）===
功能测试只能证明正常流程能跑通，你还得主动去想办法把它搞坏：
• 并发场景，适用于 server 或 API：对 create-if-not-exists 这类路径发起并行请求
• 边界值：0、-1、空字符串、超长字符串、Unicode、MAX_INT
• 幂等性：同一个会产生修改的请求连续发两次，看看会不会创建出重复数据
• 孤儿操作：删除或引用根本不存在的 ID

这些不是测试用例，更像是安全渗透测试中的攻击向量。

最“狠”的是它对输出证据的强制要求。它规定，每一次“通过”的结论，必须附带实际执行的命令和真实输出，严禁仅通过“阅读代码”就下结论。

Every check MUST follow this structure. A check without a Command run block is not a PASS — it‘s a skip.

Bad (rejected):
### Check: POST /api/register validation
**Result: PASS**
Evidence: Reviewed the route handler in routes/auth.py. The logic correctly validates...
(No command run. Reading code is not verification.)

每一项检查必须严格按照这个结构执行。如果没有实际执行的 Command run（命令运行）环节，那就不能算 PASS，只能算跳过。

错误示例（不被接受）：
检查：POST /api/register 校验
结果：PASS
证据：查看了 routes/auth.py 中的路由处理逻辑，代码确实做了校验……
（没有执行任何命令。只读代码不算验证。）

这个设计直击了当前 LLM 在测试任务上的一个核心痛点：模型太容易满足于“看起来没问题”。验证 Agent 通过流程强制，要求每一个验证结论都必须有可复现的执行证据，从根本上杜绝了“纸上谈兵”的懒惰行为。

05、通过工具隔离实现权责分离

另一个值得借鉴的设计是 Agent 之间的工具隔离。

每个专用 Agent 都配置了一个 disallowedTools 列表，明确禁止使用某些工具。以探索 Agent 为例：

disallowedTools: [
  AGENT_TOOL_NAME,        // 不能再嵌套调用 Agent
  EXIT_PLAN_MODE_TOOL_NAME,
  FILE_EDIT_TOOL_NAME,    // 不能编辑文件
  FILE_WRITE_TOOL_NAME,   // 不能写文件
  NOTEBOOK_EDIT_TOOL_NAME, // 不能编辑 Notebook
]

规划 Agent 和验证 Agent 都有类似的限制列表。

这种设计的好处是实现了严格的权责分离：

• 探索 Agent 只负责“看”，无权“改”。
• 规划 Agent 只负责“想”，也无权“改”。
• 修改代码这个高权限、高风险的操作，被保留给了主 Agent 或执行特定任务的 Agent。

每个 Agent 都在自己明确的职责边界内工作，互不越界。这完美体现了 Unix 哲学中的一个经典原则：一个工具只做好一件事。

06、三个富有创意的系统设计

除了核心的 Agent 设计，源码中还有几个颇具想象力的系统值得一看。

梦境记忆系统

这个名字本身就充满诗意。它的设计思路是模拟人类睡眠时的记忆整理过程，在后台将零散的对话片段自动整理成结构化的知识。

源码将这个过程分为四个阶段，类比人类的 REM 睡眠周期：

1. 碎片收集：收集最近的对话、代码变更、用户反馈等原始素材。
2. 关联分析：寻找不同信息碎片之间的潜在联系，例如将过去的一个配置问题与当前的一个报错关联到同一个根因。
3. 知识萃取：将关联后的碎片信息，提炼成可复用、可检索的知识点。
4. 记忆索引：将萃取出的知识点存储到向量数据库中，供后续快速检索。

这个设计让 AI 系统不止是一个被动的问答机器，而是一个能够在你“不同”的时候，主动学习和积累经验的伙伴。

安全监控器

系统定义并监控三类主要威胁：提示词注入、范围蔓延和意外损坏。

• 提示词注入：识别用户输入中试图覆盖系统指令的恶意部分，并阻止其执行。
• 范围蔓延：检测任务在执行过程中是否超出了初始设定的范围，并及时提醒用户确认。
• 意外损坏：在执行高危操作（如删除目录）前，扫描相关资源，发现潜在风险（如目录内有未提交代码）则阻止操作。

动态系统提示词拼接

源码中有一个 systemPromptManager，管理者超过 110 条碎片化的系统提示词片段。这些片段会根据运行时环境、任务类型、用户配置等动态拼接成一个完整、贴合当前上下文的提示词。

例如，当运行在 macOS 上时，会拼接关于 macOS 文件路径约定的片段；在调试模式下，会加入额外的调试指令；在处理 Git 操作时，则会附加 Git 相关的安全规范。

这种细粒度的、动态的提示词控制，是 Claude Code 能够表现出高度“情境感知”和“用户理解”能力的技术基础。

07、Claude Code 架构设计的核心启示

分析完源码，我对 Claude Code 的认知彻底改变了。它远不是一个简单的“Claude API 终端包装”，其内部是一套精心设计的、多智能体协作的工程系统。

这些内置 Agent 就像一支专业的开发团队：

• 侦察兵：只读的探索 Agent。
• 架构师：负责规划的 Plan Agent。
• 测试专家：专门“找茬”的 Verification Agent。
• 客服：指南 Agent。
• 多面手：处理杂活的通用 Agent。

最打动我的，不是它们有多“全能”，而是它们有多“克制”。

• 探索 Agent 能查看所有文件，但被禁止修改哪怕一个字符。
• 验证 Agent 能发现所有问题，但被禁止直接动手修复。

这种克制源于深刻的设计哲学：权责分离是产出可靠、可预测结果的前提。一个好的 AI Agent 系统，不在于让单个 Agent 无所不能，而在于通过清晰的边界和协作机制，让每个 Agent 在擅长的领域做到极致。

这次源码的公开，对于整个 AI 和开发者社区而言是一次宝贵的学习机会。Anthropic 在工程实践中摸索出的这套 Agent 设计模式、安全理念和架构思想，为我们构建更可靠、更高效的 AI 应用提供了极具价值的参考。

如果你对这类前沿的开源实战项目分析感兴趣，可以持续关注云栈社区，我们会分享更多深度技术解析和架构思考。