# 【论文分享】 深入解析 Claude Code 架构：生产级 Coding Agent 的设计哲学与实现

- 来源：meng shao (@shao__meng)
- 发布时间：2026-04-26 23:12
- AIHOT 分数：77
- AIHOT 标记：精选
- AIHOT 链接：https://aihot.virxact.com/items/cmofx0bfd00esslo6f8z2nk0r
- 原文链接：https://x.com/shao__meng/status/2048420026517221654

## 精选理由

这篇论文逆向拆解了 Claude Code 的完整架构，最值钱的不是那 13 条设计原则，而是 1.6% vs 98.4% 这个数字——它直接回答了「agent 系统该把工程重心放在哪」，做 coding agent 的人应该把这当设计参考书来读。

## AI 摘要

论文通过分析 Claude Code 泄露源码，揭示其生产级 Coding Agent 架构的核心是“最小 AI 决策+最大确定性环境”设计。仅约 1.6% 代码为 AI 逻辑，其余 98.4% 用于构建安全、可靠的操作框架。架构围绕人类决策权、安全等五种价值驱动，采用七层独立防御体系保障工具调用安全，并通过五层渐进压缩策略高效管理上下文窗口。其扩展机制按上下文成本分级，子 Agent 采用隔离设计，整体强调透明性与用户可控性，与依赖状态图或显式规划的主流路径形成鲜明对比。

## 正文

【论文分享】 深入阅读 Claude Code 泄露源代码，结合 Anthropic 官方文档和社区分析，重建出一个生产级 Coding Agent 的完整架构图谱，并以独立开源系统 OpenClaw 作为对照组！
论文地址：https://arxiv.org/pdf/2604.14228

# 最核心的一个数字：1.6% vs 98.4%

社区估算：Claude Code 整个代码库里，只有约 1.6% 是"AI 决策逻辑"（提示词、模型调用、循环），其余 98.4% 是确定性的运行环境（permission、context、tool routing、recovery）。

这个悬殊比例意味着：
· 模型几乎拥有完全自主决策权（reason 在哪做、调什么工具）
· 但模型从不直接接触文件系统、shell、网络
· 工程复杂度不是为了约束模型，而是为了让模型在一个安全富饶的环境里自由发挥

这和 LangGraph（用状态图约束控制流）、Devin（显式 planner）走的是相反路线：最小脚手架 + 最大化操作型 harness。

# 团队做设计权衡时的五种人类价值驱动整套架构

· 人类决策权：用户最终拥有控制权；通过原则等级（Anthropic→operators→users）形式化
· 安全/隐私：即使用户不专心，系统也要保护代码、数据与基础设施
· 可靠执行：既要单轮正确，也要跨上下文窗口、跨会话、跨子 agent 保持一致
· 能力放大：让用户做以前根本不会尝试的事（Anthropic 内部数据：~27% 任务是"没有这工具就不会做"的）
· 情境适配：系统适应用户项目、习惯、技能，关系随时间演进

第六个是评估视角而非设计价值：长期人类能力保留--这是论文最重要的批判性观察，后面会展开。

# 十三条设计原则与架构骨架

· Deny-first with human escalation（默认拒绝、不识别就升级给人）
· Graduated trust spectrum（信任是渐进光谱）
· Defense in depth（多重独立安全层）
· Externalized programmable policy（策略外部化，可配置）
· Context as scarce resource（上下文是稀缺资源）
· Append-only durable state（追加式持久化）
· Minimal scaffolding， maximal harness（最小脚手架 + 最大 harness）
· Values over rules（重价值判断，轻硬规则）
· Composable multi-mechanism extensibility（可组合的多机制扩展）
· Reversibility-weighted risk（按可逆性加权评估风险）
· Transparent file-based config/memory（透明文件而非黑盒数据库）
· Isolated subagent boundaries（子 agent 隔离）
· Graceful recovery and resilience（优雅恢复）

整体架构可以读作两层视图：
· 七组件视图（高层）：用户 → 接口 → Agent Loop → 权限系统 → 工具 → 状态/持久化 → 执行环境
· 五层视图（细化）：Surface 层（CLI/SDK/IDE）→ Core 层（loop + compaction）→ Safety/Action 层（权限、hooks、tools、sandbox、subagent）→ State 层（context 装配、session、CLAUDE.md）→ Backend 层（shell、MCP、远程执行）

# Agent 主循环：一个朴素的 while-true

queryLoop（） 是一个 async generator，每一轮固定走 9 步：设置解析 → 状态初始化 → 上下文装配 → 五个 pre-model shaper → 模型调用 → tool_use 派发 → 权限网关 → 工具执行 → 停止判定。

不再做的事：没有显式 planner，没有状态图，没有 tree search。这是 ReAct 的最简实现。

工具执行用 StreamingToolExecutor：模型一边流式输出 tool_use，一边并行执行只读工具，写操作串行。结果按收到顺序回填，保证模型看到的工具结果顺序与它发起请求时的顺序一致。

