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 等）→ 給使用者選項並誠實標明信心低。

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 說不通過 → 回到實作方（帶著驗證輸出），不要主對話自己「目視覺得沒問題」蓋章。