LuftBallon

Dive into Claude Code: The Design Space of Today’s and Future AI Agent Systems

Dive into Claude Code

2 Design Philosophies, Design Principles and Architectural Motivations（设计理念、设计原则与架构动机）

章节导言

原文要点

生产级 Agent 的核心张力是：自主执行使它产生价值，但人类仍应控制目标的实现方式。Anthropic 的安全框架提出这组约束 [2]；Claude’s Constitution 则倾向用可结合情境的判断与价值观处理它，而不是写死每一种决策流程 [3]。论文再结合开发者实际使用 Claude Code 的研究 [4]、[5]，归纳出塑造架构的五类人本价值 [1]。

读者理解

这段主要讨论 Claude Agent 如何划定自动执行与人类介入的边界。这条边界不应只由固定规则预先决定；为了知道何时可以放手、何时必须介入，产品设计还应参考真实用户的长期使用轨迹。

原文边界与待验证

“把所有用户的使用轨迹作为输入”是进一步推论，不是论文所说的运行时输入。更准确地说，论文把聚合后的使用研究作为架构设计的证据。McCain 等人的数据表明，完整自动批准率会从不足 50 次会话用户的约 20%，逐步升至 750 次会话用户的 40% 以上；与此同时，有经验的用户也会更频繁地中断 Agent，说明监督方式会随信任积累而变化 [5]。系统最终应使用个人轨迹还是群体数据，以及如何处理隐私和授权，仍需继续验证。

2.1 Five Values and Philosophies（五类价值与理念）

Human Decision Authority（人类决策权）

人类保留最终决策权；Agent 可以在明确边界内自主工作，但人必须能够观察、批准、拒绝、中断和事后审计它的行为 [1]。

Safety, Security, and Privacy（安全、安全防护与隐私）

决策权强调人有权选择，安全则强调即使人疏忽或判断失误，系统仍有义务保护代码、数据与基础设施，并防范越权、注入和隐私泄露 [1]、[2]。

Reliable Execution（可靠执行）

可靠不只是单次回答正确，而是始终忠实于人的真实意图，在长任务、上下文切换和任务委派中保持连贯，并在宣布完成前验证结果 [1]。

Capability Amplification（能力放大）

我的理解是：Claude 的能力放大不依赖显式状态图或决策执行器来规定下一步，而是让模型负责决策，再由上下文管理、工具路由和失败恢复等确定性基础设施支撑执行。它们不是另一套决策逻辑，而是让更强模型的能力可以直接转化为更强工作流，无需同步重写编排框架 [1]、[4]。

Contextual Adaptability（情境适应性）

我的理解是：Claude 的自主性由模型、用户和产品共同建构。系统面向的是随使用经验不断变化的信任轨迹，而不是固定信任状态；用户行为会改变授权和监督方式，但这不等于模型会单方面自动更新一个内部“用户信任值” [1]、[5]。

表 1 节选：人工升级与渐进式信任谱系

表 1 节选：与自动执行边界最相关的两项原则——未知动作先拒绝并升级给人，以及用户随时间进入更高信任级别 [1]。

2.2 Design Principles（设计原则）

图 1：Claude Code 高层系统结构

图 1：Claude Code 的高层系统结构。系统由用户、界面、Agent Loop、权限系统、工具、状态与持久化、执行环境七个功能组件组成；所有入口最终汇入同一个 Agent Loop，截自原论文 [1]。

3 Architecture Overview（架构概览）

3.1 Design Questions and Running Example（设计问题与贯穿示例）

本节用四个问题概括 Claude Code 的架构选择 [1]：

  • 推理放在哪里？ 模型负责决定做什么，Harness 负责把结构化的 tool_use 请求经过权限校验后执行并回收结果，使推理与执行、安全约束相互分离。
  • 需要多少个执行引擎？ 交互式终端、Headless CLI、Agent SDK 和 IDE 集成共用同一个 queryLoop()，只有渲染与用户交互层随入口变化。
  • 默认安全姿态是什么？ 采用“拒绝优先、人工升级”（deny > ask > allow），并让权限规则、PreToolUse Hook，以及启用时的 Auto-mode 分类器和可选 Shell 沙箱组成彼此独立、任一层都可阻断的多层防线。
  • 绑定资源约束是什么？ 上下文窗口是核心瓶颈，因此采用按成本由低到高运行的五层上下文削减与压缩流水线，分别处理不同类型的上下文压力。

3.2 High-Level System Structure（高层系统结构）

