Claude Code 源码解密：它不只是个”会写代码的 AI”

2026-04-04

你以为它只是一个 AI + 工具调用器？错了，它是一个完整的 Agent Operating System。

导语

如果你用过 Claude Code，你可能觉得它只是”一个很会写代码的 AI”。

但最近有人从 npm 包里还原了它的完整源码，4756 个源码文件，拆解出了一套完全不同的真相。

Claude Code 的强大，核心不在某个”神秘 system prompt”，而是一整套把 prompt、tool、permission、agent、skill、plugin、hook、MCP 统一起来的 Agent 操作系统。

今天这篇文章，带你从源码视角看懂它的真正护城河。

01 它不是单一工具，而是平台

从顶层源码结构看，Claude Code 至少有这些重要模块：

模块职责
src/entrypoints/入口层（CLI、MCP、SDK）
src/constants/提示词、系统常量、风险提示
src/tools/工具定义与实现
src/services/运行时服务
src/commands/命令系统
src/plugins/插件生态
src/hooks/Hook 系统
src/tasks/本地/远程任务管理

这说明什么？它从设计上就是一个完整的运行平台，而不是简单的 CLI 包装器。

同一个 agent runtime，可以服务多个入口：

  • 本地 CLI
  • MCP 模式（作为其他 AI 的工具）
  • SDK 消费者

这种平台化思维，让它可以灵活地嵌入不同的工作流。

02 System Prompt 不是文本，而是编排器

很多人以为 Claude Code 的强大在于”写了一段很棒的 system prompt”。

但源码显示，src/constants/prompts.ts 不是静态文本，而是一套 system prompt assembly architecture：

静态前缀（可 cache）：
├── 身份与基础定位
├── 基础系统规范
├── 做任务哲学
├── 风险动作规范
├── 工具使用规范
├── 语气风格
└── 输出效率规范
​
动态后缀（按会话注入）：
├── session guidance
├── memory prompt
├── env info
├── language / output style
├── MCP instructions
└── feature-gated sections

更关键的是，源码中存在 SYSTEM_PROMPT_DYNAMIC_BOUNDARY，明确区分：

  • 边界前：尽量可 cache
  • 边界后：用户/会话特定内容

这就是产品级思维 — 连 system prompt 的 token 成本与缓存命中都做了工程化优化。

03 Agent 专业化分工，而不是万能 Worker

很多 AI 编程工具的问题：一个 agent 既研究、又规划、又实现、又验收，最终哪件事都不够稳定。

Claude Code 的做法是 明确的职责分工：

Agent职责约束
Explore代码探索绝对只读，不能创建/修改/删除文件
Plan实现规划只读，输出 step-by-step plan
Verification质量验收try to break it，必须跑命令验证
General Purpose通用任务完整工具集，执行具体任务

为什么要这样分工？

  1. 研究任务 不会污染主线程上下文
  2. 规划和实现分离，降低混乱
  3. 验证独立出来，对抗”实现者 bias”

Verification Agent 的 prompt 尤其强 — 它的核心不是”确认实现看起来没问题”，而是：

“你的工作是 try to break it“

它会强制要求：

  • build / test suite / linter / type-check
  • 根据变更类型做专项验证
  • 必须做 adversarial probes
  • 输出 VERDICT: PASS / FAIL / PARTIAL

这直接用 prompt 反制了 LLM 常见的”差不多就算了”问题。

04 Fork 语义：并行但不污染上下文

源码中有一个非常高级的设计：fork 语义。

当开启 fork 时：

  • 继承主线程完整 conversation context
  • 工具集尽量与父线程一致，保证 prompt cache 命中
  • 不要给 fork 单独设 model（否则 cache 命中会变差）
  • 不要偷窥 fork 输出文件
  • 不要预言 fork 结果

这解决了一个核心问题：怎么让复杂子任务并行运行，但不污染主上下文？

普通人只想”子任务能跑”，Claude Code 想的是”子任务能跑，而且尽量复用主线程 cache，不白烧 token”。

05 工具执行不是直接调用，而是 Pipeline

Claude Code 的工具执行链路是这样的：

1. 找 tool
2. 解析 MCP metadata
3. Zod schema 校验
4. validateInput
5. speculative classifier check（Bash）
6. PreToolUse hooks ← 最关键拦截点
7. permission 决策
8. 执行 tool.call()
9. 记录 analytics / tracing
10. PostToolUse hooks
11. 处理 structured output
12. 失败则走 PostToolUseFailure hooks

Hook 可以产出：

  • updatedInput — 改写输入
  • permissionBehavior — allow/ask/deny
  • preventContinuation — 阻止流程继续
  • additionalContext — 注入额外上下文

这使得 Hook 真正参与控制流，而不仅仅是”记日志”。

06 安全默认：Fail-Closed 哲学

源码中最震撼的细节之一，是工具系统的默认配置：

// 默认配置 — 直到证明安全，否则默认不安全
concurrencyUnsafe: true    // 默认不安全，需证明
readOnly: false            // 默认需要权限
destructive: false          // 默认非破坏性

这不是简单的”谨慎”，而是 fail-closed 安全哲学 的制度化表达。

