事件背景：2026年3月31日，Anthropic 在发布 Claude Code CLI（npm 包 v2.1.88）时，因构建配置疏忽，将 60MB 的.mapSource Map 文件一并打包发布。任何人皆可通过该文件完整还原约1,906 个 TypeScript 源文件、512,000+ 行代码。安全研究员 Chaofan Shou 率先在 X 平台公开，社区随即在 GitHub 上建立多个镜像仓库（如instructkr/claude-code、Piebald-AI/claude-code-system-prompts）。这是 Anthropic 13 个月内第二次类似事故。

目录

1. 泄露全貌：规模与内容
2. 提示词工程深度洞察
3. 技能（Skills）设计体系
4. MCP 协议实现细节
5. 工具系统架构
6. 记忆与上下文管理
7. 多代理协同机制
8. 权限与安全体系
9. 隐藏功能与彩蛋
10. 对开发者的启示与建议

一、泄露全貌：规模与内容

技术栈概览

核心模块规模

工具系统（Tool System）      ~40,000 行
查询引擎（Query Engine）     ~46,000 行
工具注册与权限              ~29,000 行
MCP 客户端服务              services/mcp/ 目录
多代理编排                  AgentTool + Swarm 系统
IDE 桥接                    JWT 认证的 VS Code / JetBrains 通道

系统提示词模块数量

Piebald-AI 的仓库记录了截至v2.1.89（2026年3月31日）的完整提示词体系，包含110+ 个独立提示词字符串，分为：

• 代理提示词（Explore / Plan / Task 子代理）
• 斜杠命令提示词（/batch / /schedule / /security-review 等）
• 系统提醒（~40 个 System Reminders）
• 内置工具描述（18 个核心工具）
• 技能提示词（/init、debug、validate 等）

二、提示词工程深度洞察

这是泄露内容中对开发者最有价值的部分，揭示了 Anthropic 生产级提示词工程的核心设计哲学。

2.1 分段缓存策略（Prompt Caching Architecture）

Claude Code 将系统提示词分为静态段和动态段，并以SYSTEM_PROMPT_DYNAMIC_BOUNDARY标记分隔：

[静态段] 模型身份 + 核心规则 + 工具描述 + 代码风格规范
         ↑ 全局可缓存，命中率高

[动态段] 当前工作目录 + Git 状态 + 用户配置 + 环境变量
         ↑ 高频变化，不参与缓存

工程细节：

• 工具描述按字母表排序，避免微小变化导致缓存失效
• 大量辅助内容移至消息附件（Attachments），减少主提示词 token 量
• 文件读取结果会在 API 层标记并缓存，同会话内重复读同一文件直接命中缓存

启示：提示词中越固定的内容越靠前，高频变化的状态信息与静态规则严格分离，是工业级 Prompt 节省 Token 的关键。

2.2 主系统提示词结构（2,981 tokens）

主提示词体现了以下核心设计原则：

角色定义

• 明确定位为”AI 编程助手”，非通用聊天机器人
• 响应以简洁为先（CLI 环境，不适合长篇大论）
• 使用 GitHub 风格 Markdown，针对等宽字体格式化
• 严禁使用表情符号（除非用户明确要求）
• 工具调用仅用于完成任务，不得用工具与用户闲聊

行为约束

• 修改文件之前必须先读取文件（强制前置验证）
• 优先技术准确性，拒绝过度工程化和不必要抽象
• 对危险操作（如rm -rf）硬编码拦截，执行前必须解释命令意图

结构化任务管理

• 在复杂任务中自动创建TodoWrite任务列表
• 清晰标记in_progress/completed/pending状态
• 每次仅一个任务处于进行中

2.3 条件提示词加载（Contextual Prompt Injection）

提示词不是一次性全量注入，而是按需动态组合：

// 伪代码示意
const systemPrompt = [
  baseSystemPrompt,           // 静态核心（始终加载）
  environmentContext,         // 工作环境动态信息
  ...(hasMCP ? [mcpContext] : []),        // 仅当存在 MCP 连接时
  ...(isTeamMode ? [teamContext] : []),   // 仅在团队模式下
  ...(userCLAUDEmd ? [claudemdContent] : []),  // 用户的 CLAUDE.md
]

意义：避免将所有可能的指令一次性喂给模型，通过条件加载减少无关上下文噪音。

2.4 子代理提示词独立设计

每种角色的子代理（Explore / Plan / Task）都有专属提示词：

2.5 斜杠命令提示词设计规律

