type
status
date
slug
summary
tags
category
icon
password
wechat_gate
Claude Code 源码泄露事件让外界第一次系统性看到一个成熟 AI 编程工具背后的工程骨架。本文基于读书笔记和公开报道，提炼 Claude Code 在运行循环、工具系统、权限控制、记忆、上下文压缩、搜索和多 Agent 协作上的关键设计，讨论为什么 AI 产品的差异不只来自模型能力，更来自 Harness Engineering。

先说结论：模型不是全部

2026 年 3 月，公开报道显示，Anthropic 的 Claude Code npm 包因为 source map 打包问题，意外暴露了大量 TypeScript 源码。这个事件本身是一次发布流程事故，但从工程学习角度看，它让外界看到了一个成熟 AI 编程产品的内部结构。
我更关心的不是“泄露了什么八卦”，而是这些代码背后的设计取舍：
  1. 为什么 Claude Code 没有把代码搜索做成复杂的 RAG？
  1. 为什么工具系统要把 Bash 当成后备，而不是默认入口？
  1. 为什么 Auto 模式背后还需要安全审查和熔断？
  1. 为什么记忆系统只记偏好，而不是记住所有代码细节？
  1. 为什么上下文压缩必须被当成核心系统，而不是简单总结？
这些问题指向同一个概念：Harness Engineering。
所谓 harness，可以理解为围绕模型搭建的一整套运行时系统：工具调用、权限控制、上下文管理、记忆、搜索、安全审查、多 Agent 协作、UI 和缓存策略。模型决定能力上限，但 harness 决定这个上限能兑现多少。
同一个强模型，套在不同产品里的体验可能差很多。差异不一定来自模型，而是来自模型外面那套工程系统。
notion image

1. Claude Code 不是 API wrapper，而是 Agent Runtime

很多人做 AI 编程工具，第一反应是：
接一个模型 API，再加几个工具调用，就可以了。
Claude Code 暴露出的架构提醒我们：真正可用的 AI 编程工具不是 wrapper，而是一个 Agent Runtime。
它的核心循环可以概括为：
也就是常见的 TAOR 循环：
  1. Think：模型根据当前上下文判断下一步。
  1. Act：模型通过工具执行动作。
  1. Observe：系统收集工具执行结果。
  1. Repeat：把观察结果放回上下文，进入下一轮。
这个循环看起来简单，但关键在于：模型不能直接操作世界，必须通过工具间接行动。
这层间接性非常重要。它让所有危险动作都可以被拦截、审计和解释。文件读写、命令执行、网络请求、Git 操作，都不是模型“想做就做”，而是要通过工具 schema、权限系统、安全策略和上下文记录。
如果你正在做自己的 AI Agent 产品，这里有一个很直接的判断：
不要把工具调用看成模型能力的附属品。工具层本身就是产品架构的边界。

2. System Prompt 是成本工程，不只是提示词工程

很多人讨论 system prompt 时，只关心“怎么写得更聪明”。Claude Code 的设计更现实：system prompt 同时也是成本工程。
一个成熟 Agent 的 system prompt 不只是几句角色设定，它通常包含：
  1. 静态行为规则。
  1. 工具使用规范。
  1. 当前项目上下文。
  1. 用户偏好和记忆。
  1. MCP 或外部工具说明。
  1. Git 状态、目录信息、语言偏好等动态信息。
这意味着用户还没输入第一句话，系统可能已经塞进了几千到上万个 token。
所以 prompt 的物理排布会影响成本。稳定内容放前面，动态内容放后面，才能尽可能命中 prompt cache。反过来，如果把频繁变化的数据塞到缓存前缀里，缓存会被打碎，成本和延迟都会上升。
这里的经验很实用：
  1. 不变的规则放在最前面。
  1. 会变化的上下文放在后面。
  1. 个性化内容不要污染全局静态前缀。
  1. 模型升级后要重新验证 prompt 策略。
Prompt Engineering 不只是写文案，它已经变成了系统性能和成本控制的一部分。

3. 工具系统的关键不是“多”，而是“边界清楚”

