[论文分享] 深入解析 Claude Code 架构：生产级 Coding Agent 的设计哲学与实现 · AI HOT
meng shao @shao__meng 精选 77
2026-04-26 23:12 ·67天前
精选理由 这篇论文逆向拆解了 Claude Code 的完整架构，最值钱的不是那 13 条设计原则，而是 1.6% vs 98.4% 这个数字——它直接回答了「agent 系统该把工程重心放在哪」，做 coding agent 的人应该把这当设计参考书来读。
AI 摘要 论文通过分析 Claude Code 泄露源码，揭示其生产级 Coding Agent 架构的核心是“最小 AI 决策+最大确定性环境”设计。仅约 1.6% 代码为 AI 逻辑，其余 98.4% 用于构建安全、可靠的操作框架。架构围绕人类决策权、安全等五种价值驱动，采用七层独立防御体系保障工具调用安全，并通过五层渐进压缩策略高效管理上下文窗口。其扩展机制按上下文成本分级，子 Agent 采用隔离设计，整体强调透明性与用户可控性，与依赖状态图或显式规划的主流路径形成鲜明对比。
meng shao @shao__meng · X 2026-04-26 23:12 · 67天前
在 X 看原推 · x.com 精选理由 这篇论文逆向拆解了 Claude Code 的完整架构，最值钱的不是那 13 条设计原则，而是 1.6% vs 98.4% 这个数字——它直接回答了「agent 系统该把工程重心放在哪」，做 coding agent 的人应该把这当设计参考书来读。
AI 摘要 论文通过分析 Claude Code 泄露源码，揭示其生产级 Coding Agent 架构的核心是“最小 AI 决策+最大确定性环境”设计。仅约 1.6% 代码为 AI 逻辑，其余 98.4% 用于构建安全、可靠的操作框架。架构围绕人类决策权、安全等五种价值驱动，采用七层独立防御体系保障工具调用安全，并通过五层渐进压缩策略高效管理上下文窗口。其扩展机制按上下文成本分级，子 Agent 采用隔离设计，整体强调透明性与用户可控性，与依赖状态图或显式规划的主流路径形成鲜明对比。
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 系统） 可观察性-评估鸿沟：78% 的 AI 失败是隐性的，89% 团队有可观察性但只 52% 做离线评估。需要 generator-evaluator 分离的脚手架。 跨会话持久性：CLAUDE.md（静态）和 transcript（单会话）之间的"中间层"是空白 Harness 边界演化：where/when/what/with whom 四个轴向的扩展（特别是物理 VLA 行动会改变 reversibility-weighted risk 的代价不对称） Horizon scaling：从单会话到多周期科学研究的可靠性 治理与监管：EU AI Act（2026 年 8 月全面适用）、GPAI Code of Practice 对日志、透明度、人类监督提出外部约束 长期人类能力作为一等设计目标：测量层与设计层都是空白
值得记住的几个判断 "模型推理在哪里、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...
这和 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 系统） 可观察性-评估鸿沟：78% 的 AI 失败是隐性的，89% 团队有可观察性但只 52% 做离线评估。需要 generator-evaluator 分离的脚手架。 跨会话持久性：CLAUDE.md（静态）和 transcript（单会话）之间的"中间层"是空白 Harness 边界演化：where/when/what/with whom 四个轴向的扩展（特别是物理 VLA 行动会改变 reversibility-weighted risk 的代价不对称） Horizon scaling：从单会话到多周期科学研究的可靠性 治理与监管：EU AI Act（2026 年 8 月全面适用）、GPAI Code of Practice 对日志、透明度、人类监督提出外部约束 长期人类能力作为一等设计目标：测量层与设计层都是空白
值得记住的几个判断 "模型推理在哪里、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...
meng shao@shao__meng · X