深入 Claude Code：当今与未来 AI 代理系统的设计空间

源码级拆解 Claude Code 架构，对比 OpenClaw 揭示代理系统设计空间。

前置知识

代理循环（Agentic Loop）

一种让 LLM 在多轮中循环调用工具、检查结果并自主决策的运行模式，通常表现为 while-true 循环里反复调用模型、执行工具、把结果回灌给模型。Claude Code 的 queryLoop() 就是这一模式的具体实现，与 ReAct 范式一脉相承。

理解代理循环是看懂整个架构的起点——所有复杂子系统都围绕着这个极简核心展开。

Model Context Protocol（MCP）

一种让 LLM 通过标准化协议连接外部工具与数据源的开放规范，支持 stdio、SSE、HTTP、WebSocket 等多种传输。Claude Code 把 MCP 作为主要外部工具集成路径，并已捐赠给 Linux 旗下 Agentic AI 基金会。

MCP 是当前代理系统工具扩展的事实标准，理解它才能读懂 Claude Code 为什么用四种不同成本档位的扩展机制。

拒绝优先（Deny-First）权限模型

与默认放行相反，权限系统先匹配 deny 规则再匹配 allow 规则，且更具体的 allow 不能覆盖更宽泛的 deny；未匹配任何规则时按询问用户处理。这种设计的核心动机是用户对 93% 的权限提示都会机械批准，必须用结构化兜底。

这是 Claude Code 安全架构的基石，也是它与 SWE-Agent（容器隔离）和 Aider（Git 回滚）最显著的差异点。

上下文压缩（Compaction）

当对话超出 LLM 上下文窗口（Claude 老模型 200K，4.6 系列 1M）时，通过摘要、剪裁、虚拟投影等手段回收 token 的过程。Claude Code 用五层渐进式管道（预算削减→剪枝→微压缩→上下文折叠→自动压缩）逐级处理。

上下文窗口是代理系统的真正瓶颈，几乎所有架构决策——子代理隔离、CLAUDE.md 懒加载——都是为了让模型看见对的东西。

Append-Only 日志

一种只追加、不修改、不删除的持久化范式，所有事件以 JSONL 格式按行写入磁盘。Claude Code 的会话 transcript 几乎全部采用此模式，仅在显式清理时重写。代价是查询能力弱，收益是审计、回放、分支都极其简单。

这是 Claude Code 与基于数据库的代理系统在持久化设计上的关键区别，直接决定了 resume、fork、rewind 等功能如何实现。

研究动机

AI 编程工具已经从 Copilot 时代的补全建议演进到 Claude Code 这种自主执行多步任务的代理形态，但 Anthropic 等厂商只发布面向用户的文档，没有公开架构细节，导致外部研究者无法系统理解代理为什么这样设计、运行时到底发生了什么。这种黑盒性带来三重问题：第一，开发者想基于 Claude Code 做扩展或定制时只能靠逆向工程和社区猜测；第二，安全研究者发现的高危漏洞（如 CVE-2025-59536，CVSS 8.7）说明缺乏架构级解释时安全分析会滞后于攻击面演化；第三，学术界评估 Claude Code 这类代理时只能测端到端效果，无法定位是模型问题还是脚手架问题。同时，开源代理生态（OpenHands、SWE-Agent、Aider、OpenClaw）提出了不同的安全姿态，但缺乏统一的术语把它们放到同一张设计空间图上。

本文的目标是本文的核心目标是基于 Claude Code v2.1.88 公开的 TypeScript 源码（约 $1{,}884$ 个文件、约 $512\text{K}$ 行），从源文件级别逆向其完整架构；提炼出 5 项人类价值、13 条设计原则、7 大组件与 5 层子系统的分层视图；通过与开源代理 OpenClaw 在 6 个维度上的对比，验证同一组设计问题在不同部署语境下会产生不同答案的命题；最后基于现有文献提炼出 6 个面向未来代理系统的开放方向。

