Claude Code 源码泄露背后：一套 Harness 工程体系的完整解剖
本文要回答的核心问题
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 包。一年多后，同样的错误再次重演。
这次泄露虽然是一个基础工程失误，但对于关注 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 不能做什么比设计它能做什么更重要」。
