快速答案
可引用摘要基于 v2.1.88 源码深度分析，全面解析 Claude Code 的架构设计。涵盖 Prompt 缓存、多 Agent 协调、安全权限、性能优化等核心创新点。
Claude Code 工程架构技术白皮书
2026/4/1...大约 10 分钟AI 技术架构设计Claude CodeAI Agent架构设计源码分析
Claude Code 工程架构技术白皮书
基于 v2.1.88 源码深度分析
文档版本: 1.0
日期: 2026-04-01
目录
执行摘要
Claude Code 是 Anthropic 推出的生产级 AI 编程助手，其架构设计代表了 2026 年 AI Agent 系统的工程标杆。本文档基于泄漏的 v2.1.88 版本源码（约 51 万行 TypeScript，1,884 个文件），深度剖析其工程实践中的核心创新点。
关键洞察：
- 优秀的 AI 应用层开发本质上是对 API 缓存系统的精细化压榨
- 从"单体思考"向"集群并发协作"的架构演进
- 用小 AI 监管大 AI 的动态权限设计
架构概览
2.1 系统规模
| 指标 | 数值 |
|---|---|
| 源文件数 | 1,884 个 |
| 代码行数 | ~510,000 行 |
| 一级模块 | ~40 个 |
| 内置工具 | 40+ 种 |
| 核心模块体积 | 33 MB |
2.2 双模式架构
┌─────────────────────────────────────────────────────────┐
│ Claude Code │
├─────────────────────────┬───────────────────────────────┤
│ REPL 交互模式 │ 无头/SDK 模式 │
├─────────────────────────┼───────────────────────────────┤
│ • React + Ink 终端 UI │ • QueryEngine 类 │
│ • 面向人类开发者 │ • JSON 流式输出 │
│ • 实时渲染思考过程 │ • 可嵌入 IDE/Cursor │
│ • 工具进度条/Diff 预览 │ • 支持 CI/CD 流程集成 │
└─────────────────────────┴───────────────────────────────┘2.3 目录结构
src/
├── main.tsx # 入口点 (并发启动优化)
├── commands/ # CLI 命令 (87 个模块)
├── components/ # React 组件 (103 个)
├── services/
│ ├── api/
│ │ └── claude.ts # 核心 API 交互 (3,419 行)
│ ├── mcp/ # Model Context Protocol
│ └── analytics/ # 遥测与 GrowthBook
├── tools/ # 40+ 工具实现
├── screens/
│ └── REPL.tsx # 主界面 (5,005 行)
├── state/ # Zustand-style Store
├── memdir/ # 记忆系统
├── coordinator/ # 协调器模式
├── tasks/ # 多 Agent 任务
├── buddy/ # 电子宠物彩蛋
└── utils/
├── permissions/ # 权限系统
├── swarm/ # Agent 集群
└── undercover.ts # 卧底模式核心技术栈
3.1 技术选型决策
| 层级 | 技术 | 选型理由 |
|---|---|---|
| 语言 | TypeScript | 类型安全，大型项目可维护性 |
| 运行时 | Bun | 极致性能，比 Node.js 快 3-4 倍 |
| CLI 框架 | Commander | 成熟的命令行解析 |
| UI 层 | React + Ink | 声明式终端渲染，应对复杂流式状态 |
| 状态管理 | 自定义 Store | Zustand 风格，轻量级 |
3.2 为什么 CLI 工具要用 React？
在 screens/REPL.tsx (5,005 行) 中给出答案：
大模型流式输出 + 多工具并发执行场景下，终端 UI 状态管理极其复杂：
- 同时渲染思考过程
- 工具调用进度条
- 代码 Diff 预览
- 多 Agent 状态监控
声明式 React + 极简 Store 是应对高频局部刷新的最佳实践。
提示词缓存架构
4.1 背景：Anthropic Prompt Cache 机制
- 采用前缀匹配（Prefix Matching）
- 缓存命中率直接决定 API 成本
- 微小 Prompt 变化导致缓存穿透
4.2 分段缓存架构
System Prompt
├── 静态段 (Static) ← 全局缓存
│ ├── 模型身份介绍
│ ├── 系统级安全规则
│ ├── 代码风格限制
│ └── 工具使用基础指南
│
├── 动态分界线 ← 硬编码标记
│ SYSTEM_PROMPT_DYNAMIC_BOUNDARY
│
└── 动态段 (Dynamic) ← 会话级缓存/不缓存
├── 当前工作目录 (CWD)
├── Git 状态
├── MCP 指令
└── 用户配置4.3 缓存优化策略
| 优化手段 | 实现方式 | 效果 |
|---|---|---|
| 确定性排序 | 工具描述按字母表排序 | 避免顺序变化破坏缓存 |
| 哈希路径映射 | 配置文件使用内容哈希作为路径名 | 避免 UUID 随机性 |
| 状态外置 | Agent 列表移到 Attachments | 减少 10.2% Cache Creation Tokens |
4.4 核心代码逻辑
// services/api/claude.ts
function systemPromptSection() {
// 静态段：全局可缓存
return asSystemPrompt([
"You are Claude Code...",
systemSafetyRules,
codeStyleLimits,
toolUsageGuide,
]);
}
// 动态分界线硬编码
const DYNAMIC_BOUNDARY = "SYSTEM_PROMPT_DYNAMIC_BOUNDARY";
function dynamicPromptSection() {
// 动态段：高频变化
return [
getCurrentWorkingDir(),
getGitStatus(),
getMcpInstructions(),
getUserConfig(),
];
}工具系统设计
5.1 工厂模式架构
所有工具继承基础 Tool 接口：
interface Tool {
name: string;
description: string;
inputSchema: ToolInputJSONSchema;
// 权限检查
checkPermissions(context: ToolPermissionContext): PermissionResult;
// 输入验证
validateInput(input: unknown): ValidationResult;
// 并发安全标记
isConcurrencySafe(): boolean;
// 执行
execute(input: unknown, context: ToolContext): Promise<ToolResult>;
}5.2 ToolSearch 延迟加载
问题：40+ 工具描述全部塞进 Prompt，Token 成本不可接受。
解决方案：
// 非核心工具标记延迟加载
const nonCoreTools = {
defer_loading: true, // 不在初始 Prompt 中暴露
searchable: true, // 可通过 ToolSearch 发现
};
// 模型只知道 ToolSearch 存在
const toolSearchSchema = {
name: "ToolSearch",
description: "搜索并加载额外工具",
parameters: {
query: "要搜索的工具关键词"
}
};流程：
- 模型需要额外能力 → 调用 ToolSearch
- 动态加载目标工具描述
- 后续调用该工具
5.3 StreamingToolExecutor 并发执行
工具调用请求
│
▼
┌─────────────────────┐
│ ToolOrchestration │
│ (toolOrchestration.ts) │
└─────────────────────┘
│
├─── 并发批次 ───┬─── 串行批次 ───┐
│ │ │
▼ ▼ ▼
读文件 A 修改文件 X 读文件 C
读文件 B → 修改文件 X 写文件 D
网络搜索 (同一文件) (有依赖)
(无依赖)并发安全判定：
isConcurrencySafe() === true：可同时执行- 操作同一资源：强制串行
5.4 大结果集管控
const MAX_RESULT_CHARS = 100000; // 100KB 预算
function handleLargeResult(result: string): ToolResult {
if (result.length > MAX_RESULT_CHARS) {
// 截断并持久化到临时文件
const tempFile = persistToTempFile(result);
return {
summary: result.slice(0, 1000) + "...",
fullResultLocation: tempFile,
size: result.length,
};
}
return { content: result };
}多Agent协调机制
6.1 单体 Agent 的致命缺陷
执行复杂任务（跨文件排查 Bug）时：
- 模型反复读取错误文件
- 尝试错误命令
- 垃圾上下文迅速污染主对话
- 导致"精神分裂"或遗忘初始目标
6.2 Coordinator 协调器模式
架构重构：
┌─────────────────────────────────────────┐
│ Coordinator (协调者) │
│ ┌─────────────────────────────────┐ │
│ │ 可用工具： │ │
│ │ • Agent (派生子代理) │ │
│ │ • SendMessage │ │
│ │ • TaskStop │ │
│ │ │ │
│ │ 职责：工作流规划 │ │
│ │ Research → Synthesis → │ │
│ │ Implementation → Verification │ │
│ └─────────────────────────────────┘ │
└─────────────────────────────────────────┘
│
│ Fork 子 Agent
▼
┌─────────────────────────────────────────┐
│ Worker (执行者) │
│ • 携带具体工具描述 │
│ • 在隔离上下文中执行 │
│ • 共享父级 Prompt Cache │
│ • 用完即毁，只留结论 │
└─────────────────────────────────────────┘6.3 Fork 继承机制
// 子 Agent 继承父级缓存
const childAgent = forkAgent(parentContext, {
inheritCache: true, // 共享 Prompt Cache，节约成本
isolatedContext: true, // 隔离后续操作
returnFormat: 'synthesis', // 只返回提炼结论
});
// 通过 XML 格式传回结果
const result = await childAgent.run(task);
/*
<task-notification>
<synthesis>
关键发现：问题出在 auth.ts 第 145 行
相关文件：src/auth.ts, src/middleware.ts
建议修复：...
</synthesis>
</task-notification>
*/6.4 Swarm 集群模式 (utils/swarm/)
in_process_teammate 任务类型：
主进程 (Leader)
│
├── 并行唤醒 ──┬─── Teammate A ───┐
│ ├─── Teammate B ───┤
│ └─── Teammate C ───┘
│
▼
Leader 权限桥接 (permissionSync.ts)
│
└── 统一处理所有权限弹窗工程挑战与解法：
| 挑战 | 解法 |
|---|---|
| 权限弹窗冲突 | Leader 权限桥接，统一拦截 |
| UI 渲染混乱 | iTerm2 AppleScript 自动分 pane |
标志着 AI 从"单体思考"正式向"集群并发协作"演进。
记忆系统实现
7.1 复古架构设计
意外的选择：完全基于本地文件系统，非向量数据库。
memdir/
├── MEMORY.md # 高层索引 (≤ 200 行 / 25KB)
├── user_role.md
├── feedback_testing.md
├── project_deadline.md
└── reference_api_keys.md记忆分类（Frontmatter 格式）：
---
name: user_role
description: 用户角色与偏好
type: user
---
用户是资深后端工程师，新接触前端...| 类型 | 用途 |
|---|---|
user | 用户角色、偏好 |
feedback | 用户反馈与纠正 |
project | 项目上下文、决策 |
reference | 外部系统指针 |
7.2 KAIROS 助手模式 (未发布)
长期运行 (Daemon) 模式：
白天运行时
│
└── 日志追加模式
└── logs/2026/04/2026-04-01.md
夜间/闲置时
│
└── DreamTask (做梦 Agent)
├── 读取当天日志
├── 总结蒸馏
└── 提取到结构化长期记忆优势：
- 绕开向量检索的召回率痛点
- 代表端侧 AI 向"永远在线、持续学习"演进
安全与权限架构
8.1 多层防护体系
┌─────────────────────────────────────────┐
│ 第一层：沙箱隔离 │
│ @anthropic-ai/sandbox-runtime │
│ • 文件访问限制 │
│ • 网络访问控制 │
└─────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────┐
│ 第二层：危险操作硬编码拦截 │
│ • git push --force │
│ • rm -rf / │
│ • 敏感 API 调用 │
└─────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────┐
│ 第三层：YOLO Classifier │
│ 侧查询机制，用小模型评估风险 │
└─────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────┐
│ 兜底：优雅降级 │
│ Denial Tracking → 人工确认模式 │
└─────────────────────────────────────────┘8.2 YOLO Classifier 动态权限
问题：静态规则无法应对复杂场景。
解法：侧查询 (Side Query) 机制
// yoloClassifier.ts
async function classifyCommand(
transcript: ConversationTranscript,
command: string
): Promise<'Allow' | 'Deny'> {
// 调用更小、更便宜的 LLM
const result = await smallLLM.complete({
prompt: `
对话上下文：${transcript.summary}
即将执行：${command}
评估风险，回复 Allow 或 Deny
`,
model: 'claude-haiku',
});
return result.trim() as 'Allow' | 'Deny';
}Denial Tracking：
- 追踪自动工具被拒绝的频率
- 超过阈值 → 优雅降级到人工确认
8.3 卧底模式 (utils/undercover.ts)
针对场景：Anthropic 员工在开源/公共仓库工作
激活条件：
CLAUDE_CODE_UNDERCOVER=1强制开启- 或自动检测：非内部仓库 → 自动开启
- 没有 force-OFF 选项
约束：
## UNDERCOVER MODE — CRITICAL
- 禁止暴露模型身份
- 禁止内部代号 (Capybara, Tengu...)
- 禁止版本号 (opus-4-7, sonnet-4-8)
- 禁止 "Claude Code" 字样
- 禁止 Co-Authored-By 行
- 用人类开发者风格写 commit性能优化策略
9.1 启动优化
main.tsx 中的并发策略：
// 1. 标记入口时间
profileCheckpoint('main_tsx_entry');
// 2. 并行启动 MDM 配置读取
startMdmRawRead(); // 子进程
// 3. 并行预取 Keychain
startKeychainPrefetch(); // OAuth + legacy API key
// 4. 主模块加载 (~135ms)
// 上述 I/O 操作与此并行效果：避免 65ms 的同步串行阻塞
9.2 运行时优化
| 策略 | 实现 |
|---|---|
| Prompt Cache | 字节级精打细算，分段缓存 |
| 工具延迟加载 | ToolSearch 机制，降低初始 Token |
| 并发执行 | StreamingToolExecutor 分区调度 |
| 结果截断 | 超大结果持久化到文件 |
| Fork 复用 | 子 Agent 共享父级 Cache |
附录：特殊功能
A.1 Buddy System 电子宠物
// buddy/sprites.ts
const SPECIES = [
'duck', 'goose', 'blob', 'cat', 'dragon',
'octopus', 'owl', 'penguin', 'axolotl', 'capybara',
// ... 18 种
];
const RARITY = {
common: 60%,
uncommon: 25%,
rare: 10%,
epic: 4%,
legendary: 1%,
};
const ATTRIBUTES = [
'DEBUGGING', 'PATIENCE', 'CHAOS', 'WISDOM', 'SNARK'
];
const ACCESSORIES = [
'crown', 'tophat', 'propeller', 'halo', 'wizard', 'beanie'
];
// 1% 概率 shiny生成算法：用户 ID + Mulberry32 伪随机数 → 确定性但"随机"的宠物
A.2 内部构建差异
| 特性 | 内部员工 (USER_TYPE='ant') | 外部用户 |
|---|---|---|
| 代码规范 | "不要擅自添加功能" "没提需求不重构" "三行相似比过早抽象好" "默认不写注释" | "直接切入主题" "尝试最简单方法" "尽量简明扼要" |
| 卧底模式 | 强制开启 | 无 |
| 内部代号 | 可见 | 被过滤 |
| 彩蛋 | 全部 | 部分 |
A.3 绕过合规扫描的幽默
为防止检测内部模型代号（如 Capybara）：
// 使用 String.fromCharCode 动态拼装
const secretCodeName = String.fromCharCode(67, 97, 112, 121, 98, 97, 114, 97);
// 解码: "Capybara"结论
Claude Code 的架构设计揭示了大模型应用层创业的真正壁垒：
- Token 成本的极致抠门 — Prompt Cache 的精细化运营
- 多状态机协同的流式调度 — Coordinator 与 Fork 机制
- 安全干预与用户体验的平衡 — YOLO Classifier 动态权限
- 与宿主 OS 的深度集成 — 终端自动化、权限桥接
行业启示：
单纯依靠拼凑 Prompt、堆砌向量数据库、套简单循环外壳的时代已经结束。真正的竞争力建立在对系统工程的深度理解之上。
文档基于泄漏源码分析，仅供教育与研究目的。