与已有工作不同的是，与既有工作相比，本文抓住了三个被忽视的点：第一，大多数代理研究聚焦在基准分数（SWE-Bench、HumanEval），本文转向架构设计选择这一更高层的分析对象；第二，传统的代理综述（如 Weng 2023、Wang 2024a）做的是组件层面的分类，本文用单一生产系统作为案例做软件架构案例研究级别的纵深分析；第三，本文不是单一系统分析，而是把 Claude Code 和一个完全不同部署语境（多通道个人助理网关）的系统做镜像对比，揭示问题相同、答案相反的设计空间结构。

核心方法

本文的研究方法可以类比为软件考古——拿到一份公开可得的 TypeScript 包 v2.1.88，从 $512\text{K}$ 行代码里识别出哪些是 AI 决策逻辑、哪些是脚手架设施，再把这些实现映射到一组抽象的设计问题上。技术上分三条主线：源码级架构分析（读 query.ts、permissions.ts、sessionStorage.ts 等核心文件，识别 7 大组件和 5 层子系统）、设计空间编码（把代码里的选择点转化为在哪推理、用什么循环、默认安全姿态是什么、绑定资源是什么等可比较的问题）、跨系统对照（用 OpenClaw 这个独立代理做镜像比对，验证设计问题的普适性）。证据分三个等级：Tier A 来自 Anthropic 官方文档、Tier B 来自具体源文件引用、Tier C 来自社区分析或代码模式推断，全文标注得当。

本文最核心的洞察可以浓缩成一句话：Claude Code 的代理循环是一个极简的 while-loop，但围绕这个循环约 $98.4\%$ 的代码是确定性基础设施，只有约 $1.6\%$ 是 AI 决策逻辑。这种轻推理、重脚手架的哲学决定了它在 6 个设计维度上都做了用基础设施而非脚手架约束模型的同一选择——不做显式规划图（区别于 LangGraph、Devin），不恢复会话级权限（区别于典型的恢复所有状态做法），不用单一统一扩展机制（区别于大多数代理框架），而是把权限、上下文、扩展、委派都拆成渐进式分层结构。这与传统代理工程加更多规划脚手架的趋势恰好相反，论文把这种取向解读为前沿模型能力趋同时脚手架质量才是真正的差异化。

方法步骤详情

方法的具体执行分四步：第一步，价值-原则提取——从 Anthropic 官方文档和 132 位工程师调查（约 $27\%$ 任务原本不会被尝试）中归纳出 5 项人类价值（人类决策权威、安全/安保/隐私、可靠执行、能力放大、情境适应性），再把这 5 项映射到 13 条设计原则（拒绝优先、渐进信任谱、纵深防御等），形成 Table 1 的对应表。第二步，源码分解——以 query.ts 中的 queryLoop() 为入口，识别出 7 大组件和 5 层子系统，并把每一处实现选择（如 filterToolsByDenyRules、assembleToolPool、compactConversation）锚定到具体源文件。第三步，跨系统对比——把同样的 6 个设计问题抛给 OpenClaw，生成 Table 3 的 6 维对照表，揭示 per-action 安全评估 vs 外围级访问控制等相反选择。第四步，开放方向归纳——结合第 11.6 节的近景讨论和第 12 节的 6 大开放问题（静默失败、跨会话持久化、脚手架边界演化、视野缩放、治理、长期人类能力评估视角），给出未来研究议程。

技术新颖性

与已有的代理研究相比，本文的方法新颖性体现在三处：第一，分析对象是生产级代理的源文件而非学术原型，这意味着分析结论可以直接锚定到具体代码行（如 yoloClassifier.ts、AgentTool.tsx），可证伪、可复现；第二，分析维度是设计问题→设计选择→具体实现的三层映射，而不是常见的组件→功能的两层分类，这让对比 OpenClaw 这种异构系统成为可能；第三，本文首次把长期人类能力保留作为分析视角而非设计目标——既不否定其重要性，也不假装它是 Claude Code 已经追求的价值，从而打开了未来系统如何把可持续性当作一等设计问题这一全新研究方向。论文还指出 4 个具体 CVE 都是利用初始化顺序先于信任对话的时间窗口，揭示了论文本身分析就能催生新的安全发现。

**Figure 1**: High-level system structure of Claude Code

**Figure 2**: Runtime turn flow showing the end-to-end execution of a single agentic turn

