Agent Team 實戰（一）：起點——為什麼要建 Agent Team

一句話： 不是 Subagent 不夠用，是 Context 交接成本超過重建成本的那一刻。

四月初連假的某個凌晨兩點，我在 MacBook 上同時開著五個 Claude Code session，每個 session 跑著不同的事，有的在整理一份知識庫的頁面結構，有的在設計一個新 Agent 架構，有的在跑環境遷移腳本，而我在中間切來切去，把這個 session 的產出手動貼到那個 session 的 context 裡，再從那個 session 的回覆中擷取一段貼回另一個 session，像在做一種效率很低的人肉 Rounting。

到了第三次把同一段「我們之前決定了 X、原因是 Y、接下來要做 Z」的脈絡從一個 session 整理到另一個 session 的時候，我停下來了，因為我突然意識到一件事：我不是在用 AI 做事，我是在做 AI Context 搬家工人， 而這個搬運的成本已經漸漸超過讓 session 從頭開始的成本。

之前在寫 Skill vs Subagent 那篇的時候，我提過 Context 的流向決定了你該用 Skill 還是 Subagent，而在 Agent Team 那篇理論篇裡，我也解釋過為什麼當任務需要多個 Agent 互相協作時，hub-and-spoke 的 Subagent 模式會碰到天花板[7]，當我們知道了這些理論、知道了「應該會怎樣」的推演後，我們應該真正來看看「實際上怎樣」這件事。

三個讓我決定動手的原因

Subagent 模式在單一 Session 內很好用，Parent Agent 開一個 Subagent 出去做事，做完帶著結果回來，Context 自然流回 parent，不需要人工介入[7]，但當工作跨越多個 session、多個時間段、甚至多台機器時，會有三個問題開始累積。

第一個是 Context 不持久， 每個 Claude Code session 結束的時候，那個 session 裡累積的所有對話、所有決策脈絡、所有中間產出的理解，會在下一次開 session 的時候全部消失，你需要重新解釋一切給 AI (這也是心法系列提到的 Phase 1 到 Phase 5 裡最根本的挑戰)，如果你一天只開一兩個 session 做簡單的事，這不是問題，但當你同時在推進五六個相互關聯的工作流，每個工作流跨越好幾天的時候，你會發現你花在「讓 AI 理解現況」的時間已經超過了「讓 AI 做事」的時間。

第二個是身份不獨立， Subagent 繼承 parent 的工作目錄和 CLAUDE.md，他不知道自己「是誰」，他只是 parent 的一個臨時分身，做完就消失。這在簡單任務上沒問題，但當你需要一個 Agent 專門負責知識管理，另一個專門負責資產目錄，每個都有自己的工作方法和專業領域的時候，Subagent 的「臨時工」身份就不夠了，你需要的是有固定身份、固定職責、固定工具的「正職員工」，這也是 Multi Agent/Agent Team 的起點。

第三個是跨 session 無法溝通， 如果 Agent A 在某個 session 裡做了一個決策，Agent B 在另一個 session 裡需要知道這個決策，目前常見的辦法是把這個決策從 A 的 session 裡複製出來，再貼進 B 的 session 裡繼續對話，或者記錄成檔案讓 B 來讀取，這就是為什麼 Claude Code 推出 Agent Teams 功能時，設計了一個讓多 session 可以透過 mailbox 互相通訊的機制[10]，但這個功能設計是給「同一個專案裡的多個 worker」使用的，像是三個人一起 review 同一個 PR，而我需要的是「各自有獨立身份和專業的多個 specialist」，每個 Agent 有自己的目錄、自己的 CLAUDE.md、自己的 Skills，這跟 Agent Teams 的設計假設在出發點就不一樣(這個差異在後面的篇章會詳細展開)。

這三個問題加在一起，構成了一個臨界點：繼續用 Subagent 模式的成本，已經超過了重新設計一套協作架構的成本。[8]

HANDOFF.md：第一個產出不是程式碼

決定要建 Agent Team 之後，我做的第一件事不是寫程式，也不是畫架構圖，而是寫了一份 HANDOFF.md。

這份文件的內容很簡單：我是誰、我之前在做什麼、目前進度到哪裡、下一步的計畫是什麼、有哪些已經做過的決策不該被推翻。之所以從這裡開始，是因為我很清楚接下來要發生的事：這是一個多工的 Agent 團隊，要可以跨平台、跨電腦、跨 Repo 工作，我會開好幾個 session，每個 session 負責不同的面向，而每個新的 session 啟動時，他面對的都是一張白紙，沒有之前的記憶，這是 Agent workflow 很常要處理的 Memory 問題。

我寫的 HANDOFF.md 就是解決這個問題的最原始方案，沒有使用任何框架、也不需要任何基礎建設，只需要一份純文字的 MD，寫清楚「目前狀態是什麼」，讓下一個 Agent 讀完就能接手[6]。

實際過程大概是這樣：第一個 session 結束時花了一分鐘，把之前在 Claude Code memory 裡累積的工作目標和規劃寫成一份文件，存到共享的目錄下。第二個 session 啟動時，我給他的第一句話是「讀取 HANDOFF.md，知道我們要幹嘛」，他讀完之後就知道了背景脈絡、知道了已經做過的決策、知道了下一步該做什麼，不需要我再花二十分鐘解釋一遍。

