前言¶
在 Claude Code、Cursor 等环境里做复杂任务时，单会话很容易塞满测试日志、检索结果和长段探索输出，主对话上下文被拖慢，权限也难以按角色收紧。子 Agent（subagent）用独立上下文窗口承载这类工作，但「何时拆任务、如何委托、并行上限多少、子 Agent 不能再嵌套」等约束若不事先对齐，协调成本会盖过并行收益。下面介绍 oakoss 维护的 agent-patterns Skill：它把多 Agent 的设计模式、内置子 Agent 能力、配置字段与常见误用整理成可对照的参考，面向正在设计或调试多 Agent 系统的开发者。
这是什么¶
agent-patterns 是 agent-skills 仓库中的一条 Skill（当前 metadata 版本为 1.1，MIT 许可，作者 oakoss）。官方描述覆盖：自定义子 Agent、内置子 Agent（Explore / Plan / General-purpose 等）、可互换（fungible）与专用（specialized）Agent 的取舍、委托与编排、批处理工作流、上下文卫生与失败恢复。
Skill 正文与 Claude Code Sub-agents 文档 对齐；在 oakoss 的 112 条 hand-curated Skill 集合里，它归类为与 Multi-Agent 架构直接相关的一条。frontmatter 中 user-invocable: false，表示不由用户直接以斜杠命令唤起，而是由 Agent 在「设计多 Agent 系统、创建自定义子 Agent、委托批量操作、编排并行工作」等场景下自动选用。
核心功能¶
设计模式速查¶
Skill 用表格归纳八种常见模式及适用时机，例如：
| 模式 | 要点 | 典型场景 |
|---|---|---|
| Fungible swarm | 相同 Agent 从共享任务板取任务 | 大规模软件开发、需要韧性的系统 |
| Sequential pipeline | 每一步依赖上一步输出 | 依赖关系清晰的多步流程 |
| Hierarchical | 管理者拆解，工作者并行 | 子任务彼此独立的大任务 |
| Peer collaboration | 多 Agent 迭代至共识 | 代码评审、质量敏感产出 |
| Orchestrator delegation | 主会话串联子 Agent | 多阶段、多专家并行 |
| Two-stage review | 先规格符合性，再代码质量 | 高风险代码、复杂需求 |
| Question-first delegation | 先澄清再执行 | 任务含糊、重做成本高 |
| Review loop enforcement | 修—审循环并设最大迭代 | 需要收敛的评审流程 |
正文建议：大规模软件开发默认采用 fungible Agent；仅在同行评审或基于讨论的流程里再考虑 specialized Agent，以降低单点失败风险。
内置子 Agent 与工具策略¶
资料列出 Claude Code 侧常见内置子 Agent 及用途，例如 Explore（Haiku、只读，用于代码库探索）、Plan（继承模型、只读）、General-purpose（继承模型、全工具）、Bash（终端隔离）、Claude Code Guide（Haiku、只读，回答产品问题）。
对自定义 Agent，Skill 给出按角色的工具建议：只读评审用 Read, Grep, Glob；仅创建文件时避免 Bash（减少 heredoc 审批噪音）；脚本与构建任务可含 Bash；研究类可含 WebFetch, WebSearch。子 Agent 默认继承全部工具（含 MCP）；可用 tools 白名单或 disallowedTools 黑名单限制。背景子 Agent 中 MCP 不可用。
关键约束与规模建议¶
- 嵌套：子 Agent 不能再 spawn 子 Agent；多步编排必须由主会话串联子 Agent。
- 批处理：标准任务约 5–8 项/Agent。
- 并行：同时约 2–4 个 Agent；小任务不宜堆到 5 个以上。
- 前后台：前台子 Agent 会阻塞主会话；后台可并发运行。
何时用子 Agent vs 主会话¶
子 Agent 更适合：产出冗长输出（测试、日志、API 响应）、需要强制工具/权限边界、工作自包含且可只回传摘要、多条独立研究路径并行。主会话更适合：需要频繁来回打磨、多阶段共享大量上下文、小改要快、或对延迟敏感（子 Agent 冷启动需重新收集上下文）。
安装与启用¶
agent-patterns 随 oakoss/agent-skills 安装。官方 Install 示例（与仓库 README 一致）：
# 交互式浏览并选择
pnpm dlx skills add oakoss/agent-skills
# 只安装 agent-patterns
pnpm dlx skills add oakoss/agent-skills -s agent-patterns
# 指定目标 Agent（示例：Claude Code）
pnpm dlx skills add oakoss/agent-skills -a claude-code
# 用户级全局安装
pnpm dlx skills add oakoss/agent-skills -g
# 预览列表
pnpm dlx skills add oakoss/agent-skills --list
集合说明支持 Claude Code、Cursor、Gemini CLI、OpenAI Codex、VS Code、GitHub Copilot 等 27+ 类 Agent 生态（见 agentskills.io）；具体落盘路径以你所用工具的 Skill 机制为准。
自定义子 Agent 文件位置（Skill 内配置表）：
| 配置项 | 值 |
|---|---|
| 项目级 | .claude/agents/*.md |
| 用户级 | ~/.claude/agents/*.md |
| 会话级 CLI | --agents '{...}'（JSON，仅当次会话） |
| Plugin | 插件 agents/ 目录（优先级最低） |
必填 frontmatter 字段：name、description。可选：tools、disallowedTools、model、permissionMode、skills、hooks、color。model 可取 sonnet、opus、haiku、inherit（默认）。permissionMode 含 default、acceptEdits、dontAsk、bypassPermissions、plan 等。
典型用法（可对照 Skill 正文）¶
-
编排多阶段工作：在主会话里按阶段依次启动子 Agent（例如先 Explore 摸清代码结构，再 General-purpose 执行多步修改），不要把「子 Agent 再派生子 Agent」当作可行路径。
-
并行 fungible swarm：把可独立项放进共享任务板，用 2–4 个相同配置的 Agent 并行处理，每 Agent 约 5–8 条任务，最后由主会话合并摘要。
-
两阶段评审：先派只读 Agent 做需求/规格符合性检查，再派另一只读或受限 Agent 做代码质量检查；评审 Skill 建议 review 类 prompt 包含「FIX issues found」类闭环表述，并配合 Review loop enforcement 设最大迭代。
-
写自定义 Agent 文件：在
.claude/agents/my-reviewer.md中写好 frontmatter 与系统提示；关键规则放在 frontmatter 之后靠前位置，避免埋在长文 300 行之后被模型弱化。 -
权限与工具收紧：审计类 Agent 只开放
Read, Grep, Glob；对敏感操作即使继承全工具，也应在 frontmatter 用disallowedTools显式禁止。
适用场景与注意¶
适合：设计新的多 Agent 拓扑、为项目添加 .claude/agents、调试委托后结果不一致或上下文膨胀、在 fungible 与 specialized 之间做架构取舍、配置 permissionMode 与模型档位。
注意（Skill 中的 Common Mistakes 摘要）：
| 误用 | 建议 |
|---|---|
| 指望子 Agent 再嵌套子 Agent | 仅主会话可串联 |
| 只建文件却给 Bash | 用 Write/Edit，减少审批干扰 |
| 继承全工具却不禁危险项 | 用 disallowedTools 显式拒绝 |
| 小任务开太多 Agent | 先从 2–3 个开始 |
| 大规模开发过度 specialized | 优先 fungible + 任务板 |
| 关键指令写在 prompt 末尾 | 紧接 frontmatter 放置 |
Skill 声明 user-invocable: false，日常更多是靠 Agent 在相关任务时加载规则，而不是用户手动调用一条命令。
结尾¶
agent-patterns 把 Multi-Agent 在 Claude Code 语境下的模式、内置子 Agent、配置表与反模式集中成一份对照文档，适合作为编排与委托前的检查清单。安装与条目说明见官方仓库：
https://github.com/oakoss/agent-skills/tree/main/skills/agent-patterns
