前言¶
在 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