读书笔记里提到，Claude Code 的工具系统规模很大，但从能力原语看，大致可以收敛成四类：
原语
典型动作
风险
Read
读取文件、搜索内容、查看图片或文档
低到中
Write
新建文件、编辑文件、写入记忆
中
Execute
运行命令、测试、构建、Git 操作
中到高
Connect
调外部服务、MCP、网络交互
中到高
这个分类的价值在于：权限、安全和审计都可以围绕原语展开，而不是围绕每一个具体工具临时打补丁。
最值得注意的是 Bash。
Bash 是一个万能适配器。通过 Bash，Claude Code 可以调用几乎任何技术栈里的工具：npm、pytest、git、docker、xcodebuild、rg、make、cargo、bun……
但也正因为 Bash 太强，它最难控制。
所以 Claude Code 的设计思路不是“能用 Bash 就都用 Bash”，而是优先使用专用工具。读文件用 Read，改文件用 Edit，搜索内容用 Grep，只有专用工具覆盖不到时才使用 Bash。
这背后的原则很清楚：
万能工具负责兜底，专用工具负责日常路径。
如果你在设计 AI 工具系统，可以从下面这个极简 TypeScript 模型开始：
真实系统当然更复杂，但这个模型已经抓住了重点：工具不是一个函数列表，而是一套能力边界。
notion image

4. 权限系统不是为了限制 AI，而是为了建立信任

很多用户喜欢 Auto 模式，因为它减少了确认弹窗。但真正可怕的 Auto 模式，是没有边界地自动执行。
Claude Code 的权限系统给了一个很好的方向：Auto 不是“完全放开”，而是“在安全流水线里尽量自动”。
读书笔记里提到几个关键设计：
  1. 对不同工具和路径做分级。
  1. 对敏感文件做保护，例如 shell 配置、Git 配置、Claude 配置、MCP 配置。
  1. 对危险命令做额外审查。
  1. 对连续拒绝和异常行为设置熔断机制。
  1. 在 Auto 模式下临时剥离过于宽泛的危险权限。
这说明 Anthropic 并没有假设分类器或模型永远正确。相反，它承认安全判断会出错，所以设计了降级机制。
这是非常成熟的工程态度。
安全系统最重要的不是宣称“我们能识别所有风险”，而是回答：
  1. 判断错了怎么办？
  1. 用户连续拒绝怎么办？
  1. 模型反复尝试危险动作怎么办？
  1. 哪些文件即使用户平时允许写入，也不应该在 Auto 模式下随便改？
AI 产品要让用户放心，不是靠一句“请信任我”，而是靠可解释、可恢复、可降级的权限系统。

5. 记忆系统应该记慢变量，不该记快变量

Claude Code 的记忆系统有一个很克制的原则：只记偏好，不记代码。
这点很关键。
代码是快变量。今天函数在这个文件，明天可能已经重构到另一个模块。今天项目用这个框架，过几周可能切了方案。如果把这些临时事实写进长期记忆，AI 未来反而会被旧信息误导。
偏好、约定、长期习惯才是慢变量。例如：
  1. 用户喜欢 TypeScript 严格类型。
  1. 项目倾向使用 Composition API。
  1. 团队要求所有新增逻辑都补测试。
  1. 用户不希望自动提交 Git commit。
这些信息跨会话仍然有价值。
更进一步，读书笔记里提到 Claude Code 会用独立的 fork agent 做记忆提取。这样做有两个好处：
  1. 记忆提取过程不会污染主对话上下文。
  1. 写入持久记忆的权限可以被单独限制。
这也是一个可以直接迁移到其他 AI 产品里的设计：
记忆不是聊天记录仓库，而是长期偏好系统。
把记忆系统当笔记本，会越来越乱；把它当偏好和约定的持久层，才会越用越准。

6. 上下文压缩不是总结，而是有损状态迁移

长对话里，AI 偶尔忘记之前的要求，很多时候不是态度问题，而是上下文压缩的结果。
上下文窗口有限，Agent 又需要不断把工具结果、文件内容、命令输出和中间观察塞进对话。任务一长，就必须压缩。
但压缩的本质是有损的。你不可能用更短的文本无损表达更长的上下文。
所以成熟系统不会把 compact 当成“总结一下”，而是把它当成状态迁移：
  1. 当前目标是什么？
  1. 已完成什么？
  1. 正在进行什么？
  1. 哪些文件改过？
  1. 哪些约束必须保留？
  1. 哪些失败尝试不能重复？
  1. 下一步应该做什么？
这也是我们平时使用 AI 编程工具时可以反向利用的地方：
  1. 关键项目规则写进 CLAUDE.md，不要只写在聊天里。
  1. 长任务定期手动 compact，并明确要求保留重要约束。
  1. 复杂任务拆成多个会话，减少多轮压缩后的信息衰减。
  1. compact 后第一轮回复要重点检查，发现偏差马上纠正。
不要期待压缩不丢信息。真正可靠的做法，是把最重要的信息放到不会被压缩掉的位置。
notion image

7. 为什么 grep 可以打败 RAG

