Claude Code 源码解析：11 大核心设计与 Agent 架构精髓

源码泄露背景

1. 泄露原因：Anthropic 发布 Claude Code 2.1.88版本时，未排除 Bun 打包默认生成的cli.js.map源映射文件，该文件含 1906 个 TS 文件的完整源码路径与内容，还暴露 Cloudflare R2 公开地址可直接下载源码包；且为第二次出现同类泄露问题。
2. 源码规模：共 51.2 万行 TypeScript 代码，仅为客户端源码，不含服务端模型训练与API后端逻辑。
3. 技术栈：TypeScript + Bun 运行时、React/Ink 终端 UI 框架、Zod v4 schema 校验、@anthropic-ai/sdk API 客户端、@modelcontextprotocol/sdk。
4. 核心涵盖：Agent 循环引擎、40+ 内置工具实现、系统提示词组装、记忆系统、上下文压缩、权限管控及多款未上线隐藏功能。

核心架构分层

Claude Code 整体架构分为 6 层，从上层到下层层层支撑，打造高可用的 AI Agent 编程工具：

1. CLI & TUI层：基于 React/Ink 的终端交互界面，支持 Vim 模式、快捷键绑定，提供 CLI/初始化/MCP/SDK 4 种入口。
2. Agent循环引擎层：核心决策层，基于while(true)无限循环实现 ReAct 机制，是工具调用与任务执行的核心。
3. 工具系统层：42 个内置工具 + MCP 扩展，含工具注册、编排、并发执行等能力，支持工具按需加载。
4. 记忆系统层：独创三层记忆架构，解决 AI “断片”问题，实现上下文的高效管理与召回。
5. 上下文压缩层：五级压缩管线，动态控制 token 用量，避免上下文窗口溢出，降低调用成本。
6. 权限&安全层：多层安全审查与权限管控，从工具执行到命令检测全链路保障安全。

11大核心设计亮点解析

1. 极简 Agent 主循环

• 核心代码为query.ts中的while(true)无限循环，20 行伪代码即可描述，实现思考→调用模型→解析工具→执行工具→追加结果的 ReAct 闭环。
• 循环中通过stop_reason判断是否继续工具调用，流式获取模型响应，支持 token 用量累计与中断机制。
• 源码中含“巫师守则”注释，对模型 thinking block 处理做严格约束，避免调试问题。

2. 安全优先的工具设计

• 内置 42 个基础工具，通过getAllBaseTools()注册，工具清单与A/B测试配置中心同步，保障系统提示词缓存有效性。
• 基于buildTool工厂函数创建工具，采用fail-closed（失败关闭） 设计：默认标记工具为非并发安全、非只读，未显式声明则按危险操作处理。
• 支持ToolSearchTool按需加载：工具数量过多时，先提供“工具名+一句话描述”精简清单，模型选择后再加载完整定义，节省 token。
• 区分内部员工与普通用户工具集，内部代号ant对应 Anthropic 员工专属工具（如ConfigTool）。

3. 读写分离的工具并发策略

• 最大并发数默认 10，可通过环境变量CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY调整。
• 核心逻辑在toolOrchestration.ts，实现读读并行、读写互斥：连续只读工具合并为批次并行执行，写工具单独串行执行。
• 上下文修改器contextModifier排队应用：批次内工具执行完成后，按调用顺序依次应用修改，避免数据不一致。
• 异常兜底：工具并发安全判断抛异常时，直接判定为非安全，继续串行执行。

4. 系统提示词缓存优化

• 用SYSTEM_PROMPT_DYNAMIC_BOUNDARY将提示词分为静态部分与动态部分：静态部分为全球用户共享的角色定义、工具说明等，可全局缓存；动态部分为用户专属的 Git 状态、CLAUDE.md配置等，独立加载。
• 严格禁止动态内容混入静态部分，避免缓存失效，源码中添加强警告注释，关联缓存逻辑相关文件。

5. 非 RAG 的 Agentic Search 内容检索

• 摒弃主流的 RAG 检索增强生成方案，采用Grep纯文本搜索实现内容检索，无需维护向量数据库，降低工程复杂度。
• 检索范围覆盖记忆文件与历史对话，直接让AI自主决定搜索关键词与范围，适配大模型的自主决策能力。
• 创始人证实：模型能力足够强时，Agentic Search 效果优于 RAG，无需人工提前整理资料。

6. 三层自愈式记忆架构

解决AI长期记忆问题，按数据热度分层管理，从根源避免缓存与实际数据不一致：

1. MEMORY.md（热数据）：常驻加载，最多200行/25KB 双限制，仅存指针不存内容；超出限制时做行数+字节双截断，且在最后一个换行符切割，追加 WARNING 提示AI文件未加载完整。
2. 话题文件（温数据）：存储用户编码偏好、项目架构约定等，新对话时由 Sonnet 小模型智能选择最多5个相关文件加载，优先选择工具坑点、警告类文件，不加载已在使用的工具文档。
3. 历史对话（冷数据）：以.jsonl格式存储，通过 Grep 关键词搜索召回，不记录代码（避免代码更新导致记忆失效），仅记录用户偏好与判断。

7. 五级上下文压缩管线

从轻到重依次触发，动态控制上下文体积，搭配断路器机制避免无效重试：

1. Snip剪裁：裁掉过旧对话片段，仅保留工具调用结构，丢弃内容。
2. Microcompact微压缩：将大体积工具执行结果卸载到磁盘缓存，子 Agent 可按需读取。
3. Context Collapse折叠：对中间对话做折叠摘要，仅保留关键信息。
4. Autocompact自动压缩：上下文占用超阈值时，触发全量摘要压缩。
5. Reactive Compact应急压缩：API 返回 413 “提示词太长”时紧急兜底。

