[cc] 《Dive into Claude Code: The Design Space of Today's and Future AI Agent Systems》

《Dive into Claude Code: The Design Space of Today’s and Future AI Agent Systems》。它分析的是 Claude Code v2.1.88 的源码快照，大约 1,884 个 TypeScript 文件、约 51.2 万行代码；论文后来还加入了与 OpenClaw、Hermes Agent 的比较。(arXiv)

以你现在已经把 CLAUDE.md、Memory、Skill、Hook、Agent Loop、Subagent 都过了一遍的状态，我觉得现在看这篇论文正合适。以前看容易淹死在名词里，现在你已经可以看“为什么这样设计”了。

 

 

你的时间线大概是这样的

Claude Code 最初在 2025 年 2 月 24 日随 Claude 3.7 Sonnet 以 limited research preview 形式推出，到 2025 年 5 月 22 日 GA。

而你的知识已经跨过了 2025 年绝大多数重要阶段。

时间	Claude Code 的演化	你的状态
2025-02	Agent Loop / Read / Edit / Bash	✅ 已理解
2025-05	GA、IDE、background work	✅
2025-06~10	Settings、Permissions、MCP、Hooks、Subagents、Skills、Plugins、Sandbox	✅ 主体已经理解
2025-12	Production Harness、Background Agent、Rules 等	🟡 有接触
2026-02	Agent Teams、Auto Memory、Worktree Isolation	🟡 你的知识中心大致在这里
2026-05	Agent View + Dynamic Workflows + 大规模 Agent orchestration	🔴 Gap 开始明显
2026-06~07	Background / nested subagents、workflow orchestration 成熟	🔴
2026-07	Opus 5 + 1M context + 更成熟的 Dynamic Workflow	🔴
2026-08	Cross-session agents、self-hosted runner、Remote Control、Routines 等	🔴

这里真正发生了一次很大的范式变化。

 

 

 

先给你整篇论文最重要的一句话

我认为论文真正想告诉你的不是：

Claude Code 有多少个 Hook、多少个 Tool、Memory 文件放在哪里。

而是：

Claude Code 真正复杂的地方并不是 Agent 的“思考循环”，而是围绕模型建立的一整套确定性的 Harness。

论文给出了一个非常醒目的估计：

Claude Code

AI 决策逻辑
≈ 1.6%

Operational Harness
≈ 98.4%

核心 Agent Loop 本身就是很普通的：

while 没结束：

    组装 Context
    ↓
    调模型
    ↓
    模型决定：
    回答？
    还是调用 Tool？
    ↓
    Tool Call
    → 权限检查
    → 执行
    → 得到结果
    ↓
    结果送回模型
    ↓
    下一轮

论文甚至明确说，Claude Code 的核心是一个简单的 while-loop；真正庞大的代码在 permission、context management、tool routing、recovery、persistence 等外围系统里。(arXiv)

这其实就是这篇论文最大的价值。

 

 

1. Claude Code 最核心的架构思想：模型负责判断，Harness 负责控制

这个你现在应该特别容易理解。

论文总结 Claude Code 的边界：

               Claude Model
                    │
              “我想做什么？”
                    │
                    ▼
             Tool Use Request
                    │
                    ▼
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
          Claude Code Harness
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

解析 Tool Call
↓
Permission
↓
Hook
↓
Sandbox
↓
真正 Tool Executor
↓
执行
↓
返回结果

模型不能直接访问文件系统、Shell、网络。它只能提出结构化的 tool_use 请求；Harness 决定是否允许并负责真正执行。(arXiv)

这就是我们之前一直讲的那句话：

模型拥有行动意图，Harness 掌握行动权。

而论文把它提升成了一种设计哲学：

不要试图把所有“聪明”都写进复杂流程图；让模型自由判断，但把它放在一个确定性的、安全的运行环境中。

论文把这种原则叫：

Minimal scaffolding, maximal operational harness。(arXiv)

这个我认为是整篇论文你最应该带走的东西。

 

 

2. Claude Code 不是一个“大而复杂的 Planner”

这个发现也很重要。

你可能原来想象一个成熟 Agent：

Planner
↓
Task Manager
↓
Reasoner
↓
Critic
↓
Executor
↓
Reviewer
↓
Planner
...

Claude Code 并没有把核心搞成这么复杂。

论文发现它更倾向：

强模型
+
简单 Loop
+
很强的外围 Harness

而不是：

模型
+
非常复杂的人工决策 Graph

 

## 统计收敛的哲学 ##

论文甚至专门把它和 LangGraph 进行对照：

LangGraph 思路

开发者显式规定：

A → B → C
     ↓
     D


Claude Code 思路

模型决定下一步是什么

Harness：
“可以，你可以自由判断，
但我控制 Context、Tool、Permission、
Sandbox、State、Recovery。”

(arXiv)

 

这并不是说 LangGraph 不好。

而是两种 Harness 哲学：

Claude Code
更多决策权 → Model

LangGraph
更多控制流 → Developer

 

对于你以后做银行 Harness，这个区别特别重要。