**Figure 3**: Expanded layered architecture showing five subsystem layers

**Figure 4**: Permission gate overview and design principles

**Figure 6**: Context construction and memory hierarchy

**Figure 7**: Subagent isolation and delegation architecture

**Figure 8**: Session persistence and context compaction

实验结果

本文以架构发现为主，可归纳为五组核心发现。第一组规模与结构：Claude Code 约 $1{,}884$ 文件、$512\text{K}$ 行 TypeScript；query.ts 为 $68\text{KB}$ 核心代理循环；最多 54 个内置工具（19 个始终启用）；context window 上限对老模型是 $200\text{K}$ tokens，Claude 4.6 系列为 $1\text{M}$ tokens。第二组安全失效：用户对权限提示的批准率高达 $93\%$；auto-approve 率从 $<50$ 会话时的约 $20\%$ 升至 $750$ 会话时的 $>40\%$；超过 50 个子命令的 bash 因 UI 卡顿回退为单一通用提示；4 个 CVE 都利用项目初始化先于信任对话的窗口。第三组上下文：5 层压缩管道顺序执行；2026 年 1 月实验显示关闭缓存复用路径会导致 $98\%$ 缓存未命中、约占 fleet cache_creation 的 $0.76\%$。第四组多代理：agent teams 在 plan 模式下消耗约 $7\times$ 单代理 token。第五组生态副作用：Cursor 引入后代码复杂度上升 $40.7\%$，25% 入门级技术岗位在 2023–2024 年间流失，EEG 显示 LLM 用户神经连接减弱且撤掉 AI 后仍持续。

**Table 1**: Design principles, the values they serve, and the design-space question each answers

**Table 2**: What each extension mechanism uniquely provides

**Table 3**: Architectural comparison: Claude Code vs. OpenClaw across six design dimensions

**Table 4**: Tensions between values, with supporting evidence

**Table 5**: AI coding tool categories by degree of autonomous action

**Table 6**: Design space of context management approaches in LLM-based tools

**Table 7**: Key files by approximate size and runtime responsibility

**Table 8**: Conditional tool availability categories

查看结构化数据

任务	指标	本文	基线	提升
代理系统架构分类（按自主程度）	类别与代表系统	Claude Code 归为 Agentic CLI（命令行 + 工具调用循环），保留交互式审批默认	Copilot（行内补全）、Cursor（IDE 集成聊天）、Devin（完全自主沙箱）	首次基于源码给出 5 维分类的精确系统定位
权限提示疲劳量化	用户批准率	Claude Code 文档披露约 93% 的权限提示被批准	SWE-Agent（容器隔离，无逐次提示）、Aider（Git 回滚，无提示）	以经验数据驱动逐次审批不可靠的架构论断
会话级信任建立速度	auto-approve 率随会话数变化	<50 会话约 20%，750 会话升至 >40%（McCain et al., 2026）	未发表同类纵向数据	首次量化信任共构现象，支撑渐进信任谱设计原则
代理代码引入的技术债务持久性	AI 引入问题的持久率	约 25% 问题持久到最新版本；安全问题持久率显著更高（Liu et al., 2026，304K commits）	无传统基线对照	首次用大规模 commit 审计量化代理代码质量
多代理 token 成本	相对单代理 token 消耗	Agent teams 在 plan 模式下约 7×（Anthropic, 2025b）	无对照	用具体倍数支撑 summary-only 返回的必要性
AI 工具对开发者速度的真实影响	实测速度 vs 主观感知	RCT 显示实测慢 19%，主观感觉快 20%（Becker et al., 2025，16 开发者 246 任务）	传统估算多基于感知	首次用 RCT 拆穿感知-现实差距
代理引入的代码复杂度变化	复杂度相对增量	+40.7%（He et al., 2025，807 代码库因果分析）	传统开发基线复杂度变化	首次大样本因果识别

局限与改进

