当前位置：首页 > news >正文

Claude Code 系统拆解：一个 Coding Agent 是如何被工程化出来的

news 2026/4/21 23:05:00

本质是Harness

Claude Code 的核心 agent loop 其实很简单，本质上就是一个不断重复的循环——组装上下文、调用模型、请求工具、执行动作、写回结果、继续下一轮。

真正复杂的部分，主要不在这个循环里，而在循环外那一整圈工程系统：权限控制、上下文压缩、扩展机制、子代理编排、会话恢复和持久化。

论文甚至引用社区分析估算，Claude Code 代码库里真正属于 AI 决策逻辑的部分只有约 1.6%，剩下 98.4% 更接近 operational harness，也就是围绕模型搭起来的运行壳层。

这其实很能说明今天 Agent 产品的竞争焦点已经变了。

模型当然重要，但真正决定一个 Agent 能不能在真实环境里稳定干活的，往往是模型外面的那套系统设计。

Claude Code 的价值，不只是“会写代码”，更在于它把模型塞进了一个可控、可恢复、可扩展、可持续运行的工程环境里。

7个功能组件与5层架构

论文先把 Claude Code 抽象成七个功能组件：用户、接口层、Agent Loop、权限系统、工具层、状态与持久化、执行环境。

这个抽法的意义在于，它把 Claude Code 从“一个会调用工具的大模型”提升成了“一个带操作约束和状态管理的运行时系统”。

用户请求不是直接扔给模型，而是先进入统一入口，再进入 Agent Loop，由它发起动作请求，经权限系统判定后，才会触达文件、Shell、Web 或 MCP 等执行环境。与此同时，系统还会把状态和历史持续记下来。

在这七个组件之外，论文又进一步把它展开成五层架构：表层入口、核心层、安全/动作层、状态层、后端层。

这里最值得注意的是，权限系统、hooks、扩展能力、内置工具、MCP 工具、子代理、会话存储，并不是零散功能，而是被组织进一套层次化结构里的。换句话说，Claude Code 不是东拼西凑出来的工具集合，而是一个有明确边界和分层意识的 Agent 系统。

权限管理

Claude Code 的权限系统，是整篇论文里最值得安全从业者关注的部分。

它的基本立场很明确：默认不是放行，而是 deny-first，再视情况 ask 或 allow。

论文梳理出七种权限模式，覆盖从最保守的 plan，到 default、acceptEdits、auto、dontAsk、bypassPermissions，以及一个内部使用的 bubble 模式。

这背后体现的不是“开或不开自动执行”的二元选择，而是一条逐步放权的信任光谱。

这套权限系统的核心也不是单点判断，而是三层组合：声明式规则、全局模式、可编程 hooks。

规则可以按工具名和输入内容做匹配；模式决定系统整体的放权级别；hooks 则允许在动作前后做拦截、修改和注解。

论文特别强调，这是一种 defense in depth 的思路，也就是安全不是押注在某一个开关上，而是让多层机制同时起作用。

但更关键的是，论文没有把这套机制写成“理所当然正确”。

它直接点出一个现实问题：用户会疲劳。

相关分析显示，用户大约会批准 93% 的权限提示，这意味着“每次都弹窗确认”看起来安全，长期看却不可靠。

于是 Claude Code 才会继续往前做：用规则、分类器、hooks、沙箱这些层，去减少系统对人工逐次审批的依赖。

论文还提到了一个非常有启发的安全点：权限系统不只要看逻辑，还要看生效时序。

独立安全研究发现，项目初始化阶段的一些动作，比如 hooks、MCP 连接、配置解析，可能发生在交互式 trust dialog 出现之前。

也就是说，在“用户正式建立信任”之前，系统就可能先进入一个带执行能力的窗口期。

这个发现很重要，它说明 Agent 安全不能只画静态流程图，还要盯紧初始化阶段、加载顺序和激活顺序。

插件体系

很多人理解 Agent 扩展时，习惯问一句：“它的插件体系是什么？”

Claude Code 的答案不是只给一种插件接口，论文总结了它的四类扩展机制：MCP、plugins、skills、hooks，而且这四类东西并不是平铺的，它们分别插在 agent loop 的不同位置上。

论文把这个逻辑概括得很清楚：assemble() 决定模型能看到什么，model() 决定模型能碰到什么，execute() 决定动作是否以及如何真正执行。

这个设计很值得借鉴，因为扩展能力本来就不该只有一种。

有人要加工具，有人要加上下文，有人要改动作执行策略，有人要在生命周期节点上插逻辑。

Claude Code 的做法，本质上是在告诉我们：成熟的 Agent 系统不该只设计“一个插件入口”，而应该设计“多种扩展面”，并且每种扩展面对应不同的成本、权限和控制粒度。

上下文管理

Claude Code 在上下文管理上的设计，也非常能体现“工程感”。

