dispatching-subagents

🌐 English version · 繁體中文（正本 / 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 等）→ 給使用者選項並誠實標明信心低。