Claude Code 的高层结构由七个功能组件构成 [1]：

  1. User（用户）：提交提示、审批权限并检查输出。
  2. Interfaces（界面）：交互式 CLI、Headless CLI（claude -p）、Agent SDK 和 IDE／桌面／浏览器入口最终都汇入同一个 Agent Loop。
  3. Agent Loop（代理循环）：由 queryLoop() 异步生成器反复执行模型调用、工具分发与结果收集。
  4. Permission System（权限系统）：组合拒绝优先的规则评估、Auto-mode 分类器和 Hook 拦截。
  5. Tools（工具）：assembleToolPool() 汇合内置工具与 MCP 工具，插件则通过 MCP 服务和 Skill／Command 注册表间接扩展能力。
  6. State & Persistence（状态与持久化）：以追加式 JSONL 会话记录、全局提示历史和子代理 Sidechain 文件保存状态，并支持恢复、分叉与回退。
  7. Execution Environment（执行环境）：承载可选沙箱中的 Shell 执行、文件系统操作、网页访问、MCP 连接和远程执行。

图 3：Claude Code 扩展分层架构

图 3：Claude Code 的扩展分层架构。七组件模型进一步展开为 Surface、Core、Safety / Action、State 和 Backend 五个子系统层，截自原论文 [1]。

4 Turn Execution: The Agentic Query Loop（单轮执行：Agent 查询循环）

4.1 The Query Pipeline（查询流水线）

每一轮都由 queryLoop() 按固定顺序推进 [1]：

  1. 解析与初始化：解析系统提示、用户上下文、权限回调和模型配置，并用一个 State 对象集中保存消息、工具上下文、压缩状态与恢复计数器。
  2. 组装上下文：从最近一次压缩边界之后取回消息，再依次运行五个模型调用前的上下文整形器。
  3. 流式调用模型：将组装后的消息、完整系统提示、工具集、模型配置和中止信号交给模型，并持续接收输出。
  4. 执行并回灌：若模型返回 tool_use，请求依次经过工具分发和权限校验；执行结果以 tool_result 加回对话，进入下一轮迭代。
  5. 结束本轮：若模型只返回文本、不再请求工具，本轮执行结束。

图 2：Claude Code 单轮运行流程

图 2：Claude Code 单轮运行流程。用户提示经过上下文组装后进入模型，工具请求通过权限门，执行结果回流到下一次迭代；上下文压力升高时触发压缩，截自原论文 [1]。

论文将这个循环归入 ReAct 模式：模型生成推理和工具调用，Harness 执行动作，结果再进入下一轮。queryLoop() 以 AsyncGenerator 向界面持续产出事件，同时在循环内部保持单一顺序控制流；这种设计以较低延迟和实现简单性为优先，代价是每轮沿一条动作轨迹前进，不做树搜索式回溯 [1]。

4.2 Tool Dispatch and Streaming Execution（工具分发与流式执行）

模型响应中出现 tool_use 后，系统提供两条执行路径 [1]：

  • 流式主路径：StreamingToolExecutor 在工具调用仍随模型响应流式到达时就开始执行，以降低一次响应包含多个工具时的等待时间。
  • 批处理后备路径：runTools() 先由 partitionToolCalls() 将调用划分为可并发组，再逐组执行。
  • 安全并发原则：两条路径都会区分可安全并发与必须独占的工具；只读操作可以并行，Shell 等修改状态的操作保持串行。

流式执行器用 Sibling Abort Controller 在任一 Bash 工具报错时终止其他在途子进程，并用进度信号唤醒结果消费者。即使工具并行运行，结果也会先缓冲，再严格按照工具请求的原始顺序输出；两条路径最终都暴露为同一种异步结果流，供同一个 for await 循环消费。若 PostToolUse Hook 发出停止信号，循环也会阻止继续执行 [1]。

参考文献

[1] J. Liu, X. Zhao, X. Shang, and Z. Shen, “Dive into Claude Code: The Design Space of Today’s and Future AI Agent Systems,” arXiv:2604.14228v2 [cs.SE], 2026. [Online]. Available: https://arxiv.org/abs/2604.14228v2

[2] Anthropic, “Our Framework for Developing Safe and Trustworthy Agents,” 2025. [Online]. Available: https://www.anthropic.com/news/our-framework-for-developing-safe-and-trustworthy-agents

[3] Anthropic, “Claude’s Constitution,” 2026. [Online]. Available: https://www.anthropic.com/constitution

[4] S. Huang et al., “How AI Is Transforming Work at Anthropic,” Anthropic Research, 2025. [Online]. Available: https://www.anthropic.com/research/how-ai-is-transforming-work-at-anthropic

[5] M. McCain et al., “Measuring AI Agent Autonomy in Practice,” Anthropic Research, 2026. [Online]. Available: https://www.anthropic.com/research/measuring-agent-autonomy