作者承认的方法学局限有四点。其一是静态快照偏差——分析对应 v2.1.88 一个版本，feature flag（如 TRANSCRIPT_CLASSIFIER）会让不同构建产生功能性差异；动态 require() 是 bun:bundle tree-shaking 约束倒逼的设计，加剧构建时变异性。其二是逆向工程认识论——源码只能揭示结构、控制流、依赖、feature gate，无法确认设计意图或生产构建实际启用的 flag。其三是单系统分析——结论描述 Claude Code 的设计空间，外推需谨慎。其四是 OpenClaw 快照问题——分析反映特定开发状态。我观察到两点独立分析：第一，约 $1.6\%$ 决策逻辑比例这个数字有冲击力，但来源是 community analysis of the extracted source，属于 Tier C 证据，需要谨慎采信；第二，论文引用的第三方实证研究（Becker 2025、He 2025、Kosmyna 2025）的对象是 Cursor、Copilot 而非 Claude Code，论文自己也承认其适用于任何具有有界上下文与工具调用循环的代理系统。

独立分析的弱点

基于独立分析，本文至少存在四个可改进的弱点。第一，证据等级标注虽清晰，但 Tier C 推断（如 $1.6\%$ 决策逻辑比例、agent teams $7\times$ token 消耗）与 Tier B 源码引用混排，读者容易把不同可信度的数据视为同等权威；改进方向是在每个数字旁标注证据等级和置信区间。第二，OpenClaw 对比维度仅 6 维且每维只有两列叙述，没有引入量化指标（如各自工具数、平均响应延迟、上下文压缩率），改进方向是为对比设计一个最小量化框架。第三，论文反复强调模型推理放在 prompt 外部，但未给出 prompt 工程层面的实证数据——例如 CLAUDE.md 内容放在 user message vs system prompt 是否真的影响模型遵循度（7.2 节只说 probabilistic 但没量化）；改进方向是补一组注意力分布或合规率的对照实验。第四，权限系统的独立层假设被论文自身承认有缺陷，但未提出量化层独立性的指标，建议引入形式化验证的 coverage 指标量化各层失效的相关性。

未来方向

作者在第 12 节给出 6 个开放方向。第一是静默失败与可观测性-评估差距——$78\%$ AI 失败是不可见的、$89\%$ 团队有可观测性但只有 $52.4\%$ 做离线评估，开放问题在于评估脚手架应放在 harness 内部还是外部。第二是跨会话持久化——介于 CLAUDE.md 静态指令与会话 transcript 之间是否存在既非静态又非单次的持久化层。第三是脚手架边界演化——Martin et al. (2026) 的 Managed Agents 把 session/harness/sandbox 虚拟化，是否会引发架构碎片化。第四是视野缩放——从单任务到科学程序级别（Lu 2024、Gottweis 2025）需要跨会话协调原语。第五是治理与外部约束——EU AI Act（2026 年 8 月全面适用）要求日志、透明度、人工监督的可审计接口，deny-first 评估虽内部可审计但缺乏外部可审计形式。第六是长期人类能力——是否设计机制保留人类理解力、代码库一致性、开发者培养链路。我的补充方向：把 CLAUDE.md 的 @include 指令与 OpenClaw 的 dreaming 长期记忆晋升结合，构建跨会话累积的技能剧本。

复现评估

复现评估需要分两层看。第一层（架构分析的复现）：极佳——论文给出了 GitHub 仓库 https://github.com/VILA-Lab/Dive-into-Claude-Code，分析对应的源码版本是公开可获取的 npm 包 v2.1.88（约 $1{,}884$ 文件、$512\text{K}$ 行 TypeScript），论文还给出了完整的源文件-功能对照表（Table 7、Figure 9），任何研究者都能独立验证论文的具体引用。第二层（结论的复现）：中等偏难——架构事实容易验证，但实证预测（如代理代码复杂度上升、长期能力下降）依赖第三方数据（Becker 2025、He 2025、Kosmyna 2025），其中 EEG 实验（54 人）和 RCT（16 人）规模较小，需要谨慎采信；论文明确标注 OpenClaw 是用于校准而非 ground truth，所以跨系统对比结论不应被视为强可复现结论。算力上，本文不训练任何模型，复现只需源码阅读工具（VS Code、ripgrep）和文档处理能力，零 GPU 需求。

深入 Claude Code：当今与未来 AI 代理系统的设计空间 Dive into Claude Code: The Design Space of Today's and Future AI Agent Systems