ClaudeCode源码深度研究报告-260331+资源地址
发布日期：2026/4/1 7:46:20 浏览量：
ClaudeCode源码深度研究报告
March31,2026
资源地址：
https://github.com/sanbuphy/claude-code-source-code
https://github.com/instructkr/claude-code
1.1目录. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
2 1.研究范围与结论总览4
2.1 1.1这次到底研究了什么. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
2.2 1.2关键确认事实. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
2.3 1.3先给最重要的总判断. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
3 2.源码结构全景：它为什么更像AgentOperatingSystem 5
3.1 2.1顶层结构暴露出的系统复杂度. . . . . . . . . . . . . . . . . . . . . . . . . 5
3.2 2.2入口层说明它是平台，而不是单一界面. . . . . . . . . . . . . . . . . . . . 6
3.3 2.3命令系统是整个产品的操作面板. . . . . . . . . . . . . . . . . . . . . . . . 6
3.4 2.4Tools层才是模型真正“能做事”的根. . . . . . . . . . . . . . . . . . . . . 7
4 3.系统提示词总装：prompts.ts的真实地位7
4.1 3.1真正的主入口：src/constants/prompts.ts . . . . . . . . . . . . . . . 7
4.2 3.2getSystemPrompt()不是文本，而是编排器. . . . . . . . . . . . . . . . 8
4.2.1静态前缀（更适合cache）. . . . . . . . . . . . . . . . . . . . . . . . 8
4.2.2动态后缀（按会话条件注入）. . . . . . . . . . . . . . . . . . . . . . . 8
4.3 3.3Promptcacheboundary：基础设施级思维. . . . . . . . . . . . . . . . . 8
5 4.Prompt全量提取与模块级拆解9
5.1 4.1身份与基础定位：getSimpleIntroSection() . . . . . . . . . . . . . . 9
5.2 4.2基础系统规范：getSimpleSystemSection() . . . . . . . . . . . . . . . 9
5.3 4.3做任务哲学：getSimpleDoingTasksSection() . . . . . . . . . . . . . 10
5.4 4.4风险动作规范：getActionsSection(). . . . . . . . . . . . . . . . . . . 10
5.5 4.5工具使用规范：getUsingYourToolsSection() . . . . . . . . . . . . . 10
5.6 4.6Session‑specificguidance：运行时可变的局部指令. . . . . . . . . . . . . 11
5.7 4.7Outputefficiency：高价值但常被忽视的section . . . . . . . . . . . . . . 11
5.8 4.8Toneandstyle：统一交互感受. . . . . . . . . . . . . . . . . . . . . . . . 11
5.9 4.9DEFAULT_AGENT_PROMPT：子Agent的基础人格. . . . . . . . . . . . 12
1
6 5.AgentPrompt与built‑inagents深挖12
6.1 5.1AgentTool/prompt.ts：Agent协议说明书. . . . . . . . . . . . . . . . 12
6.2 5.2fork语义为什么很强. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
6.3 5.3“Howtowritetheprompt”一节非常值钱. . . . . . . . . . . . . . . . . 13
6.4 5.4built‑inagents：职责分工而不是万能worker . . . . . . . . . . . . . . . . 13
6.5 5.5ExploreAgent：纯读模式的代码探索专家. . . . . . . . . . . . . . . . . . 13
6.5.1绝对只读. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
6.5.2核心能力. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
6.6 5.6PlanAgent：纯规划，不做编辑. . . . . . . . . . . . . . . . . . . . . . . . 14
6.7 5.7VerificationAgent：为什么它非常值钱. . . . . . . . . . . . . . . . . . . 14
7 6.Agent调度链深挖：从AgentTool到runAgent再到query 15
7.1 6.1总体调用链长什么样. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
7.2 6.2AgentTool.call()：真正的调度总控. . . . . . . . . . . . . . . . . . . . 15
7.3 6.3forkpathvsnormalpath . . . . . . . . . . . . . . . . . . . . . . . . . . 16
7.3.1 forkpath. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
7.3.2 normalpath. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
7.4 6.4为什么fork会强调cache‑identicalprefix . . . . . . . . . . . . . . . . . 16
7.5 6.5backgroundagent与foregroundagent是两套生命周期. . . . . . . . . 17
7.5.1 backgroundpath特点. . . . . . . . . . . . . . . . . . . . . . . . . . 17
7.5.2 foregroundpath特点. . . . . . . . . . . . . . . . . . . . . . . . . . . 17
7.6 6.6runAgent()：真正的子Agentruntime. . . . . . . . . . . . . . . . . . . 17
7.7 6.7agent‑specificMCPservers：真正的additive能力注入. . . . . . . . . . 18
7.8 6.8frontmatterhooks与frontmatterskills . . . . . . . . . . . . . . . . . . 18
7.9 6.9query()才是最终主循环执行器. . . . . . . . . . . . . . . . . . . . . . . 18
7.106.10transcript/metadata/cleanup：产品化runtime的证据. . . . . . . . 18
8 7.Skills/Plugins/Hooks/MCP生态深挖19
8.1 7.1Skill：不是文档，而是workflowpackage. . . . . . . . . . . . . . . . . . 19
8.1.1 Skill的本质. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
8.2 7.2Plugin：Prompt+Metadata+RuntimeConstraints . . . . . . . . . . . 19
8.3 7.3Hook：运行时治理层. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
8.4 7.4Hook与权限的耦合方式非常成熟. . . . . . . . . . . . . . . . . . . . . . . 20
8.5 7.5MCP：不只是工具桥，还是行为说明注入通道. . . . . . . . . . . . . . . . 20
9 8.权限、Hook、工具执行链深挖21
9.1 8.1toolExecution.ts：真正的工具runtime主线. . . . . . . . . . . . . . 21
9.2 8.2输入校验：先挡低级错误. . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
9.3 8.3PreToolUsehooks：最关键的拦截点. . . . . . . . . . . . . . . . . . . . . 21
9.3.1 updatedInput . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
9.3.2 permissionBehavior . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
9.3.3 preventContinuation. . . . . . . . . . . . . . . . . . . . . . . . . . . 22
9.4 8.4resolveHookPermissionDecision()：权限语义的关键粘合层. . . . . 22
9.5 8.5工具执行后也不是结束. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
2
109.为什么ClaudeCode这么强：从源码看它真正的护城河22
10.19.1它不是一个prompt，而是一个operatingmodel . . . . . . . . . . . . . . 22
10.29.2它把“好行为”制度化了. . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
10.39.3它特别懂“上下文是稀缺资源”. . . . . . . . . . . . . . . . . . . . . . . . 23
10.49.4Agentspecialization是很深的设计优势. . . . . . . . . . . . . . . . . . . 23
10.59.5它的生态不是“可安装”，而是“模型可感知” . . . . . . . . . . . . . . . . 24
1110.关键文件索引与后续可继续深挖方向24
11.110.1核心Prompt文件. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
11.1.1主系统提示词. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
11.1.2AgentToolPrompt . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
11.1.3SkillToolPrompt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
11.1.4其他可继续挖的tool‑specificprompt . . . . . . . . . . . . . . . . . . 24
11.210.2核心Agent文件. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
11.2.1built‑inagents. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
11.310.3核心Skill/Plugin/Hook/MCP文件. . . . . . . . . . . . . . . . . . . 25
11.3.1Skill . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
11.3.2Plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
11.3.3Hook . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
11.3.4Toolexecution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
11.3.5MCP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
11.410.4如果继续做下一轮，还能怎么挖. . . . . . . . . . . . . . . . . . . . . . . 25
11.510.5最终结论. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
3
基于@anthropic-ai/claude-code npm 包的 cli.js.map 还原源码后完成
的系统性研究。本文是单文件、长篇、研究报告版，重点覆盖：整体架构、系统提示
词、Agent提示词、Skills、Plugins、Hooks、MCP、权限与工具调用机制，以及
新增的全量Prompt提取框架分析与Agent调度链深挖。
1.1 目录
1. 研究范围与结论总览
2. 源码结构全景：它为什么更像AgentOperatingSystem
3. 系统提示词总装：prompts.ts的真实地位
4. Prompt 全量提取与模块级拆解
5. Agent Prompt 与built‑in agents 深挖
6. Agent 调度链深挖：从AgentTool到runAgent再到query
7. Skills / Plugins / Hooks / MCP 生态深挖
8. 权限、Hook、工具执行链深挖
9. 为什么ClaudeCode这么强：从源码看它真正的护城河
10. 关键文件索引与后续可继续深挖方向
2.1 1.1这次到底研究了什么
这次不是只看某一个prompt文件，也不是只做“目录级扫一眼”。这次研究的核心，是把
cli.js.map 中的sourcesContent还原成可读源码后，沿着以下主线做系统性拆解：
‧ ClaudeCode的整体源码结构
‧ 主系统提示词如何动态拼装
‧ AgentTool/SkillTool 的模型侧协议
‧ built‑in agents 的角色分工
‧ Agent调度链路如何跑通
‧ Plugin/Skill / Hook / MCP如何接入并影响运行时
‧ Permission / Tool execution / Hook decision 如何协同
‧ 它为什么在体验上比“普通LLM+工具调用器”强很多
本次已经确认：
1. npm包里的cli.js.map包含完整sourcesContent
2. 已从map中提取出4756个源码文件
3. 主系统提示词核心文件为：
4
‧ src/constants/prompts.ts
4. Agent Tool Prompt 核心文件为：
‧ src/tools/AgentTool/prompt.ts
5. Skill Tool Prompt 核心文件为：
‧ src/tools/SkillTool/prompt.ts
6. Agent 调度核心文件至少包括：
‧ src/tools/AgentTool/AgentTool.tsx
‧ src/tools/AgentTool/runAgent.ts
7. 工具执行链核心文件至少包括：
‧ src/services/tools/toolExecution.ts
‧ src/services/tools/toolHooks.ts
Claude Code 的强，不是来自某个“神秘systemprompt”，而是来自一个完整的软件工程系
统：
‧ Prompt不是静态文本，而是模块化runtimeassembly
‧ Tool 不是直接裸调，而是走permission/hook/analytics / MCP‑aware execution
pipeline
‧ Agent不是一个万能worker，而是多种built‑in/fork/subagent的分工系统
‧ Skill 不是说明文档，而是prompt‑nativeworkflowpackage
‧ Plugin不是外挂，而是prompt+metadata+runtimeconstraint的扩展机制
‧ MCP不是单纯工具桥，而是同时能注入工具与行为说明的integrationplane
一句话总结：
ClaudeCode的价值，不是一段prompt，而是一整套把prompt、tool、permission、
agent、skill、plugin、hook、MCP、cache和产品体验统一起来的AgentOperating
System。
3 2. 源码结构全景：它为什么更像AgentOperatingSystem
3.1 2.1顶层结构暴露出的系统复杂度
从提取出来的src/顶层看，ClaudeCode至少有这些重要模块：
‧ src/entrypoints/：入口层
‧ src/constants/：prompt、系统常量、风险提示、输出规范
‧ src/tools/：工具定义与具体实现
‧ src/services/：运行时服务，例如tools、mcp、analytics
5
‧ src/utils/：底层共用能力
‧ src/commands/：slashcommand与命令系统
‧ src/components/：TUI/UI组件
‧ src/coordinator/：协调器模式
‧ src/memdir/：记忆/memoryprompt
‧ src/plugins/与src/utils/plugins/：插件生态
‧ src/hooks/与src/utils/hooks.js：hook系统
‧ src/bootstrap/：状态初始化
‧ src/tasks/：本地任务、远程任务、异步agent任务
这已经说明它不是简单CLI包装器，而是一个完整运行平台。
可见入口包括：
‧ src/entrypoints/cli.tsx
‧ src/entrypoints/init.ts
‧ src/entrypoints/mcp.ts
‧ src/entrypoints/sdk/
也就是说它从设计上就考虑了：
‧ 本地CLI
‧ 初始化流程
‧ MCP模式
‧ SDK消费者
这是一种平台化思维：同一个agentruntime，可以服务多个入口和多个交互表面。
src/commands.ts 暴露出非常多系统级命令，例如：
‧ /mcp
‧ /memory
‧ /permissions
‧ /hooks
‧ /plugin
‧ /reload-plugins
‧ /skills
‧ /tasks
‧ /plan
‧ /review
‧ /status
‧ /model
‧ /output-style
‧ /agents
6
‧ /sandbox-toggle
这说明命令系统不是“锦上添花”，而是用户与系统运行时交互的重要控制面。
更关键的是，它不仅注册builtincommands，还统一加载：
‧ plugincommands
‧ skill commands
‧ bundledskills
‧ 动态skills
‧ 可用性过滤后的commands
所以commandsystem本身就是生态入口。
从prompt和工具名能确认的重要工具包括：
‧ FileRead
‧ FileEdit
‧ FileWrite
‧ Bash
‧ Glob
‧ Grep
‧ TodoWrite
‧ TaskCreate
‧ AskUserQuestion
‧ Skill
‧ Agent
‧ MCPTool
‧ Sleep
工具层的本质，是把模型从“回答器”变成“执行体”。ClaudeCode的强，很大程度来自
这层做得正式、清晰、可治理。
4.1 3.1真正的主入口：src/constants/prompts.ts
这份文件是整个系统最关键的源码之一。不是因为它写了一大段神奇文案，而是因为它承担了：
‧ 主系统提示词的总装配
‧ 环境信息注入
‧ 工具使用规范注入
‧ 安全与风险动作规范
‧ Session‑specific guidance 注入
‧ language/output style 注入
7
‧ MCPinstructions 注入
‧ memoryprompt注入
‧ scratchpad 说明注入
‧ function result clearing 提示注入
‧ brief/ proactive / token budget 等 feature‑gated section 注入
Claude Code 的prompt不是静态字符串，而是一个systempromptassemblyarchi
tecture。
getSystemPrompt() 里最核心的结构，是先构造静态部分，再加上动态部分。你可以把它理
解成：
‧ getSimpleIntroSection()
‧ getSimpleSystemSection()
‧ getSimpleDoingTasksSection()
‧ getActionsSection()
‧ getUsingYourToolsSection()
‧ getSimpleToneAndStyleSection()
‧ getOutputEfficiencySection()
4.2.2 动态后缀（按会话条件注入）
‧ session guidance
‧ memory
‧ antmodeloverride
‧ envinfo
‧ language
‧ outputstyle
‧ mcpinstructions
‧ scratchpad
‧ function result clearing
‧ summarizetoolresults
‧ numericlengthanchors
‧ tokenbudget
‧ brief
这个设计非常值钱，因为它不是“把能想到的都写进systemprompt”，而是把prompt当
作可编排运行时资源来管理。
源码中明确存在：
‧ SYSTEM_PROMPT_DYNAMIC_BOUNDARY
8
并且注释说明：‑边界前尽量可cache‑边界后是用户/会话特定内容‑不能乱改，否则会
破坏cache逻辑
这点非常重要。
因为这说明ClaudeCode已经不是“会写prompt”，而是在做：
Prompt assembly with cache economics
也就是说，它连systemprompt的token成本与缓存命中都做了工程化优化。
这一节是本次新增重点：不是只说prompt在哪，而是把主prompt的主要section和行为
价值拆出来。
这一段做的事包括：
‧ 定义自己是interactiveagent
‧ 说明是帮助用户完成软件工程任务
‧ 指出输出风格会受OutputStyle约束
‧ 注入CYBER_RISK_INSTRUCTION
‧ 明确禁止随意生成或猜URL
这段意义不在于“介绍自己”，而在于为后续行为定基调：
1. 它不是普通聊天机器人
2. 它是工具驱动的工程协作者
3. 风险防护从第一屏开始就被注入
5.2 4.2基础系统规范：getSimpleSystemSection()
这段本质上在定义runtimereality：
‧ 所有非工具输出都直接给用户看
‧ 工具运行在permissionmode下
‧ 用户拒绝后不能原样重试
‧ toolresult / user message 里可能有等标签
‧ 外部工具结果可能包含promptinjection
‧ 有hooks
‧ 上下文会被自动压缩，不是硬性上下文窗口
这段极其重要，因为它把模型从“语言模型幻觉世界”拉回了“受控runtime世界”。
9
这部分是ClaudeCode行为稳定性的核心之一。它非常明确地约束模型：
‧ 不要加用户没要求的功能
‧ 不要过度抽象
‧ 不要瞎重构
‧ 不要乱加comments/docstrings/typeannotations
‧ 不要做不必要的errorhandling/fallback/validation
‧ 不要设计一堆future‑proofabstraction
‧ 先读代码再改代码
‧ 不要轻易创建新文件
‧ 不要给时间估计
‧ 方法失败时要先诊断再换策略
‧ 注意安全漏洞
‧ 删除确认没用的东西，不搞compatibility垃圾
‧ 结果要如实汇报，不能假装测试过
这块本质上不是prompt细节，而是：
Anthropic 对 AI 工程师行为规范的制度化表达
很多codingagent不稳定，不是不会写代码，而是行为发散。这一段就是为了解决行为漂
移。
这部分定义了什么叫“需要确认”的风险动作：
‧ destructive operations
‧ hard‑to‑reverse operations
‧ 修改共享状态
‧ 对外可见动作
‧ 上传到第三方工具
并且还强调：‑不要用destructiveactions当捷径‑发现陌生状态先调查‑mergeconflict
/ lock file 不要粗暴删
这一段值钱的点在于：它把blastradius思维编码进了系统提示词。
这里面有非常清楚的工具策略：
‧ 读文件优先FileRead，不要cat/head/tail/sed
‧ 改文件优先FileEdit，不要sed/awk
‧ 新建文件优先FileWrite，不要echo重定向
‧ 搜文件优先Glob
‧ 搜内容优先Grep
10
‧ Bash只保留给真正需要shell的场景
‧ 有任务管理工具时要用TodoWrite/TaskCreate
‧ 没有依赖关系的工具调用要并行
这非常关键，因为它不只是说“你有工具”，而是说：
你要以正确的操作语法使用这些工具
Claude Code 的稳，和这套toolusagegrammar有很大关系。
getSessionSpecificGuidanceSection() 是个非常关键的动态section。里面会根据当
前工具集和featuregate拼出一些当下约束，例如：
‧ 如果有AskUserQuestion，被拒绝后可以问用户
‧ 非交互模式下的行为差异
‧ 是否启用AgentTool
‧ Explore/Planagents 是否可用
‧ slashskill 的使用规则
‧ DiscoverSkills 工具的调用guidance
‧ Verification agent 的强制验证合同
这一段说明ClaudeCode的systemprompt不是“总规则”，而是“总规则+当前会话的
局部规则”。
这一段在ant与外部用户上有分支，但核心目标一致：
‧ 用户看的是自然语言，不是日志
‧ 先说动作或结论，不要铺垫
‧ 该更新时更新，但不要废话
‧ 不要过度解释
‧ 不要塞无谓表格
‧ 短句直给
这说明ClaudeCode不只管“能不能完成任务”，还管“完成任务时用户体验像不像正式产
品”。
这部分规定：
‧ 不要乱用emoji
‧ 响应要简洁
‧ 引用代码位置时用file_path:line_number
‧ GitHubissue/PR用owner/repo#123
‧ toolcall 前不要加冒号
这类细则看起来小，但它们会显著塑造产品质感。
11
在prompts.ts里还定义了：
‧ DEFAULT_AGENT_PROMPT
核心意思是：
‧ 你是ClaudeCode的agent
‧ 用工具完成任务
‧ 任务要完整，不要半成品
‧ 完成后给简洁报告
这说明主线程与子agent在prompt结构上是有分层的。
6.1 5.1AgentTool/prompt.ts：Agent协议说明书
这份文件非常值钱。它不是普通说明文，而是AgentTool的模型侧协议文档。
它主要说明：
‧ 如何展示agentlist
‧ 每个agent的描述格式
‧ 何时fork自己
‧ 何时显式指定subagent_type
‧ fork与freshagent的区别
‧ 什么情况下不要用AgentTool
‧ 如何写给子agent的prompt
‧ foreground / background 的行为差异
‧ isolation: worktree / remote 的语义
这说明多agent不是暗箱，而是明确写给模型看的使用协议。
当fork开启时，prompt明确告诉模型：
‧ omitsubagent_type就是fork自己
‧ fork继承完整conversationcontext
‧ 研究任务很适合fork
‧ 实现任务如果会产生大量中间输出，也适合fork
‧ fork很便宜，因为共享promptcache
‧ 不要给fork单独设model，否则cache命中会变差
‧ 不要偷窥fork输出文件
‧ 不要预言fork结果
12
这个设计本质上是在解决一个大问题：
怎么让复杂子任务并行运行，但不污染主上下文
这是多agent系统里非常核心、也非常难做对的一件事。
Agent prompt 里很明确地教育模型：
‧ freshagent 没有上下文，要像对新同事briefing一样写prompt
‧ 说明目标和原因
‧ 说明你已经排除了什么
‧ 提供足够背景，让它能做判断
‧ 如果要短答，明确说
‧ 不要把理解任务的工作外包给agent
‧ 不要写“基于你的发现再去修bug”这种偷懒prompt
‧ 应该给到filepath、line、具体改动要求
这其实是在限制“懒delegation”。也是为什么ClaudeCode的subagent效果会更稳：主
agent 被prompt强制要求承担synthesis责任。
从源码能确认至少有这些内建agents：
‧ GeneralPurposeAgent
‧ ExploreAgent
‧ PlanAgent
‧ Verification Agent
‧ ClaudeCodeGuideAgent
‧ Statusline Setup Agent
这说明Anthropic的方向不是让一个agent什么都做，而是：
‧ 探索给Explore
‧ 规划给Plan
‧ 验证给Verification
‧ 通用任务给GeneralPurpose
这是典型的specialization 思路。
exploreAgent.ts 的system prompt 很有代表性。它明确规定：
13
6.5.1 绝对只读
‧ 不能创建文件
‧ 不能修改文件
‧ 不能删除文件
‧ 不能移动文件
‧ 不能写临时文件
‧ 不能用重定向/heredoc写文件
‧ 不能运行任何改变系统状态的命令
‧ 用Glob/Grep/FileRead快速探索代码库
‧ Bash只允许读操作：ls,git status,git log,git diff,find,grep,cat,head,
tail
‧ 尽量并行用工具
‧ 要快，尽快给结果
这说明Explore不是“会搜索的普通agent”，而是被故意裁成read‑onlyspecialist。
planAgent.ts 的systemprompt也非常清晰：
‧ 只读
‧ 不准改文件
‧ 需要先理解需求
‧ 需要探索代码库、模式、架构
‧ 需要输出step‑by‑stepimplementationplan
‧ 最后必须列出CriticalFilesforImplementation
这里最关键的是：PlanAgent被定义成architect/planner，而不是executor。这样做的
价值是降低角色混杂。
6.7 5.7Verification Agent：为什么它非常值钱
verificationAgent.ts 是本轮挖掘里非常重要的新增部分。
它的prompt非常强，核心方向不是“确认实现看起来没问题”，而是：
你的工作是trytobreakit
它甚至在prompt开头就点出两类失败模式：
1. verification avoidance：只看代码、不跑检查、写PASS就走
2. 被前80%迷惑：UI看起来还行、测试也过了，就忽略最后20%的问题
然后prompt强制要求：
‧ build
14
‧ testsuite
‧ linter / type‑check
‧ 根据变更类型做专项验证
‧ frontend要跑浏览器自动化/页面子资源验证
‧ backend要curl/fetch 实测响应
‧ CLI要看stdout/stderr/exit code
‧ migration 要测up/down和已有数据
‧ refactor 也要测publicAPIsurface
‧ 必须做adversarialprobes
‧ 每个check必须带command和outputobserved
‧ 最后必须输出VERDICT: PASS / FAIL / PARTIAL
这说明VerificationAgent 不是“再跑一次测试”，而是一个adversarialvalidator。
这非常强，因为它把很多LLM常见的“差不多就算了”直接用prompt反制掉了。
这是本次新增的第二个重点：Agent调度链深挖。
从AgentTool.tsx与runAgent.ts看，主链路可以抽象为：
1. 主模型决定调用Agent工具
2. AgentTool.call() 解析输入
3. 解析是否teammate/fork/built‑in/ background / worktree / remote
4. 选择agentdefinition
5. 构造promptmessages
6. 构造/继承systemprompt
7. 组装工具池
8. 创建agent‑specific ToolUseContext
9. 注册hooks/skills / MCPservers
10. 调用runAgent()
11. runAgent() 内部再调用query()
12. query 产出消息流
13. runAgent 记录transcript、处理lifecycle、清理资源
14. AgentTool 汇总结果或走异步任务通知
这已经是一条非常完整的subagentruntimepipeline。
AgentTool.call() 的职责远比“转发到子agent”复杂。它要处理：
‧ 解析输入参数：description、prompt、subagent_type、model、run_in_background、
name、team_name、mode、isolation、cwd
15
‧ 判断是否multi‑agentteammatespawn
‧ 解析teamcontext
‧ 判断是否允许background
‧ 区分forkpath与normalpath
‧ 根据permissionrules过滤agent
‧ 检查MCPrequirements
‧ 计算selectedAgent
‧ 处理remoteisolation
‧ 构造systemprompt/promptmessages
‧ 注册foreground/asyncagenttask
‧ 启动worktreeisolation
‧ 调用runAgent()
也就是说，AgentTool本质上是agentorchestrationcontroller。
源码里有非常明显的分叉：
‧ subagent_type省略且forkfeature开启
‧ 继承主线程systemprompt
‧ 用buildForkedMessages()构造promptmessages
‧ 用父线程完整context
‧ 工具集尽量与父线程一致，保证promptcache命中
‧ useExactTools = true
‧ 明确指定built‑in/customagenttype
‧ 基于agentDefinition生成新的agentsystemprompt
‧ 只给该agent所需上下文
‧ 走该agent的toolrestrictions
这里最值钱的地方是：fork不是“再开一个普通agent”，而是为了cache和context继
承专门优化过的执行路径。
在注释里可以看出，forkpath会尽量继承父线程的systemprompt和tooldefs，以保持API
request prefix byte‑identical，从而提高 prompt cache 命中。
这是非常高级的设计：
‧ 普通人只想“子任务能跑”
‧ ClaudeCode想的是“子任务能跑，而且尽量复用主线程cache，不白烧token”
这就是产品级系统思维。
16
AgentTool.call() 会根据条件决定：
‧ foreground sync path
‧ asyncbackgroundpath
‧ remotelaunchedpath
‧ teammatespawnedpath
‧ 注册asyncagenttask
‧ 独立abortcontroller
‧ 可以在后台运行
‧ 完成后通过notification回到主线程
‧ 可选自动summarization
‧ 可查看outputFile但prompt里明确不鼓励偷看
‧ 主线程等待结果
‧ 可以在执行中被background化
‧ 有foregroundtask注册与progresstracking
这说明ClaudeCode对agentlifecycle的处理是产品化的，而不是“一次函数调用”。
runAgent.ts 负责的事情很多：
‧ 初始化agent‑specificMCPservers
‧ 过滤/克隆contextmessages
‧ 处理filestatecache
‧ 获取system/usercontext
‧ 对read‑onlyagent做claudeMd/gitStatus slimming
‧ 构造agent‑specificpermission mode
‧ 组装resolvedtools
‧ 获取agentsystemprompt
‧ 创建abortController
‧ 执行SubagentStarthooks
‧ 注册frontmatterhooks
‧ 预加载frontmatterskills
‧ 合并agentMCPtools
‧ 构造subagentToolUseContext
‧ 调用query()进入主循环
‧ 记录transcript
‧ 清理MCP、hooks、perfetto、todo、bashtasks等资源
这说明runAgent不是简单wrapper，而是子agent的完整runtimeconstructor。
17
initializeAgentMcpServers() 很有意思。
它支持agentDefinition自带mcpServers，并且可以：
‧ 从现有配置按名字引用服务器
‧ 在frontmatter里内联定义agent‑specificMCPserver
‧ 连接server
‧ 拉取tools
‧ 把agent‑specific MCPtools 合并进当前agent的tools
‧ 在agent结束时做cleanup
这说明agent不只是消费全局MCP，它还可以带自己的外接能力。这对插件agent/专职
agent 很强。
runAgent() 里还会：
‧ registerFrontmatterHooks(...)
‧ 读取agentDefinition.skills
‧ 通过getSkillToolCommands()加载技能
‧ 把skillprompt内容预加载成metausermessages注入初始消息
这很关键：说明agent本身也是可配置的promptcontainer，而不是固定硬编码角色。
虽然这次没有把query.ts全文展开，但从runAgent()能明确看到：
‧ 真正的模型对话循环发生在query({ ... })
‧ runAgent()只是子agent的上下文准备与生命周期控制器
这就让整个分层很清楚：
‧ AgentTool：调度与模式分流
‧ runAgent：子agent上下文构造与生命周期管理
‧ query：真正的模型消息流与tool‑calling主循环
runAgent() 里非常多产品级细节：
‧ recordSidechainTranscript()
‧ writeAgentMetadata()
‧ registerPerfettoAgent()
‧ cleanupAgentTracking()
‧ killShellTasksForAgent()
‧ 清理sessionhooks
18
‧ 清理clonedfilestate
‧ 清理todosentry
这说明Anthropic 并不是只让 subagent “跑起来”，而是把 transcript、telemetry、
cleanup、resume 都纳入正式生命周期。
8.1 7.1Skill：不是文档，而是workflowpackage
源码里：‑SKILL_TOOL_NAME = ’Skill’
在SkillTool/prompt.ts 以及命令系统相关代码中，它明确要求：
‧ task匹配skill时必须调用Skilltool
‧ 不能只提skill不执行
‧ slashcommand可以视为skill入口
‧ 如果skill已经通过tag注入，则不要重复调用
这说明Skill是一个first‑classprimitive。
可以把它理解成：
‧ markdownpromptbundle
‧ 带frontmattermetadata
‧ 可声明allowed‑tools
‧ 可按需注入当前上下文
‧ 可把重复工作流压缩成可复用能力包
这比“在systemprompt里塞一堆固定流程”高级很多。
关键文件：‑src/utils/plugins/loadPluginCommands.ts
插件能提供的能力至少包括：
‧ markdowncommands
‧ SKILL.mdskill 目录
‧ commandsMetadata
‧ userConfig
‧ shellfrontmatter
‧ allowed‑tools
‧ model/efforthints
‧ user‑invocable
‧ disable‑model‑invocation
19
‧ runtime变量替换
例如支持：‑${CLAUDE_PLUGIN_ROOT}‑${CLAUDE_PLUGIN_DATA}‑${CLAUDE_SKILL_DIR}‑ ${CLAUDE_SESSION_ID}‑ ${user_config.X}
所以plugin不是普通CLI插件，而是模型行为层面的扩展单元。
关键文件：‑src/services/tools/toolHooks.ts
Hook支持：‑PreToolUse‑PostToolUse‑PostToolUseFailure
而且hook结果不仅仅能“记日志”，还能：
‧ 返回message
‧ blockingError
‧ updatedInput
‧ permissionBehavior
‧ preventContinuation
‧ stopReason
‧ additionalContexts
‧ updatedMCPToolOutput
这意味着Hook是runtimepolicylayer。
resolveHookPermissionDecision() 说明：
‧ hook可以给出allow/ask/deny
‧ 但hook的allow也不自动突破settingsdeny/askrules
‧ 如果需要userinteraction或requireCanUseTool，仍然要走统一permissionflow
‧ hook还能通过updatedInput满足交互输入
这说明Hook强，但没有绕开核心安全模型。
从prompts.ts可以明确看到：
‧ getMcpInstructionsSection()
‧ getMcpInstructions(mcpClients)
逻辑是：‑如果connectedMCPserver提供instructions‑ 就把这些instructions 拼进
system prompt
也就是说MCP能同时注入：
1. 新工具
2. 如何使用这些工具的说明
这让MCP的价值远高于简单toolregistry。
20
9.1 8.1toolExecution.ts：真正的工具runtime主线
Claude Code 的工具执行并不是“模型决定→直接跑函数”。实际链路大致是：
1. 找tool
2. 解析MCPmetadata
3. 做inputschema校验
4. 做validateInput
5. 为Bash启动speculativeclassifier check
6. 运行PreToolUsehooks
7. 解析hookpermissionresult
8. 走permission 决策
9. 再次根据permissionupdatedInput修正输入
10. 真正执行tool.call()
11. 记录analytics / tracing / OTel
12. 运行PostToolUse hooks
13. 处理structured output / tool_result block
14. 失败则走PostToolUseFailure hooks
这是一条标准的runtimepipeline，而不是直连函数调用。
工具执行前会先做：
‧ Zodschemaparse
‧ tool‑specific validateInput
如果失败：‑直接生成tool_result错误消息‑记录tengu_tool_use_error
这保证模型随便乱生成参数时不会直接污染执行层。
在runPreToolUseHooks() 中，hook可以产出：
‧ 普通message
‧ hookPermissionResult
‧ hookUpdatedInput
‧ preventContinuation
‧ stopReason
‧ additionalContext
‧ stop
最关键的几个能力是：
hook 可以改写输入，但不一定做权限决策。
21
hook 可以直接说：‑allow‑ask‑deny
即使没deny，也能阻止流程继续。
这使得Hook能真正参与控制流。
这段逻辑非常值钱。它定义了：
‧ hookallow不一定绕过settings规则
‧ 如果tool要求userinteraction，而hook没提供updatedInput，则仍要走canUseTool
‧ ask类型hook会作为forceDecision传递下去
‧ deny类型直接生效
也就是说，Hook的权限语义是被严格嵌进总权限模型里的，不是外挂旁路。
runPostToolUseHooks()与runPostToolUseFailureHooks()说明，ClaudeCode不
把“tool成功返回”当终点。
成功后hook还能：‑追加message‑注入additionalcontext‑ 阻断continuation‑ 对
MCPtool output 进行更新
失败后hook还能：‑补充失败上下文‑发阻断说明‑给用户更多恢复线索
这就是为什么整个系统比“toolcall一把梭”可治理得多。
10.1 9.1 它不是一个prompt，而是一个operatingmodel
很多人复刻codingagent时只会拿走：
‧ 一个systemprompt‧ 一个文件编辑工具
‧ 一个bash工具
‧ 一个CLI壳
但ClaudeCode真实的护城河是：
‧ Promptarchitecture
‧ Toolruntimegovernance
‧ Permission model
‧ Hookpolicylayer
‧ Agentspecialization
22
‧ Skill workflowpackaging
‧ Pluginintegration
‧ MCPinstruction injection
‧ Promptcacheoptimization
‧ Async/background/remote lifecycle
‧ Transcript / telemetry / cleanup / task system
少一个都行，但会显著掉“手感”。
Claude Code 最大的优势之一，不是模型更聪明，而是：
它不把“好习惯”交给模型即兴发挥，而是写进prompt和runtime规则里。
例如：‑不要乱加功能‑不要过度抽象‑不要瞎重试被拒绝的工具‑不要未验证就说成功‑不
要随便做风险操作‑不要让fork输出污染主上下文‑匹配skill时必须执行skill‑verification
不能只看代码，必须跑命令
这种制度化，会极大提高系统一致性。
源码中大量设计都在围绕上下文做优化：
‧ systemprompt动静边界
‧ promptcacheboundary
‧ forkpath共享cache
‧ skill 按需注入
‧ MCPinstructions 按连接状态注入
‧ function result clearing
‧ summarizetoolresults
‧ compact/transcript / resume
这说明他们不是把token当免费空气，而是当runtime预算来管理。
Explore / Plan / Verification 这套 built‑in agents 的价值，不在于“多了三个agent”，而在
于：
‧ 研究和探索不用污染主线程
‧ 规划和实现分离，降低混乱
‧ 验证独立出来，对抗“实现者bias”
很多系统的问题，就是一个agent既研究、又规划、又实现、又验收，最终哪件事都不够稳
定。
Claude Code 则是明确分工。
23
这是ClaudeCode另一个很强的点。
很多系统也有插件，也有工具，也有外部协议，但模型本身不知道：‑有哪些扩展‑什么时
候该用‑怎么用
Claude Code 不一样。它通过：‑skills列表‑agent列表‑MCPinstructions‑session
specific guidance‑ command integration
让模型“知道自己的扩展能力是什么”。这才是生态真正能发挥作用的关键。
11.1 10.1 核心Prompt文件
11.1.1 主系统提示词
‧ src/constants/prompts.ts
‧ src/tools/AgentTool/prompt.ts
‧ src/tools/SkillTool/prompt.ts
‧ src/tools/FileReadTool/prompt.ts
‧ src/tools/GlobTool/prompt.ts
‧ src/tools/GrepTool/prompt.ts
‧ src/tools/BriefTool/prompt.ts
‧ 以及更多prompt.ts
‧ src/tools/AgentTool/AgentTool.tsx
‧ src/tools/AgentTool/runAgent.ts
‧ src/tools/AgentTool/resumeAgent.ts
‧ src/tools/AgentTool/forkSubagent.ts
‧ src/tools/AgentTool/agentMemory.ts
‧ src/tools/AgentTool/agentMemorySnapshot.ts
‧ src/tools/AgentTool/builtInAgents.ts
‧ src/tools/AgentTool/built-in/exploreAgent.ts
‧ src/tools/AgentTool/built-in/planAgent.ts
24
‧ src/tools/AgentTool/built-in/verificationAgent.ts
‧ src/tools/AgentTool/built-in/generalPurposeAgent.ts
‧ src/tools/AgentTool/built-in/claudeCodeGuideAgent.ts
‧ src/tools/AgentTool/built-in/statuslineSetup.ts
11.3.1 Skill
‧ src/tools/SkillTool/constants.ts
‧ src/tools/SkillTool/prompt.ts
‧ src/commands.ts
‧ src/utils/plugins/loadPluginCommands.ts
‧ src/services/tools/toolHooks.ts
‧ src/utils/hooks.js
‧ src/services/tools/toolExecution.ts
‧ src/services/mcp/types.ts
‧ src/services/mcp/normalization.ts
‧ src/services/mcp/mcpStringUtils.ts
‧ src/services/mcp/utils.ts
‧ src/entrypoints/mcp.ts
如果要再往下继续深挖，下一轮我建议重点看：
1. query.ts：主会话循环与模型交互流
2. resumeAgent.ts：agent 恢复机制
3. loadSkillsDir：skills 完整加载链
4. pluginLoader：插件加载与内建插件生态
5. systemPromptSections.ts：prompt section registry 细节
6. coordinator/*：多agent协调器模式
7. attachments.ts：skill / agent listing / MCP delta 的消息注入方式
8. AgentSummary：后台agent进度总结机制
25
如果只给一句话总结这份增强版研究报告：
Claude Code的真正秘密，不是一段systemprompt，而是一个把promptarchi
tecture、tool runtime、permission model、agent orchestration、skill pack
aging、pluginsystem、hooksgovernance、MCPintegration、contexthygiene
和productengineering 全部统一起来的系统。
这就是为什么它不像一个“会调工具的聊天机器人”，而更像一个真正可扩展、可治理、可
产品化的AgentOperatingSystem。
业务实施流程 马上咨询： 如果您有业务方面的问题或者需求，欢迎您咨询！我们带来的不仅仅是技术，还有行业经验积累。
QQ: 39764417/308460098 Phone: 13 9800 1 9844 / 135 6887 9550 联系人：石先生/雷先生