這聽起來很原始，對吧？畢竟現在現在市面上有太多的 Memory Solution，但這正是我後來在整個建構過程中反覆驗證的一件事：Agent Team 的核心不是複雜的通訊協定或精巧的架構設計，而是把「人類腦中的隱含知識」寫成「Agent 能讀懂的明文」， 這件事聽起來簡單，做起來卻比想像中花時間得多，因為你必須把那些你覺得「這不是廢話嗎」的東西也寫下來，之前在 Context Engineering 那篇提過的 JIT loading 原則，在這裡有了完全不同的實踐意義[1]，也因此我決定到後面整個 Agent Team 的框架完善之後才來決定這個 Agent Team 的 Memory 機制，這個時間點，HANDOFF.md 足夠了。

架構不是設計出來的，是長出來的

寫完 HANDOFF.md 之後，下一步並不是開始設計一個完整的 Agent Team 架構：幾個 Agent、分別負責什麼、怎麼溝通、怎麼協調，因為那是理想中的狀況，為了 Operation 而誕生的 Agent Team 應該從 Operation 中產生，所以架構應該是從需求裡一個一個長出來的。

第一個長出來的是 Agent Em，因為我在每個 session 裡都會討論到之前的決策和知識，但這些知識散落在不同的對話紀錄裡，沒有人在系統性地整理它們，所以我需要一個專門負責「把知識結構化」的 Agent，他不做別的事，只做 ingest、query、lint，把原始的對話和文件轉化成可搜尋的 wiki 頁面。

第二個長出來的是 Agent C7，因為隨著 Em 的 wiki 越來越豐富，我開始需要管理 Skills、Commands、MCP Servers 這些可執行的資產，而這些資產需要有人處理目錄、索引、驗證品質、Provisioning，總不能每次都手動複製 Skill 吧？所以我設計了 C7 作為資產管理員。

第三個是 Agent Dm，因為當我需要建新的 Agent 或者處理新專案時，設計和搭建 Agent 或者梳理/管理專案的流程是重複的(讀 wiki 知識、設計架構、建立 scaffold、驗證合規)，這個流程本身就可以被標準化，而 Dm 的三角色分工(Architect 用 Opus 思考設計、Scaffolder 用 Sonnet 執行搭建、Validator 用 Sonnet 驗證合規)就是從這個標準化需求長出來的。

第四個是 Agent G7，因為當 Layer 3 的工作用 Agent 開始增加時，需要有人管理這些 Agent 的註冊、派工、狀態追蹤，而這些事情不該由人類手動做，也不該由其他 Specialist Agent 兼任，因為 fleet management 本身就是一個獨立的職責。

最後是 GM，也就是總管的 Lead Agent，他是這個 Agent Team 最晚成形的，原因很簡單：在前面四個 Agent 都還沒建好之前，GM 的職責一直是我自己在承擔，我就是那個在不同 session 之間切來切去、決定誰該做什麼、把 Context 從這邊搬到那邊的人，GM 的設計本質上是在映射一組基於事實的問題：「我現在手動做的這些協調工作，哪些是可以被系統化的？哪些是可以被自動化的？哪些可以被 Agent 接管？哪些需要人類介入？」

回頭看這個過程，架構最終長成了三層：

• Layer 1（Leader）： GM，唯一的人類接口，負責對話、萃取 insight、協調 Layer 2
• Layer 2（Specialists）： Em、C7、Dm、G7，各自有獨立的身份、目錄、Skills，負責特定領域
• Layer 3（Workers）： 由 Dm 設計、G7 管理的工作用 Agent，負責實際的專案執行

但這個三層不是我在白板上畫出來的，是我在七天的建構過程中，每次碰到「這件事沒有人負責」的時候，一個一個補上去的，那這些架構是建立在什麼之上？程式碼嗎？不，是定義 Agent 規格的文件，這是我們下一篇要說的。

參考資料

[1] Anthropic — Effective Context Engineering for AI Agents https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents

[6] Black Dog Labs — Claude Code Decoded: The Handoff Protocol（handoff 將 10,000+ token 壓縮至 1,000-2,000 token） https://blackdoglabs.io/blog/claude-code-decoded-handoff-protocol

[7] Rick Hightower — Claude Code Subagents and Main-Agent Coordination: A Complete Guide（subagent hub-and-spoke 模型的限制） https://medium.com/@richardhightower/claude-code-subagents-and-main-agent-coordination-a-complete-guide-to-ai-agent-delegation-patterns-a4f88ae8f46c

[8] Towards Data Science — Why Your Multi-Agent System is Failing: Escaping the 17x Error Trap（DeepMind 研究：無結構 “bag of agents” 產生 17.2x 錯誤放大；部分反面：強調需要 upfront architectural planning） https://towardsdatascience.com/why-your-multi-agent-system-is-failing-escaping-the-17x-error-trap-of-the-bag-of-agents/

[10] Claude Code Agent Teams 官方文件 https://code.claude.com/docs/en/agent-teams