从Claude Code 源码看Agent设计原则

我把 Claude Code 源码拆了一遍，发现 AI Agent 做错的根本原因只有一个

不是模型不够强，而是你从第一步就做错了

现在大多数人做 AI Agent，有一个非常典型的路径：

先写 Prompt
再接工具
再加一个 Agent Loop
最后开始补各种问题

结果是什么？

👉 Prompt 越写越长
👉 Agent 越拆越复杂
👉 系统却越来越不稳定

很多人会以为问题在模型。

但如果你把 Claude Code 的源码完整看一遍，你会发现：

问题不在模型，而在你根本没有在“做一个系统”。

一、Claude Code 在做的，不是 Agent，而是 Runtime

大多数教程会告诉你：

Agent = LLM + Tools + Loop

但 Claude Code 做的完全不是这件事。

它真正做的是一套：

可长期运行
可恢复
可治理
可扩展

的 Agent Runtime

换句话说：

模型不是核心，运行时才是核心。

这直接带来一个关键分歧：

你在做什么	Claude Code 在做什么
写 Prompt	设计运行时
调模型	调度模型
拼工具	管理工具
写逻辑	设计系统

如果这个认知没转过来，你后面所有优化基本都会变成“打补丁”。

二、为什么你的 Agent 越做越复杂？

很多系统演进路径是这样的：

第一阶段：很简单

一个模型
一段 Prompt
一个输出

一切看起来都很顺。

第二阶段：开始出问题

输出要给上游系统用（开始有 SLO）
用户输入变复杂
无法人工 review

你会看到：

同样输入结果不稳定
写了规则但模型不遵守
改 A 场景影响 B 场景

第三阶段：疯狂加结构

拆多 Agent
加更多 Prompt
加更多规则

系统看起来更“工程化”了，但本质问题没有解决：

模型到底在“按谁的判断做事”？

三、Claude Code 给出的答案：把“判断”从 Prompt 里拿出来

Claude Code 做了一件本质不同的事情：

把判断从“对话过程”，变成“系统结构”。

这也是它和普通 Agent 最大的区别。

1. Prompt 是“劝模型”

Prompt 的潜台词是：

“这一次，你最好这么做”

所以：

可以改
可以试
可以反复调整

但它没有稳定性。

2. Skill / Runtime 是“约束模型”

Claude Code 的核心机制是：

Tool（工具协议）
Skill（能力模块）
Permission（权限系统）
Task（任务系统）

这些共同做了一件事：

规定哪些判断是允许的，哪些是禁止的

这意味着：

模型不再“自由发挥”
系统行为开始稳定
错误不再随机

四、真正的分层：L0 / L1 / L2（99%的人都写反了）

这是我认为整套体系里最重要的一点。

L0：世界是什么（事实）

什么是可信信息
什么是系统边界
什么算“输入”

👉 一旦错，系统整体漂移

L1：什么不能做（约束）

不允许编造
信息不足必须停止
不允许越权判断

👉 决定系统是否稳定

L2：通常怎么做（经验）

推荐结构
写作习惯
常见路径

👉 可以变，但不能当规则

最大的问题：大家都在把 L2 写成 L1

比如：

❌ “输出必须包含背景/分析/总结”
❌ “务必保证准确”

这些都是典型错误：

不可判断
不可验证
会逼模型编造

好的 Skill 是什么样？

只做一件事：

规定“不能干什么”

例如：

✔ 不得引入输入中未提供的事实
✔ 信息不足必须中止
✔ 不允许隐性补全

同时：

✔ 允许失败
✔ 允许输出“不知道”

五、为什么 Multi-Agent 往往没用？

很多人会问：

“我已经做了多 Agent，为什么换 Skills 没提升？”

答案其实很简单：

因为你原来的 Multi-Agent，本质还是 Prompt

你只是：

把一个模型 → 拆成多个模型
把一段 Prompt → 拆成多段 Prompt

但你没有改变：

判断是如何被表达的

Multi-Agent 解决的是：怎么思考

多路径
多步骤
多角色

Skills 解决的是：能不能这么想

哪些判断合法
哪些路径禁止
哪些情况必须停止

一句话总结：

ReAct 决定怎么走，Skills 决定哪些路不存在。

六、Claude Code 最值得学的 5 个设计

我帮你压缩成最关键的 5 个点：

1. QueryEngine（会话级内核）

不是一次调用，而是一个长期运行的 session。

2. Tool 是协议，不是函数

有 schema
有权限
有并发规则

3. 权限系统在主循环里

每一次 tool call 都要重新判断：

allow / deny / ask

4. Task 是一等公民

后台运行
可恢复
可追踪

5. AgentTool 实现多代理

子 Agent 不是递归调用，而是：

👉 一个“正式工具”

七、真正的开发顺序（90%的人都反了）

大多数人：

写 Prompt
调模型
再补系统

Claude Code：

启动链
消息协议
QueryEngine
工具系统
权限系统
Task 系统
多 Agent
UI / 持久化

最后才是：

👉 模型如何调用

八、结论：Agent 的核心不是“更聪明”，而是“更可控”

Claude Code 给出的答案其实非常克制：

它并没有追求：

更复杂的推理
更花哨的 Agent 结构

它做的，是另一件更难但更重要的事：

让模型的行为变得可预测、可约束、可复用

最后一句话

如果你现在的 Agent 有这些问题：

同样输入结果不稳定
需要不断调 Prompt
越优化越复杂
只能人工兜底

那问题几乎可以确定不是模型。

而是：

你还在“写 Prompt”，但 Claude Code 已经在“做操作系统”。

如果你正在做：

Coding Agent
AI Workflow / Agent 平台
Solo AI 工具链

下一步可以思考一件事：

👉 你现在的系统里，“判断”是写在 Prompt 里，还是已经变成系统结构？

这会直接决定你这个项目的上限。