章节导航 第 15 章 / 共 23 章
从 Claude Code 学到的 Agent 设计范式
Harness >> Model 的核心论点、Context Engineering 方法论、工具设计的 7 条原则——可复用到自己 Agent 产品的模式清单
15.1 Harness 比 Model 更重要
这是 Claude Code 给出的最核心启示。51 万行代码中，与模型交互的 API 调用代码可能不到 1000 行。剩下的 50 万行都是 Harness——工具系统、权限系统、System Prompt 构建、上下文管理、多代理编排、UI 和基础设施。
真正决定 Claude Code 能力上限的不是 Claude 模型有多强，而是 Harness 有多精细。这个判断的详细数据佐证和行动建议见第 18 章教训一。
Harness 的核心价值在于”Agent（谁）与 Skill（怎么做）的分离”。Agent 定义文件承载角色、原则、协议；Skill 承载具体执行方式。这一设计使系统可以灵活替换底层模型而不影响上层业务逻辑——51 万行 Harness 是可迁移的资产，而模型是可替换的组件。
补充证据：规模之外的”构成”
“51 万行”给的是规模，更有说服力的是构成。Dive into Claude Code: The Design Space of Today's and Future AI Agent Systems（arXiv:2604.14228v2，2026-07-02）对 v2.1.88 源码的拆解给出的比例是：约 1.6% 是 AI 决策逻辑，其余 98.4% 是运行基础设施。同一研究把结构归纳为 7 层安全防护、9 步 turn 管线、5 层压缩、54 个工具、27 个 hook 事件、4 种扩展机制、7 种权限模式，并抽象为 5 Values → 13 Principles。论文对语料规模的描述是”约 1,884 个文件、约 512K 行 TypeScript”（此前流传的”~1,900 个文件”说法可据此收敛为 1,884）。
⚠️ 但这个比例不是”可测量的事实”，引用时必须带上它自身的限定。论文原文写的是 “Community analysis of the extracted source estimates that only about 1.6%…”——即来自社区分析的估算，不是作者团队的实测。更要紧的是，该论文自设了证据分层，而这一条属于最弱的 Tier C（reconstructed）：论文对 Tier C 的定义是”由社区分析、与其他 Agent 的结构比对、或从代码模式推断得出的主张，均以对冲措辞陈述”。
上述原文的措辞（“estimates”、“An estimated”）正是论文 Tier C 政策所要求的对冲语。因此正确的读法是：这个比例指出了一个方向性事实（决策层极薄、工程层极厚），但不构成可精确的量化结论。把它当成”1.6% 这个数字已被测量确认”来引用，会超出来源自身的证据强度。论文对架构的定性判断（” overwhelmingly deterministic infrastructure … with the LLM invoked as a stateless completion endpoint”）则比这个比例稳健得多。
但”Harness 决定产品”不只是说 Harness 比 Model 重要——更准确地说，Harness 和 Model 是协同优化的。 Addy Osmani 指出：“Today’s agent products are post-trained with harnesses in the loop. The model gets specifically better at the actions the harness designers think it should be good at.” Opus 4.7 装进 Claude Code 的 Harness 里，比装进自己手搓的 while 循环里好用一大截，部分原因正是共训（co-training）造成的——Anthropic 在后训练时把 Harness 和模型一起优化，让模型专门适配 Harness 期望的行为。
这形成了一个正反馈循环：Harness 设计 → 训练数据设计 → 模型适配 Harness → 改进 Harness → 改进训练数据……业界共识也在收敛于此——OpenAI 2026 年发布 Harness Engineering 博文，Martin Fowler 网站凝练出 Agent = Model + Harness 公式，shareAI-lab 发布 learn-claude-code 12 节渐进课程（从 while 循环到多 Agent 团队），都确认了这一判断。
竞品侧的独立证据：OpenAI 的 Codex 实验
同类现象不只出现在 Anthropic 一侧，这一点很关键——它说明 Harness 优先不是某家公司的路线选择，而是行业级现象。OpenAI 官方工程博文《Harness engineering: leveraging Codex in an agent-first world》（2026-02-11）报告了一次极端实验：3 名工程师、5 个月、约 100 万行代码、约 1,500 个已合并 PR，人均 3.5 PR/天，且全程零手写代码。规模之外有两点值得注意：团队扩大到 7 人后人均产出不降反升（与传统软件工程的 Brooks 法则相反）；瓶颈从”代码产出”转移到了人类 QA 的注意力容量。
博文给出的一条反面经验与本书 15.2 直接互补：“one giant AGENTS.md fails”。他们最初把所有约定塞进单个巨型 AGENTS.md，失败方式有四种——上下文是稀缺资源（大指令文件挤掉了任务本身）、“当所有事都重要时就没有真正重要的”、庞大的手册会立刻变成过时规则的坟场、单一大文件无法机械化校验（覆盖率/更新状态/归属/交叉链接）。修正做法是把 AGENTS.md 压到约 100 行，只作目录索引，细节放进结构化的 docs/ 并视其为系统的唯一事实来源。
这个”约 100 行”与 15.2 的 150 指令预算是同一约束的两个观测面：前者从工程实践反推，后者从模型遵从度实验正推，结论量级相当。本书前文讲”怎么组织上下文”，这条讲”不该怎么组织”——把 AGENTS.md 当百科全书是最常见的失败姿势。
适用边界（2026-10-01 更新）：AGENTS.md 支持此前有 provider 限定，v2.1.281（2026-09-23）起改为也覆盖 Amazon Bedrock、Google Vertex AI、Microsoft Foundry、LLM 网关，以及遥测关闭的会话。读者若按更早的资料以为「Bedrock / Foundry / 自建网关上用不了 AGENTS.md」，该限制已不存在。
博文另有一条方法论值得单列：“对 Agent 来说，运行时不在上下文里的东西，实际上就不存在”（储存在 Google Docs、聊天记录或某个人脑子里的知识，系统够不着）。这解释了为什么他们的结论是把知识版本化进仓库，而不是写得更详细。
15.2 Context Engineering 的七个实践
从 prompts.ts 中提炼的七个实践（详细分析见第 6 章和第 18 章教训二）：
| # | 实践 | 关键实现 |
|---|---|---|
| 1 | 静态/动态分离 | SYSTEM_PROMPT_DYNAMIC_BOUNDARY 标记 |
| 2 | 环境感知注入 | OS、Shell、CWD、Git 状态动态写入 |
| 3 | 条件加载 | 50+ 个 Feature Flag 控制提示片段 |
| 4 | 工具描述即指令 | description 影响模型选择行为 |
| 5 | 角色定义 | 能力边界 + 行为规范 + 输出格式 |
| 6 | 动态记忆加载 | CLAUDE.md / memory.md 会话时注入 |
| 7 | 预算感知 | 信息量与 token 效率平衡 |
150 指令预算约束：HumanLayer 2026 年初内部研究显示，LLM 指令遵从度在约 150 条行为指令处显著退化。Claude Code 自身的系统提示已消耗约 50 条预算，留给 CLAUDE.md 的只有约 100 条。超过此阈值后，模型不是均匀降低所有指令的遵从度，而是选择性忽略最新添加的指令、与预训练强先验冲突的指令、以及深埋在长文档底部的指令。这解释了为什么社区趋向 3-Layer Agent Harness 架构（CLAUDE.md → Skills → Agents）——每一层承载不同类型的指令，避免单层膨胀。SAP 社区进一步提出”disallowedTools 不是权限而是架构保证——让捏造不可能，不只不鼓励”。
提示腐化与体检：/doctor prompt-audit
上面的七个实践与 150 指令预算回答的是写多少、怎么写。还缺一环：写完会坏，坏了怎么查。
这件事现在有了一等入口。v2.1.283（2026-09-25）新增 /doctor prompt-audit（别名 /checkup prompt-audit），审计 CLAUDE.md 文件、skills、agents、commands 中为旧模型写的提示模式。同一版本改进了报告排序：陈旧路径、陈旧命令、互相矛盾的指令文件排在最前，并保留 Claude Code 自身文档化的 thinking 关键词，不作为陈旧项误报。
⚠️ 沿革要写准。底层 audit 能力早于本轮——本书第 18 章已把它与
claude plugin eval并列收录，写作「上一版已收录的prompt-audit子命令（扫描旧模型冗余提示）」。v2.1.283 的新增量是「一等入口 + 报告排序」，不是「这个功能从无到有」。 把它写成「Anthropic 新增了提示审计功能」是错的。
这一条对本章的意义不止于多一个命令。15.1 的论点是 Model 是可替换组件、Harness 是可迁移资产；若 Model 可替换，那么写给 Model 看的提示就必然有保质期——为上一代模型写的措辞，在新模型上可能不再是最佳提示，甚至是有害提示。「提示会腐化」是「Harness 比 Model 更重要」的直接推论，而官方把它产品化，等于承认了这个推论。
「互相矛盾的指令文件」被单列为一类尤其值得注意。本节上文 one giant AGENTS.md fails 给出的修正做法是把 AGENTS.md 压到约 100 行、细节拆进 docs/——拆分的代价就是文件之间会互相打架，而这条代价此前只能靠人肉 review 承担。现在它是检测器的一个独立类别，且排在报告最前。OpenAI 博文指出的「单一大文件无法机械化校验」这个缺陷，在 Claude Code 这一侧正被逐个类别补上。
15.3 工具设计的七条原则
从 Claude Code 的 50+ 工具中，可以总结出工具设计的七条原则：
| 原则 | 说明 | 例子 |
|---|---|---|
| 1. Schema 即契约 | 用 Zod 做运行时验证，不信任模型的输出 | 所有工具都有 inputSchema |
| 2. 行为标记驱动调度 | 声明式标记（并发安全/只读/破坏性）让编排层做决策 | isConcurrencySafe |
| 3. Fail-Closed 默认 | 不确定的标记选择更安全的默认值 | isReadOnly: false |
| 4. 精确 > 通用 | FileEdit（精确替换）和 FileWrite（完整覆写）分离 | 不同权限粒度 |
| 5. 描述引导选择 | 告诉模型”何时用这个”比”这个能做什么”更有用 | Grep vs FileRead 的选择指导 |
| 6. 延迟加载节省上下文 | 不常用工具按需加载 | shouldDefer + ToolSearch |
| 7. 工具池排序影响缓存 | 稳定的工具顺序提升 Prompt Caching 命中率 | assembleToolPool 排序 |
反向向量：分发物可以给自己发许可证。上表七条默认的前提是「工具被授权后才能用」——授权发生在用户或管理员一侧。v2.1.284 与 v2.1.282 的两条修复指出还有相反方向：来自 marketplace、claude.ai、npm 的插件（v2.1.284），以及 repository / user / --add-dir 的 skills、commands 与 skills-directory 插件 manifest（v2.1.282），曾通过 allowed-tools 自我预授权自己的工具。在托管 allowManagedPermissionRulesOnly 下，修复后只有来自 Anthropic 官方源、或被 managed settings 背书的源的插件保留该预授权。
这条对自研 Agent 产品的提醒是结构性的：只要允许第三方分发「带工具声明的封装物」，你就默认引入了一条绕过授权方的通道。它不是 bug 而是设计——allowed-tools 本来就是为了让 skill 声明它需要的工具；问题只出在「谁有权替用户批准」。判据是：分发物的来源分级，必须与管理侧的授权策略打通，否则「官方源」与「随便谁的源」在用户眼里长得一样。
15.3.1 12 个 Harness 设计模式
社区从 Claude Code 源码中提炼出 12 个可复用的 Agentic Harness 设计模式（by Bilgin Ibryam，Kubernetes Patterns 作者），分四类：
记忆与上下文（2 个）
| 模式 | 描述 |
|---|---|
| 持久化指令文件 | CLAUDE.md / CLAUDE_TOML 定义项目级指令，session 启动时自动注入 |
| 上下文压缩与恢复 | 长会话时自动压缩历史，保留关键信息，支持恢复 |
工作流与编排（4 个）
| 模式 | 描述 |
|---|---|
| 工具适配器层 | 统一封装不同工具的调用接口，隐藏底层差异 |
| 无头批处理 | 后台批量执行任务，不阻塞交互界面 |
| 两阶段确认 | 破坏性操作分”预览意图”和”确认执行”两步 |
| 状态机驱动 | Agent 行为用状态机建模，避免混乱 |
工具与权限（4 个）
| 模式 | 描述 |
|---|---|
| 最小权限范围 | 工具只申请完成任务所需的最小权限集 |
| 行为标记驱动调度 | 声明式标记（并发安全/只读/破坏性）让编排层做决策 |
| 延迟加载 | 不常用工具按需加载，减少冷启动开销 |
| Schema 即契约 | 用 Zod 做运行时验证，不信任模型输出 |
自动化（2 个）
| 模式 | 描述 |
|---|---|
| Pre/Post Hook 扩展点 | 用户在工具执行前后插入自定义逻辑 |
| 异步消息流 | 使用 AsyncGenerator 实现流式进度展示 |
编辑说明：12 个 Harness 模式基于 hubwiz.com 和 besthub.dev 文章补充（2026）。子 Agent 使用 Sonnet 模型筛选相关记忆、主动过滤刚使用过的工具文档——这是”用合适成本的模型做合适复杂度的事”的成本优化策略的具体实现。
从”设计模式”到”工程资产”：ant apply。上面 12 个模式长期停留在设计建议层面——可读、可借鉴，但不可版本控制、不可 Code Review、不可回滚。Anthropic 于 2026-09-03 随 CLI v1.30.0 引入 ant apply，把这件事推进了一步：agents、environments、skills、memory stores、deployments 五类资源可以声明为仓库中的文件，通过 ant apply 与 API 侧资源保持同步。
它的工作流与 Terraform 同构：写声明文件 → ant apply 打印计划 → 人工确认 → 生成并提交 claude-lock.json 锁文件（记录每个文件创建的资源 ID、组织、工作区，以及本地/远端两侧的 hash）。后续运行据此更新同一批资源而非重复创建，也能发现”文件被改过”或”资源在仓库之外被改过”。CI 用法是默认分支合并后跑 ant apply --yes .，PR 上跑 ant apply --dry-run . 让评审者看计划。
三条值得读者注意的边界：资源之间用相对路径互相引用（不必硬编码 ID），改一个被引用者会在同一次运行里更新所有引用者；ant apply 无法接管在 Console 里或用 ant beta:agents create 创建的资源；删除文件不会删除远端资源，需要 --prune（多数资源为归档，skills 为删除）。
⚠️ 提案原文称
ant apply管理「agents / skills / memory / deployments」四类，实际官方为五类，遗漏了 environments。已按官方docs.anthropic.com的 apply 文档更正。对本章的意义：
ant apply是”Agent Config as Code”落地的官方信号——本节所述模式从此可以进 Git、过 Code Review、随提交回滚，从设计建议变成工程资产。
15.3.2 Anthropic 官方五大多代理协调模式
Anthropic 于 2026 年 4 月发布官方多代理协调模式指南，提出五种模式：
| 模式 | 描述 | 对应 Harness 模式 |
|---|---|---|
| Generator-Verifier Pairs | 一个生成、一个验证的配对模式 | 对抗性验证（15.5） |
| Parallelization | 多个代理并行执行独立子任务 | 无头批处理 |
| Orchestration | 中心协调器分配和汇总任务 | 状态机驱动 |
| Routing | 根据输入特征路由到专业代理 | 工具适配器层 |
| Specialization with Feedback Loops | 专业代理 + 反馈闭环持续改进 | Pre/Post Hook 扩展点 |
关键指导原则：“从识别系统最可能的失败模式开始选择模式”——如果你的系统最怕幻觉，选 Generator-Verifier；最怕延迟，选 Parallelization；最怕不一致，选 Orchestration。
Generator-Verifier 的生产级实现：Dynamic Workflows。Opus 4.8 引入的 Dynamic Workflows（2026-05-28）是 Generator-Verifier Pairs 模式的生产级落地。核心机制不再是单个 Verification Agent 的单次检查，而是持续的 Generator-Validator 循环——一组 Agent 生成代码，另一组 Agent 对抗性验证，反复迭代直到答案收敛，类似 GAN 的”生成器-判别器”对抗训练。关键创新：(1) 中间结果存储在 JS 编排脚本的变量中而非对话上下文中，避免上下文膨胀；(2) 支持断点恢复，长时间运行的 workflow 中断后可从断点继续；(3) 杀手锏不是”并行 Agent”而是”对抗收敛”——每个生成结果都经过对抗性验证。
Bun 移植案例：Bun 创始人 Jarred Sumner（2025 年 12 月被 Anthropic 收购后成为 Anthropic 员工）用 Dynamic Workflows 将 Bun 从 Zig 移植到 Rust——6 天、96 万行代码、99.8% 测试通过，含约 1.3-1.4 万个 unsafe 块。每个 .zig 文件有 2 个 reviewer Agent，数百个 Agent 并行工作。
Claude Code 的纵深防御体系：确定性规则匹配（快速）→ AI 分类器（智能）→ 用户确认（兜底），加上 Fail-Closed 默认值和熔断机制。详细架构见第 7 章，可执行建议见第 18 章教训三。
15.5 多代理的实践经验
四条核心经验：代理是权限边界（最小必要权限）、模型选择是成本优化（不是所有代理都需要最强模型）、对抗性验证（“敌意挑错”而非”友好检查”）、协调器 vs 直接调用（复杂度匹配）。详见第 8 章和第 18 章教训五。
Conductor vs Swarm：行业架构收敛趋势
2026 年多代理架构正收敛为两极：
| 维度 | Conductor（集中式） | Swarm（去中心化） |
|---|---|---|
| 协调方式 | 中心协调器分配和汇总 | 代理对等通信，自主协作 |
| 故障隔离 | 协调器单点风险 | 无单点故障 |
| 复杂度 | 简单可控 | 灵活但难调试 |
| 典型案例 | Claude Code Agent Teams（Team Lead） | Cognition Managed Devins |
LangChain 提出四模式分类（Subagents、Skills、Handoffs、Routers），与 Anthropic 五大模式互补。行业实际趋势：Cognition 从”反多代理”转向 Managed Devins（Conductor 模式），Anthropic 走 decoupled brain/hands 路线——两者都趋向 Orchestrator + Isolated Subagents 模式，在集中协调和自主执行之间找平衡。
Dynamic Workflows：脚本驱动动态编排
Opus 4.8 引入的 Dynamic Workflows 代表了第三种架构模式——既不同于静态编排的 Conductor，也不同于去中心化的 Swarm：
- JS 编排脚本驱动：Claude 动态编写 JavaScript 编排脚本，在单个会话中运行数十到数百个并行 sub-agent，每个 sub-agent 独立执行子任务。不是 Agent 自主决策如何协作，而是由 AI 生成的脚本决定编排逻辑
- Generator-Validator 循环：一组 Agent 生成代码，另一组 Agent 对抗性验证，反复迭代直到答案收敛（类似 GAN）
- 断点恢复：长时间运行的 workflow 中断后可从断点继续
- 变量级中间结果：中间结果存储在脚本变量而非对话上下文中，避免上下文膨胀
四模式对比：
| 维度 | Single-agent looped | Supervisor-workers | Dynamic Workflows | Peer-to-peer Swarm |
|---|---|---|---|---|
| 编排方式 | 单代理循环执行 | 中心协调器分配 | 脚本驱动动态编排 | 去中心化对等通信 |
| 决策主体 | 单一模型 | 协调器 | AI 编写的 JS 脚本 | 各代理自主 |
| 中间状态 | 对话上下文 | 协调器汇总 | 脚本变量 | 共享消息 |
| Token 开销 | 基线 | +285% | 中等（变量不占上下文） | +58% |
| 适用场景 | 简单任务 | 标准生产部署 | 大规模代码工程 | 去中心化协作 |
| 生产部署占比 | ~10% | ~70% | 新兴 | ~20% |
Token 开销数据来自 DecodetheFuture 统计：独立多代理额外 token 开销约 58%，集中式约 285%。Orchestrator-Worker 占 70% 生产部署。
Dynamic Workflows GA：六大编排模式分类（2026-06-08）
Dynamic Workflows 于 2026-06-08 从 research preview 升级为 GA，扩展到 Pro 计划（$20/月）。GA 版本的核心架构变化是”编排计划外置”——Claude 编写 JavaScript 编排脚本，由独立运行时在后台执行，模型上下文仅接收最终综合答案，使得长达数天的自主运行在架构上成为可能。GA 后明确了 6 种编排模式，每种有清晰的适用场景：
| 模式 | 描述 | 典型场景 |
|---|---|---|
| Classify-and-act | 按任务类型路由（switchboard） | 多类型工单分流 |
| Fan-out-and-synthesize | 并行 Agent → barrier 合并（map/reduce） | 大规模代码移植、批量文件操作 |
| Adversarial verification | 独立 Agent 攻击每个结果 | 代码审查、安全审计 |
| Generate-and-filter | 广撒网 → 只保留幸存者 | 头脑风暴、方案筛选 |
| Tournament | Agent 竞争 + 成对评判 | 设计决策、命名 |
| Loop-until-done | 持续生成直到满足停止条件 | bug 修复、测试驱动补全 |
使用方式：通过”ultracode”关键词或 /effort ultracode 触发。Pro 计划默认关闭（需 /config 手动启用），Max/Team 默认开启。v2.1.202（7/6）新增 workflow-size 引导配置（small/medium/large），最多支持 1,000 并行子 Agent（16 并发硬上限）。
成本警告：并行 Agent 不共享 token，成本线性增长。复杂 workflow 24 小时可达 $400-600。子 Agent 应使用 Sonnet 等轻量模型做初步筛选，仅在必要时使用旗舰模型。
Dynamic Workflows 的失败模式与硬约束
上面四段讲的都是能力参数——GA 时间、编排模式、规模上限、成本。对一本讲设计模式的书，缺了另一半：它会怎么失败。
一条会静默生效的硬约束（已获官方确认）。workflow 文件必须以 export const meta 作为第一条语句，且 meta 必须是纯字面量对象，包含 name 与 description。若其中含有任何非字面量的东西——变量、函数调用、或展开运算符（spread）——Claude Code 会把 /<name> 从 / 自动补全中移除。
注意这里的失败形态：不是报错，而是静默消失。读者写了一个带变量的
meta，不会看到任何错误信息，只会发现自己的 workflow 在补全列表里找不到了。这比报错难排查得多。另一条相关约束：
phases若在meta中列出，每一项的标题必须与传给phase()的标题逐字一致；用了phase()标题却没有对应条目，会单独成组显示。
三条已知失败模式（社区来源）。Dynamic Workflows 的设计者之一 Thariq Shihipar（Anthropic）与 Sid Bidasaria 归纳了三类：
- agentic laziness——Agent 倾向走最短路径，跳过必要步骤
- self-preferential bias——Agent 评审自身产出时系统性高估
- goal drift——长流程中目标逐渐偏离初始意图
📌 来源强度：以上三条在官方 workflows 文档中零命中（已 grep 核验），目前只能作为实践者经验而非官方结论来读。它们的价值在于提示一个方向——本节”Adversarial verification”模式存在的理由，正是为了对抗第 1 与第 2 条；而”断点恢复”与阶段化结构则是对抗第 3 条的手段。换句话说，这些失败模式不是孤立经验，而是与前述六大编排模式互为因果的：后者是前者的对策。
三条官方失败模式（changelog 一手，2026-10-01 补）。上面三条来自社区，来源强度已在批注中标明。下面三条性质不同——它们逐条出现在官方 changelog 里，且都不是上面三类能覆盖的：
| 版本 | 失败模式 | 为什么危险 |
|---|---|---|
| v2.1.285 | workflow 脚本中被晚 await、或完全不 await 的失败 agent() / parallel() / pipeline() 调用，被当作 unhandled promise rejection | 可能直接结束一个后台会话。这是编排层的生命周期陷阱：错误没在它该出现的地方被处理，而是浮到最外层把整个会话带走 |
| v2.1.283 | 在 model fallback 期间启动的 dynamic workflow，每个 agent 都跑在 fallback model 上，而不是重试配置的模型 | 静默错误。用户看到的是「跑完了」，不是「跑错了模型」——整条 workflow 的模型选择被一次降级悄悄污染，且事后从结果上几乎看不出来 |
| v2.1.285 | disableWorkflows 开启时，Code Review 的 PR 评审与 /ultrareview 仍然运行 | 组织策略的逃逸口。除非运行评审的那台机器由它自己的管理员设置了该键（MDM 或 managed-settings 文件），否则管理员以为关掉的编排能力仍在跑 |
第二条是这里最该被记住的一条。它把两个此前分离的主题连了起来：模型降级与编排。前面讲过模型可用性降级（第 14 章 14.4），那里的影响是「换了个模型」；一旦进入 workflow，影响面变成「整条流水线上几十上百个 agent 全换了模型」，且没有任何一条报错。第三条则说明「策略键」与「策略实际覆盖的执行位置」是两件事——disableWorkflows 管的是这台机器上的 workflow，而 Code Review 的评审可能跑在另一台机器上。
子 agent 的权限继承
15.3.2 的五大协调模式与本节前面讲的多是怎么拆、怎么协调。还有一个切面此前没有：拆出去的 agent 继承什么样的权限边界。v2.1.285 三条给出了答案：
- fork subagent 现在运行在父会话的权限模式下，且不能退出 plan mode。此前 fork subagents 不保留会话的 plan mode 或
dontAskmode——意味着一次 fork 就可能把一个「只读规划」会话变成「有个子 agent 在真改文件」。修复之后，plan mode 从「一个会话状态」变成「一个向下继承的约束」。 claude -p配CLAUDE_CODE_FORK_SUBAGENT=1时，子 agent 自己的 Agent 调用改为前台运行，使子 agent 能拿到 child 的结果。claude -p --permission-prompt-tool下，后台 subagent 的权限请求改为走 prompt tool，不再被自动拒绝。
第一条的抽象价值高于它的修复价值：权限边界若不显式声明继承规则，默认的继承行为就是「不继承」。而「不继承」在多代理系统里几乎总是错的——它意味着权限只约束发起者，不约束被发起者。
子 agent 何时该停。v2.1.285 改进：auto mode 下的 subagent 交回报告后立刻结束运行，不再多跑那些「到不了任何人手里」的额外轮次（同版本还修掉了 background subagent 在每次报告后再发一条多余回复的问题）。这既是成本修正也是语义修正——「报告已交回」才是终止条件，「还有话说」不是。
15.6 可复用的模式清单
如果你正在构建自己的 AI Agent 产品，以下是从 Claude Code 中可以直接复用的模式：
| 模式 | 适用场景 | 参考章节 |
|---|---|---|
| AsyncGenerator 消息流 | 需要流式展示进度的 Agent | 第 4 章 |
| 工具的并发/串行分批 | 多工具调用编排 | 第 4-5 章 |
| 静态/动态 Prompt 分离 | 使用 Prompt Caching | 第 6 章 |
| 六层权限规则 + AI 审批 | 企业级安全需求 | 第 7 章 |
| 双阶段 AI 分类器 | 自动模式的安全保障 | 第 7 章 |
| 专业代理 + 权限白名单 | 多代理系统 | 第 8 章 |
| 对抗性验证代理 | 代码质量保障 | 第 8 章 |
| 三层记忆作用域 | 跨会话知识管理 | 第 9 章 |
| 上下文压缩 + 恢复 | 长会话支持 | 第 9 章 |
| Pre/Post Hook 扩展点 | 用户自定义扩展 | 第 11 章 |
| 构建时 Feature Flag 消除 | 安全的灰度发布 | 第 13 章 |
| 多云模型标识符映射 | 企业级多云部署 | 第 14 章 |
| 会话级 web search/subagent 上限 | 防止失控循环 | 新增（v2.1.212） |
| 后台子 Agent 默认 + 完成通知 | 长时间并行任务 | 第 8 章 |
| /fork 后台会话复制 | 实验性分支探索 | 第 4 章 |
| subagent tool 列表逐字节稳定 | 恢复会话后仍要命中 Prompt Caching | 第 9 章（v2.1.280） |
提示腐化体检（/doctor prompt-audit） | 指令文件随模型换代而失效 | 15.2（v2.1.283） |
subagent 的 tool 列表必须逐字节稳定。v2.1.280 修的一条 bug 值得提炼成模式：恢复的 fork subagent 若重建 tool 列表、而不是重发它首次使用的那个列表，会破坏该 agent 的 prompt caching。它把上表「静态/动态 Prompt 分离」这一行从会话级推进到 subagent 级：缓存命中的前提不只是「提示前缀不变」，还包括「工具定义序列不变」。与第 18 章教训七同源——凡是靠前缀匹配省钱的设计，「重建一个等价但字节不同的东西」就是最隐蔽的破财方式。
一次 24 小时内的命名空间往返（脚注）。v2.1.282（09-24）保留
anthropic-skills与claude-ai两个命名空间：该命名空间下的 skill 文件夹 / command 文件 / workflow command 不再加载，以此命名的 MCP server 不列出 skill 与 prompt，并把Skill(anthropic-skills:*)与Skill(claude-ai:*)的 allow 规则收紧为「只覆盖从 claude.ai 同步来的 skill」。⚠️ v2.1.283 只回滚了
claude-ai这一个。官方 v2.1.283 的原文是 “Reverted the 2.1.282 reservation of theclaude-ainame”，同版本对anthropic-skills做的是另一件事——把Skill(anthropic-skills:<name>)的 deny 规则扩展到 Claude Desktop 以插件形式投递的场合，并让Skill(skill:<name>)的 deny 匹配 skill 的别名与显示名。anthropic-skills的保留并未撤销。这次往返的净效果不是零：24 小时内回滚了一个命名空间，另一个留了下来并被加固。它仍可作为第 18 章教训八「Feature Flag 是产品演进的基础设施」的实证，但实证的是「能回滚一半」，不是「一键复原」。
15.7 最后的话
本章是一份模式清单——把 Claude Code 的设计决策提炼为可迁移到你自己产品的模式。每个模式都附带了参考章节，方便你回到源头深入理解。
如果你想要更聚焦、更可执行的行动建议（每条都有”明天就能做什么”），请看第 18 章的十个教训。那一章不是本章的重复，而是从不同角度切入——本章回答”Claude Code 里有哪些可复用的模式”，第 18 章回答”你构建 AI 产品时最应该先改变的十个认知”。
系统性解剖到此完成。接下来的专题研究会持续追加新章节，深入探讨社区发现的有趣设计点。