银行很可能应该采用混合方式：

确定业务流程
→ Graph 控制

需要调查 / 推理的部分
→ Agent 自主 Loop

 

 

3. Context 是 Claude Code 真正重点优化的“稀缺资源”

这篇论文特别强调了一件事：

Claude Code 把 Context Window 当作系统主要瓶颈之一。

所以你最近学到很多看起来互不相关的东西，其实都是为了同一个目标：

CLAUDE.md lazy load
Skills progressive disclosure
Tool Search
Compaction
Auto Memory
Subagent 独立 Context
Subagent 只返回 Summary
Tool Result 限长
Prompt Cache

它们全都在解决：

Context 太宝贵了
↓
不要什么都塞进去

 

论文描述了一个多层 Context 管理体系，并指出 Claude Code 有五层渐进式 compaction；同时还会延迟加载目录规则、Tool schema，让 Subagent 只把 summary 返回主 Agent，并限制单个 Tool Result 的大小。(arXiv)

所以你可以突然把以前学的东西串起来：

Memory
      ┐
CLAUDE.md
      │
Skills
      ├──→ Context Engineering
Tool Search
      │
Compaction
      │
Subagent
      ┘

它们不是六七个孤立 Feature。

都是围绕 Context Architecture 的。

 

 

4. Hook、Skill、Plugin、MCP 为什么要分成四套？

论文这里的分析我觉得也非常漂亮。

Claude Code 没有搞：

Everything = Tool

而是不同东西承担不同成本和职责：

Hooks
↓
几乎零 Context 成本
确定性事件处理


Skills
↓
较低 Context 成本
按需加载 SOP / 知识


Plugins
↓
打包和分发
把 Skill / Hook / MCP 等组合起来


MCP
↓
增加真正的新 Tool / 外部能力
Context 成本相对更高

论文认为这是一种 按照 Context Cost 分层的扩展架构。它明确指出

• Hooks 默认几乎不占模型 Context，
• Skills 较低，
• 而 MCP 新增完整 Tool surface 的成本更高；
• Plugin 更像包装与分发层，而不是新的 runtime primitive。(arXiv)

 

这也回答了我们之前那个问题：

为什么 Claude Code 搞那么多机制，看起来有点重复？

现在答案更漂亮：

因为它们虽然都叫“扩展 Claude Code”，但扩展的是 Harness 的不同位置。

论文甚至把 Agent Loop 简化成三个关键插入点：

① assemble()
   ↓
模型“看到什么”

② model()
   ↓
模型“可以选择什么”

③ execute()
   ↓
模型的选择“能不能真的执行”

Hook、Skill、MCP 等就是围绕这些不同位置插进去的。(arXiv)

这个抽象非常值得你记下来。

 

 

5. 安全不是一个 Permission，而是一层一层叠起来

Claude Code 没有认为：

Permission System
=
安全问题解决

而是：

Deny rules
      ↓
Permission modes
      ↓
Human approval
      ↓
PreToolUse Hooks
      ↓
Auto-mode classifier
      ↓
Sandbox
      ↓
Tool restrictions

 

其中真正值得你掌握的，我会按重要性排：

• Permission / Deny rules：必须懂
  因为这是最直接的“Agent 能不能做某件事”。
• PreToolUse Hook：值得懂
  因为它代表一种很重要的 Harness 思想：在动作发生前做确定性拦截。
• Sandbox：值得理解概念
  因为它解决的是“即便 Agent 做错了，也只能在受限环境里错”。
• Human approval：不用深挖
  本质就是高风险动作需要人确认。
• Tool restrictions：和 Permission 很接近
  不必独立学一遍。
• Auto-mode classifier：知道即可
  这是更偏 Claude Code 内部产品机制，不是你最值得投入时间的用户层能力。

 

 

其中一个拒绝，都可能阻止操作。论文把它称为 Defense in Depth，并指出默认理念是 deny-first：deny 优先于 ask，ask 优先于 allow；未知的高风险动作不会默认直接放行。(arXiv)

所以以后你写银行 Harness，千万不要想：

“我有一个 Guardrail 了，安全解决。”

真正 production architecture 更像：

模型判断
+
Tool权限
+
业务权限
+
Policy
+
Sandbox
+
Human Approval
+
Audit

任何一层出问题，还有下一层。

 

 

6. Multi-Agent 的重点不是“多”，而是“隔离”

这个又正好接上我们刚才讨论 Codex 和 LangGraph。

Claude Code 的 Subagent：

Main Agent
     ↓
Agent Tool
     ↓
Subagent

但不是：

复制 Main Agent 整个 Context
↓
一起乱干

而是：

Subagent

独立 Context
+
自己的 Tool Set
+
重新建立 Permission Context
+
可以有独立 Worktree
+
自己的 transcript

最后：

Subagent 可能工作了 20,000 tokens

↓
只返回一个 Summary

Main Agent

论文明确指出 Subagent 使用隔离 Context，拥有独立 tool/permission 配置；完整 Subagent history 不进入父 Agent，而只返回 summary，以避免多 Agent 导致 Context 爆炸。(arXiv)