从泄露的斜杠命令提示词中，可以总结出 Anthropic 的设计规律：

/security-review  → 2,607 tokens（高复杂度，详细检查清单）
/schedule         → 2,468 tokens（任务调度逻辑完整）
/batch            → 1,106 tokens（并行变更指令）
/review-pr        → 211 tokens （简洁，目标明确）
/pr-comments      → 402 tokens （固定格式输出）

规律总结：任务越复杂、越容易出错 → 提示词越长，包含详细验收清单；任务越格式化、越确定性 → 提示词越短，仅定义输出结构。

三、技能（Skills）设计体系

3.1 SKILL.md 标准结构

从泄露的内置技能和社区实践中提炼出的标准SKILL.md模板：

3.2 渐进式披露机制（Progressive Disclosure）

这是 Claude Code Skills 设计中最值得学习的架构思想：

元数据（YAML frontmatter）  → 常驻内存，用于索引和触发判断
指令正文（SKILL.md body）   → 触发时加载，占主要 token
附加资源（scripts/ 等）      → 按需加载，不默认注入

核心价值：通过三层结构控制 token 消耗，不相关的技能不占用上下文窗口。

3.3 决策矩阵：何时用 Skills vs 其他组件

3.4 Claude Code 四大配置组件

从泄露源码和官方文档整合的最佳实践目录结构：

your-project/
├── CLAUDE.md                    # 项目说明书（顶层上下文）
└── .claude/
    ├── rules/                   # 编码规范库（每条规范独立 .md 文件）
    │   ├── controller.md
    │   └── database.md
    └── skills/                  # 自动化技能包
        └── create-api/
            ├── SKILL.md         # 技能定义
            └── scripts/         # 辅助脚本（按需加载）

四、MCP 协议实现细节

4.1 MCP 客户端完整实现

泄露的services/mcp/目录揭示了 Anthropic 的生产级 MCP 客户端实现：

支持的连接方式

stdio      → 本地进程通信（最常用）
SSE        → Server-Sent Events（远程只读流）
WebSocket  → 双向实时通信

自动配置加载

• 从~/.claude/mcp.json全局配置加载
• 支持动态 OAuth 2.0 认证流程
• 连接状态会与会话一同序列化持久化

4.2 MCPTool 适配器模式

// 所有 MCP 工具均通过 MCPTool 适配器封装
// 对模型透明，与内置工具体验完全一致
interface MCPTool extends Tool {
  mcpServer: string;
  originalToolName: string;
  // 内部自动处理协议转换和错误映射
}

关键设计：MCP 工具对模型层完全透明，Claude 无需知道调用的是本地工具还是远程 MCP 服务，统一工具接口是 MCP 可扩展性的核心。

4.3 MCP 与 Skills 的协作模式

用户触发技能（Skill）
    ↓
Skill 定义中声明 allowed-tools 包含 MCP 工具
    ↓
MCP 工具负责访问外部数据（数据库/API/搜索）
    ↓
Skill 的提示词负责清洗数据、格式化输出
    ↓
最终结果返回用户

最佳实践：MCP 负责”拿数据”，Skills 负责”用数据”，职责清晰分离。

4.4 MCP 安全注意事项（来自源码分析）

• MCP 工具同样经过权限门控，不会绕过 Claude Code 的权限系统
• 恶意 MCP 服务器可能通过精心构造的工具描述影响模型行为（Prompt Injection via Tool Description）
• 建议：只连接可信的 MCP 服务器，定期审查~/.claude/mcp.json配置

五、工具系统架构

5.1 工具接口统一定义

interface Tool {
  name: string;
  description: string;           // 这段描述直接进入提示词，至关重要
  inputSchema: ZodSchema;        // 严格的类型约束
  permissions: PermissionGate;   // 多级权限检查
  isConcurrencySafe?: boolean;   // 标记是否可并行执行
  maxResultSizeChars?: number;   // 结果大小限制
  defer_loading?: boolean;       // 是否延迟加载（减少初始 token）
  
  execute(context: ToolContext): Promise<ToolResult>;
}

5.2 流式并发执行（StreamingToolExecutor）

API 流式响应
    ↓
StreamingToolExecutor 监听响应流
    ↓
检测到完整工具调用块 → 立即触发执行（无需等待整个响应）
    ↓
isConcurrencySafe=true  → 并行执行（如多个文件读取）
isConcurrencySafe=false → 串行执行（如文件写入，防止竞争条件）
    ↓
