Agent Team 多輪迭代：從失敗到成功的設計演進

Document Status: Living Document (持續更新)
Last Updated: 2026-03-17
Author: Claude Code + Tom
Purpose: 從 SimpleEC OMS 多次失敗的 Agent Team 經驗中提煉最佳實踐

序言：為什麼我們一直失敗

從 2026-03-03 到 2026-03-17，我們嘗試啟動過至少 4 個 Agent Team，每一次都卡住 24+ 小時：

1. simpleec-oms-audit (3/3) — 任務分配錯亂，Agent 互相等待
2. simpleec-oms-bidirectional-audit (3/10) — 複雜的雙向驗證設計，Agent 不知道什麼時候應該停止
3. simpleec-oms-quality-audit (3/16) — Task 被分配給錯誤的 Agent，導致 3 個 Agent 空轉 24 小時

根本原因不在代碼，而在於：

• ❌ 設計太複雜，隱式依賴沒有編碼
• ❌ Prompt 寫得不清楚，Agent 不知道什麼時候應該停止或等待
• ❌ 沒有 Timeout 機制，導致無限期等待
• ❌ 任務分配邏輯複雜，容易出錯
• ❌ Agent 沒有明確的”停止條件”，導致亂工作或空轉

本文將詳細解析這些問題，並提供可複製的最佳實踐。

我要啟動 Agent Team 做 [你的任務]

系統：[系統名]
檢查維度：[A], [B], [C]
時間：[時間限制]
Agent：[N 個]

創建：TEAM_PLAN.md / AGENT_PROMPTS.md / CHECKLIST.md / settings.json

You are ARCHITECT on [TEAM_NAME].

Verify [SYSTEM]:
- [Check A]
- [Check B]

DELIVERABLE (JSON):
{ "task_id": 1, "findings": { "score": X, "ready": true } }

BEGIN PHASE 1 NOW.

第一部分：為什麼 Agent Team 會卡住？

原因 1：複雜的隱式依賴

❌ 壞設計示例：使用 Provider Chain + Consumer Chain 雙向驗證（複雜且失敗）。有 4 個同步點，但都是文字描述，沒有編碼到 Task 系統。Task 之間的依賴關係是隱式的（”Task #1 完成後才能開始 Task #2″，但沒有在 blockedBy 里標記）。Agent 不知道應該等待誰或被誰等待。

後果：當任務分配出錯（比如 Task #2 被分給了錯誤的 Agent），整個鏈條斷裂。Architect 和 Backend-QA 無所事事，空轉 24+ 小時，持續消耗內存。

原因 2：Prompt 寫得不清楚 → Agent 不知道什麼時候該停止

Prompt 缺少明確的停止條件。完成 Task #1 後，Agent 不知道應該做什麼——是否應該主動聯繫其他 Agent？是否應該重新檢查自己的工作？內存會持續增長（因為 Agent 一直在運行）。

實際情況：Architect 完成 Task #1 後，發現沒有 Task #2 和 #3 的結果（因為被分配錯了）。開始懷疑，重新讀一遍所有文件。14 小時後，內存從 380MB 漲到 440MB。最後 OOM → 系統當機。

原因 3：沒有 Timeout 機制

原因 4：Agent 之間沒有同步點

舊設計中，Task #1 在工作，Task #2 也在工作，但 Task #2 應該等待 Task #1。沒人告訴他們應該等待誰。新設計中，用 Task.blockedBy = [1, 2] 明確表示”我要等 Task #1, #2″。

第二部分：好的 Agent Team 設計原則

原則 1：Show, Don’t Tell（編碼依賴，不要寫文字）

為什麼？ Task 系統會自動強制依賴順序，不會分配錯誤。不依賴人工判斷。系統可以自動檢測循環依賴或孤立任務。

原則 2：一個 Agent 做一件事

❌ 壞：Task #2 包含 3 個不同的東西（Schema 驗證、Kafka 驗證、Handler 驗證）。Agent 容易分心，難以判斷什麼時候”完成”。

✅ 好：Task #2 目標清晰：”驗證數據層能否支持 API 承諾”。包含 3 個驗證點，但都是同一件事的一部分。交付物是一個結構化的 JSON 對象。

原則 3：明確的交付物結構

❌ 壞：”Generate audit report with Executive summary, Critical issues list…” 模糊，無法驗證是否合格。

✅ 好：返回結構化 JSON，包含量化指標（alignment score）、布爾標誌（ready_for_next_phase）、具體問題列表。下一個 Agent 可以用 JSON parser 讀取。

原則 4：Prompt 要明確定義”停止條件”

