Claude Code 源码泄露背后：一套 Harness 工程体系的完整解剖

图片来源：Unsplash

本文要回答的核心问题

Claude Code 为什么用起来比其他 AI 编程工具更「靠谱」？是模型本身强，还是围绕模型搭建的工程体系在起作用？1902 个泄露的源文件揭示了一个清晰答案：60% 靠模型能力，40% 靠一套精心设计的 harness 工程。

事件背景：一次低级失误引发的公开课

Anthropic 在更新 Claude Code 的 npm 包时，意外将一个约 60MB 的 source map 调试文件留在了发布包中。这个文件本应在打包阶段排除，但构建流水线未能正确处理。任何人都可以通过这个 source map 还原出 Claude Code 完整的 TypeScript 源码——1902 个文件全部暴露。

值得注意的是，这并非首次发生。2025 年 2 月 Claude Code 刚发布时就出现过完全相同的事故，Anthropic 当时紧急删除了旧版 npm 包。一年多后，同样的错误再次重演。

图片来源：Pexels

这次泄露虽然是一个基础工程失误，但对于关注 AI Agent 工程实践的开发者而言，意外获得了一份难得的学习材料。源码完整展示了 Anthropic 如何围绕一个大语言模型搭建一整套工程系统——即 2026 年越来越受关注的「harness engineering」。

一、系统提示词：你以为 AI 只收到一句话，其实它收到一整本说明书

核心问题：当我在 Claude Code 里输入一条简短指令，AI 实际接收到的完整信息是什么？

你输入的那句话只是冰山一角。源码中的 prompts.ts 文件揭示，Claude Code 每次对话时会拼装一个极为庞大的系统提示词，分为静态与动态两个部分。

静态部分（所有用户共享，用于缓存）

组成模块 内容说明
身份定义 「你是 Claude Code，Anthropic 的官方 CLI 工具」
安全准则 由安全团队专门编写的行为边界规则
做事原则 不要过度工程、不要编造数据、不要随意删文件等
工具使用规则 优先使用专用工具而非 Bash 命令
风格要求 不使用 emoji、简洁直接

动态部分（每个用户独立加载）

组成模块 内容说明
CLAUDE.md 配置文件 用户自定义的项目级指令
当前工作目录与操作系统信息 运行环境上下文
已连接的 MCP 服务器说明 外部工具的能力描述
自动记忆文件 历史积累的用户偏好
Git 仓库状态 当前分支、修改、冲突等信息

打个比方：就像餐厅后厨，顾客只点了一道菜（你的指令），但厨师同时看到了食谱手册、食材清单、过敏信息、出菜标准、这桌客人的历史偏好。所有这些上下文共同决定了最终端上来的那道菜的品质。

缓存分界线设计

源码中有一个关键常量 SYSTEM_PROMPT_DYNAMIC_BOUNDARY，将系统提示词一刀切成两段。分界线以上的所有内容在用户之间共享缓存，节省计算成本与响应时间；分界线以下的内容则针对每个用户独立加载，保证个性化体验。

MCP 服务器的隐性成本

据源码分析，每接入一个 MCP 服务器，其工具定义大约固定消耗 4000 到 6000 个 tokens。如果接入了 5 个 MCP Server，仅工具描述就占去上下文窗口的 12% 左右。这意味着工具并非越多越好——每一个额外的工具都带有实实在在的认知成本。

“

反思： 这个设计让我重新审视了自己日常使用 MCP 的方式。以前总觉得多接几个工具让 AI 更「万能」，但实际上每多一个工具，AI 可用于理解实际问题的上下文空间就缩小一点。克制，比贪多更重要。

二、安全审查：全自动模式背后有一个「第二 AI」在把关

核心问题：Claude Code 的 Auto 模式是否真的「全自动」放行所有操作？

并不是。Auto 模式背后实际运行了两个 AI。主 AI 负责执行任务，另一个独立的 AI 分类器负责判断每次操作是否安全。

四层权限流水线

蚂蚁集团工程师陈成（Umi.js 作者）此前逆向分析过这套系统，源码证实了其四层流水线架构：

层级 判断逻辑 结果
第一层 查询已有规则，命中即放行 Allow
第二层 检查是否为低风险操作，是则跳过 Allow
第三层 白名单放行只读类工具 Allow
第四层 调用独立的 Claude Sonnet 做安全分类（温度设为 0） Allow / Soft Deny / Hard Deny

独立分类器拥有自己独立的 system prompt，与主 AI 完全不同，分三档输出判断结果：

  • Allow：直接放行
  • Soft Deny：需要用户手动确认
  • Hard Deny：直接拦截，不允许执行

熔断机制