它不是靠单一的截断或单次总结来压缩历史，而是做了一个五层压缩流水线：budget reduction、snip、microcompact、context collapse、auto-compact。

它们分别处理不同问题：有的针对单条工具输出太长，有的裁掉更早的历史，有的结合缓存机制做细粒度压缩，有的对长会话做投影视图，有的最后才触发模型生成总结。

这套设计的思想很清晰：上下文窗口不是“能塞多少塞多少”，而是一种稀缺资源调度问题。

先做代价最小、破坏最小的压缩，再逐步升级到更重的压缩方式。

论文把这叫作 lazy degradation，意思就是先做轻度降级，实在顶不住了再做重压缩。

这个思路比很多 Agent 系统里常见的“超了就裁”要成熟得多。

不过它也带来一个代价：用户不容易看清楚，系统到底压掉了什么。

论文明确指出，五层压缩虽然有效，但对用户来说不够透明。某些压缩是可见摘要，某些只是内部投影视图，某些还和缓存行为有关。结果就是，系统更强了，用户却更难形成稳定心智模型。

Claude Code 在记忆管理上的另一点也很有意思：它偏向用用户可见、可编辑、可版本控制的文件来承载记忆，比如多层级的 CLAUDE.md 和自动记忆文件，而不是把很多长期上下文藏进一个黑盒数据库里。

论文认为，这是一种用透明性换灵活性的选择：检索可能没那么“花哨”，但更便于审计、修改和协作。

子代理系统

Claude Code 通过 AgentTool 把任务分给内建或自定义子代理，每个子代理运行在隔离上下文中，拥有重建后的权限上下文、独立工具集、可选隔离工作区，最后返回给主会话的通常只是结果摘要，而不是完整中间过程。

与此同时，每个子代理还会单独写自己的 transcript 和元数据文件。

这个设计很重要，因为它说明 Claude Code 对“多代理协作”的理解，不是把多个 agent 平铺展开，而是做有边界的委派。

主会话负责总控，子代理负责局部探索、局部规划、局部执行；隔离是默认前提，摘要回传是控制上下文成本的关键手段。

这样做的好处是，系统不会因为多代理而立刻把主上下文撑爆。代价则是，每个子代理看到的是局部世界，容易在全局一致性上打折。论文后面就提到，这种架构会让模式重复、规范漂移这类问题更值得警惕。

持久化机制

在持久化上，Claude Code 采取的是一种非常“系统型”的做法：会话主要存成 append-oriented 的 JSONL transcript。

系统会把消息、压缩标记、历史快照、替换记录等事件持续追加到会话文件中；子代理也有自己的 sidechain 文件。这样做的好处非常直接：可恢复、可分叉、可审计、可回放。

更有意思的是，它在恢复会话时做了一个偏保守的安全选择：恢复消息，不恢复会话级权限。也就是说，resume 和 fork 可以把历史对话接回来，但之前临时授予的权限不会自动沿用，需要在新的会话上下文里重新确认。

论文把这理解为一种“信任不应隐式继承”的设计立场。这个选择会增加一点使用摩擦，但能避免把旧信任带进新上下文里。

Cluade Code vs OpenClaw

论文把 Claude Code 和 OpenClaw 放在一起比较，非常有意思。

因为两者都在回答 Agent 的共性问题：安全怎么做、扩展怎么做、上下文怎么管、系统中心放哪儿。

但它们给出的答案并不一样。

Claude Code 把 agent loop 放在系统中心，更强调对单次动作的权限评估、更强调单个会话内的工具表面和上下文压缩；

OpenClaw 则把 gateway control plane 放在中心，更强调外围接入控制、共享能力面和多通道多代理路由。

这个对照最有价值的地方，在于它告诉我们：Agent 架构没有唯一正确答案，答案取决于部署语境。

如果你的产品是一个单用户、本地或近本地的 coding agent，你大概率会像 Claude Code 一样，把重心放在 loop、权限、上下文和工具执行上；
如果你的产品是一个跨渠道、多身份、多会话的代理网关，你更可能像 OpenClaw 一样，把重心放在网关边界、身份路由和全局能力管理上。

几点启发

读完这篇论文，我觉得它至少给了我们四个很实在的启发。

第一，Agent 的核心竞争力，越来越不只是模型能力，而是围绕模型搭出来的 harness。 Claude Code 最重要的设计，不是某个神奇提示词，而是权限、工具、上下文、持久化、恢复、扩展这些配套机制。
第二，权限不该只做“开/关”，而要做“渐进信任”。从 plan 到 bypassPermissions，这背后不是更多按钮，而是更细的信任经营机制。
第三，上下文管理要按资源调度来设计。超长上下文不是万能药，真正决定可用性的，是压缩顺序、透明性、恢复能力和长期一致性。
第四，多代理协作的关键不是多，而是隔离、委派和摘要回传。子代理如果没有边界，只会把复杂度和上下文成本一起放大。