执行结果按请求顺序缓冲 → 保证对话连贯性

性能意义：流式执行相比等待完整响应后再执行，可将整体延迟降低 30-50%（特别是涉及多工具调用的复杂任务）。

5.3 核心内置工具详细规格

5.4 工具描述工程原则

从泄露内容中提炼的工具描述写作规律：

1. 明确使用场景：描述”何时用”，不仅是”能做什么”
2. 包含安全约束：危险工具的描述中直接嵌入使用限制
3. 指定输出格式：预期输出的结构和大小限制
4. 错误处理提示：常见失败场景及恢复建议
5. 性能提示：大文件/长时间操作的最佳实践

六、记忆与上下文管理

6.1 三层记忆架构

Layer 1: MEMORY.md（高层索引）
         → 轻量 Markdown 文件，存储简短引用而非完整信息
         → 相当于记忆的"目录"

Layer 2: 主题文件（详细知识库）
         → 按 Frontmatter 分类的单独文件
         → 仅在需要时按需加载

Layer 3: 历史会话记录（情景记忆）
         → 选择性检索，不全量加载
         → 执行前验证记忆与当前代码状态的一致性

核心洞察：Claude Code 的记忆哲学是”智能遗忘比盲目记忆更重要“——索引化存储而非堆砌，防止上下文”记忆中毒”。

6.2 KAIROS 与 Dream 机制（未发布功能）

源码中包含两个仍处于特性开关保护下的高级记忆功能：

KAIROS 模式

• 疑似”守护进程”形态，支持 AI 在后台无需用户实时干预持续运行
• 在任务暂停期间异步处理低优先级工作

Dream（梦境）机制

• 在 Agent 空闲时自动整合短期日志为长期记忆
• 消除矛盾的记忆条目，将”观察”升级为”验证事实”
• 类似人类睡眠期间的记忆巩固过程

6.3 上下文压缩（Context Compaction）

长会话 → 自动触发上下文压缩
    ↓
保留：关键决策、代码变更、用户偏好
丢弃：中间探索过程、已解决的错误、重复内容
    ↓
压缩后仍能继续会话，且不丢失核心上下文

6.4 会话序列化与断点续传

所有以下内容会被序列化持久化到磁盘：

• 完整对话历史
• 权限批准状态（不重复询问已授权操作）
• MCP 连接配置
• Token 成本统计
• 进行中的任务状态

七、多代理协同机制

7.1 三种 Agent 隔离模式

enum AgentIsolationMode {
  IN_PROCESS = 'in_process',       // 共享内存，最轻量
  WORKTREE   = 'worktree',         // Git worktree 隔离代码副本，避免互相干扰
  REMOTE     = 'remote',           // 云端运行（需 COORDINATOR_MODE 开启）
}

7.2 TeammateTool 多代理协调系统

社区研究员通过字符串扫描发现的完整多代理协议（已于2026年2月正式发布）：

13 个操作原语：

团队管理：spawnTeam / discoverTeams / cleanup
加入管理：requestJoin / approveJoin / rejectJoin
通信机制：write（P2P消息）/ broadcast（广播）
计划协商：approvePlan / rejectPlan
关闭流程：requestShutdown / approveShutdown / rejectShutdown

存储目录结构：

~/.claude/
├── teams/{team-name}/
│   ├── config.json
│   └── messages/{session-id}/    # 消息邮箱，文件系统实现
└── tasks/{team-name}/

启用方式：

CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 claude

7.3 五种多代理架构模式

7.4 Fork Subagent 上下文隔离原则

父代理执行主流程
    ↓ 遇到需要隔离的子任务
Fork 子代理（继承父代理的缓存）
    ↓
子代理在隔离上下文中执行（探索性、可能犯错的工作）
    ↓
仅返回提炼后的结论（不将中间过程污染主上下文）
    ↓
父代理接收干净结论，继续主流程

八、权限与安全体系

8.1 双轨权限系统

Track 1：规则匹配（快速路径）

文件操作  → glob/regex 路径匹配
Shell 命令 → 白名单 + 黑名单模式匹配
结果     → 始终允许 / 始终拒绝 / 需要询问

Track 2：ML 分类器（慢速路径，用于模糊情况）

危险程度不明的操作
    ↓
调用 Claude API 进行风险评估
    ↓
AI 自主判断是否安全（"Auto Mode Classifier"）

符号链接防护：防止通过../链接突破沙盒边界

8.2 权限检查层次

