我们能从 Claude Code 学习到哪些优秀的技术架构设计

3 阅读8分钟

凌晨两点,Agent 还在自己改代码、跑命令、调工具。
真正让人紧张的从来不是“它会不会”,而是“它这一轮失控了谁来兜底”。

我想聊的 Claude Code,不是功能秀,而是一套把高自主行为压进工程边界的运行机制。
它的代价也不藏着:架构更重,治理和维护都更贵。
下面就按真实运行链来拆:请求怎么进、动作谁裁决、边界怎么守、失败怎么收口。


一、启动链路:快路径和主路径分离,先把冷启动预算管住

模式名:冷启动预算管控模式(Cold-start Budget Control)

从源码看,Claude Code 的启动不是“一个入口跑到底”,而是两段式思路:
一类是 entrypoints/cli.tsx 这种偏快路径分流,另一类是 src/main.tsx 的完整主流程。

而在 src/main.tsx 里,顶层又明确做了并行预热(如 MDM 读取、Keychain 预取)。这类动作放在最早阶段并行,目的很直接:把后续交互前的空转时间压下去。

这个设计的价值不只是“快”。
Agent 一旦进了日常研发链路,启动时延会直接影响人机协作节奏:慢几秒,用户就会切回手工命令。

微场景
同样是开新会话,A 系统先串行读配置再连外部依赖,B 系统先并行预热关键依赖。
A 的体感是“每次都要等”,B 的体感是“我输入时它已经在路上了”。


二、意图层与执行层分离:用户命令不等于模型工具

模式名:意图-执行解耦模式(Intent-Execution Decoupling)

Claude Code 的另一个关键点,是把“用户交互入口”和“模型可执行能力”拆开:

  • 用户层:commands.ts / commands/
  • 执行层:tools.ts / tools/ 与 Tool.ts
  • 会话主循环:QueryEngine.ts

这个拆法的好处是,产品体验和安全边界可以分开演进。
命令怎么设计,可以继续贴近用户;工具怎么授权、怎么审计,可以独立收紧。

从 commands.ts 能看到大量 feature('...') 条件加载。
这不是普通开关,而是“同一代码基按环境裁剪能力面”的工程策略。

微场景
如果命令层和工具层耦合在一起,改一个交互命令可能意外扩大执行权限。
分层后,新增入口不必然放大爆炸半径。


三、权限架构:不是“多弹窗”,而是风险分级 + 默认路径

模式名:风险滑动标尺裁决模式(Risk-graded Decision Ladder)

很多团队做 Agent 权限,最后变成“允许/不允许”二选一。
Claude Code 在工程博文里的思路更实用:把动作按风险等级分流,而不是把所有动作都塞进同一个审批模型。

在《Claude Code auto mode: a safer way to skip permissions》中,可以看到它讨论了审批疲劳、分层判定与分类器兜底:
常规动作不该全靠人肉点确认,高风险动作才需要更高强度审查。

这背后最关键的取舍是:
安全目标不是“审批次数最大化”,而是“危险动作被拦截、正常研发不中断”。

微场景
用户说“清理分支”,模型如果直接删远端分支,风险很高。
分级权限体系会把这类高破坏动作升级判断,而不是和普通文件编辑同级处理。


四、QueryEngine 的启发:把一次回答做成持续回合

模式名:会话连续推进模式(Session-continuous Loop)

src/QueryEngine.ts 体现了一个很工程化的认知:
Agent 不是一次性回答器,而是跨多轮的会话执行器。

从结构看,它明确管理了跨回合状态:消息、用量、权限拒绝跟踪、文件状态缓存、工具调用循环。
这意味着系统设计目标不是“当下这轮说对”,而是“多轮任务持续推进不失真”。

微场景
让 Agent 连续做三步重构,如果每轮都像新会话,系统会反复读同一批文件、重复试错。
有会话级状态后,第二轮能接着第一轮推进,而不是重开。


五、安全边界升级:从“是否允许”走向“在哪个边界内允许”

模式名:双边界隔离模式(Dual-boundary Isolation)

在《Beyond permission prompts: making Claude Code more secure and autonomous》中,Anthropic 给了一个很关键的实践:
安全不只靠授权动作本身,还要靠执行环境边界。

文中强调了两条边界要同时成立:

  • 文件系统边界(可读写目录)
  • 网络边界(可访问域名/服务)

这点非常实用。
只有文件隔离没有网络隔离,数据仍可能外流;只有网络隔离没有文件隔离,仍可能越界读取敏感内容。

