Claude Code 源码中的
8 套 Agent 设计模式

01 / SOURCE

这份源码从哪来，我读了多少

Claude Code 发布在 npm 上，包名 @anthropic-ai/claude-code。包里有一个 cli.js.map——57MB 的 source map 文件，有人写脚本从 sourcesContent 字段里把原始 TypeScript 源码全部提取了出来，版本 2.1.88。我 clone 了这个仓库，两天里读完的是核心目录：src/coordinator/ 是多 Agent 编排核心，src/tools/AgentTool/ 负责 Agent 的创建与管理，其 built-in/ 子目录放着 6 个内置专家 Agent，src/services/autoDream/ 做后台记忆整合，src/utils/swarm/ 做蜂群协作。

我读出来的不是架构模块清单，而是设计模式——可以脱离 Claude Code 本身、搬进任何多 Agent 系统的工程判断。按解决的问题，8 套模式分成四组。编排组解决“谁来指挥、怎么分活”：Coordinator Orchestrator、Task Concurrency、Worker Prompt Craft。诚实组解决“怎么防止 AI 偷懒”：Adversarial Verification、Self-Rationalization Guard。记忆组解决“记忆存在哪、对谁可见”：Memory Type System、Smart Memory Guard。成本组只有一个 Lightweight Explorer，回答调用量最大的操作如何控制开销。

下面按组讲，诚实组着墨最多——那是整份源码里最让我震动的部分。

02 / ORCHESTRATION

编排：Coordinator 不碰代码，也不外包理解

Coordinator 模式的精髓可以写成一句话：Coordinator 自己不碰代码。源码里它的核心工具只有三个——Agent 用来派任务，SendMessage 用来给 worker 续指令，TaskStop 用来叫停；Bash、Read、Edit 这些直接操作代码的工具，一个都没有。工作流是一条四阶段 pipeline：Research、Synthesis、Implementation、Verification。

其中 Synthesis 阶段有一条铁律，写在 coordinatorMode.ts 第 253 行：“Workers can’t see your conversation. You must understand findings before directing follow-up work.” Worker 看不到 coordinator 与用户的对话，所以 coordinator 必须自己消化研究结果，再写出包含具体文件路径和行号的实现 spec。不是把研究结果转发给下一个 worker，而是自己先看懂，再产出一份精确的施工图。源码把这条纪律称为“Never delegate understanding”。

并发控制的规则同样简洁，按操作类型分级：只读的 Research 任务随便并行，写入类 Implementation 在同一组文件上串行，Verification 可以与 Implementation 并行但前提是操作不同文件。Continue 沿用旧 worker 还是 Spawn 新 worker，决策矩阵收敛为一条原则：context overlap 高就复用，低就新开。研究过的文件恰好就是要改的，继续用同一个 worker；研究范围广而实现范围窄，开新的，避免探索噪音；验证刚写完的代码，必须开新 worker——验证者不能带着实现者的假设去验证。

Worker Prompt Craft 是 coordinator 最核心的技能：给看不到对话历史的 worker 写任务指令。源码里有一组好坏对照。差的写法是“Based on your findings, fix the auth bug”。好的写法是：“Fix the null pointer in src/auth/validate.ts:42. The user field on Session (types.ts:15) is undefined when sessions expire but the token remains cached. Add a null check before user.id — if null, return 401 with ‘Session expired’. Commit and report the hash.”

区别不在措辞，在理解的归属：差的版本把理解丢给了 worker，好的版本证明 coordinator 已经理解——文件路径、行号、根因、修复方案、完成标准，一样不缺。源码另附五条规则：说清任务目的；说清“做完是什么样”；区分研究与实现，研究就写明“Report findings — do not modify files”；Git 操作精确到 commit；续接 worker 时引用它做过的事，而不是引用与用户的对话。

03 / HONESTY

诚实：预判 AI 会怎么偷懒，再逐条封堵

接下来两个模式，是我读整份源码时最意外的地方。Anthropic 的工程师给 Verification Agent 写了约 120 行 system prompt，其中大半不是在描述功能，而是在预判 AI 会怎么偷懒，然后逐条封堵。

Adversarial Verification 的第一句话就定调：“Your job is not to confirm the implementation works — it’s to try to break it.”你的工作不是确认实现正确，是试图把它搞坏。prompt 针对约十种变更类型给出完全不同的验证路径：前端变更要起 dev server、浏览器自动化截图、curl 子资源确认页面不是空壳；后端变更要 curl endpoint、验证 response shape 而不只是 status code；修 bug 要先复现原始 bug、再验证修复、再跑回归测试；重构要求现有测试原封不动通过，并 diff public API surface；移动端要 clean build、装进模拟器、dump accessibility tree，再按坐标点击验证。

每一项验证必须按固定格式输出：

第三条是关键：输出必须 copy-paste，不允许 AI 用自己的话复述——一旦允许意译，就有空间“美化”结果。报告末尾还必须包含至少一次对抗性测试，覆盖并发、边界值、幂等性或孤立操作，否则即使全部 PASS 也会被驳回。源码原话是：“If all your checks are ‘returns 200’ or ‘test suite passes,’ you have confirmed the happy path, not verified correctness.”

Self-Rationalization Guard 是我认为整份源码里最有原创价值的设计。工程师列出 6 句 AI 最常说的偷懒话术，逐条给出封堵：

