大多數人在嘗試 Multi-Agent 的第一步，做的事情其實是讓多個 AI 輪流對話。每個 Agent 用自然語言描述它的「角色」，然後把自由格式的回應傳給下一個。結果就是：系統跑了一半，某個 Agent 輸出了不對的格式，下一個 Agent 沒有報錯就直接繼續，到最後你根本不知道哪裡壞了。
要建立一套真正能跑的 Claude Code multi-agent 系統，你需要的不是更多 Agent，是更嚴格的合約規格。本篇從 Supervisor 設計開始，完整走過五個開發階段，說明每個 Agent 的輸入輸出規格、自動失敗規則，以及 Claude Code 的設置方式。
如果你對 Claude Code 的基本使用方式還不熟悉，可以先看 Claude Code 的相關介紹，再回來設計這套架構。
為什麼 Multi-Agent 常常跑不起來？
問題不在 Agent 數量，在於每個 Agent 只有描述，沒有明確的合約規格。
一個只有描述的 Agent 長這樣：
「你是市場分析師，負責分析競爭對手並給出建議。」這樣的描述沒有告訴系統：
- 它接收什麼格式的輸入
- 它只能產出哪種格式的輸出(
Output Contract) - 它被允許做哪些操作。
一個有明確合約的 Agent，prompt 裡會定義這三件事，讓系統得以驗證每一次輸出是否符合預期，而不是只能靠「感覺」判斷 Agent 有沒有做對。
有明確合約規格的 Agent，當它輸出了錯誤格式，系統立刻知道要停下來。在沒有合約規格的情況下，錯誤會繼續傳遞，等你發現問題時，已經在第四個 Agent 跑完之後了。
這也是為什麼 Auto-Fail 機制缺失是最常被忽略的設計問題。沒有 schema 驗證，pipeline 就沒有可靠的失敗點，每一次錯誤都會在不知道的階段被忽略。
系統角色設計：Supervisor 和分享幾個我在用的 Agent
整套系統的核心是 Supervisor，但不要把它想成人類 PM。Supervisor 是編曲家 orchestrator，這是我自己給它的名稱，它的工作只有一件事：讀取全域狀態，寫出任務派發文件。
Supervisor 有三個嚴格限制：不寫程式、不分析資料、不修改任何 Agent 的輸出。一旦 Supervisor 開始做這些事，它就從 orchestrator 變成了另一個普通 Agent，整個系統的控制層就消失了。
每一筆任務派發，Supervisor 必須明確指定四件事：
- 這個任務派給誰
- 它接收什麼格式的輸入
- 它必須產出什麼格式的輸出
- 以及如果輸出不符合預期，系統應該做什麼。
除了 Supervisor 外，還有其餘幾個 Agent，每個各有明確的職責邊界，設計多個 Agent 的執行順序時，先畫出資訊依賴圖，哪個 Agent 的輸出是另一個的輸入，這張圖決定了序列化的必要範圍：
- Competitor Analyst — 輸出競品結構化資料
- Market Analyst — 輸出目標族群與風險因子
- Domain Consultant — 驗證可行性，輸出 pass/fail
- Product Strategist — 輸出產品定義 JSON spec
- Designer — 輸出 design token 和 component 定義
- Frontend Engineer — 依規格實作前端程式碼
- Backend Engineer — 定義並實作 API、DB schema
- QA Engineer — 輸出測試計畫和 bug report
每個 Agent 在定義時都需要三個要素：
- input schema（接收什麼格式）
- output schema（輸出什麼格式）
- allowed actions（被允許做哪些操作）。
如果不知道如何定義輸出欄位，可以從「如果這個欄位空白，下一個 Agent 還能正確運作嗎？」來想，如果答案是「不能」，這個欄位就是必填。例如：通常市場分析師在做完競品分析後，一定得把市面上有哪些競品、優劣和SWOT等等，最後不管是產出表格還是報告都是一種輸出格式。
少了任何一個，pipeline 就無法可靠地自動驗證。
Phase 1：Discovery – 三個 Agent 依序跑
這邊因為這三個 Agent 有資訊依賴關係，我讓三個 Agent 依序執行：
這個設計的關鍵在於：Domain Consultant 是一個 validator，不是分析師。Validator Agent 的職責是做出二元判斷，不是提供更多分析，可以讓接下來的決策邏輯保持簡單：拿到 pass 就繼續，拿到 fail 就停止。
每個 pipeline 都需要至少一個這樣的 validator，沒有它，Supervisor 就要自己判斷「這份輸出算好還是不好」，又回到了不可驗證的狀態。
Discovery 階段是最一開始從發現痛點、定義問題的解段，參與這個階段的 agent 有：
- Competitor Analyst
- Market Analyst
- Domain Consultant
Competitor Analyst
Competitor Analyst 的核心問題只有一個：這個市場裡有哪些對手？他們各自的定價、優勢和弱點是什麼？輸出格式必須固定，且每筆競品記錄都要包含相同的欄位，因為 Market Analyst 要程式化地讀取這份資料，不是讓人類閱讀。設計這個 Agent 的輸出格式時，不是我們看不看得懂，而是「下游 Agent 需要讀取哪些欄位才能完成它的任務」。
Market Analyst
Market Analyst 的分析品質取決於 Competitor Analyst 給出的競品資料。
從這裡開始會有上下游關係，Market Analyst 接收前者的輸出（競品資料），加上原始的產品類別定義，然後產出三件事：目標客群是誰、市場上有哪些需求訊號、有哪些風險因子需要提前注意。這三件事必須同時存在於輸出中，缺一不可。
完成後會交給下一位繼續執行。
Domain Consultant
這裡我給了 Domain Consultant 一個明確的限制：如果要開始工作，得需要前面兩份分析結果，才能做出有依據的可行性判斷。
需要注意：平行化會讓下游 Agent 在資訊不完整的狀態下工作，得出的結論不可靠。
Domain Consultant 是這個階段最特別的 Agent，它不產出分析內容，只做一件事：讀取前兩份報告，回答一個 yes/no 問題：這個產品在市場上是否可行？
輸出只有兩個部分：結論（pass 或 fail）和具體理由列表。如果回傳 fail，Supervisor 讀到這份報告後，Discovery 階段整體標記為失敗，不進入 Phase 2。
Phase 2：Product Definition
Product Strategist 的輸出是整個 Claude Code multi-agent 系統的 唯一真相來源（source of truth）。
什麼叫做唯一真相來源？意思是後續所有 Agent：Designer、Backend、Frontend、QA，都必須引用這份文件作為依據，不能自己詮釋需求、不能假設沒寫到的細節。
這份文件的設計原則是：每一個欄位都是必填的，任何一個欄位缺失，pipeline 立即停止。
為什麼這麼嚴格？因為這份 spec 在後續每個階段都會被引用：Designer 依它設計 component，Backend 依它定義 endpoint，QA 依它寫測試案例。如果 feature 沒有驗收標準，QA 無法判斷測試通不通過；如果沒有 success_metrics，完成交付後也無從驗證價值。
設計「唯一真相來源」文件時，方法是列出所有下游 Agent 需要讀取的資訊，把它們全部設為必填欄位。
Phase 3：Design 的嚴格格式要求
Designer 不能只描述 UI，它的輸出必須是機器可讀的結構。因為 Frontend Engineer 在這個系統裡是 Agent 不是人類，沒有辦法閱讀「按鈕應該是藍色、帶有圓角、hover 時有陰影」這樣的自然語言描述，然後把它轉換成精確的實作。
Designer 必須輸出三個結構化文件：
- Design Tokens（定義顏色、間距、字體的具體數值）
- Component Definitions（每個 UI 元件的 props、支援的 states、以及 error_state 的具體樣式）
- Layout Specs（各個頁面的元件排列邏輯）。
其中 error_state 是必填欄位，理由很簡單：Frontend 在處理 API 呼叫失敗、表單驗證錯誤、或資料載入失敗時，需要知道每個 component 在錯誤狀態下應該長什麼樣子。如果這個欄位缺失，Frontend 只能自行發明錯誤樣式，導致整個產品的錯誤狀態呈現不一致。
怎麼判斷哪些 Design 欄位是必填？跟前面一樣，「如果 Frontend Agent 拿到一份缺少這個欄位的 Design 輸出，它能產出正確的程式碼嗎？」不能，就是必填。
Phase 4 Engineering：先定權限，再寫程式
Engineering 階段的核心原則只有一條：權限先行，也就是合約。
Backend Engineer 在寫任何一行程式碼之前，必須先完成三份文件：
- API Endpoints Spec
- DB Schema
- Security Rules
這三份文件不是給人看的參考文件，它們是 Frontend 和 QA 的操作依據，格式必須精確到機器可讀的程度。
API Endpoints Spec 的主要用途在每一個 endpoint 必須定義它的完整 request 格式和 response 格式、是否需要認證、以及 rate limiting 規則。不能用「接收使用者資料，回傳 token」這樣的自然語言描述，這讓 Frontend 必須猜測欄位名稱，而猜錯就是 integration bug。
DB Schema 要定義每張資料表的欄位名稱、型別、是否 nullable、主鍵和外鍵關係。
Security Rules 要定義每個輸入欄位的 validation 規則、哪些 endpoint 需要 auth、rate limiting 設定。這兩份文件同樣不能用自然語言描述，必須是 Frontend 和 QA 可以直接引用的結構。
Frontend Engineer 只能讀取 Backend 已定義的合約規格。這個規則有兩個方向的強制：如果 Frontend 使用了一個 Backend spec 裡沒有的欄位，系統自動標記 fail；如果 Backend 定義了一個 Frontend 從未使用的 endpoint，系統 flag 它，要求說明原因（是設計多餘了，還是 Frontend 遺漏了？）。
這個雙向強制的作用是：讓每一個介面不匹配的問題，在寫程式之前就被發現，而不是在 integration testing 的時候才爆出來。
Phase 5 QA：強制測試清單與 Do-Not-Ship 機制
QA Engineer 的輸出是兩份文件：Test Plan 和 Bug Report。
Test Plan 的設計原則是三類測試缺一不可：
- functional tests（正常流程能不能跑通）
- edge case tests（邊界情況有沒有處理）
- security tests（已知攻擊向量有沒有防禦）
這三類測試覆蓋不同的失敗模式，每個 feature 必須在這三類裡各有至少一個 test case，任何 feature 缺少任意類別，QA 階段整體 fail。
Bug Report 記錄每一個發現的問題：
- severity（嚴重程度）
- affected_feature（影響哪個功能）
- reproduction_steps（重現步驟）
沒有 reproduction_steps 的 bug report 視為無效，Engineering 無法修一個他們不能重現的 bug。
安全測試是強制項目，不是建議。QA Engineer 必須模擬兩類攻擊：SQL injection（所有有資料庫寫入的 endpoint）和 auth bypass（所有 auth_required: true 的 endpoint）。
任何一個攻擊成功，build 立即標記 do_not_ship，回傳 Supervisor，工程階段必須重新執行後才能再次進入 QA。
這個 do_not_ship 機制的設計邏輯是：安全問題沒有「允許帶著 bug 繼續跑」的空間，它是一個對錯機制，通了才能繼續，沒通就必須退回。設計 QA Agent 的輸出格式時，把 do_not_ship 設為一個明確的欄位，而不是藏在 severity 分類裡，這樣 Supervisor 讀到輸出時不需要解讀語義，只需要判斷這個欄位的值。
失敗與重啟：從哪個 Phase 壞掉，就從那裡重來
當某個 Phase 失敗，系統的重啟邏輯很重要，也很容易做錯。
常見的錯誤做法是從 Phase 1 重新開始。如果 QA 在 Phase 5 失敗，重跑 Discovery 是在浪費 token，因為競品分析的結果沒有改變。
另外，我讓 Supervisor 維護一份全域狀態文件，記錄每個 Phase 的最新輸出和狀態（pass/fail/pending）。Supervisor 在每次派發任務前先讀這份狀態，決定從哪裡開始。
Claude Code 設置：CLAUDE.md 和三個資料夾
知道架構怎麼設計之後，來看怎麼在 Claude Code 中實際建起來。
第一步：建立空的 CLAUDE.md
CLAUDE.md 是 Claude Code 讀取全域規則的入口。先建這個檔案，之後所有 Agent 的共用限制都寫在這裡，例如「所有 Agent 輸出必須是 valid JSON」、「Supervisor 不得產出 JSON 以外的任何內容」。
第二步：建立三個資料夾
your-project/
├── CLAUDE.md
├── rules/
│ ├── global-constraints.md
│ └── security-checklist.md
├── agents/
│ ├── supervisor/
│ │ ├── prompt.md
│ │ ├── input-schema.json
│ │ └── output-schema.json
│ ├── competitor-analyst/
│ │ ├── prompt.md
│ │ ├── input-schema.json
│ │ └── output-schema.json
│ └── ... (其他 Agent)
└── skills/
├── generate-api-spec.md
├── run-security-tests.md
└── validate-json-schema.md
rules/存放所有全域限制，所有 Agent 都必須遵守。agents/裡每個 Agent 有獨立資料夾，包含它的 prompt、input schema 和 output schema。skills/存放可重用的函式定義，例如「生成 API spec」「執行安全測試」「驗證 JSON schema」。
最重要的一條規則
Agent 只能呼叫 skills，不能直接呼叫其他 Agent。所有 Agent 間的溝通都透過 Supervisor 的任務派發文件進行。這條規則確保整個系統的控制權始終在 Supervisor 手上，任何繞過 Supervisor 的直接通訊都是架構違規。Anthropic 在 Building effective agents 中也強調這個核心設計原則：orchestrator 和 subagent 職責分離是 multi-agent 系統可靠運行的基礎。
常見問題
Q：如果只有兩三個人的小團隊，這套架構是不是太複雜？
A：Agent 數量可以縮減。Discovery 的三個 Agent 可以合併成一個，Design Agent 可以跳過 token 定義只輸出 component。但 Supervisor 的結構化派發格式和 QA 的強制安全測試，無論團隊大小都不應該省略。
Q：Supervisor 的全域狀態文件要怎麼維護？
A：在 Claude Code 中，最簡單的做法是在專案根目錄建立一份 pipeline-state.json，記錄每個 Phase 的狀態和最新輸出路徑。Supervisor 每次執行前讀取這份文件，結束後更新它。
Q：Phase 4 的 DB schema 要寫多詳細？
A：至少包含每張表的欄位名稱、型別、是否 nullable、主鍵和外鍵關係。不需要是完整的 migration script，但 Frontend 和 QA 必須能從這份文件推斷出所有資料結構。
總結
Multi-Agent 系統難跑，大多數失敗都發生在角色是「描述」而不是「明確的合約規格」，這容易讓每個下游 Agent 都在對一個可能錯誤的輸入繼續工作。
Input schema、output schema、allowed actions，三個要素缺一不可。五個階段的流水線，每個階段都是一道閘，通不過就不往下走。
用這套架構在自己的 Claude Code 專案中建立第一個 CLAUDE.md 和 agents/ 資料夾，從 Supervisor 開始定義，把它的 output schema 鎖死。剩下的包含 agents, skills 都可以慢慢加，很快一個小型團隊就成形了！