微场景
被注入后的 Agent 想把本地密钥上传外部服务。
双边界都在时,它要么拿不到,要么发不出,风险被限制在局部。


六、Skills 体系:把组织经验做成可按需加载的能力单元

模式名:按需知识注入模式(Progressive Skill Loading)

在《Equipping agents for the real world with Agent Skills》里,一个很有价值的观点是:
模型能力再强,也不自动等于你团队的流程知识。

Skills 的架构意义在于三件事:

  1. 让经验以目录和 SKILL.md 的形式沉淀
  2. 采用 progressive disclosure,按需加载而非全量常驻
  3. 支持“指令 + 资源 + 脚本”组合成可迁移能力

和“超长 system prompt 一把梭”相比,这条路更稳。
前者前期省事,后期会被上下文膨胀反噬;后者前期稍重,但更利于团队协作和长期维护。

微场景
同一个 Agent 既要处理 PDF,又要走公司发布流程。
全堆在系统提示里,回合越多越乱;拆成 Skills,谁相关谁加载,干扰更小。


七、长任务 Harness:最值得抄的是“交接纪律”

模式名:接力棒式状态传递模式(Baton-style Handoff)

在《Effective harnesses for long-running agents》里,Anthropic 讲得很坦白:
长任务失败往往不是模型不会写代码,而是跨上下文交接做不好。

文中给的方案核心不复杂,但非常工程化:

  • 初始化回合先搭任务骨架
  • 后续回合坚持增量推进
  • 每轮留下可交接工件(进度记录、结构化状态、可追溯提交)

这其实就是把人类工程团队里的“交接班纪律”移植到 Agent 系统。

微场景
没有交接工件时,下一轮只能猜上一轮做了什么。
有进度记录和提交线索时,下一轮可以直接接力,不用先做灾后重建。


八、常见反模式对照:为什么很多团队越做越乱

优秀设计常见反模式反模式代价
意图-执行解耦用户命令直接映射工具执行权限边界模糊,误操作爆炸半径不可控
风险滑动标尺裁决所有动作同级审批或同级放行要么审批疲劳,要么高风险漏拦截
双边界隔离只做权限,不做环境隔离被注入后可能越界读取或外流数据
按需技能加载全量知识塞进 system prompt上下文膨胀,噪声增多,判断劣化
接力棒式交接无交接工件直接接班多轮返工,状态失真,项目“假完成”

九、对国内团队最可迁移的四个动作

如果不是做 Claude Code 复制品,而是做自己的工程化 Agent,我建议先做这四件事:

  1. 启动预算治理:快路径分流 + 关键依赖并行预热
  2. 意图/执行解耦:命令层、工具层、会话循环分开演进
  3. 权限分级:危险动作高强度审查,常规动作低摩擦通过
  4. 长任务交接制度化:每轮必须留可交接工件

代价也很直接:系统复杂度和治理成本会上升。
但换来的是线上可控性、故障可追踪性和团队协作稳定性。

决策流程(可直接套用)

  1. 若仍在 MVP 验证期:先上“接力棒式状态传递模式”,降低多轮失忆返工。
  2. 若进入持续交付:补齐“冷启动预算管控 + 意图-执行解耦 + 风险滑动标尺裁决”。
  3. 若进入生产运维:再强制叠加“双边界隔离 + 按需知识注入”,并做全链路回放演练。
  4. 若跨团队协作增加:把反模式对照表纳入架构评审清单,防止局部优化破坏整体秩序。

十、适用边界:什么时候该学,什么时候别硬抄

更适合借鉴这套架构取向的场景:

  • 已经从 demo 走到持续交付
  • 有权限、审计、回放等合规压力
  • 已出现“能干活但容易翻车”的不稳定阶段

不适合重型照搬的场景:

  • 还在验证 MVP,速度优先于治理
  • 团队尚未具备运维和策略维护能力
  • 业务风险低、生命周期短

一句话:
Claude Code 值得学的,不是“能力越多越好”,而是“让能力始终在可控边界内运行”。


结语

看 Claude Code,最容易学到的是工具名单;最难学到的是运行时秩序。
但真正决定系统能不能进生产、能不能长期稳定交付的,恰恰是后者。

如果只留一个结论:
优秀的 Agent 架构,不体现在它被允许做什么,而体现在它被明确禁止做什么、以及禁止后如何收口。
真正的“智能”,不是放开执行权限,而是系统级自律。