系统还设置了熔断保护：连续 3 次被拒，或累计 20 次被拒后，自动降级为手动确认模式。这防止了 AI 在异常状态下反复尝试高风险操作。

这个设计像一栋大楼的分层门禁：第一道门刷工卡自动通过，第二道确认你是否为员工，第三道检查楼层授权，第四道才是人工安保审查。连续 3 次被拦？保安直接把你请到大厅等人来领。

“

独特见解： harness engineering 的核心不在于告诉 AI 「做什么」，而在于设计它在什么条件下「不能做什么」。安全边界并非限制能力，而是建立信任的基础。正因为用户相信它有底线，才敢授予它更大的操作权限。这个思路适用于所有 AI Agent 的产品设计。

三、记忆系统：只记偏好，不记代码

核心问题：Claude Code 如何「自动记住」用户偏好，又如何避免记忆变成误导？

Claude Code 的 auto memory 功能是许多用户觉得最惊艳的体验之一——它会自动记住你偏好 TypeScript、喜欢用「」引号、不喜欢 AI 味太重的文字。但源码揭示，这套系统的设计远比表面体验要严谨。

记忆提取的触发机制

记忆提取并非每条消息都触发，而是有严格的条件限制：

  • 仅在 AI 完成一轮完整回答后才启动
  • 设有限流机制，每 N 轮才检查一次
  • 提取工作由一个独立的 fork agent 完成

这个子 AI 继承了主对话的上下文，但权限被严格限制：只能读取文件和写入记忆目录，连 Bash 命令都不能执行。这意味着记忆提取过程本身不会对系统造成任何副作用。

四类记忆分类

提取出的记忆被严格划分为四个类别：

类别 存储内容 示例
user 用户个人偏好 喜好某种编程语言、代码风格
feedback 对 AI 行为的反馈 「上次那样做不对，应该先测试」
project 项目相关信息 项目使用的技术栈、目录结构约定
reference 外部资源引用 常用文档链接、API 地址

「不记代码」的设计决策

这是整个记忆系统中最值得学习的一条原则。代码会随着开发不断变化，但记忆不会自动更新。如果记忆中存了「函数 X 在文件 Y 的第 30 行」，下次对话时代码可能已经被重构，这条记忆就变成了误导信息。

Claude Code 的做法是：记忆只存人的偏好和判断，代码相关的事实永远去源码里实时读取。

autoDream：自动整理机制

源码中还发现了一个名为 autoDream 的功能。当满足以下条件时，会自动启动后台 agent 整理记忆文件：

  • 距上次整理超过 24 小时
  • 且已积累了 5 个以上新会话

这个功能命名为「Dream」，隐喻人在睡眠时整理白天记忆的过程。

“

反思： 「不记代码」这个决策看似简单，实际上需要很强的工程克制力。从直觉上，记下代码细节会让 AI 显得更「聪明」，但长期来看，过期信息造成的误导成本远大于短期收益。这种「少做比多做更好」的设计哲学，值得每个做 AI 产品的人深思。

四、上下文压缩：9 段式结构化提取

核心问题：对话变长后，Claude Code 如何压缩历史内容而不丢失关键信息？

Claude Code 的上下文压缩不是简单的「总结一下」，而是一套结构化的 9 段式提取方案：

序号 提取内容 说明
1 核心请求 用户最初要解决的问题
2 关键概念 讨论中涉及的重要技术概念
3 文件和代码 涉及的具体文件路径与代码片段
4 错误和修复 遇到的错误及对应的修复方法
5 解决过程 问题排查的推理链路
6 所有用户消息 用户说过的每一句话（完整保留）
7 待办任务 尚未完成的事项
8 当前工作 正在进行的操作
9 下一步行动 接下来应该做什么

最关键的设计：完整保留所有用户消息

用户的每一句话都可能包含隐含的偏好。AI 可能在第 3 轮对话中被纠正了一个做法，如果压缩时丢掉了那条纠正消息，后续就会重蹈覆辙。因此，所有用户消息必须完整保留，不允许在压缩中被概括或省略。

实践启示

如果你在多轮对话中需要保持 AI 的记忆一致性，可以借鉴这个思路：不要对 AI 说「总结一下我们之前聊了什么」，而是给出明确的结构化指令——哪些信息必须保留、哪些可以丢弃、按什么格式组织。结构化压缩比自由总结可靠得多。

五、多 Agent 协作：像真实公司一样运转

核心问题：Claude Code 如何在多任务场景下协调多个 AI Agent 协同工作？

源码中 utils/swarm/ 目录下包含一个完整的多 Agent 协作框架，这可能是整个源码中最复杂的部分。

组织架构