Prompt 必須明確說：完成 Task 後，Agent 應該做什麼（答案是：停止工作，等待通知）。沒有”循環工作”的空間。明確的等待機制（team-lead 會告訴你什麼時候開始下一個 Phase）。

原則 5：Timeout 是必需的

新設計：2 小時 timeout。時間到了，自動標記 timeout。自動解鎖下一個 Task（即使當前 Task 沒完成）。自動通知 team-lead。防止無限期等待。

第三部分：Prompt 編寫終極檢查清單

A. 責任清晰度（Clarity of Responsibility）

• ✅ 一個 Agent，一件事 — 避免重載式任務設計
• ✅ 目標可測 — 不是”驗證 schema 完整性”，而是”生成 JSON with schema_integrity score”
• ✅ 交付物明確 — 結構化 JSON，而不是自由文本報告

B. 停止條件明確（Clear Stop Conditions）

• ✅ Prompt 明確說什麼時候應該停止 — “After Task #1 is complete, do NOT continue. Wait for team-lead notification.”
• ✅ 沒有”循環工作”的空間 — “After generating findings JSON, stop. Do not re-read files.”
• ✅ 明確的等待機制 — “Wait for team-lead message: ‘Phase 2 begins’”

C. 依賴關係編碼（Dependency Encoding）

• ✅ Task.blockedBy 明確填寫 — "blockedBy": [1] 表示”我等 Task #1″
• ✅ Task.blocks 明確填寫 — "blocks": [3, 4] 表示”我阻擋 Task #3 和 #4″
• ✅ 沒有循環依賴 — Task #1 blocks #2, #2 blocks #3, #3 blocks #1 ← 循環！

D. 超時保護（Timeout Protection）

• ✅ Prompt 中明確提到超時時間 — “You have 2 hours to complete Task #1”
• ✅ 告訴 Agent 超時時會發生什麼 — “If 2 hours pass, next phase will begin regardless”
• ✅ Timeout 不應該導致錯誤，只是解鎖 — 後自動繼續下一階段

E. Agent 之間的協調（Inter-Agent Coordination）

• ✅ 明確說是否應該主動聯繫其他 Agent — “Do NOT contact backend-qa or frontend-qa”
• ✅ 明確說如何接收通知 — “You will receive explicit notification from team-lead when Phase 2 begins”
• ✅ 明確說何時應該報告問題 — “Report them in your findings JSON. Do NOT try to fix them yourself.”

第四部分：Prompt 好與壞的完整對比

❌ 壞 Prompt（導致失敗）

缺少：明確的完成後行為、明確的等待規則、Timeout 時間、停止條件、交付物格式的具體性。

後果：Architect 完成 Task #1 後，發現沒有 Task #2 和 #3 的結果。不知道應該等待還是繼續工作。開始懷疑自己的分析，重新讀文件。持續讀文件和重新分析 14+ 小時。內存從 380MB 漲到 440MB。最後 OOM，系統當機。

✅ 好 Prompt（成功設計）

特點：明確的時間表（0-2h Phase 1, 2-4h 等待, 4-6h Phase 4）。明確的停止條件（”完成後停止，不要做任何其他事”）。明確的交付物（結構化 JSON）。明確的等待機制（team-lead 會告訴你什麼時候開始 Phase 4）。明確的禁止行為（❌ 列出了不應該做的事）。

後果：Architect 完成 Task #1。知道自己應該停止（Prompt 明確說了）。進入等待模式（不讀文件，不重新分析）。2 小時後，如果沒有 Task #4 通知，自動 timeout。內存穩定在 380MB（沒有持續增長）。系統正常運行。

第五部分：常見錯誤與修正

錯誤 1：Prompt 寫得太長和太複雜

修正：用清晰的結構（Markdown headers）。用列表而不是段落。用例子而不是抽象描述。用”禁止行為”而不是”允許行為”。目標：500 字清晰 Prompt，而不是 2000 字複雜 Prompt。

錯誤 2：隱式假設 Agent 會自己推斷

❌ 壞：”After Task #1, you will know when to start Task #2″（Agent 怎麼知道？沒人告訴他！）

✅ 好：”After Task #1, wait for team-lead message: ‘Task #2 begins’. Only then should you proceed.”

錯誤 3：交付物格式模糊

❌ 壞：”Generate a report with findings”

✅ 好：生成 JSON，具有明確的字段結構 (status, findings, critical_issues 等)

錯誤 4：沒有明確的超時時間

✅ 修正：Timeout: 2 hours — If 2 hours pass, your task is automatically marked timeout. Next phase will proceed regardless. You will be notified when your timeout occurs.

第六部分：Agent Team 設計檢查清單

Pre-Launch Checklist

系統狀態：內存充足 (>8GB available)。沒有舊的 Agent Team 在運行。Task 目錄是空的。