1. 底层沙箱（最底层硬约束）
2. 危险命令硬编码拦截（如 rm -rf /，格式化磁盘等）
3. 工具级权限门控（每个工具独立）
4. 用户配置白名单/黑名单
5. 运行时交互确认（最上层软约束）

8.3 泄露发现的安全漏洞

源码分析中发现的三处安全问题（供参考和修复）：

1. PLAN 文件权限绕过：白名单匹配使用startsWith前缀匹配，匹配范围过宽（如blue-fox-backup.md可被误判为合法的 plan 文件）

2. 符号链接处理缺陷：多级符号链接链处理不完整，可能导致沙盒边界被突破

3. WebSocket 重连不一致：Node.js 与 Bun 运行时下的重连行为差异，可能引发消息丢失

九、隐藏功能与彩蛋

未发布功能（通过特性开关隐藏）

未公开模型代号

彩蛋功能

• Buddy System（电子宠物）：使用确定性随机算法生成个性化 ASCII 宠物伴侣，原计划作为愚人节彩蛋
• Undercover Mode（卧底模式）：向开源仓库提交代码时隐藏 Anthropic 身份，引发伦理争议
• 内部员工模式：通过process.env.USER_TYPE === 'ant'区分内部员工，可解锁额外工具（ConfigTool、TungstenTool）

十、对开发者的启示与建议

10.1 提示词工程核心原则

基于 Anthropic 生产实践总结的7 条黄金法则：

1. 静动分离：固定规则与动态状态严格分离，分别管理缓存效率
2. 渐进披露：按需加载，不相关的上下文不注入（减少噪音和 token 浪费）
3. 角色专一：每个子代理只做一件事，职责越单一越稳定
4. 验收清单化：复杂任务提示词必须包含明确的验收标准，不依赖模型自判
5. 工具描述即约束：工具的 description 是”第二个提示词”，安全约束直接写入
6. 前置读取原则：修改任何资源之前强制先读取，防止盲目操作
7. 反过度工程：提示词应鼓励最简解法，明确写入”避免不必要的抽象”

10.2 Skills 设计最佳实践

✅ DO:
- 每个技能聚焦单一可复用的 SOP 流程
- 在 YAML frontmatter 中写清楚触发条件（description）
- 包含阶段性检查点，允许中途暂停确认
- 使用 allowed-tools 明确最小权限
- 脚本化固定格式的重复操作（不让模型"自由发挥"）

❌ DON'T:
- 把所有规范塞进一个巨型 SKILL.md
- 技能之间互相高度耦合
- 在技能中存储数据（技能是流程，不是数据库）
- 假设模型会记住上次执行的技能结果

10.3 MCP 开发实践

MCP 工具描述写作要点：
1. 描述"适合场景"而非只是"功能列表"
2. 指定预期的输入/输出格式
3. 注明性能特征（是否耗时，是否有限流）
4. 包含错误码和错误处理建议

MCP 架构建议：
- 单个 MCP 服务器应聚焦一个领域（单一职责）
- 提供幂等操作（相同输入，相同输出，方便重试）
- 状态变更操作提供显式确认机制
- 为高频读取提供缓存层

10.4 AI Agent 架构设计要点

10.5 工程化运维建议

npm 发布安全清单（避免重蹈 Anthropic 覆辙）：

# 发布前检查
npm pack --dry-run         # 预览将要发布的文件列表
cat .npmignore             # 确认 *.map 已被排除
npx publint                # 包发布质量检查

# .npmignore 必须包含
*.map
*.d.ts.map
dist/**/*.map

CI/CD 保护：

# GitHub Actions 示例
- name: Check for source maps
  run: |
    npm pack --dry-run 2>&1 | grep -E "\.map$" && exit 1 || exit 0

总结

Claude Code 的源码泄露，本质上是一份生产级 AI Agent 工程实践的教科书。

Anthropic 用 512,000 行代码证明了一个重要结论：AI Agent 的竞争壁垒不在于模型本身，而在于以下五个维度的系统工程化能力：

1. Prompt 的工业化管理（缓存、分段、条件注入）
2. 工具系统的精细化设计（权限、并发、按需加载）
3. 上下文的智能管理（记忆索引化、会话持久化、上下文压缩）
4. 多代理的协同架构（隔离、通信、编排模式）
5. 安全与可信执行环境（双轨权限、操作可逆性、沙箱隔离）

对于开发者而言，这次”意外开源”是难得的学习机会——不是用来复制代码，而是用来理解工业级 AI Agent 应该长什么样。