所以这里的设计原则实际上是：

Multi-Agent 不只是并行计算，而是 Context Isolation + Authority Isolation。

这个对你以后自己做行业 Harness 非常重要。

 

7. Session 设计：不要不断“修改过去”，而要追加历史

还有一个很漂亮的架构选择：

Claude Code 的 Session 主要采用：

append-only JSONL

大致：“不是保存一张不断被擦改的白板，而是保存一本流水账”

User message
↓
append

Assistant message
↓
append

Tool Call
↓
append

Tool Result
↓
append

Compact boundary
↓
append

而不是不断修改一个巨大 state 文件。

因此：

Resume
Fork
Rewind
Audit

都比较自然。

论文特别强调：

Conversation 的生命周期不应该被 Context Window 的大小限制。

Context 可以 compact：

Live Context
100k
↓
compact
↓
30k

但是磁盘上的完整历史仍然存在。(arXiv)

所以：

Context
≠
Session

这也是一个非常重要的 Harness 概念。

 

 

8. 论文真正厉害的地方，不是“还原 Claude Code”

到这里我反而建议你不要把它当成：

《Claude Code 源码说明书》

这样会低估这篇论文。

作者真正做的是：

Claude Code 实现
        ↓
往上抽象
        ↓
为什么这样设计？
        ↓
它实际上在回答哪些通用 Agent 问题？

他们总结了五个顶层价值：

Human Decision Authority
人的最终决定权

Safety / Security / Privacy
安全

Reliable Execution
可靠执行

Capability Amplification
能力放大

Contextual Adaptability
适应用户和环境

然后从这些价值推导出 13 个设计原则，再落到具体代码。(arXiv)

所以真正的结构其实是：

人想要什么
    ↓
Design Values
    ↓
Design Principles
    ↓
Architecture
    ↓
Code

而不是：

看源码
↓
记 Feature

 

 

对你来说，我认为这篇论文最重要的 5 个结论

如果 53 页你最后只记住这些，我觉得已经值了：

① Agent Loop 本身并不复杂

   真正复杂的是 Loop 周围的 Harness。


② Model 决定“想做什么”

   Harness 决定：
   能不能做、怎么做、看到什么、留下什么。


③ Context 是核心系统资源

   Memory / Skill / Compaction /
   Subagent / Tool Search
   都是在管理 Context。


④ Production Safety 是分层的

   不是一个 Prompt
   也不是一个 Permission。


⑤ 好的 Harness 不一定意味着
   给模型写越来越复杂的流程。

   模型越强，
   越可以把“判断”交给模型；

   Harness重点建设
   Environment / Tool / Context /
   Permission / Verification / State。

其中第⑤点，我认为尤其重要。

论文的 Discussion 几乎明确表达了这个观点：Claude Code 的架构大量投资于确定性 operational infrastructure，而不是 decision scaffolding；模型被当作 stateless completion endpoint，在 Harness 给出的边界内拥有较大的决策自由。(arXiv)

 

 

还有一个特别值得你注意的地方：论文并没有说“Claude Code 就是标准答案”

这一点非常重要。

论文专门拿：

Claude Code
OpenClaw
Hermes Agent

进行比较。

最后发现：

它们面对的是相同的设计问题，但是因为产品定位和部署环境不同，答案完全可以不同。

 

1. 例如 Claude Code 是 repository-bound coding harness；
2. OpenClaw 更像 gateway；
3. Hermes 又是 single-process multi-surface agent。

 

论文最后强调，这些系统并不是简单的谁替代谁，而可以处在不同架构层，甚至组合。(arXiv)

这正好回答你最近一直在追问的：

“我以后写银行 Harness，是不是把 Claude Code 抄一遍？”

不是。

应该是：

Claude Code
↓
发现通用 Design Questions

我自己的银行业务
↓
重新回答这些 Questions

例如：

Claude Code：

危险 Bash 怎么审批？


银行 Harness：

高风险交易怎么审批？

又比如：

Claude Code：

Context 怎么压缩？


银行 Harness：

客户历史、Policy、交易证据
怎么选择性进入 Context？

这才是这篇论文真正可以迁移到你身上的价值。

 

 

我建议我们接下来这样学习这篇论文

不用53页从第一页一行一行啃。

我们可以只做 4次左右：

第 1 次  ← 今天
全景图 + 论文核心思想
        ✅


第 2 次
Agent Loop + Permission
真正看看源码层是怎么流动的


第 3 次
Context + Memory + Skill + Hook + MCP
把你最近学的东西统一起来


第 4 次
Subagent + Persistence
+ 
论文最后的 Future Agent Architecture

↓
然后结束 Claude Code 这一阶段

我觉得这样非常合适。你现在已经不是在“学 Claude Code 怎么用”了，最后这几次真正应该做的是：

借 Claude Code 这个已经被打开的产品级样本，把我们学到的东西提升成一套你以后自己设计 Business Harness 时可以复用的架构思想。

这才是这篇论文对你最大的价值。(arXiv)