51万行代码的AI编程工具里，藏着18种宠物的抽卡系统。
源码中有一条对主代理的编排纪律：「Never delegate understanding」——主代理不能把「理解」这件事推给子代理。
AI 需要搜索代码时，不靠模型自己的记忆去猜，而是调用一个确定性的搜索工具。
这些看似不相关的细节，来自同一个产品——Claude Code。2026年3月31日，Anthropic 因一个配置疏漏，意外把它的完整源码塞进了 npm 发布包。51万行 TypeScript、1884个文件，第一次看到一个成熟AI Agent产品的完整内部。
这篇文章从产品设计的视角拆解它——不是讲代码怎么写，而是讲产品怎么想。 它的很多设计体现了深度的 AI Native 思维，同时在安全工程、成本控制、多代理协作等维度也有大量值得学习的实践。
一、全貌：AI 驱动的执行循环
Claude Code 不是聊天工具，而是以 AI 为执行引擎的多代理操作系统。
与 AI 模型交互的核心代码只有约 6,400 行，占总量 1.2%。剩下 50 万行全部是让 AI 安全、准确、高效工作的基础设施。据社区分析，还有大量 internal-only 模块在泄露中缺失，我们看到的只是冰山一角。
五层架构：入口层 → 智能体循环（Agentic Loop） → 工具运行时（40+ 工具） → 执行层 → 上下文与记忆。
核心是 Agentic Loop——AI 在循环里持续运行：接收指令 → 构建上下文 → 选择工具 → 权限检查 → 执行 → 看结果 → 决定下一步 → 继续。传统产品是「用户点按钮触发功能」，Claude Code 是「用户说意图，AI 自己规划和执行」。AI 不是产品的一个功能模块，而是产品的执行引擎——这是 AI Native 架构的核心。
这次意外泄露让我们第一次有机会看到一个生产级 AI Agent 的完整内部设计——51万行代码、1884个文件、光安全相关就超过8000行。
二、分工：AI 做什么，工具做什么
这是 Claude Code 最能体现 AI Native 思维的设计原则。
当 AI 需要搜索代码时，不让模型自己去「想」结果在哪里，而是调用内置的搜索工具去精确搜索。文件查找、文件读取、内容搜索——都有专门的确定性工具，输入确定、输出确定，不需要 AI 的概率推理。源码行为手册中甚至明确指导 AI：搜索用内置工具，不要自己写 shell 命令。
这个原则不只体现在搜索上——AI 不直接修改文件（调用专门的编辑工具做精确替换）、不自己记文件状态（系统维护缓存追踪）、不自己判断 Git 状态（系统自动获取真实信息注入上下文）。
背后的产品判断：AI 的价值不在于「能做所有事」，而在于「知道该做什么以及谁来做」。 AI 擅长理解意图、选择工具、编排顺序、处理异常。精确搜索、确定性匹配、文件操作，交给专门工具更可靠。
如果你在做 AI 产品：不要让 AI 做所有事，让 AI 做 AI 最擅长的事。 很多产品体验不好，不是模型不强，是把不该交给 AI 的事也交给了 AI。
三、感知：AI 怎么理解工作环境
为什么同一个 Claude 模型，在普通对话框和在 Claude Code 里表现判若两人？
想象一个场景：你说「帮我把这个函数优化一下，然后提个 PR」。在你敲下回车的瞬间，AI 已经知道：你在哪个分支、主分支是什么、有哪些未提交修改、最近提交是什么、项目用什么技术栈、团队的编码规范、自己当前的权限范围、你上次说过偏好 TypeScript。你什么都没交代，AI 全知道了。
对比普通聊天——每次都要说「我在用 React，项目在 feature-xxx 分支…」。
这个差距来自六层动态上下文系统：系统上下文（Git 状态自动获取）→ 用户上下文（CLAUDE.md 项目说明书，可入 Git 团队共享）→ 工具行为手册（BashTool 370 行的「AI 员工手册」）→ 权限上下文 → 记忆系统（范围×温度双维度：用户级/项目级/本地级 × Hot/Warm/Cold）→ 沙箱配置。
全部动态生成。 不存在固定 System Prompt——系统根据用户类型、权限模式、项目配置实时拼装。
如果你在做 AI Agent，第一件事不是选模型——列出 AI 每次决策需要的所有信息，然后设计获取和组装的机制。上下文丰富程度直接决定 AI 表现上限。
四、安全：AI 犯错了怎么兜底
AI 是概率系统，它一定会犯错。Claude Code 的安全设计不是试图让 AI 不犯错，而是假设 AI 一定会犯错，然后层层兜底。
具体在防什么？
想象一个场景：你对 Claude Code 说「帮我清理一下项目里的临时文件」。
AI 理解了你的意图，决定执行一条删除命令。但它可能理解得不够准确——也许它会删除的范围比你预期的大，也许它拼错了路径，也许它被某种 Prompt 注入误导去删除了不该删的东西。
这就是 AI 产品安全要防的核心问题：AI 理解了你的意图，但执行的结果可能偏离你的预期——而且一旦执行了，可能不可逆。
传统产品主要防外部攻击者。AI 产品还要防 AI 自身的不可预测性——幻觉、理解偏差、被恶意 Prompt 误导。这些不是 bug，是概率系统的固有属性。
六层层层兜底
Claude Code 的做法是设六道关卡，每一道都假设前一道会失败：
第一道：先告诉 AI 规矩。 在 AI 的系统指令中明确写清行为边界——什么能做、什么不能做。但这是最弱的一层，AI 可能被巧妙的 Prompt 注入绕过。
第二道：规则硬匹配。 24 个权限文件定义了白名单和黑名单——rm -rf、sudo、kubectl 这些危险命令，不管 AI 怎么说，规则引擎直接拦截。
第三道：另一个 AI 来审核。 用一个独立的 AI 模型（Claude Sonnet 4.6）实时审核主 AI 的每个动作。它评估的核心不是「这个动作危不危险」，而是「AI 的行为和用户的意图是否匹配」——这就是 intent gap（意图差距）的概念。比如用户说「清理临时文件」，AI 要删除 .env 配置文件——意图明显不匹配，阻断。
第四道：代码级硬检查。 2,593 行安全代码，用模式匹配检测各种命令注入、进程替换等攻击手法。这是纯确定性的检查，不依赖 AI 判断。
第五道：操作系统级隔离。 即使前四道都没拦住，操作系统的沙箱会限制 AI 能访问的文件范围和网络范围。
第六道：熔断。 如果 AI 连续被拦了3次或累计被拦了20次，系统自动从自动模式降级到手动确认——交回人类判断。
六种使用模式
除了六层防御，Claude Code 还设计了六种权限模式，让用户根据场景选择不同的信任程度：
日常模式——每次编辑和执行都要问你，危险命令直接拒绝。最保守。
信任编辑模式——AI 编辑代码不再问你，但执行命令还是要问。
只看不做模式——AI 只能分析和建议，不能动任何东西。适合「让 AI 先看看再说」。
自动模式——由审核 AI 自动判断是否放行。效率最高，但需要信任分类器。
CI/CD 模式——白名单内自动执行，其他拒绝。适合自动化流水线。
完全放开模式——全部自动执行。仅在完全隔离的沙箱里使用，极危险。
而且有动态降级——系统会根据 AI 的实际表现自动调整，不是只靠用户手动切换。
如果你在做有执行能力的 AI 产品：安全不能只设一道关卡，权限不能只有开和关，而且一定要有自动降级机制——AI 频繁出问题时系统要能自己退回更保守的模式。
五、指令：Prompt 是动态的行为手册
传统产品里产品经理写 PRD 给工程师。AI Native 产品里，Prompt 就是写给 AI 的 PRD。
Claude Code 里最复杂的一份是 BashTool 的，370 行——工具偏好、工作细则、安全红线、工作流程、沙箱边界，像一本完整的岗位说明书。
这份手册不是固定的。 不同用户看到不同版本——内部员工有保密条款，外部用户有不同规则。不同场景也不一样——沙箱开了就多一段规则，没开就没有。系统根据当前条件实时拼出一份定制化手册。
手册管理还直接影响成本。AI 每次工作前要读一遍手册，内容没变就能复用缓存，变了就得全部重新处理。Anthropic 发现了两个导致缓存大面积失效的问题：一是手册里有个经常变动的子代理清单，每次变动整份缓存失效——拿出来单独放；二是沙箱规则里有每个用户独有的路径，导致用户之间无法共享缓存——换成统一写法。核心逻辑：让手册尽量稳定、尽量通用。仅这两处优化，省了全站 10%+ 的 API 成本。
如果你的 AI 产品有 Prompt：把它当正式工作手册管理——要有版本控制、要分场景定制、要关注改动的成本影响。随手写一段文字，离生产级还很远。
六、协作：一群 AI 怎么分工
Claude Code 不是单一 AI，而是有明确主从关系的多代理系统——主代理负责理解和决策，子代理负责执行。
五种子代理各有专精：Explore 用最便宜的 Haiku、只读、跳过配置减 token；General Purpose 用默认模型、完整工具集；Plan 只分析不执行；Verification 对抗性检验；Guide 帮用户学产品。
三个关键设计：
成本差异化。 搜索用 Haiku（最便宜），推理用默认模型（更强）。不是所有代理都需要最强模型。
Fork 机制。 Fork 继承上下文+共享缓存，比独立启动快且省。反直觉：不要给 Fork 换模型——换模型 = 缓存全失效 = 成本翻倍。
Never delegate understanding——全文最重要的一条设计纪律。
源码要求主代理在给子代理派任务时，不能说「基于你的发现，修这个 bug」——这句话把「理解」的责任推给了子代理，而子代理的上下文可能不完整，理解可能有偏差。
正确做法：主代理自己消化信息，用具体文件路径、行号、分析结论指导下一步。源码原话：「Write prompts that prove you understood.」
这是管理哲学。最差的管理者就是「委托理解」的人——把模糊任务甩给下属。好的管理者先想清楚，再给具体指令。AI 代理编排完全一样。
七、探索：意想不到的设计维度
源码里有几个发现超出了常规产品设计的范畴，但恰恰揭示了 AI Native 产品需要思考的新维度。
BUDDY 电子宠物——完整的 Tamagotchi 系统，18种宠物、5个稀有度、gacha 抽卡、使用频率驱动成长。一个严肃编程工具里藏了抽卡养成系统。背后的产品探索：当你每天和 AI 高强度协作12小时，和一个有「性格」的 AI 协作，会不会比冷冰冰的命令行更有动力？ AI 工具的情感化设计，可能是被低估的方向。
卧底模式——内部员工向开源贡献代码时自动隐藏 AI 痕迹，90 行代码。边界模糊：用 AI 写初稿再人工修改提交，算人写的还是 AI 写的？但它揭示了一个全新维度——AI 产品还有「社会设计」：AI以什么身份在人类社会中行动。 传统产品设计里完全不存在这个问题。
KAIROS 守护进程——内部代号「assistant mode」，后台持续运行、自主整理记忆、15秒阻塞预算不打断用户。如果上线，Claude Code 从「你问我答」进化为「我主动干活」——AI Agent 从被动响应到主动规划。
反蒸馏保护：污染竞争对手的训练数据；Claude Code 在调用 API 时，会在请求中注入假的工具定义。这不是防黑客，是防蒸馏——在 AI 领域，「蒸馏」是指用一个模型的输入输出数据去训练另一个模型，让小模型模仿大模型的行为。
Claude Code 每次调用 API 都会发送完整的工具定义。如果竞争对手拿到这些数据，就可以用来训练自己的模型，让它学会 Claude Code 的工具调用模式。注入假工具定义的目的就是污染这些潜在的训练数据——如果对手用被污染的数据做蒸馏，训练出来的模型会学到错误的模式。
内外双轨：源码中有一个判断条件贯穿始终——当前用户是不是 Anthropic 内部员工。内部员工权限更激进也更严格（可以跳过中间模式直接进高权限，但禁止操作 AWS、Kubernetes 等云资源）。Explore 代理对内用默认模型，对外用便宜的 Haiku。外部用户体验到的，不是这个产品的最强形态。
成本黑箱：源码有完整的 token 消耗追踪和成本计算，但对用户完全不可见。用户不知道一次对话花了多少钱，不知道 Auto Mode 每个动作额外消耗一次分类器调用，也不知道 Fork 比独立启动便宜得多。用户看不见成本，就没法做出理性的使用决策。
AutoDream：AI 也需要「睡觉」；Claude Code 有一个叫 AutoDream 的后台机制——灵感来自人类的 REM 睡眠。AI 在日常工作中会不断往记忆文件里写入笔记，时间久了记忆会变得臃肿：同一件事记了五遍，过期的架构笔记还留着，有用的信息被噪音埋住。AutoDream 会在后台定期启动一个子代理，自动回顾、清理、合并、整理这些记忆——就像人类在睡眠中巩固和整理白天的记忆一样。醒来之后，记忆文件更干净、更有序、检索效率更高。这是一个非常有想象力的 AI Native 设计。
八、回到12原则：这次拆解带来的审视
用 Claude Code 的实践反哺我之前提出的「AI 产品设计 12 原则」（👉AI Native系列①产品设计12原则），有两类收获：
对现有原则的深化——上下文即产品需要「范围×温度」双维度；AI 宪法从规则分层延伸到六层技术落地且要防 AI 自身概率性行为；结构化弹性补充了 intent gap 概念；渐进授权不只线性升级还要动态降级；双用户中「为 AI 设计」比想象的复杂；接口即语义需要延伸到 Prompt 运营层的工程化。
尚未覆盖的领域——AI 产品的经济模型（每个设计决策背后都有成本考量）、AI 的社会设计（卧底模式揭示的新维度）、AI 的情感化设计（BUDDY 宠物系统的认真探索）。
写在最后
读完51万行源码，最深的感受是：
好的 AI 产品设计，本质上是在做一件事——想清楚 AI 能做什么、不能做什么、做错了怎么办。
Claude Code 的答案不是一个天才想法，而是无数个具体的设计决策——搜索交给工具而不是模型，安全做六层而不是一层，权限分六档而不是两档，Prompt 写370行而不是一段话，代理分五种而不是一种，甚至连一个临时目录路径都要替换成变量来优化缓存命中率。
这些决策单独看都不惊艳。但叠在一起，构成了一个其他人短期内很难复制的系统。
模型能力会被追平。但这种一层层堆砌起来的产品工程，才是真正的护城河。
「Brief the agent like a smart colleague who just walked into the room.」
像对待一个刚走进房间的聪明同事那样给 AI 做指令——给足上下文，划清边界，然后让它去做事。
转载请注明：好奇网 » Claude Code源码里的AI产品设计学