这可能是 Claude Code 最有启发性的取舍之一：代码搜索没有默认走复杂 RAG，而是大量依赖 grep、glob、read 这类简单工具。
表面看，这很反直觉。2026 年做 AI 应用，不上向量数据库，好像就不够先进。
但代码搜索的消费者不是普通用户，而是 LLM。
如果搜索结果是直接展示给人看，语义搜索很有价值，因为人希望系统先帮忙筛选。可如果搜索结果是给强模型看的中间材料，情况就变了。
grep 的优势是：
  1. 精确。
  1. 快。
  1. 零索引维护。
  1. 总是基于最新代码。
  1. 结果可解释。
  1. 不需要处理 chunk、embedding、向量库和召回调参。
LLM 可以自己理解 grep 结果之间的关系，推断调用链，继续发起下一轮搜索。也就是说，把“理解”集中交给模型，把外围搜索工具保持简单，反而更稳定。
这不是说 RAG 没用，而是要分场景。
当系统消费的是非结构化知识库、FAQ、文档语义匹配，RAG 很合适。但在代码库里，尤其是 Agent 会多轮搜索、读取和验证时，精确文本搜索往往已经足够强。
这里的工程判断是：
手里有 RAG，不代表所有问题都应该向量化。

8. 多 Agent 的难点不是并发，而是组织设计

多 Agent 很容易被讲成“多个 AI 并行干活”。但真正的难点不在并发，而在组织设计。
一个成熟的多 Agent 系统要回答：
  1. 谁负责拆任务？
  1. 子 Agent 能看到多少上下文？
  1. 子 Agent 的权限是否低于主 Agent？
  1. 子 Agent 的结果如何合并？
  1. 多个 Agent 结论冲突时听谁的？
  1. 主 Agent 被中断时，子 Agent 是否继续？
这些问题和管理真人团队很像。
如果没有清晰的任务边界，多 Agent 只会把一个人的混乱变成多个人的混乱。如果没有结果合并机制，多 Agent 会制造更多上下文噪音。如果没有权限隔离，子 Agent 会扩大安全风险。
所以多 Agent 不应该从“我要开几个 Agent”开始设计，而应该从组织结构开始：
  1. Coordinator 是否能自己解决简单问题？
  1. 什么时候才委派？
  1. 委派任务是否足够窄？
  1. 返回结果是否有统一格式？
  1. 是否有验证者或审查者角色？
技术实现可以很轻量，组织边界必须很清楚。

9. 从 Claude Code 学到的 10 条工程原则

整理这份读书笔记后，我认为最值得带走的是下面 10 条：
  1. AI 编程产品不是 API wrapper，而是 Agent Runtime。
  1. 模型决定能力上限，harness 决定兑现率。
  1. 工具 schema 是控制 AI 行为的核心边界。
  1. Bash 这类万能工具应该兜底，不应该成为默认路径。
  1. 权限系统的目标不是阻止 AI，而是让用户敢于授权。
  1. 安全分类器一定会误判，所以必须有熔断和降级。
  1. 记忆应该存慢变量，快变量交给实时搜索和读取。
  1. 上下文压缩必然有损，关键约束要写进稳定配置。
  1. 代码搜索不一定需要 RAG，精确搜索加 LLM 理解往往更可靠。
  1. 多 Agent 的核心是组织设计，不是简单并发。
如果把这些原则压缩成一句话，就是：
复杂度应该集中在模型和少数关键边界上，外围系统要尽量简单、可控、可解释。

总结

Claude Code 的源码泄露是一次事故，不值得浪漫化。但它暴露出来的架构思路，确实给 AI 产品开发者上了一堂很有价值的工程课。
过去一年，很多 AI 应用的问题不是“模型不够聪明”，而是 harness 太薄：工具没有边界，权限没有分层，记忆什么都存，上下文压缩随便总结，搜索一上来就堆 RAG，多 Agent 只是并发调用几个模型。
Claude Code 的启发在于，它没有把每个模块都做得很复杂。相反，很多地方都很朴素：grep 搜索、纯文本记忆、工具 schema、权限流水线、结构化 compact。
但这些朴素组件组合起来，形成了一个可靠的 Agent Runtime。
这可能才是 AI 编程工具真正的竞争壁垒：不是单点能力，而是把模型能力变成稳定交付能力的工程系统。

参考资料

  • 读书笔记：《Claude Code 源码解析：一份价值数十亿美元的 AI 工程蓝图》
 
2026.06.03 20:50 沪 · 赵巷
📌 声明：本文由 AI 辅助完成