Claude Code Agent Team 協作協定

你會學到什麼

Claude Code agent teams 是實際的 CLI 功能，不是抽象的訊息佇列。Lead session 會建立 teammates、協調共享任務清單並接收訊息。本課聚焦可靠操作需要的協定：

• 明確啟用實驗性 team 功能；
• 每位 teammate 都有不重疊的檔案所有權；
• 共享任務清單是唯一進度來源；
• 完成時必須附驗證證據；
• 範圍完成後確實關閉 teammate。

明確啟用 Agent Teams

此版本仍把 agent teams 標為 experimental。只在需要的程序中啟用：

CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 claude

如果邊界尚未釐清，先以 Plan mode 啟動：

CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 \
  claude --permission-mode plan

先確認檔案所有權與驗收條件，再讓 lead 建立 teammates。

Team Contract

可在 lead prompt 中直接寫：

建立兩位 teammates：一位驗證前端，一位驗證 API。

Frontend owner:
- 只負責 src/components/ 與 browser tests
- 不修改 API 檔案

API owner:
- 只負責 src/api/ 與 API tests
- 不修改前端檔案

每位 teammate 必須：
1. 只領取自己的 task；
2. 回報變更檔案；
3. 執行受影響測試；
4. 把失敗與證據傳給 lead；
5. 不覆寫其他 teammate 的修改。

Claude Code 已提供 task 與 messaging tools，不需要另外發明一套 request_id 協定。

以所有權定義並行邊界

一個可執行任務至少要有：

Owner: api-verifier
Scope: src/api/** 與 tests/api/**
Outcome: endpoint 符合文件 schema
Evidence: pnpm test tests/api 與範例 response

不要讓兩位 teammates 同時擁有相同的可寫檔案。若兩個任務都會修改共享模組，交給 lead，或將兩個任務改成循序執行。

合理拆分：

Task A — 修正 API implementation
Task B — 更新獨立的 browser coverage
Task C — 唯讀審查合併後的 diff

訊息要帶決策與證據

下列事件發生時才需要傳訊息：

• blocker 改變原定計畫；
• 共享介面需要改動；
• 範圍外的測試失敗；
• 任務完成，且已有驗證證據。

完成訊息範例：

API validation completed.
Changed: src/api/session.ts, tests/api/session.test.ts
Verification: 14/14 tests passed
Open issue: none

Lead 仍要負責整合結果、檢查最終 diff，並執行產品層級的完整 gate。

回復與安全收尾

若 teammate 停滯，先檢查共享 task 狀態，只重新指派未完成工作，不要複製整個 team。

全部任務整合後：

1. 要求每位 teammate 停止；
2. 確認沒有進行中的 task；
3. 審查合併 diff；
4. 執行完整測試與 build；
5. 收齊證據後再關閉 lead session。

Teammate 完成不等於產品完成；lead 的最終驗證才是 completion gate。

實作命令

CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 \
  claude --permission-mode plan \
  "規劃雙 owner 稽核：一位負責 CLI reference UI，一位負責 MCP tests。檔案所有權不可重疊，最後回報精確驗證。"

下一課

Session 11 會把協作概念轉成受控的非互動式 CLI 自動化：claude -p、結構化輸出、預算限制與外部排程器。