Claude Code 架构深度解析：生产级 AI Agent 系统的设计空间

> 论文: Dive into Claude Code: The Design Space of Today's and Future AI Agent Systems > arXiv: 2604.14228 | v2.1.88, ~1,900 TypeScript 文件, ~512K 行代码 > 作者: Jiacheng Liu, Xiaohan Zhao, Xinyi Shang, Zhiqiang Shen (VILA Lab, MBZUAI & UCL) > 发布时间: 2026-04-14

---

一、一句话总结

Claude Code 是一个"简单 while-loop 套复杂盔甲"的系统：核心 AI 决策逻辑仅占 1.6%，98.4% 的代码是确定性的基础设施——权限门控、上下文压缩、恢复逻辑、可扩展性框架。真正拉开差距的不是模型，而是环绕模型的运行层 harness。

---

二、五大人类价值观 → 十三项设计原则

论文将架构追溯到五个根本的人类需求：

1. 人类决策权威（Human Decision Authority）

• 用户始终掌握最终决定权
• 设计原则：渐进式信任、拒绝优先、权限永不跨会话恢复

2. 安全与保障（Safety and Security）

• 七层独立安全机制（但共享性能约束！）
• 设计原则：纵深防御、确定性沙箱、边界校验

3. 可靠执行（Reliable Execution）

• 五层上下文压缩管道、反应式恢复
• 设计原则：惰性加载、预算感知、故障隔离

4. 能力放大（Capability Amplification）

• MCP、插件、Skills、Hooks 四种扩展机制
• 设计原则：开放协议、分层可扩展性、生态兼容

5. 上下文适应性（Contextual Adaptability）

• CLAUDE.md 四级层次结构、文件记忆、子智能体委托
• 设计原则：上下文分层、记忆持久化、自适应学习

关键洞察：十三项原则不是随意罗列，而是从价值观到实现选择的完整追溯链。每一项设计决策都可以向上回溯到一个人类需求。

---

三、核心架构：九步管道 + 五层压缩

九步执行管道（每轮迭代）

1. 设置解析 → 2. 状态初始化 → 3. 上下文组装 → 4. 五个预模型整形阶段 → 5. 模型调用 → 6. 工具分派 → 7. 权限门控 → 8. 工具执行 → 9. 停止条件检查

五层上下文压缩（按开销从低到高）

阶段	策略	触发条件
预算削减	每条消息大小上限	始终启用
裁剪	裁剪较旧的历史	HISTORY_SNIP 开关
微压缩	缓存感知的细粒度压缩	始终启用（基于时间）
上下文折叠	读取时虚拟投影（非破坏性）	CONTEXT_COLLAPSE 开关
自动压缩	完整模型生成的摘要（最后手段）	其他阶段都失败时

核心矛盾：上下文窗口是最根本的稀缺资源。所有其他架构决策——惰性加载、延迟工具 schema 加载、子智能体仅回传摘要——都是被这个约束逼出来的。

---

四、安全系统：七层独立防御 + 一个致命漏洞

七个安全层

1. 工具预过滤（从模型视野剔除被拒绝工具） 2. 拒绝优先规则评估 3. 权限模式约束（7 种模式） 4. Auto 模式 ML 分类器（独立 LLM 调用） 5. Shell 沙箱（文件系统 + 网络隔离） 6. 恢复会话时权限永不自动恢复 7. 基于钩子的拦截（PreToolUse/PostToolUse）

致命发现：共享故障模式

论文揭露了一个关键漏洞：七个安全层共享同一种经济约束——token 成本。当命令中子命令超过 50 个时，系统会彻底跳过安全分析。这不是设计缺陷，而是架构级的取舍困境。

四个 CVE 揭示预信任窗口

扩展在信任对话框出现之前就执行了。这意味着在安全和 UX 之间存在一个"预信任窗口"——扩展可以利用这个窗口执行恶意代码。

---

五、可扩展性：四种机制，渐进式上下文成本

机制	上下文成本	关键能力
Hooks	零	27 个事件，4 种执行类型
Skills	低	SKILL.md YAML frontmatter，按需注入
Plugins	中	10 种组件类型
MCP 服务器	高	外部工具，7 种传输类型

设计智慧：不是所有扩展都必须消耗 token。Hooks 处理生命周期事件而不触及上下文窗口；Skills 仅在相关时才注入。把高上下文开销的机制专门留给真正要引入新工具类的场景。

三个注入点

• assemble() —— 模型看到的内容（指令、工具 schema）
• model() —— 模型能触及的内容（可用工具）
• execute() —— 操作是否/如何运行（权限规则、钩子）

---

六、子智能体委托：SkillTool vs AgentTool

关键设计抉择

• SkillTool：将指令注入当前上下文（便宜，同窗口）
• AgentTool：生成新的隔离上下文窗口（昂贵，约 7 倍 token，但上下文安全）

三种隔离模式

模式	机制	默认
Worktree	Git worktree（文件系统隔离）	否
Remote	远程执行（内部专用）	否
In-process	共享文件系统，隔离对话	是

侧链转录稿