恢复机制有五种（输出 token 升级、reactive compact、prompt-too-long 处理、流式回退、fallback model），全部是"先静默自救、不行才告诉人"。

# 安全的"七层防御"

任何工具调用都要穿过这七层，任何一层都可以否决：
1. Tool 预过滤（被全局拒绝的工具甚至不会出现在模型视野里）
2. Deny-first 规则（deny 永远压制 allow，即使 allow 更具体）
3. Permission Mode 约束（plan/default/acceptEdits/auto/dontAsk/bypassPermissions/bubble 共七模式）
4. Auto-mode ML 分类器（yoloClassifier.ts，独立 LLM 调用判定安全性）
5. Shell sandbox（独立于权限系统的文件系统/网络隔离）
6. Resume 不恢复 session 级权限（强制重新授权）
7. Hook 拦截（PreToolUse 可阻断/重写/异步审批）

最关键的设计哲学：Anthropic 自己的研究发现用户对权限提示的批准率高达 93%--这意味着交互式确认在行为上不可靠。所以架构选择是"不靠人盯着"，而是用 sandbox + 分类器把需要人决策的次数压低 84%。

# 上下文管理：五层渐进式压缩

模型的上下文窗口是整套系统的瓶颈资源。每次模型调用前依次跑 5 个 shaper：
· Budget reduction（始终生效）：单条 tool 结果超尺寸就替换为引用
· Snip：删掉旧历史段
· Microcompact：缓存友好的细粒度压缩，等 API 返回后再用真实 cache_deleted_input_tokens
· Context collapse：read-time projection--存储不动，模型看到的是投影视图（这是论文里很精彩的设计）
· Auto-compact：兜底的全模型生成式摘要

为什么要 5 层而不是 1 层：每层成本不同，先做便宜的轻压缩，不行才升级。这是 lazy-degradation 思想。代价是用户难以预测系统行为，因为有些层（特别是 context collapse）对用户不可见。

CLAUDE.md 的四级层次（managed→user→project→local）是文件型记忆--刻意拒绝向量数据库，理由是"用户必须能读、能改、能 git commit"。代价是检索粒度只能到文件级（用 LLM 扫文件头选最多 5 个），不如向量检索精细。

重要洞察：CLAUDE.md 是以"用户消息"形式注入而非 system prompt，因此对模型的约束是概率性的。真正的强制力来自 deny-first 的权限规则。这是一个刻意的"指引层（概率） vs 执行层（确定）"分离。

# 扩展机制：四个、不是一个

论文回答了一个常见困惑--为什么 Claude Code 既有 MCP，又有 plugins、skills、hooks？

答案是这四者承担的上下文成本不同：
· MCP servers：外部服务集成，上下文开销高
· Plugins：多组件打包分发，上下文开销中
· Skills：领域指令 + 元工具，上下文开销低
· Hooks：生命周期拦截，上下文开销默认零

梯度上下文成本意味着便宜的扩展（hooks）可以大量铺开，昂贵的（MCP）保留给真正需要新工具的场景。代价是开发者要学 4 套 API。

Hook 系统极其细致：源码定义了 27 种事件，其中 5 种参与权限决策，22 种用于生命周期/编排。

# 子 Agent：隔离而非共享

通过 AgentTool（Task 是它的 legacy alias）派遣。子 agent 有三种隔离模式：
· Worktree：临时 git worktree，文件系统隔离
· Remote（仅内部）：远端 Claude Code 运行
· In-process（默认）：共享 FS，隔离上下文

关键约束：子 agent 只把最终摘要文本回传给父级，完整 transcript 走 sidechain 存独立 .jsonl 文件--既保留可审计性，又不污染父上下文。

代价：每次调用基本都得自包含 prompt（除 fork-subagent 外）。Anthropic 自己披露 agent teams 模式 token 开销约为普通 session 的 7×，这才是为什么"摘要回传"如此关键。

多 agent 协调用文件锁而不是 message broker--零依赖、可调试，但牺牲吞吐。

# 持久化：append-only JSONL

Session 存为几乎只追加的 JSONL（极少数清理重写除外）。三条独立持久化通道：
1. Session transcript（项目级，每 session 一文件）
2. 全局 prompt history（仅用户输入，supports Up 与 Ctrl+R）
3. 子 agent sidechain（独立 .jsonl + .meta.json）

--resume 重放 transcript 重建会话，但刻意不恢复 session 级权限--这是把"信任"作为会话隔离的安全不变量：用户每次都重新授权，避免旧上下文中的授权决策被带进新的语境。

compact_boundary 标记里嵌入 headUuid/anchorUuid/tailUuid，让 loader 在读取时打补丁拼接消息链--既压缩了上下文，又保留了完整历史的可重建性。

