---
name: dispatching-subagents
description: Use when about to spawn or delegate work to a subagent (Agent/Task tool), choosing a model tier (haiku/sonnet/opus/fable) for a task, writing a delegation prompt, deciding whether something should be delegated at all, deciding whether to dispatch multiple subagents in parallel, verifying a delegated result, or after a delegated task failed twice and needs escalation.
---

> 🌐 [English version](https://github.com/tienenwu/fables/blob/main/en/dispatching-subagents/SKILL.md) · 繁體中文（正本 / canonical）

# 模型調度守則（dispatching-subagents）

目標：主對話 context 只裝結論與決策，執行細節外包。派工 prompt 模板見 `references/templates.md`；判斷測驗見 `references/test-scenarios.md`。

## 0. 什麼時候「不要」派工（先看這條，避免過度委派）
- 已知確切檔案與位置的單點查證（例：看某設定檔第 N 行的值）→ 自己 Read，比派 agent 便宜。
- 對話性回覆、解釋概念、改一兩行 → 自己做。
- 判準：**已知確切檔案路徑或唯一關鍵字、且預計讀的內容 < 200 行 → 自己做；需要跨多目錄搜尋或猜命名 → 派工。**

## 1. 指揮官不下場
以下工作一律派 subagent，主對話只收結論：
- 大量讀檔／掃 repo／「找出所有用到 X 的地方」→ `Explore` agent（唯讀，最便宜）
- 查網頁、讀文件、比較方案 → `general-purpose` agent（可用 WebSearch/WebFetch）
- 批次改檔（同一模式套用到多處）→ `general-purpose` agent
- 設計實作方案 → `Plan` agent
- 程式碼審查 → `code-reviewer` agent（另有 `system-architect` 做設計層第二輪）

## 1.5 平行派工（可平行就平行，序列是例外）
- **預設平行**：2 個以上子任務彼此獨立（無共享狀態、無順序依賴），且唯讀或寫入範圍互不相交 → 同一則訊息一次派出，不要一個等一個。典型：多目錄搜尋、多維度審查（正確性／安全各派一個）、研究查證、read-back 驗收。
- **禁止平行**：會寫同一批檔案（衝突），或後者輸入依賴前者結論（平行只是白跑）。寫入類要平行，先切出互斥的檔案範圍；切不開就序列。
- **規模上限**：一批 ≤ 6 個。更大規模 fan-out（幾十個）屬重型多代理編排（`Workflow` 等，見 §3），維持「使用者明確要求才用」。
- **失敗隔離**：批次中單一 agent 失敗不阻塞其他結果回收；失敗者單獨照 §5 升降級，不整批重派。

## 2. 派工三件套（每個派工 prompt 必含，模板見 references/templates.md）
1. **目標與動機**：要做什麼、為什麼（讓 agent 遇到岔路能自己判斷）。
2. **驗收條件**：可機械檢查的完成定義（例：「編譯通過並貼出 gradle 輸出最後 5 行」，不是「確保品質」）。
3. **回報格式**：只回結論 + `檔案:行號`；長產物寫到指定路徑，回傳路徑。

## 3. model 與 effort 的實際可用值（2026-07-24 更新）
- `Agent` 工具的 `model` 參數：`haiku` / `sonnet` / `opus` / `fable`。**省略 = 繼承主對話模型，這是預設正解**。
- **主迴圈預設跑 Opus**（日常駕駛）；`fable`（Fable5）是最貴、消耗最快的層級，只保留給下面標「`fable`」的兩類，其餘一律不點。
- `Agent` 工具**沒有 effort 參數**；effort 由 agent 定義的 frontmatter 或 session 的 effortLevel 決定。
- `Workflow` 工具（多代理編排）並非所有 harness 都有；只在使用者明確要求多代理編排、且工具確實存在時使用。
- 選型基準（由便宜到貴）：
  - `haiku`：機械性批次套用（模式已驗證過）、格式轉換、簡單 grep 彙整。
  - 省略（=主對話同級，預設 Opus）：一般搜尋、實作、審查。
  - `opus`：難 bug 根因、非品味的高難度評審裁判（卡關升級鏈的終點，見 §5）。
  - `fable`：**只兩個用途**——(1) 品味「判斷題」（UI 美感、文案語感的裁決）；(2) 架構取捨/決策的裁決。丟足 context、拿一個裁決回來執行，不要讓它長時間留在迴圈裡動手。
- **動手打磨型品味**（要跨多輪看 render 成品、逐輪迭代 UI）subagent 給不了——這時**手動 `/model` 把主迴圈切成 Fable5**，收工切回 Opus。判準：**「要 Fable5 看著成品逐輪改」→ 切主迴圈；「只要一個裁決／選一案」→ 派 `fable` subagent**。
- 仍解不了的品味題/模糊題：向另一個模型家族要第二意見（`codex:rescue` 等）→ 給使用者選項並誠實標明信心低。

## 4. 回報合約（寫進每個派工 prompt）
- 只回：結論、關鍵證據（`檔案:行號`、測試輸出末段）、遇到的阻礙。
- 禁止：整檔貼回、逐步過程流水帳。
- 產物超過 ~50 行 → 寫到檔案（scratchpad 或指定路徑），回傳路徑。

## 5. 升降級路徑
- **haiku 錯 1 次** → 直接升級到主對話同級重派，不要對 haiku 講道理。
- **同級 agent 同一子任務連錯 2 次** → 升級到 `opus`，並把**完整失敗軌跡**（做了什麼、輸出什麼、為何算失敗）放進新 prompt——不帶軌跡的升級只是換個模型再猜一次。
- **解出模式後**：把解法寫成明確步驟，降回 `haiku` 批次套用到其餘位置。
- **重試上限：同一模型層級內最多 3 次嘗試；升級到新層級時計數歸零**。最高層級也用完 3 次 → 停下，照 judgment.md §3 的「該問使用者」處理。
- **品味/架構裁決不走這條卡關升級鏈**：它由任務性質決定、一開始就派 `fable` subagent（見 §3），不是「卡關才升」。這條鏈處理難 bug／執行卡關，終點是 `opus` ＋外部第二意見。

## 5.5 唯讀/研究任務的副作用邊界（實戰教訓 2026-07-06）
派「研究/審計/唯讀」任務時，prompt 必須界定可執行的驗證命令——**「唯讀」不會自動阻止 agent 跑有副作用的命令**。
- ❌ 派「研究這專案有什麼可改」不加限制 → agent 為驗證「測試通過」跑 `npm test`，該專案測試寫正式 DB，研究任務污染了資料。
- ✅ prompt 明列：「只讀原始碼與設定；跑測試/build 前先確認它是否寫正式資源，不確定就回報不執行」。驗證「測試綠不綠」優先讀 CI 記錄或問使用者，而非親跑。

## 6. 驗證不自驗
**適用範圍：委派出去的任務，以及高風險改動（release 路徑、刪東西、公開 API）。主對話自己做的 ≤3 檔小修，自跑編譯/測試並貼輸出即可，不必另派驗收 agent。**
做的人不驗自己的活。委派任務的**初驗**派 **fresh-context agent**（新開，不給它實作過程，只給驗收條件）；驗不過修正後的**複驗**回到同一個驗證 agent 延續 session，只給修正 diff 與受影響的驗收條件——不要每輪都開新的 fresh agent，它不知道上輪驗過什麼，會重開舊戰場。fresh 只再用於 high-risk 收尾前的最終 gate。複驗上限一次；仍不過就帶完整驗證記錄照 judgment.md §3 升級使用者，不無限轉圈：
- 檔案類產出 → read-back：新 agent 讀檔，回答「是否包含 X、Y、Z」。
- 程式碼 → 跑測試或實際編譯/執行，貼輸出；沒有測試就寫一個最小重現。
- 高風險判斷（架構、安全、要不要刪東西）→ 第二意見：再派一個 agent 從反方立場審（「試著推翻這個結論」），或多答案評審選優。
- 驗收條件必須含至少一條「實際執行並貼輸出」的項目——只有存在性檢查的驗收單不合格。
- 驗證 agent 說不通過 → 回到實作方（帶著驗證輸出），不要主對話自己「目視覺得沒問題」蓋章。