Task 設計：每個 Task 有明確的 id, subject, description。每個 Task 的 blockedBy 和 blocks 已填寫（沒有循環依賴）。沒有孤立的 Task。每個 Task 有 2 小時的隱式 timeout。

Prompt 設計：每個 Agent 的 Prompt 有明確的責任（一件事）。每個 Prompt 有明確的停止條件。每個 Prompt 有具體的交付物格式（JSON）。每個 Prompt 有明確的等待機制。每個 Prompt 禁止了不應該做的事情（❌ 列表）。

交付物定義：所有交付物都是結構化的（JSON）。每個交付物都有 status 字段。下一個 Agent 能解析上一個 Agent 的交付物。交付物不應該是自由文本，應該是結構化數據。

同步機制：有明確的”team-lead”角色負責協調。有明確的通知機制。有明確的失敗恢復流程。沒有 Agent 之間的直接通信（都通過 team-lead）。

Launch Checklist

監控：每 30 分鐘檢查一次內存使用。監控是否有 Agent 卡住。準備好 2 小時後手動檢查 timeout 機制。

信號：知道什麼樣的行為表示”卡住”（讀同一個文件超過 1 小時，內存持續增長 10% 以上，沒有進展 30 分鐘以上）。準備好應急措施（2 分鐘內關掉所有 Agent，清理內存，回滾到之前的狀態）。

第七部分：迭代和改進

本文將根據實驗結果進行迭代。每當我們啟動新的 Agent Team 時：

1. 記錄過程 — 啟動時間、Agent 行為、完成時間、內存使用、任何卡住或異常情況
2. 在本文中更新 — 如果發現新的問題、更好的 Prompt 寫法、或 Timeout 時間不合適的情況
3. 版本控制 — 每次大的更新，提升版本號。在文件頂部記錄更新日期和內容

總結

從失敗中學到的核心真理：

1. 設計要簡單，依賴要明確 — 不要用複雜的 Provider Chain，用簡單的 Sequential Phase
2. 編碼依賴，不要寫文字 — blockedBy 和 blocks 必須填寫，隱式依賴是毒藥
3. Prompt 要明確停止條件 — Agent 必須知道什麼時候應該停止
4. Timeout 是必需的保險 — 沒有 timeout，Agent 可以無限期卡住
5. 交付物要結構化 — JSON 而不是自由文本，下一個 Agent 能解析
6. 有一個協調者（team-lead） — 不要讓 Agent 之間直接通信

下一步：用 v2 設計啟動 Quality Audit Team。記錄過程和結果。根據結果更新本文。建立標準範本（Task 和 Prompt 的 template）。

實施深度：v3 計畫的四層架構

前面的原則是設計哲學。但實際部署 v3 計畫時，我們加入了四項關鍵實施細節，把抽象的原則轉換為可監控、可恢復、可自動化的運作。

①分層監控架構（Team-lead 的心跳）

v3 計畫引入了 Team-lead 監控層，專職於此，间隔嚴格：30秒 Session 健康檢查、30分鐘超時檢查、60分鐘進度報告、5分鐘內存監控。

②事件驅動協調（4 個事件）

v3 計畫改為事件驅動模型，完全由 Team-lead 控制狀態轉遷。4個事件：Task#1完成→解鎖Task#2&3、Task#2&3都完成→通知Architect進行Task#4、Task#4完成→生成報告。

③應急與恢復（5 個故障模式）

v3 計畫為5種情況預先定義恢復策略：Orphaned Agents(中止審計)、Multiple Timeouts(部分報告)、Invalid JSON(記錄錯誤繼續)、OOM Event(強制超時解鎖)、Stalled Task(檢測重啟或強制超時)。

④完整實現範例

完整的Task生命週期：t=0初始化、t=0-30分鐘Architect驗證、t=25觸發Event1解鎖Task#2&3、t=25-50並行執行QA驗證、t=50觸發Event2&3通知Architect、t=50-110Task#4最終驗證、t=115報告生成完成。總耗時115分鐘，4個Agent共消耗1.8GB內存。

v3 計畫 vs v2：7 個關鍵改進

依賴編碼從文字敘述改為JSON(blockedBy/blocks)、停止條件從暗示改為明確、超時機制從提到改為實現(120min+30min+自動unlock)、監控從無改為Team-lead 30秒心跳、協調從Agent間通信改為Team-lead主控、交付物從文字改為JSON schema、故障恢復從無預案改為5個策略。

「後即時」監控與自動恢復

v3 計畫的終極目標是達到「後即時(Near Real-Time)監控」：不是等Task失敗才發現，而是任何異常2分鐘內自動檢測並響應。解決之前24小時卡住的問題。