以 Bash 工具为例，源码中实现了 23 层安全检查：

  • 命令黑名单
  • 参数验证
  • 路径遍历防护
  • 危险命令检测
  • 超时限制
  • 输出过滤
  • …

这种设计理念的价值：安全性不是事后补丁，而是从第一行代码就开始的默认假设。

07 Skills 不是文档，而是 Workflow Package

很多人以为 Skill 就是”一些使用文档”。

但源码显示，Skill 更接近 prompt-native workflow package：

  • markdown prompt bundle
  • 带 frontmatter metadata
  • 可声明 allowed-tools
  • 可按需注入当前上下文
  • 可把重复工作流压缩成可复用能力包

为什么这很重要？

因为这意味着你可以把”某个任务的完整工作流”打包成一个 Skill，然后模型会在匹配时自动加载并执行。

比如 TDD 工作流、代码审查流程、某个框架的最佳实践 — 都可以被封装成 Skill。

08 为什么它比”普通 LLM + 工具调用器”强很多

如果只复刻：

  • 一个 system prompt
  • 一个文件编辑工具
  • 一个 bash 工具
  • 一个 CLI 壳

你会错过真正的护城河：

维度Claude Code 的做法
Prompt模块化 runtime assembly，带 cache 优化
Tool完整的 permission / hook / analytics pipeline
Agentbuilt-in / fork / subagent 分工结构
Skillprompt-native workflow package
Pluginprompt + metadata + runtime constraint
MCP工具桥 + 行为说明注入通道
Context动静边界、function result clearing、summarize

一句话总结：

Claude Code 的价值，不在某一段 prompt，本质上是一整套把 prompt、tool、permission、agent、skill、plugin、hook、MCP、cache 和产品体验统一起来的 Agent Operating System。

09 它把”好行为”制度化

Claude Code 最大的优势之一，是把好习惯写进 prompt 和 runtime 规则里，而不是交给模型即兴发挥：

  • ❌ 不要乱加功能
  • ❌ 不要过度抽象
  • ❌ 不要瞎重试被拒绝的工具
  • ❌ 不要未验证就说成功
  • ❌ 不要随便做风险操作
  • ❌ verification 不能只看代码，必须跑命令

这种制度化，会极大提高系统一致性。

10 它特别懂”上下文是稀缺资源”

源码中大量设计都在围绕上下文做优化：

  • system prompt 动静边界
  • prompt cache boundary
  • fork path 共享 cache
  • skill 按需注入
  • MCP instructions 按连接状态注入
  • function result clearing
  • summarize tool results

这说明他们不是把 token 当免费空气，而是把它视为 runtime 预算来管理。

11 启动性能：500ms 的极致追求

除了运行时上下文优化，源码中对启动时间也有极致要求 — 目标 <500ms。

为了达成这个目标，工程团队做了这些优化：

优化项节省时间
Keychain 并行预取~65ms
MDM 重叠读取~135ms
懒加载工具~100ms
preAction guards~50ms

这说明什么？

Claude Code 的产品哲学不是”能用就行”，而是”每个可优化的细节都要优化到极致”。

500ms 可能只是一个数字，但它背后反映的是对用户体验的极致追求 — 从你敲下命令到看到响应，这半秒的时间内，整个系统已经完成了初始化、配置加载、环境检查等一系列复杂操作。

12 核心结论

如果只给一句话总结这份源码研究报告：

Claude Code 的真正秘密，不是一段 system prompt，而是一个把 prompt architecture、tool runtime、permission model、agent orchestration、skill packaging、plugin system、hooks governance、MCP integration、context hygiene 和 product engineering 全部统一起来的系统。

这就是为什么它不像一个”会调工具的聊天机器人”，而更像一个真正可扩展、可治理、可产品化的 Agent Operating System。

参考资料

[1]  Claude Code 源码深度研究报告 – 作者 Xiao Tan

[2]  Claude Code 官方 GitHub – Anthropic 官方 AI 编程助手仓库

[3]  Claude Code 官网 – Anthropic 官方 AI 编程助手

[4]  MarkItDown – Microsoft – 用于 PDF 转 Markdown 的工具

常见问题 Q&A

Q: 我可以自己复刻 Claude Code 吗？

A: 可以复刻部分功能，但真正的护城河是整个系统的协同效应。单个模块好做，但把它们整合成产品级的体验很难。

Q: 源码里有什么惊喜发现吗？

A: 最大的惊喜是 Verification Agent — 它的 prompt 核心是”try to break it”，而不是”check if it works”。这种对抗性思维非常强。

Q: Skill 和 Plugin 有什么区别？

A: Skill 更像 workflow package（可复用的工作流），Plugin 更像 extension（带运行时约束的扩展）。两者都会被模型”感知”并在合适时调用。

Q: 为什么 fork 语义这么重要？

A: 因为它解决了多 agent 系统的一个核心难题：怎么让子任务并行运行，既共享上下文，又不污染主线程？Claude Code 用 cache-aware fork 做到了。

Q: 普通开发者能从中学到什么？

A: 最重要的启示是：好产品不是靠某一个大招，而是靠无数细节的系统性优化。prompt engineering、cache 优化、权限治理、agent 分工 — 每一项都很重要。