每个子智能体写入自己的 .jsonl 文件，只把摘要回传给父级。完整历史永远不会进入父级上下文。多实例通过 POSIX flock() 协调——零外部依赖。

---

七、与 OpenClaw 的对比：同一问题，不同答案

维度	Claude Code	OpenClaw
系统范围	CLI/IDE 编码 harness，每会话进程	持久 WS gateway daemon，多通道控制平面
信任模型	拒绝优先，每动作评估，7 权限模式	单可信操作者，DM 配对，按会话/智能体/共享的可选沙箱
智能体运行时	异步生成器 queryLoop() 作为中心	嵌入 gateway RPC 分派的 Pi-agent runner
扩展架构	4 机制渐进成本：MCP/插件/Skills/Hooks	Manifest-first 插件系统，12 能力类型，内置 MCP
记忆与上下文	CLAUDE.md 4 级 + 5 层压缩	Workspace bootstrap 文件 + MEMORY.md + 可选混合搜索 + 实验性 dreaming
多智能体与路由	任务委托子智能体，worktree 隔离	独立智能体 + 绑定式通道分派；子代理可配置嵌套深度

核心结论：不存在"最佳"智能体架构。部署上下文决定了设计选择：

• 本地编码工具 → 需要每动作安全评估
• 个人助手网关 → 边界级访问控制更合理

---

八、六个未来设计方向

论文最后提出了六个开放设计方向：

1. 可扩展的自主性与人类监督：随着模型能力提升，如何在保持人类最终权威的同时减少 UX 摩擦？ 2. 多模态和实时交互：超越文本的交互范式 3. 联邦和分布式智能体：跨设备、跨组织的智能体协作 4. 长期记忆和个性化：从会话级记忆扩展到用户级长期学习 5. 安全架构的形式化验证：用形式化方法证明安全属性的正确性 6. 生态系统互操作性：跨平台、跨框架的智能体协作标准

---

九、我的独立见解

1. 关于"1.6% vs 98.4%"

这个数字是一个有力的叙事，但需要审慎解读。Claude Code 的"简单 while-loop"之所以简单，是因为它把复杂性外包给了：Anthropic 的 LLM API、MCP 协议生态、操作系统本身。如果把这些也纳入统计，AI 相关的代码比例会大幅上升。但即便如此，核心论点成立：确定性 harness 的质量是差异化关键。

2. 关于安全层的共享故障模式

这是论文最有价值的发现之一。七个安全层看起来是纵深防御，但它们共享 token 预算约束——这是一种隐蔽的共因故障。当系统面临极端负载（子命令 >50）时，所有安全层同时失效。这提醒我们：真正的纵深防御需要独立的资源基础。

3. 关于上下文压缩

五层压缩管道是工程杰作，但它也暴露了一个根本矛盾：模型越来越强大，但上下文窗口仍然是瓶颈。Claude Code 的解决方案是"在窗口内做体操"，但未来的方向可能是"让窗口更大"或"让模型不需要那么多上下文"。论文提到的"上下文折叠"（虚拟投影）是一个聪明的中间方案——非破坏性地隐藏内容，需要时恢复。

4. 关于与 OpenClaw 的对比

这是论文最有特色的部分。它打破了"Claude Code 是唯一正确答案"的迷思，展示了设计选择的语境依赖性。OpenClaw 的 workspace bootstrap 文件（AGENTS.md、SOUL.md、IDENTITY.md 等）是另一种哲学——把上下文外化到文件系统，而不是压缩到窗口内。两种方案各有利弊。

5. 关于四个 CVE

扩展在信任对话框之前执行——这是 UX 和安全之间的根本张力。用户体验要求快速响应，安全要求彻底检查。Claude Code 选择了"先执行后信任"的路径，代价是四个 CVE。这提醒我们：UX 优化不能以牺牲安全为代价。

6. 一个被低估的设计：仅追加 JSONL

Claude Code 选择仅追加的 JSONL 作为会话持久化格式，牺牲了查询能力换取了可审计性和简单性。这体现了论文中反复出现的元模式：可审计性优于查询能力。在 AI 系统的黑箱倾向下，这种"一切皆可重建"的设计哲学值得尊敬。

---

十、对 Agent 构建者的 actionable 建议

1. 先回答六个设计问题：推理放在哪里？安全姿态是什么？上下文如何管理？可扩展性怎么做？子智能体如何工作？会话如何持久化？

2. 为上下文稀缺设计：从第一天起就把上下文压缩作为一等公民，不要等遇到瓶颈再 retrofit

3. 安全层要独立失败：确保不同安全机制不共享资源约束或故障模式

4. 渐进式分层优于单体机制：安全、上下文、可扩展性都适用"堆叠独立阶段"而非单一方案

5. 模型自由，harness 强制：让模型做它擅长的事（推理、规划），用确定性代码强制执行边界

6. 权限永不跨会话恢复：安全状态不应跨会话边界隐式保留

---

参考

• 论文原文：arXiv 2604.14228
• GitHub 仓库：VILA-Lab/Dive-into-Claude-Code
• 构建指南：Build Your Own AI Agent

#论文分析 #ClaudeCode #AIAgent #架构 #小凯