六条之上还有一条元规则：“If you catch yourself writing an explanation instead of a command, stop. Run the command.”发现自己在写解释而不是跑命令，停下来，去跑命令。

AI 偷懒的方式不是拒绝执行，而是用看起来很负责的解释替代实际执行。

它会说“我仔细审查了代码逻辑，确认没有问题”——听起来很负责，实际上什么都没有跑。值得注意的还有应对方式：不是叠加更多“你必须”“你一定要”，命令式语气对模型并不构成约束；真正有效的是预判它的逃避话术，一条一条堵死。这更像管理经验的移植：好的工头不是教工人怎么砌墙，而是提前知道工人会用哪些借口不砌墙。

04 / MEMORY

记忆：三层作用域，三层防护

记忆组回答两个问题：Agent 的知识存在哪里，以及它能动哪些文件。Claude Code 把记忆分成三层作用域，agent 声明用哪一层，系统自动注入对应的行为提示。

配合 Snapshot 机制，项目可以在 .claude/agent-memory-snapshots/ 提供初始记忆快照，新人 clone 仓库后，agent 自动用快照初始化本地记忆。换句话说，agent 的知识可以像代码一样做版本管理和团队共享。

防护侧同样分三层，各管一件事。canUseTool 沙箱对记忆类 agent 精确到单个工具：Read、Grep、Glob 完全允许；Bash 仅放行 ls、find、grep、cat 等只读命令；Edit 和 Write 仅当目标路径在记忆目录内；其余工具全部拒绝，并返回明确原因。路径检查用 isAgentMemoryPath() 配合 normalize() 阻止 ../ 路径穿越，三层 scope 各有合法路径白名单。负责后台整理的 AutoDream 还有三重触发门控：距上次整理满 24 小时、新会话数达到 5 个、PID 文件锁加 1 小时过期与 write-verify-reread 竞争检测——保证它既不频繁启动，也不并发冲突。

05 / COST

成本：最高频的操作，用最便宜的方式跑

代码搜索是 Claude Code 调用最频繁的操作，源码注释给出的数字是 34M+ 次 Explore agent 调用。这个量级决定了它必须又快又便宜，做法是在四个维度同时压缩：模型降级，外部用户的探索请求走 haiku——最快最便宜的模型；上下文裁剪，省略 CLAUDE.md（注释标注的节省是 5-15 Gtok/week）和 gitStatus（40KB 以上）；工具限制，禁止 agent 嵌套、禁止 Edit 和 Write；行为优化，prompt 直接要求一次发起多个并行工具调用。

主 agent 一侧还有一道分流阈值：“only when a simple, directed search proves insufficient or when your task will clearly require more than 3 queries”。不超过 3 次查询的简单搜索，主 agent 自己用 Grep 和 Glob 就完成了，不启动子 agent。这套逻辑很朴素：高频低复杂度的操作，用最便宜的方式跑。但朴素逻辑要落地，靠的是“3 次”这样写进 prompt 的精确阈值，而不是一句“尽量省着用”。

06 / THE REAL GAP

真正的鸿沟：不是更聪明，是更诚实

8 套模式读完，我确认了一件事：多 Agent 系统最难的部分不是让 AI 干活——那是 prompt engineering 能解决的——而是确保 AI 真的干了它说自己干了的事。

多 Agent 系统真正该回答的问题是：凭什么相信 AI 做了它说自己做了的事？

前面的每条设计都能用这个动机重新解释。Coordinator 为什么不外包理解？因为理解一旦外包，就无法验证 worker 是真懂了还是在糊弄。验证为什么要求 copy-paste 原始输出？因为允许意译，就留下了“美化”结果的空间。偷懒话术为什么要逐条预判？因为 AI 的逃避从不以拒绝的形式出现。

可以用一个比喻收束：8 套模式加在一起，像一套建筑工地的质量管理体系。Coordinator 是项目经理，Worker Prompt Craft 是施工图标准，Adversarial Verification 是独立质检员，Self-Rationalization Guard 是质检员的反舞弊手册，记忆系统是项目档案室，Explorer 是跑腿的实习生。工地上最重要的文件从来不是图纸——图纸每个工地都有；最重要的是质检标准和反舞弊手册，因为偷工减料很少源于不会建，更多源于有人找理由不好好建。

这些模式也不需要读完 4756 个文件才能复用，有几条可以立刻搬走：给自己的 verification agent 加一段偷懒话术封堵，把 AI 最常说的几句话列出来，逐条写清“如果你发现自己在说这句，就去做那件事”；worker prompt 里永远写文件路径和行号，不写“Based on your findings”这类空泛指令；只读类 agent 用最小的模型加裁剪过的上下文，不是所有 agent 都需要满血模型；记忆文件按 scope 分层，跨项目的习得和项目特定的知识分开存放；后台任务加时间、数量、锁三重门控，既防频繁触发，也防并发冲突。

多 Agent 系统从 demo 到 production 的真正鸿沟：不是让 AI 更聪明，是让 AI 更诚实。

07 / LIMITATIONS

这篇分析自身的边界

诚实是这篇文章的主题，也应该适用于这篇文章本身。几个限制如实列出：

即使带着这些边界，这份源码依然是目前 Agent 工程实践最密集的可读样本之一：注释清晰、设计意图明确，每一处优化都标注了理由和量级。看得出来这是一个大规模生产系统的代码，而不是实验项目。