• 断路器机制：自动压缩连续失败 3 次则停止，避免源码中出现的“单会话连续失败 3272 次、全球每天浪费 25 万次 API 调用”问题。
• 压缩后自动恢复最近 5 个文件 + 技能文件，防止任务漂移。

8. 多层全链路安全审查

即使开启--dangerously-skip-permissions（YOLO模式），仍有多层安全防护，工具调用需通过五层过滤，最终取最严格结果：

1. 运行模式过滤：Plan/Auto/Bypass 三种模式的基础权限限制。
2. Hooks规则过滤：用户自定义的钩子拦截规则。
3. YOLO Classifier过滤：独立影子 AI 模型分析操作风险，返回 allow/soft_deny/hard_deny 结果。
4. Bash安全过滤：定义23种检查规则，拦截rm -rf、Unicode 空白欺骗、IFS 注入等危险操作。
5. 规则引擎过滤：.claude.json配置文件中的 23种 自定义检查规则。

• 结果处理：allow 直接执行，soft_deny 需用户手动确认，hard_deny 直接拦截。

9. Feature Flag灰度发布与未上线功能

• 广泛使用feature('XXX')做功能开关，支持按用户/环境灰度发布，未开启的功能通过require条件加载，可被 tree-shaking 剔除，不增加包体积。
• 泄露的产品路线图：KAIROS 长期助手模式（24h 持久运行 + AutoDream 自动记忆整理）、COORDINATOR_MODE 多 Agent 协作（研究→综合→实现→验证四阶段，子 Agent 通过 Mailbox 文件通信）、VOICE_MODE 语音交互、WEB_BROWSER_TOOL 浏览器控制等。

10. 反蒸馏与卧底模式的防御机制

1. 反蒸馏：为官方 CLI 客户端注入fake_tools假工具定义，向竞品的API流量录制行为投喂假数据，让其训练的模型效果变差，仅对官方入口生效，不影响 SDK 调用。
2. 卧底模式：Anthropic 内部员工（USER_TYPE=ant）向开源项目提交代码时自动开启，无强制关闭开关，自动剥离所有内部模型代号、项目名称等信息，避免内部信息泄露；默认开启，仅内部仓库可关闭。

11. 极致的性能优化细节

• 按需动态加载：--version等简单请求不加载任何模块，其他功能通过await import()动态引入，减少启动时间。
• 早期输入捕获：启动加载时缓存用户输入，加载完成后回放，提升交互体验。
• TCP预连接：初始化时异步发起 Anthropic API 的 TCP+TLS 握手，与模块加载并行，节省 100-200ms 等待时间。
• 硬编码优化：针对AI频繁执行mkdir检查目录的问题，硬编码提示词告知AI目录已存在，避免浪费对话轮次。

趣味隐藏功能

• BUDDY虚拟宠物系统：共 18 种物种（鸭子、水豚、龙、仙人掌等），含调试力/耐心/混沌/智慧/阴阳怪气5个属性，基于 Mulberry32 PRNG 实现抽卡，原计划2026 年 4 月预热、5 月正式上线，因源码泄露提前曝光。

核心设计哲学与结论

1. 核心哲学

• 模型负责智能，代码负责工程：将复杂的决策、推理交给 Claude 大模型，代码仅实现稳定、可靠的工程化能力，不做过度抽象。
• 概念极简，工程极重：核心循环、检索、记忆等核心逻辑的概念简单易懂，但在工程实现上做足细节，覆盖并发、安全、性能、容错等全维度。
• 放弃通用性，追求极致深度：原生仅支持Claude系列模型，将所有工程精力投入到单模型的深度协同优化，而非多模型的通用适配。

2. 关键结论

1. Claude Code的成功并非依赖复杂的 Agent 框架，而是简单可组合的模式+极致的工程化实现，直接调用 LLM API 反而能实现更高的可靠性。
2. 计算机基础设计思想（读写分离、分层缓存、断路器、fail-closed）在 AI Agent 场景中依然适用，优秀的产品是基础思想的合理组合与场景适配。
3. 大模型能力的提升，让很多传统复杂工程方案（如RAG）可被更简单的Agentic方案替代，AI能力与工程能力的边界需要重新定义。
4. 源码泄露虽暴露 Anthropic 的发布流程问题，但也为 AI Agent 开发者提供了最佳实践参考，其记忆、压缩、安全等设计可直接复用到各类AI应用中。
5. AI Agent 框架的终局是核心变薄，协议统一，生态为王：MCP（Model Context Protocol）作为Agent的“USB协议”，已成为行业事实标准，不支持MCP的框架将失去商业竞争力。

3. 开发启示

1. 做 AI Agent 无需迷信第三方框架，直接调用 LLM API + 可靠的工程化实现，更易打造高性能产品。
2. 上下文工程是 AI Agent 的核心能力，记忆分层、动态压缩、按需召回是提升体验的关键。
3. 安全设计需贯彻“默认禁止”原则，多层过滤、异常兜底能有效避免AI操作的风险。
4. 性能优化要关注细节，异步加载、预连接、输入缓存等小优化能显著提升用户体验。
5. 大模型应用的核心是让模型做擅长的事，让工程解决可靠的事，避免用工程逻辑替代模型智能。

参考资料

• 刚刚 Claude Code 源码泄露！我扒出了 11 个隐藏秘密