模組 5 · 進階考點
5.1 委派與診斷 5.2 Session 與輸出 schema 5.3 Batch 與 review pass 5.4 MCP 與工具補遺 5.5 錯誤回應設計 討論題
5.1 Subagent 委派策略與 spawn 診斷
委派光譜：procedural（程序式）vs goal-oriented（目標式）
Procedural 指令 Goal-oriented 指令 形式 逐步腳本（先做 A、再做 B、輸出 C） 目標 + 邊界，怎麼做交給 subagent 行為 可預測、一致（≈ workflow 思維） adaptive ——依中間發現調整做法（≈ agent 思維）適用 well-defined、步驟可事先寫死 open-ended、無法預測需要幾步 代價 彈性低，遇到沒寫到的情況就卡 成本較高 + compounding errors 風險
官方立場是中間解 ，不是二選一：委派內容必含四件套（objective、輸出格式、工具/來源指引、任務邊界） ——定義「什麼算完成」；但不 逐步規定怎麼執行——那部分用 heuristics 引導（effort scaling、start wide then narrow），讓 subagent 保有 adaptive 空間。原句："instilling good heuristics rather than rigid rules" 。
最大陷阱：goal-oriented ≠ 指令越短越好 。官方實測反例：只給 "research the semiconductor shortage" 這種一句話目標 → subagent 誤解任務、和別的 agent 做重複搜尋（"duplicate work, leave gaps, or fail to find necessary information" ）。詳細的任務描述 （目標＋邊界）≠ 詳細的步驟腳本 ——考題誘答常把兩者混為一談。
Coordinator 保住可見性與控制的手段 （選 goal-oriented 不等於放手）：stopping conditions / max iterations、checkpoint 暫停等人核准、顯示 planning steps（transparency）、production tracing；驗收看 end state 不看過程 ——官方原句："Instead of judging whether the agent followed a specific process, evaluate whether it achieved the correct final state."
約束三件套（#5）：tools / context / system prompt
約束面 規格 考點鑰匙 Tool 限制 tools = allowlist，省略 = 繼承全部 ；disallowedTools = denylist，兩者並存時 denylist 先套用「省略 tools 最安全」= 反向陷阱；唯讀審查 = Read/Grep/Glob Context scoping subagent 是 fresh context ：看不到主對話歷史、已讀檔案；父傳子只有 Agent tool 的 prompt string ；子回父只有 final message（中間過程不回流） 檔案路徑/錯誤訊息/決策要明寫進 prompt ；唯一例外 = fork（繼承整段對話） System prompt 檔案版 = markdown body；SDK = prompt 欄。description 是給協調者決定「何時委派」用的，不是給 subagent 的角色說明 description（何時用它）vs prompt（它是誰）分工——對調 = 經典誘答
Spawn 診斷（#6）：三大失因 checklist
subagent 沒 spawn / 沒被委派，照序檢查：
① 權限面：coordinator 的 allowedTools 含 Agent 嗎？
（SDK：缺了 → 呼叫 fall through 到 canUseTool；dontAsk mode → 直接 deny）
（Task 是 Agent 的舊名，settings 裡寫 Task(...) 仍有效）
② 定義面：AgentDefinition 參數對嗎？
SDK 必填 description + prompt｜檔案版必填 name + description
tools 全部拼錯 → 直接拒絕啟動並回報錯誤（不是無工具啟動）
Python：欄位要 camelCase（disallowedTools）——snake_case 直接 TypeError
③ 佈線面：定義有被載入嗎？描述夠清楚嗎？
新建 agents/ 目錄 → 要重啟 session（最常見原因）
同名優先序：managed > --agents CLI > project > user > plugin；SDK 程式定義蓋過同名檔案
SDK 設了 settingSources: [] → .claude/agents/ 完全不載入
description 太模糊 → Claude 不委派（正解：寫清楚何時用 + "use proactively"）
辨識訊號 ：「定義了卻不委派」→ 先查 allowedTools、再查 prompt 有沒有指名、最後改寫 description（官方 troubleshooting 的順序）；「@-mention 指名」才保證執行，自然語言只是「通常會委派」。
5.2 Session 管理與輸出 schema
Session 三選一（#2）
手段 機制 何時用 Continue --continue：載入當前目錄最近一個 session，不用追 ID單人單線、剛剛才離開 Resume --resume 指定 session ID/name 續同一段對話（state 原封）多 session 場景（每個使用者/任務一條）；跑到 max-turns/budget 上限 → 調高再 resume Fork fork_session / --fork-session（搭配 resume/continue）：複製對話史開新分支 ，原 session 不動同一份前置分析要試多個方向 ——不重跑上游 新 session + summary 開新對話、把結構化 summary（發現/決策/檔案 diff）塞進第一個 prompt——官方："Don't rely on session resume... This is often more robust" prior tool result 已 stale （檔案 ID 全變、資料過期）、跨機器交接
陷阱三連 ：① session 持久化的是對話、不是檔案系統 （官方原句 "Sessions persist the conversation, not the filesystem" ）——fork 出來的 agent 改檔案，所有 session 都看得到；檔案回滾靠 checkpointing。② --session-id 是給新 對話指定 UUID，不是 resume 用的。③ resume 拿到全新空 session 的最常見原因 = cwd 不符 （session 綁工作目錄存放）。
改過檔案後的 targeted re-analysis ：session 進行中檔案被外部改動（隊友 force-push、generator 重跑）→ 告知 agent 哪些檔變了 + 只 re-read 那些檔 ，不重跑整個探索、也不假裝沒事。Claude Code 只在 Edit 時偵測 stale 並報錯，不會自動刷新 context ——「它會自己發現」是假機制。
Subagent 輸出 schema 設計（#18）與 synthesis 不確定性（#19）
三欄輸出 schema ：subagent 回報同時帶 structured data （表格/JSON——給程式彙整）、prose summary （敘事摘要——給 lead 判讀）、citation metadata （claim→source 對應——給引用驗證）。只回 prose = 下游無法機器彙整；只回 structured = 失去判讀脈絡；沒有 source metadata = 引用錯置在 synthesis 才爆 內容型決定呈現 ：財務數據 → 表格；新聞脈絡 → 散文；技術規格 → 結構化清單——schema 按下游用途設計，不是一律 JSONSynthesis 保留不確定性 ：兩個可信來源數字衝突 → 並列呈現 + 標註來源與口徑差異 ，絕不擅自挑一個當事實；資料帶時間 metadata （發布/採集日期）——2022 vs 2026 的數字是時序變化，不是矛盾；區分 well-established（多源一致）vs contested（來源衝突），confidence 分級寫進輸出
陷阱 ：「讓 synthesis agent 挑最可信的那個值」= 把衝突塌縮成單一自信陳述，正是 objective 點名的反模式。正解永遠是「並陳 + 標註 + 讓讀者看得到分歧」。
5.3 Batch API 與 review pass 設計
同步 vs 非同步（#23）
Messages API（同步） Message Batches API（非同步） 延遲 秒級回應 多數 <1 小時，上限 24 小時 、無 latency SLA 成本 標準價 50% 折扣 適用 阻塞流程 （pre-merge check、互動）非阻塞、可容忍延遲 （隔夜報告、週 audit、大量回填）機制 request/response custom_id 對應請求與結果；結果順序不保證 ；部分失敗只重送失敗項 （單一 request 失敗不影響其他）；不支援單一請求內 multi-turn tool calling、不支援 stream: true規模/保留 — 上限 100,000 requests 或 256 MB （先到為準）；結果保留 29 天 （從 created_at 起算）；過期未完成項標 expired、不計費 、需重送；追蹤靠輪詢或 Console
陷阱 ：「batch 比較便宜所以全部改 batch」——擋 merge 的檢查走 batch = PR 卡 24 小時。選型鑰匙是阻塞行為 ，不是成本。反向：「結果照提交順序回來」= 官方明文否定的迷思，對應要靠 custom_id。
Review pass 拆分（#24）
按 concern 拆 ：security / business logic / API design 各開一個 focused pass，各配自己的 few-shot 範例 ——單一 prompt 塞多個 concern 會互相競爭 recall（顧了 security 漏了 logic）按範圍拆 ：per-file local pass + cross-file integration pass（防 attention dilution）獨立 instance review ：模型 review 自己剛生成的 code 較差（保留生成時的推理 context）——開乾淨 context 的獨立 instance
準則邊界與 extraction 一致性（#31、#29）
明確 inclusion/exclusion 準則 > 模糊指令 ：「只在宣稱行為與實際 code 牴觸時 flag」勝過「檢查註解正確」；"be conservative" 這類通用語沒有效果 某類 finding false-positive 率極高（如 90%）→ 暫時停用該類別 保全整體信任，之後用 few-shot 校準再開回來——不是調 prompt 語氣
模糊邊界 → 4–6 個 targeted few-shot ，示範 flag / no-flag 與「為什麼」——few-shot 是最有效的一致性工具
Format normalization 指示 （#29）：多格式文件（日期三種寫法、金額含幣別符號）→ 在 prompt 明訂正規化規則（ISO 8601、去符號十進位），配 few-shot 示範模糊 case——降幻覺三件套 = optional schema + normalization 指示 + few-shot
5.4 MCP 與 built-in tools 補遺
Skill 隔離與工具限制（#14）
context: fork（SKILL.md frontmatter）：skill 在隔離的 subagent context 執行——冗長中間輸出不污染主對話 session state。工具語意最容易考反 ：allowed-tools 是「授權免確認」（grants permission... It does not restrict which tools are available ）；要限制 用 disallowed-tools（把工具移出可用池），或 fork + 唯讀 agent type（agent: Explore）。
Built-in tools 選型（#32）
工具 本質 用在 Grep 搜檔案內容 （regex） 「誰定義/呼叫 X」「error 字串在哪」——找寫在檔案裡的東西 Glob 配檔名/路徑 pattern（**/*.test.ts），永不看內文 「某類檔案在哪」 Read 讀已定位的檔 Grep/Glob 找到後讀內容 Bash 跑指令 git log、跑測試——不是 拿來 cat 全部檔案搜內容 Edit / Write Edit 精準改（唯一 anchor）；找不到唯一 anchor → Read + Write 整檔 fallback 目標字串出現多次 → fallback
MCP resources vs tools（#34）
Tools Resources Prompts 控制者 Model （模型自己決定何時呼叫）Application （application-driven：host/使用者決定何時注入）User 性質 可執行動作（寫 DB、呼叫 API、改檔） 被動、唯讀 context （檔案內容、DB schema、文件）指令模板 識別 name URI （resources/list 列目錄、resources/read 取內容；支援參數化 template）name
設計判準 ：跨系統查詢的「內容目錄型資料」（issue 清單、DB schema、文件層級）→ 曝露為 resources 讓 client 直接列出/注入，省掉模型連環 tool call 摸索；會寫入/觸發動作的才做 tool。Claude Code 引用：@server:protocol://resource/path（如 @github:issue://123），引用後自動抓取當 attachment。
Tool description 寫作（#36）
Description 是選 tool 表現的最重要因素 （官方："by far the most important factor"）。四要素：做什麼／何時該用（與不該用）／每個參數的意義／caveats 與限制 ；至少 3–4 句 ，複雜工具更長邊界句防 misrouting ：官方好範例明寫 "It will not provide any other information about the stock or company" ——明說「不做什麼」，相似工具才分得開消歧三板斧 ：① namespacing（asana_search vs jira_search；按 resource 再細分 asana_projects_search）② 相關操作合併 成單一 tool + action 參數（"Fewer, more capable tools reduce selection ambiguity"）③ 每個 tool 一個清楚、不重疊的用途參數名去歧義：user → user_id；心法：「像對新進同事介紹這個工具一樣寫」
量化門檻 ：工具超過 30–50 個 ，選擇準確度開始退化——「更多工具 ≠ 更好」；response 設計 pagination/filtering/truncation，只回高訊號欄位
陷阱 ：「description 寫短一點省 token」——官方立場相反（詳細描述是第一優先）；token 要省在 response 內容 和工具數量 。「用 input_examples 解決選錯工具」也錯位：examples 示範「怎麼填參數」，「何時用這個工具」永遠靠 description。
5.5 Tool 錯誤回應設計
結構化錯誤三件套：isError flag ＋ 錯誤分類 （如 errorCategory）＋ 可否重試 （如 isRetryable）＋ 人類可讀說明。絕不回統一的 "Operation failed" ——agent 拿到通用錯誤字串就無法決定「重試、修輸入、還是換路徑」。註：errorCategory/isRetryable 是設計 pattern 的自訂欄位，MCP spec 本身只定義 isError。
錯誤類別 例子 Agent 該做的事 Transient timeout、上游暫時掛掉 可 retry （isRetryable: true）Validation 輸入格式錯、缺參數 修正輸入再試——原樣 retry 沒有用 Business 政策違反（發票總額不符、超退款上限） 絕不 retry ——永遠會失敗，走專屬處理路徑/升級Permission 憑證過期、權限不足 升級處理；絕不能偽裝成空結果
空結果 vs 存取失敗（必考分界） ：「查詢成功但沒有 match」是合法結果 ，「存取失敗」是錯誤——兩者都回空陣列 = agent 把合法空結果無限 retry、把憑證失效當「查無資料」寫進報告（silent swallow）。正解：response 結構區分兩者，coordinator 把存取失敗記為 coverage gap 而不是 finding錯誤傳播 （multi-agent）：subagent 失敗要回結構化 error context ——failure type、attempted query、partial results、建議替代方案——讓 coordinator 能智慧復原。三大反模式：通用 error status 藏掉 context／無聲吞錯（空結果當成功）／單一失敗就終止整個 workflow
討論題（讀書會 session 用）
「research the semiconductor shortage」這個委派指令問題在哪？把它改寫成合格的四件套版本。
你的 subagent 定義了卻從來沒被委派過——照 5.1 的三面 checklist 走一遍，每一步你會檢查哪個檔案/參數？
兩個可信來源對同一數字給出不同值——synthesis agent 的正確輸出長什麼樣？為什麼「挑一個」是反模式？
你們公司哪些內部查核適合搬去 Batch API？哪些絕對不行？判準一句話。
挑一個你實際用過的 MCP server：它的 tool description 有沒有寫「何時不該用我」？resources 和 tools 的分工合理嗎？