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

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

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

到了第三次把同一段「我們之前決定了 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 啟動時，他的 Context 都是一張白紙，沒有之前的記憶，這是 Agentic Flow 很常要處理的 Memory 問題。

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

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

這聽起來很原始，對吧？畢竟現在現在市面上有太多的 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 的架構應該是從需求裡一個一個長出來。

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

Em 之後，其他 Agent 也陸續從需求裡冒出來：C7 是因為 Skill 和 Plugin 越來越多，總不能每次都手動複製，所以我決定我們需要一個資產管理員，Dm 是因為建新 Agent 的流程是重複的(讀知識、設計、搭建、驗證)，而我希望這個流程可以被標準化且復用，G7 是因為工作用跟操作用的 Agent 會隨著 AI 的導入開始增加，如果沒有人統一管理註冊、派工、狀態追蹤，一定會變得混亂，因為 fleet management 本身就應該是一個獨立的職責。

最後才是管理用的 GM，這是這個 Agent Team 最晚成形的 Agent，但他是 Lead Agent，原因很簡單：在前面四個 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