设计要素 实现方式
角色分工 每个 Team 设有 Leader 和多个 Teammate
执行隔离 支持三种方式：同进程隔离、tmux 窗口、iTerm2 分割窗格
异步通信 每个 Agent 拥有独立的邮箱文件
代码隔离 每个 Agent 在独立的 Git Worktree 中工作，互不干扰

权限冒泡机制

Teammate 在执行过程中遇到需要确认的操作时，权限请求不会直接弹给用户，而是「冒泡」给 Leader。由 Leader 决定是否批准。这跟管理真人团队的逻辑完全一致：任务怎么拆分、信息怎么流转、冲突怎么解决、结果怎么合并。

“

独特见解： 看完这套架构，我理解了为什么 Claude Code 的多任务能力明显强于其他工具。很多竞品的多 Agent 实现只是简单的「并行调用多个 API」，而 Claude Code 实现的是企业级的组织管理架构。差异不在于用了多少 Agent，而在于 Agent 之间如何协调。

六、内部版与外部版的差异

核心问题：Anthropic 内部员工使用的 Claude Code 和公开版有什么不同？

源码中有大量 USER_TYPE === 'ant' 的条件判断，揭示了内部版与外部版的显著差异。

关键差异对比

维度 外部版 内部版
代码注释 无特殊要求 「默认不写注释」，仅在 WHY 不明显时才加
诚实性 无特殊指令 有反虚假声明指令：测试失败就说失败，不要粉饰；没运行验证就说没运行，不要暗示通过
输出风格 「简洁直接」 「像写给人看的文字，不是往控制台打日志」「假设用户已经离开并丢失了上下文」
Undercover 模式 无 启用后从 system prompt 中移除所有模型名称，防止测试未发布模型时泄露信息
Verification Agent 无 内部 A/B 测试中，完成复杂实现后自动启动独立 agent 做对抗性验证，必须通过才能报告完成

这些差异说明 Anthropic 将 Claude Code 当作内部效率的核心工具。内部版的要求代表的是他们对「AI 应该怎么工作」的理想状态。

“

学到的教训： 想让 AI 给出更高质量的结果，可以在指令中明确要求「不确定的地方直接说不确定」「完成前必须验证结果」。不要给 AI 留模糊过关的空间。这些原则不需要等 Anthropic 开放，现在就可以用在自己的 prompt 里。

七、搜索策略：最先进的 AI 工具用的是最朴素的搜索

核心问题：Claude Code 搜索代码用的是向量数据库还是传统文本搜索？

很多人以为 Claude Code 会用向量数据库、Embedding 索引之类的 RAG 方案来搜索代码。实际上，源码显示它用的是 grep 和 ripgrep——最朴素的文本搜索工具。没有 Embedding，没有向量数据库。

这个选择背后的逻辑是：当你有一个足够聪明的大脑（LLM）来理解搜索结果时，不需要一个很聪明的搜索引擎。grep 给你精确匹配，LLM 负责理解结果之间的关系与语义。

与其让每个环节都变复杂，不如让一个环节足够强，其他环节保持简单。这大概是整个 harness engineering 最核心的一条设计原则。

八、未发布功能与彩蛋

核心问题：从源码的 feature flags 中能看到 Claude Code 未来的什么方向？

源码中的 feature flags 暴露了一批正在开发中的功能：

功能名称 出现频次 推测方向
PROACTIVE — 主动模式，AI 不等指令就自己干活
KAIROS 154 次 助手模式，最高频的 flag，具体功能待确认
DAEMON — 守护进程，常驻后台运行
ULTRAPLAN — 超级规划能力

此外，src/buddy/ 目录下藏着一个完整的虚拟宠物系统（尚未发布）。每个用户会拥有一只用确定性算法生成的伙伴精灵：18 种物种（鸭子、猫、龙、水豚、仙人掌等），6 种眼睛样式，完整的稀有度系统（从普通到传说）。代码注释写了一句：「Mulberry32, good enough for picking ducks」——用来挑鸭子够用了。

这些迹象表明 Claude Code 不满足于做一个「你问它答」的编程助手，而是在走向一个能主动思考、持续运行的 AI 伙伴。

九、整体反思：Harness 工程才是产品差异化的真正战场

核心问题：为什么同样调用底层大模型 API，不同 AI 编程工具的体验差异如此巨大？

看完 1902 个文件后，核心判断非常清晰：Claude Code 的竞争力 60% 在于模型能力，40% 在于 harness 工程。

模型能力决定了「能不能做」，harness 决定了「做得好不好、稳不稳、安不安全」：

  • 你觉得「这 AI 好靠谱不会乱来」——背后是四层安全流水线
  • 你觉得「这 AI 居然记得我的偏好」——背后是限制严格的记忆提取管线
  • 你觉得它搜代码搜得准——背后其实就是 grep 加上一个足够聪明的大脑