# 与 OpenClaw 的对照：同样的问题，不同的答案
维度：Claude Code vs. OpenClaw
· 系统形态：临时 CLI 进程 vs. 持久化网关 daemon
· 信任模型：每动作 deny-first 评估 + 7 模式 vs. 网关边界鉴权（DM 配对、白名单、可选沙箱）
· Agent runtime：queryLoop（） 是系统中心 vs. Pi-agent 嵌入网关 RPC，per-session 队列
· 扩展架构：4 机制按上下文成本梯度 vs. manifest-first 插件，12 种能力，集中注册表
· 内存：CLAUDE.md 4 级 + 5 层压缩 vs. 工作区引导文件 + dreaming 长期记忆推举
· 多 agent：父-子任务委派 vs. 路由（多 agent 服务不同渠道） + 委派两层分离

最有意思的发现是两者可组合：OpenClaw 可以通过 ACP 把 Claude Code 当作外部 coding harness 托管。这暗示 agent 设计空间不是平面分类，而是层级式的--网关层和任务层可以叠在一起。

核心洞察："Claude Code 把信任边界放在模型与执行环境之间；OpenClaw 把它放在网关周界。"

# 五大价值张力（最有思想深度的章节）

· Authority × Safety：93% 批准率证明人类督查不可靠，安全要靠分类器/sandbox 补
· Safety × Capability：>50 子命令的 bash 会跳过 per-subcommand 检查（解析慢导致 UI 卡顿）--defense-in-depth 的层共享性能瓶颈
· Adaptability × Safety：多个 CVE 利用"信任对话框出现前"的 hook/MCP 初始化窗口攻击
· Capability × Adaptability：主动式提示让任务完成率 +12-18%，但高频时用户偏好骤降
· Capability × Reliability：上下文有界 + 子 agent 隔离 → 局部好决策 ≠ 全局好结果

# 第六视角：长期人类能力保留

论文不把它列为价值，而作为评估透镜，外部经验证据汇总：
· Becker et al. 2025（16 名经验丰富开发者 RCT）：AI 工具使开发者慢 19%，但他们自我感觉快了 20%
· Shen & Tamkin 2026：AI 辅助组理解力测试低 17%
· He et al. 2025（Cursor 在 807 个仓库的因果分析）：代码复杂度 +40.7%，初期速度增益三个月内消散
· Liu et al. 2026：30.4 万 AI 提交审计，约 1/4 引入的问题持续到最新版本，安全问题留存率更高
· Kosmyna et al. 2025（54 人 EEG 研究）：LLM 用户神经连接性减弱，且移除 AI 后仍持续
· Rak 2025：2023→2024 入门级技术岗招聘下降 25%

论文的判断是：Claude Code 显著放大短期能力，但提供的支持长期人类成长、深度理解、代码库连贯性的机制非常有限。 论文结尾把"未来系统应当把可持续性差距作为一等公民设计问题"作为最重要的开放挑战。

# 六个开放方向（未来 agent 系统）

1. 可观察性-评估鸿沟：78% 的 AI 失败是隐性的，89% 团队有可观察性但只 52% 做离线评估。需要 generator-evaluator 分离的脚手架。
2. 跨会话持久性：CLAUDE.md（静态）和 transcript（单会话）之间的"中间层"是空白
3. Harness 边界演化：where/when/what/with whom 四个轴向的扩展（特别是物理 VLA 行动会改变 reversibility-weighted risk 的代价不对称）
4. Horizon scaling：从单会话到多周期科学研究的可靠性
5. 治理与监管：EU AI Act（2026 年 8 月全面适用）、GPAI Code of Practice 对日志、透明度、人类监督提出外部约束
6. 长期人类能力作为一等设计目标：测量层与设计层都是空白

# 值得记住的几个判断

"模型推理在哪里、harness 执行在哪里--是整个 agent 系统设计的根问题。"

"95% 单步准确率下，100 步任务成功率只有 0.6%。"--这是为什么每一步都要验证。

"前沿模型在编码任务上的能力正在收敛，operational harness 的质量正在成为主要差异化因素。"

"agent 的设计选择不是平面的分类，而是层级化的--任务级 harness 可以被网关级控制平面托管。"

"工程复杂度不是为了限制模型决策，而是为了让模型能更好地决策。"

# 对工程实践的启示

对正在构建 agent 系统的我们：
· 投入确定性基础设施（context 管理、安全分层、恢复机制）比给越来越强的模型套 planning 脚手架更有回报
· deny-first + 多层独立检查比单一沙箱在生产环境更鲁棒，但要警惕共享性能瓶颈导致的同时降级
· 上下文压缩做成多层渐进式比一次性截断或单步摘要更可靠，但用户需要可观察性
· append-only 持久化 + 不跨会话恢复权限是把审计性和安全不变量同时拿到的便宜做法
· 扩展机制按上下文成本分层：让"贵的"扩展（MCP）只用在真正需要新工具的场景，"便宜的"（hooks）可以铺开
· 子 agent 用摘要回传，不要共享 transcript--否则 token 开销线性爆炸（Claude Code 数据：7×）
· 把用户长期能力保留写进设计目标，而不是只在事后用 metric 衡量

### 引用推文

> BURKOV：A must read for anyone interested in building practical AI systems in 2026: Dive into Claude Code: The Design Space of Today's and Future AI Agent Systems The p...