目錄
代理團隊協調
概述
Claude Code 代理團隊能讓多個 Claude CLI 程序透過基於檔案系統的協定協作處理共享工作。每個團隊成員以獨立的 claude 程序在 tmux 窗格中執行，透過由 fcntl 鎖保護的 JSON 檔案進行通訊。無需資料庫、無需守護行程、無需網路層。
此技能提供有效協調代理團隊的範本。
使用時機
- 跨多個檔案或模組的平行實作
- 多代理程式碼審查（一個代理審查，另一個代理實作修正）
- 需要跨子系統協調變更的大型重構
- 受益於並行代理的自然平行任務
何時不應使用
- 單一檔案變更或小型任務（開銷超過效益）
- 需要緊密順序推理的任務（代理之間協調鬆散）
- 當無法使用
claudeCLI 或未安裝 tmux 時
先決條件
# 驗證 Claude Code CLI
claude --version
# 驗證 tmux（分割窗格模式需要）
tmux -V
# 啟用實驗性功能（生成器會自動設定）
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
協定架構
~/.claude/
teams/<團隊名稱>/
config.json # 團隊元資料 + 成員名冊
inboxes/
<代理名稱>.json # 每個代理的訊息佇列
.lock # fcntl 獨佔鎖
tasks/<團隊名稱>/
1.json ... N.json # 自動遞增的任務檔案
.lock # fcntl 獨佔鎖
設計原則：
- 檔案系統即資料庫：JSON 檔案，透過
tempfile+os.replace進行原子寫入 - fcntl 鎖定：防止對收件匣和任務的並發讀寫損壞
- 編號任務：使用自動遞增 ID 與連續檔案命名
- 鬆散耦合：代理輪詢自己的收件匣；無推送通知
快速開始
1. 建立團隊
# 程式化團隊設定（透過 MCP 或直接 API）
# 團隊設定寫入至 ~/.claude/teams/<團隊名稱>/config.json
團隊設定包含：
name、description、created_at（毫秒時間戳）lead_agent_id、lead_session_idmembers[]— LeadMember 和 TeammateMember 物件的陣列
2. 生成團隊成員
每個團隊成員都是一個獨立的 claude CLI 程序，並使用身分識別旗標啟動：
claude --agent-id "backend@my-team" \
--agent-name "backend" \
--team-name "my-team" \
--agent-color "#FF6B6B" \
--parent-session-id "$SESSION_ID" \
--agent-type "general-purpose" \
--model sonnet
請參閱 modules/spawning-patterns.md 了解 tmux 窗格管理和顏色指派。
3. 建立具有依賴關係的任務
{
"id": "1",
"subject": "實作 API 端點",
"description": "為使用者管理建立 REST 端點",
"status": "pending",
"owner": null,
"blocks": ["3"],
"blocked_by": [],
"metadata": {}
}
請參閱 modules/task-coordination.md 了解狀態機和依賴管理。
4. 透過訊息進行協調
{
"from": "team-lead",
"text": "API 端點已準備好進行整合測試",
"timestamp": "2026-02-07T22:00:00Z",
"read": false,
"summary": "API 已就緒"
}
請參閱 modules/messaging-protocol.md 了解訊息類型和收件匣操作。
協調工作流程
agent-teams:team-created— 初始化團隊設定和目錄agent-teams:teammates-spawned— 在 tmux 窗格中啟動代理agent-teams:tasks-assigned— 建立具有依賴關係的任務，指派擁有者agent-teams:coordination-active— 代理認領任務、交換訊息、標記完成agent-teams:team-shutdown— 透過核准協定優雅關閉
團隊角色
每個團隊成員都有一個 role，決定其能力和任務相容性。定義了五種角色：implementer（實作者，預設）、researcher（研究員）、tester（測試員）、reviewer（審查員）和 architect（架構師）。角色限制了代理可以處理的風險等級 — 請參閱 modules/crew-roles.md 了解完整能力矩陣和角色風險相容性表格。
健康監控
團隊成員的健康狀況可透過心跳訊息和認領到期進行監控。負責人每 60 秒輪詢團隊健康狀態，採用 2 階段停滯檢測協定（health_check 探測 + 30 秒等待）。停滯代理的任務會被釋放，並按照「替換而非等待」的原則重啟或更換。請參閱 modules/health-monitoring.md 了解完整的協定和狀態機。
模組參考
- team-management.md：團隊生命週期、設定格式、成員管理
- messaging-protocol.md：訊息類型、收件匣操作、鎖定模式
- task-coordination.md：任務 CRUD、狀態機、依賴循環檢測
- spawning-patterns.md：tmux 生成、CLI 旗標、窗格管理
- crew-roles.md：角色分類、能力矩陣、角色風險相容性
- health-monitoring.md：心跳協定、停滯檢測、自動復原
與 Conjure 整合
代理團隊擴展了 conjure 委派模型：
| Conjure 模式 | 代理團隊等效模式 |
|---|---|
delegation-core:task-assessed | agent-teams:team-created |
delegation-core:handoff-planned | agent-teams:tasks-assigned |
delegation-core:results-integrated | agent-teams:team-shutdown |
| 外部 LLM 執行 | 團隊成員代理執行 |
首先使用 Skill(conjure:delegation-core) 來判斷任務是否受益於多代理協調而非單一服務委派。
工作樹隔離替代方案（Claude Code 2.1.49+）
對於修改檔案的平行代理，isolation: worktree 提供了基於檔案系統協調的輕量級替代方案。每個代理在其自己的臨時 git 工作樹中執行，無需 fcntl 鎖定或基於收件匣的衝突避免機制來處理共享檔案。
- 何時偏好工作樹而非代理團隊訊息：代理處理重疊檔案但不需要中執行通訊
- 何時偏好代理團隊訊息：代理需要協調發現或根據彼此的進度調整計畫
- 兩者結合使用：使用代理團隊進行協調，同時為每個團隊成員使用
isolation: worktree以確保檔案系統安全
疑難排解
常見問題
找不到 tmux
透過套件管理器安裝：brew install tmux / apt install tmux
過時的鎖定檔案
如果代理在中途崩潰，鎖定檔案可能會持續存在。手動從 ~/.claude/teams/<團隊>/inboxes/ 或 ~/.claude/tasks/<團隊>/ 中移除 .lock 檔案。
孤兒任務
由崩潰代理認領的任務會無限期保持 in_progress 狀態。使用 modules/health-monitoring.md 進行基於心跳的停滯檢測和自動任務釋放。健康監控協定可在 60 秒 + 30 秒探測視窗內檢測到無回應的代理，並釋放其任務以供重新指派。
訊息順序 檔案系統時間戳解析度各不相同（HFS+ 為 1 秒）。使用編號檔案名稱或 UUID 排序名稱，以避免在快速訊息突發時發生衝突。
Bedrock/Vertex/Foundry 上的模型錯誤（2.1.39 之前版本） 團隊成員代理可能在企業供應商上使用錯誤的模型識別碼，導致 400 錯誤。請升級至 Claude Code 2.1.39+ 以在所有供應商上獲得正確的模型 ID 限定。
巢狀會話防護（2.1.39+）
如果 claude 拒絕在現有會話內啟動，請確保您使用的是 tmux 窗格分割（而非子 shell 調用）。此防護是有意的 — 請參閱 modules/spawning-patterns.md 了解詳細資訊。
完成條件
- 已建立團隊，包含設定和目錄
- 團隊成員已生成並在設定中註冊
- 已建立任務，包含依賴關係圖（無循環）
- 代理正在透過收件匣訊息進行協調
- 已完成優雅關閉