同样的底层模型，套上不同的 harness，就是完全不同的产品。市面上大量 AI 编程工具底层都在调用 Claude 或 GPT 的 API，使用体验却天差地别。差异不在模型，在 harness。

“

最终反思： Hacker News 上有人评价 Anthropic 的代码像是 vibe coded——「感觉对了就行」的写法。这个评价是否公允另说，但它说明一件事：Claude Code 的竞争力不在代码优雅度，而在系统设计的决策做对了。对于所有正在构建 AI 产品的人来说，这可能是最重要的一课——把精力放在决策质量上，而不是代码本身的精致度上。

实用摘要 / 操作清单

以下是从 Claude Code 源码中提炼出的、可直接借鉴到自身 AI 工程实践中的设计原则：

  • [ ] 系统提示词分层缓存：将 prompt 切分为共享静态部分与个性化动态部分，静态部分利用缓存节省成本
  • [ ] 控制工具数量：每个 MCP/工具接入都有固定 token 成本，按需接入而非贪多
  • [ ] 多层安全审查：用规则白名单过滤低风险操作，仅对模糊操作调用独立 AI 分类器
  • [ ] 设置熔断机制：连续失败后自动降级，防止异常状态下反复尝试
  • [ ] 记忆只存偏好不存事实：代码类信息实时读取源码，避免过期记忆造成误导
  • [ ] 压缩时完整保留用户消息：用户的每句话都可能含隐含偏好，不可在压缩中丢失
  • [ ] 用结构化提取替代自由总结：明确指定保留哪些信息、丢弃哪些、按什么格式
  • [ ] 简单工具 + 强模型 > 复杂工具 + 弱模型：grep 加 LLM 的组合优于复杂 RAG 管线
  • [ ] Prompt 中要求诚实与验证：明确要求「不确定就说不确定」「完成前必须验证」

一页速览（One-page Summary）

维度 Claude Code 的做法 核心原则
系统提示词 静态/动态分层，共享缓存 降本 + 个性化的平衡
安全机制 四层流水线 + 独立 AI 分类器 + 熔断 不信任单一判断，层层收窄
记忆系统 只存偏好不存代码，四类分类，限流触发 防过期记忆变成毒药
上下文压缩 9 段式结构化提取，用户消息完整保留 结构化压缩优于自由总结
多 Agent Leader/Teammate 架构，权限冒泡，Git Worktree 隔离 模拟真实团队管理
代码搜索 grep + ripgrep，无向量数据库 简单工具配强模型
内部版差异 反虚假声明、对抗性验证、Undercover 模式 不给 AI 模糊过关的空间
未来方向 PROACTIVE、KAIROS、DAEMON、ULTRAPLAN 从被动工具走向主动伙伴

常见问答

Claude Code 的「全自动模式」是完全不受限的吗？

不是。Auto 模式背后运行了一个独立的 AI 安全分类器，每次操作都经过四层权限流水线审查，高风险操作仍会被拦截或要求确认。

Claude Code 的记忆系统会记住我的代码内容吗？

不会。记忆系统刻意设计为只存用户偏好和判断，不存代码事实。代码相关信息每次都从源码实时读取，避免过期记忆产生误导。

为什么 Claude Code 不用向量数据库做代码搜索？

因为当 LLM 本身足够聪明时，精确文本匹配（grep/ripgrep）加上 LLM 的语义理解能力，已经足够有效。简单工具配强模型的组合优于每个环节都复杂化。

Claude Code 的系统提示词有多大？

具体大小取决于用户配置，但仅 MCP 工具定义每接入一个就消耗约 4000-6000 tokens。5 个 MCP Server 的工具描述可能占上下文窗口的 12% 左右。

上下文压缩时会丢失用户说过的话吗？

不会。9 段式压缩方案中，「所有用户消息」被列为必须完整保留的类别，因为每条用户消息都可能包含隐含的纠正或偏好。

Anthropic 内部版和外部版的主要区别是什么？

内部版增加了反虚假声明指令（要求诚实报告测试结果）、对抗性验证 Agent、更严格的输出风格要求，以及隐藏模型名称的 Undercover 模式。

Claude Code 的多 Agent 是怎么协作的？

采用 Leader/Teammate 组织架构，Agent 之间通过邮箱文件异步通信，各自在独立 Git Worktree 中工作，权限请求向上冒泡给 Leader 而非直接打扰用户。

harness engineering 的核心原则是什么？

围绕模型搭建的工程体系（工具、约束、反馈循环、安全机制、记忆系统）决定了产品体验的上限。核心原则是「让一个环节足够强，其他环节保持简单」，以及「设计 AI 不能做什么比设计它能做什么更重要」。