Skip to content

Claude Code Agent Teams 怎麼用?從 GitHub 6,400+ 個 agent 看設計模式

2026年4月4日 1 分鐘
TL;DR GitHub 上已有 6,400+ 個 .claude/agents/*.md 檔案。我們拆解了 4 個代表性專案——ChemistryTimes(內容生產 pipeline)、claude-sub-agent(document-driven 開發流水線)、agentic(Temporal.io DAG 平行執行)、vs-copilot-multi-agent(Hook 強制記憶寫入)——加上 ruflo 的企業級 swarm 架構,歸納出 6 種設計模式和 5 個實戰趨勢。

GitHub 上目前有超過 6,400 個 .claude/agents/*.md 檔案。Claude Code 的 multi-agent 生態系正在快速成長,但多數人還停留在「裝一堆 subagent 然後隨便用」的階段。

這篇拆解 5 個代表性專案,看它們怎麼設計 agent pipeline、怎麼管 context、怎麼保證品質——然後歸納出可複用的設計模式。

案例一:ChemistryTimes — 10 Agent 的虛擬編輯部

專案chemistrywow31/chemistry-times 用途:每天 08:30 自動發刊的雙語(繁中+英文)內部電子報 技術:Go + Gin + MongoDB + Docker Compose Agent 數:基礎版 10 / 英文學習版 14 模式:Orchestrator-led sequential pipeline + 部分平行

架構

.claude/agents/
├── editor-in-chief.md          # 總編輯(orchestrator, sonnet)
├── journalism/
│   ├── digital-journalist.md   # 數位記者
│   └── data-auditor.md         # 查核員
├── analysis/
│   ├── tech-analyst.md         # 科技分析師
│   ├── marketing-analyst.md    # 行銷分析師
│   └── online-english-education-analyst.md
├── writing/
│   ├── chinese-daily-writer.md # 中文寫手
│   └── english-daily-writer.md # 英文寫手
├── production/
│   └── html-daily-producer.md  # HTML 製作人
└── review/
    ├── code-reviewer.md        # 程式碼審查
    └── process-reviewer.md     # 流程審查

Pipeline

六階段,Phase 4 是唯一的平行段:

選題 → 採訪 → 事實查核 → 分析+撰稿(平行) → HTML製作 → 審查+發佈

總編輯透過 Task tool 調度所有 agent,跑在單一 Claude Code session 的 subagent mode。不允許橫向委派,不允許建立 sub-coordinator——純星狀拓撲。

最大亮點:Context 管理紀律

這是所有案例中 context 管理做得最嚴格的:

  • 500 字摘要上限:subagent 回報結果不超過 500 字
  • Workspace offloading:超過 200 字的原始資料寫入 workspace/ 檔案
  • Worklog 系統:每個 phase 留下 references.md / findings.md / decisions.md 三份文件
  • 狀態格式DONE / DONE_WITH_CONCERNS / BLOCKED / NEEDS_CONTEXT
  • 來源標記:每個 agent 聲明輸入來源和輸出位置

品質閘門

3 道(英文學習版 4 道),任一失敗 pipeline 停止:

Gate負責人驗證內容
事實查核Data Auditor資料正確性、來源可信度
程式碼審查Code ReviewerHTML/CSS/JS 正確性
最終核准Editor-in-Chief編輯一致性、主題平衡

降級策略

Phase 4 產出不到 3 篇 → 縮小範圍或跳過英文版。這在其他專案極少見。

英文學習版(14 Agents)

基礎版擴展為 10 階段 pipeline,新增翻譯、文法分析(CEFR B1-B2)、TTS 語音(OpenAI API)、教育品質審查。Phase 6 是串流觸發——英文內容完成即啟動教育 pipeline,不等中文版。

設計決策

  • Orchestrator 用 sonnet 而非 opus:成本考量,coordinator 不需要最強生成能力
  • 中英文寫手同步獨立寫作:不是先寫一種再翻譯,避免品質損失
  • Skills 跟 Agents 分離:6 個 skills(daily-production-pipelinefact-checking-framework 等)作為共用 SOP,agent 按需呼叫

案例二:claude-sub-agent — Document-driven 開發流水線

專案zhsama/claude-sub-agent 用途:把專案想法變成 production-ready 程式碼的自動化開發流水線 Agent 數:8 個核心 + 4 個專家 模式:三階段 sequential pipeline,document-driven handoff

架構

agents/spec-agents/
├── spec-orchestrator.md    # 工作流協調(不直接調度 agent)
├── spec-analyst.md         # 需求分析師
├── spec-architect.md       # 系統架構師
├── spec-planner.md         # 實作規劃師
├── spec-developer.md       # 全端開發者
├── spec-tester.md          # 測試專家
├── spec-reviewer.md        # 程式碼審查
└── spec-validator.md       # 最終驗證

另外還有 4 個領域專家(senior-backend-architectsenior-frontend-architectui-ux-masterrefactor-agent),在特定階段加入。

Pipeline:三階段 + 品質閘門

Phase 1: Planning (20-25%)          Phase 2: Development (60-65%)       Phase 3: Validation (15-20%)
analyst → architect → planner       developer → tester                  reviewer → validator
        ↓                                   ↓                                   ↓
   [Gate: 95% threshold]              [Gate: 80-85%]                    [Gate: 85-95%]

每個閘門失敗會回到對應的上游 agent 重做,最多 3 輪迭代。預期收斂路徑:Round 1 (80-90%) → Round 2 (90-95%) → Round 3 (95%+)。

核心機制:Document Handoff

Agent 之間不直接溝通。每個 agent:

  1. 讀取前一個 agent 產出的文件
  2. 執行自己的專業工作
  3. 寫出結構化文件到檔案系統
  4. 由 slash command 或 orchestrator 路由到下一個

產出的文件包括:requirements.mduser-stories.mdarchitecture.mdapi-spec.md(OpenAPI 3.0)、tasks.md(含依賴矩陣和 Gantt chart)、test-plan.md

工具權限分離

這是最值得注意的設計——不同 agent 有不同的工具存取權:

Agent特有工具意義
developerBash, Edit, MultiEdit唯一能改檔案的 agent
reviewermcp__ESLint__lint-files, mcp__ide__getDiagnostics能跑 linter 和 IDE 診斷
analyst, architectWebFetch能查外部資料
orchestratorTask能發任務但不直接調度 agent

只有 developer 能真正動程式碼。reviewer 能跑 lint 但要改 code 必須回到 developer。這種「最小權限」設計防止了 agent 越界。

跟 ChemistryTimes 比

維度ChemistryTimesclaude-sub-agent
Orchestrator 角色主動調度所有 agent設計工作流但不直接調度
Agent 溝通透過 orchestrator 中轉透過檔案系統 handoff
品質閘門3 道,binary pass/fail3 道,分數制 + 回溯重做
平行執行Phase 4 有平行完全序列
工具隔離未明確限制嚴格的 per-agent 工具權限

案例三:agentic — Temporal.io + DAG 平行執行

專案skmtkytr/agentic 用途:通用任務分解與平行執行引擎 技術:TypeScript + Temporal.io + Claude Agent SDK + Svelte Web UI Agent 數:6 個功能性 agent 模式:DAG-based wave 平行執行 + 雙層 retry

架構

跟前兩個案例不同,agentic 的 agent 不是用 .claude/agents/*.md 定義的角色,而是用 TypeScript 實作的 Temporal Activities

Prompt → Planner → Validator → [Executor ×N ‖ Reviewer ×N] → Integrator → Integration Reviewer → 結果

整個 pipeline 是一個 Temporal Workflow,每個 agent 是一個 Activity。

6 個 Agent

Agent職責關鍵機制
Planner把自然語言 prompt 分解為 DAGZod schema 強制結構化輸出,LLM 生成的 ID 替換為 crypto.randomUUID()
Validator驗證 DAG 正確性檢查循環依賴、懸空引用、任務模糊度。致命錯誤直接終止 workflow
Executor執行單一任務注入已完成任務的結果作為 context,可選工具(Read/Write/Bash/WebFetch 等)
Reviewer審查單一任務的輸出三種結果:pass / pass+修訂 / fail(觸發重試)。會驗證工具是否真的被使用
Integrator合併所有任務結果大結果從檔案讀取(context 管理),產出寫入 _integrated/response.md
Integration Reviewer最終品質評分5 維度 1-5 分(完整性、正確性、結構、實用性、整體),overall ≥ 4 才通過

核心機制:Wave-based DAG 執行

executeDag() 函數實作波次平行執行:

  1. 每輪找出所有依賴已滿足的任務
  2. 限制到 maxParallelTasks(預設 3)
  3. Promise.all() 平行執行
  4. 死鎖偵測:如果沒有任務 ready 但還有未完成的,拋出 PlanCircularDependencyError

每個任務在一個波次內走 Executor → Reviewer 迴圈。失敗的任務帶著 reviewer 的 feedback 重試。

雙層 Retry

第一層:Task-level Reviewer 拒絕 → feedback 注入任務描述 → Executor 重試(maxTaskRetries 次)

第二層:Pipeline-level Integration Reviewer 拒絕 → 整個 pipeline 從 Planner 重來,帶上失敗原因。所有狀態歸零。(maxPipelineRetries 次)

Context 管理

  • 大結果寫檔os.tmpdir()/agentic/{workflowId}/{taskId}/result.md,傳 file path 而非 inline
  • Reviewer 讀檔:如果結果是檔案,Reviewer 拿到 Read tool 去讀,不走 inline
  • 截斷保護:Integration Reviewer 的 inline 上限 15,000 字元,工具證據上限 10 筆
  • 工具輸出截斷:evidence 中的工具輸出限 500 字元,reviewer 限 200 字元

Temporal.io 的價值

用 Temporal.io 帶來幾個前兩個案例沒有的能力:

  • 持久化狀態:workflow 狀態自動持久化,crash 後可恢復
  • Signal/Query:外部可發 cancelSignal 取消,可查 statusQuery 取得即時狀態
  • Retry policy:10 秒初始間隔、指數退避、最多 3 次、auth 錯誤不重試
  • Worker 配置:最多 10 個平行 activity、20 個平行 workflow

跟前兩個案例比

維度ChemistryTimesclaude-sub-agentagentic
Agent 定義.md 角色檔.md 角色檔TypeScript Activities
執行模式單一 sessionSlash command 串接Temporal Workflow
平行執行部分平行完全序列DAG wave 平行
Retry最多 3 輪回溯雙層(task + pipeline)
狀態持久化Temporal 自動持久化
品質評分Binary分數制5 維度 1-5 分

案例四:vs-copilot-multi-agent — Hook 強制記憶寫入

專案ethansadism/vs-copilot-multi-agent 用途:跨平台(Claude Code + VS Code Copilot)的多 agent 開發框架 Agent 數:4(PM + 3 Specialist) 模式:PM coordinator + 強制知識持久化

架構

跟其他案例最大的差異:這個專案的核心不是 pipeline 設計,而是記憶管理

PM (Opus) ─── 調度 ──→ Crawler Expert (Sonnet)
              │         Database Expert (Sonnet)
              │         Frontend Engineer (Sonnet)

              └── 管理 ──→ contracts/(跨 agent 介面合約)
                           memory-kb/(知識庫)

PM 是唯一的 coordinator(disable-model-invocation: true,其他 agent 不能呼叫 PM)。三個 Specialist 各自負責爬蟲、資料庫、前端。

核心創新:「不寫記憶 = 任務未完成」

記憶寫入在三個層級強制執行:

Level 1:Agent 定義規則 每個 specialist 的 .md 裡明確寫著:「Stop hook 會檢查記憶是否更新;未更新則封鎖(無法完成任務)。不記錄 = 任務未完成。」

Level 2:SubagentStop Hook subagent-memory-check.sh 在 agent 嘗試結束時:

  1. 讀取 agent 啟動時寫的 timestamp 檔
  2. 掃描 memory-kb/<agent>/ 下的 .md 檔是否有比啟動時間更新的
  3. 如果沒有任何更新的檔案exit 2(block),強制 agent 回去寫記憶

Level 3:Session Stop Hook 整個 session 結束時,檢查 project-overview.md 是否在最近 10 分鐘內被更新。沒有就提醒。

Contracts 系統:跨 Agent 介面合約

當任務涉及 2+ agent 共享介面時(API endpoint、DB schema、WebSocket event),PM 必須先在 contracts/ 寫合約再派任務:

# mta_demo4 Interface Contracts
## API Contracts
### GET /api/stocks
- response_field :: price (float)
- producer :: database
- consumer :: frontend
## DB Schema Contracts
### stock_prices
- column :: ticker (varchar, unique)

PM 派任務時帶上合約的 permalink。任務完成後 PM 交叉驗證欄位名稱——不一致就退回修改。

validate-write-note.sh Hook 還會驗證合約的 tag 格式(必須有 type:contract + app: tag),格式不對直接 block。

8 個 Hook 的完整系統

Hook用途
SessionStart模式選擇(一般 / PM),載入活躍 topic
UserPromptSubmit審計日誌 + 關鍵字偵測(「筆記」「儲存」觸發 topic 存檔)
SubagentStart記錄啟動時間、列出既有知識、列出共享合約
PostToolUse審計每一次工具呼叫
PreCompactcontext 壓縮前自動儲存 session 活動到 conversations/
Stop檢查 project-overview 是否更新
PreToolUse驗證 write_note 的 tag 合規性
SubagentStop強制記憶寫入檢查

[[Note Title]] 語法建立雙向連結,用 key :: value 語法建立可查詢的知識原子:

## Observations
- app :: mta_demo3
- problem_id :: CRAWLER-001
- root_cause :: TWSE API requires TLS 1.2

## Relations
- relates_to [[Crawler Best Practices]]

Basic Memory MCP 提供語義搜尋(search_notes)和圖譜遍歷。所有記憶不進 git——「每個人擁有自己的記憶庫」。

PreCompact:Context 壓縮前的自動存檔

這是最巧妙的 hook——在 Claude Code 做 context compaction 之前:

  1. 自動把 session 活動存到 conversations/ 作為 markdown note
  2. 提取最近的 hook events、修改過的 notes、git diff
  3. 注入專案摘要 + 知識庫統計到壓縮後的 context

這創造了一個即使 context window 被壓縮也能存活的恢復點

跟其他案例比

維度ChemistryTimesclaude-sub-agentagenticvs-copilot
記憶持久化Worklog 檔案文件 handofftmpdir 檔案MCP 語義搜尋 + Hook 強制
跨 session 知識Wiki-links 知識圖譜
Agent 介面Orchestrator 中轉文件Workflow 函數Contracts 合約
Hook 使用8 個 Hook 全覆蓋

案例五:Ruflo — 企業級 Swarm + RL 路由

專案ruvnet/ruflo(29.6k stars) 用途:企業級 AI agent 編排平台 技術:TypeScript monorepo(10 packages),v3.0.0-alpha.1 Agent 數:預設 15,支援 100+ 模式:Queen-led hierarchical-mesh swarm + 強化學習路由

架構

Ruflo 跟前四個案例完全不同——它不是「幾個 agent 串起來」,而是一個分散式系統模擬框架

預設 15 agent 分佈在 6 個領域:

Layer 0:  agent-1 (Queen Coordinator)
Layer 1:  agent-2~4 (Security) | agent-5~9 (Core) | agent-10~12 (Integration)
Layer 2:  agent-13 (Test) | agent-14 (Perf) | agent-15 (Release)

支援 4 種拓撲:

拓撲通訊方式適用規模
Hierarchical-Mesh(預設)Queen + 域內 mesh100+ agent
Mesh全連接 peer-to-peer~20 agent
Hierarchical嚴格樹狀100+ agent
Centralized單一 hub~50 agent

Queen Coordinator

整合三種職能在一個類別裡(~2,025 行):

  • Strategic:任務分析、複雜度評分、耗時估算、pattern matching(< 50ms)
  • Tactical:agent 能力評分、主/備 agent 指派、執行策略選擇(< 20ms)
  • Adaptive:學習整合、健康監控、瓶頸偵測(< 30ms)

共識機制

三種分散式共識演算法的 in-process 模擬:

Raft:選舉超時 150-300ms 隨機化、50ms 心跳、多數決 commit。標準教科書實作,但 peers 是 Map 物件不是網路連線。

Byzantine (PBFT):四階段(pre-prepare → prepare → commit → reply),容忍 f ≤ ⌊(n-1)/3⌋ 個故障節點。

Gossip:每 100ms 隨機選 3 個鄰居廣播,TTL 10 hop,90% 參與率才算收斂。

重要的是:這三個都是單 process 模擬,不是真的分散式。適合單機器上的多 agent 協調。

Q-Learning 路由

表格式 Q-Learning 做任務路由:

  • 連續狀態離散化為 10 bins × 8 維度
  • ε-greedy 探索(1.0 → 0.01,10,000 步衰減)
  • Q-table 超過 10,000 狀態時 LRU 淘汰到 80%
  • 單次更新 < 1ms

另外還有 DQN、PPO、A2C、SARSA、Curiosity、Decision Transformer 共 9 種 RL 演算法。

SONA(WASM 快速路徑)

透過 @ruvector/sona(Rust 編譯的 WASM)做 < 0.05ms 的 pattern matching。如果找到高信度匹配(基於過去的 trajectory 學習),可以跳過 LLM 直接路由——這是「簡單任務不用 LLM」的實作方式。

務實評估

值得學的

  • 4 種拓撲模式的抽象(不是所有場景都適合同一種拓撲)
  • RL-based 路由讓系統能從歷史中學習
  • Agent 健康監控 + 自動 failover

需要注意的

  • 所有分散式演算法是 in-process 模擬,不是真正的分散式部署
  • 「100+ agents」是 100+ 邏輯狀態物件,不是 100+ 獨立 process
  • v3.0.0-alpha 狀態,很多功能還在開發中
  • AGENTS.md 明確寫著「claude-flow does NOT execute code」——它是 coordination layer,實際工作還是靠 Claude API

跟其他案例的根本差異

前四個案例是「pipeline」思維——任務從 A 流到 B 流到 C。Ruflo 是「network」思維——任務被路由到最適合的 agent,routing 本身是學習出來的。

維度Pipeline 模式(案例 1-4)Swarm 模式(Ruflo)
適用場景流程固定、步驟明確任務多變、需要動態路由
複雜度低,容易理解和除錯高,需要理解分散式概念
Agent 數量4-1415-100+
學習能力RL-based routing
部署門檻零(純 markdown)高(TypeScript monorepo)

六種設計模式

從 5 個案例和更廣泛的 GitHub 生態系中,可以歸納出 6 種 multi-agent 設計模式:

1. Orchestrator Pipeline

代表:ChemistryTimes 特徵:一個 orchestrator 依序調度專業 agent,星狀拓撲 適合:流程固定、品質要求高的重複性任務(日報、code review、CI/CD) 關鍵設計:orchestrator 不做事只協調,嚴格的角色邊界

2. Document-driven Handoff

代表:claude-sub-agent 特徵:agent 間透過檔案系統交換 artifacts,無直接溝通 適合:多階段開發流程,需要可追溯的中間產物 關鍵設計:per-agent 工具權限隔離,分數制品質閘門 + 回溯重做

3. DAG Wave Execution

代表:agentic 特徵:任務分解為 DAG,波次平行執行,外部 workflow engine 管控 適合:可平行化的複雜任務,需要持久化狀態和 crash recovery 關鍵設計:雙層 retry(task + pipeline),Temporal.io 提供狀態持久化

4. Knowledge-Persistent Coordination

代表:vs-copilot-multi-agent 特徵:Hook 強制記憶寫入,跨 session 知識累積,語義搜尋 適合:長期專案,需要跨 session 累積團隊知識 關鍵設計:SubagentStop hook 封鎖未寫記憶的 agent,contracts 系統做跨 agent 介面管理

5. Hierarchical Swarm

代表:Ruflo 特徵:Queen-led 多拓撲,RL 路由,共識機制 適合:大規模、多領域、需要動態路由的企業場景 關鍵設計:學習式路由取代固定 pipeline,WASM 快速路徑跳過 LLM

6. Parallel Agent Teams(補充)

代表Anthropic C 編譯器 特徵:多個獨立 Claude Code 實例平行工作,共享 task list + mailbox 適合:大型、可分割的程式碼專案 關鍵設計:每個 agent 負責獨立領域減少衝突,16 agent / ~2,000 session / $20K

五個實戰趨勢

1. Model Tiering 是標配

專案OrchestratorWorker
ChemistryTimesSonnet(預設)
vs-copilotOpusSonnet
RufloOpusSonnet/Haiku
claude-sub-agent(未指定)(未指定)

多數專案用高階模型做決策、低階模型做執行。ChemistryTimes 反其道用 sonnet 當 orchestrator 是一個務實的成本選擇——如果 orchestrator 只需要穩定的指令跟隨而非創造性生成,sonnet 就夠了。

2. Context 管理決定成敗

每個案例都發展出自己的 context 管理策略:

策略誰在用
摘要字數上限ChemistryTimes(500 字)
檔案 offloadingChemistryTimes(workspace)、agentic(tmpdir)
截斷保護agentic(inline 15K 字元、工具輸出 500 字元)
PreCompact 自動存檔vs-copilot(context 壓縮前存 note)
Wiki-links 知識圖譜vs-copilot(跨 session 知識累積)

Context window 是 multi-agent 系統的硬天花板。不處理這個問題,agent 越多品質越差。

3. 品質閘門的三種實作

  • Binary(ChemistryTimes):pass/fail,失敗停 pipeline
  • 分數制 + 回溯(claude-sub-agent):低於閾值回到上游重做,最多 3 輪
  • 多維度評分(agentic):5 維度 1-5 分,overall ≥ 4 才通過

沒有哪種一定最好。Binary 簡單可靠,分數制更細緻但需要校準閾值,多維度最完整但增加 LLM 呼叫成本。

4. 記憶持久化是新興戰場

vs-copilot 的 Hook 強制記憶 + Basic Memory MCP 是目前看到最完整的實作。多數專案(包括 ChemistryTimes 和 claude-sub-agent)的知識是 session-scoped 的——session 結束就沒了。

跨 session 知識累積是下一個要解決的問題。方向包括:

  • MCP server(Basic Memory、sqlite)
  • Git-tracked markdown notes
  • 外部 vector database

5. 3-5 個 Agent 是甜蜜點

Agent 數案例觀察
4vs-copilot最精簡,靠 Hook 和 contracts 補強
6agentic功能性分工,剛好
8-12claude-sub-agent涵蓋完整開發週期,偏多
10-14ChemistryTimes用嚴格 context 紀律抵消 overhead
15-100+Ruflo需要 RL 路由才能管理

超過 5 個 agent 後,協調開銷增長快於吞吐量。ChemistryTimes 用 10 個之所以可行,是因為它的 context 管理紀律(500 字上限、workspace offload)讓協調成本可控。Ruflo 用 15+ 個則靠 RL 路由和拓撲管理。

結論:agent 不是越多越好。先用 3-5 個跑通,碰到瓶頸再加,每加一個都要有對應的 context 管理策略。

更多值得探索的專案

專案Stars一句話
VoltAgent/awesome-claude-code-subagents16.2k130+ 即插即用 subagent 目錄
K-Dense-AI/claude-scientific-skills17.3k134 科研 skills,100+ 資料庫
disler/claude-code-hooks-multi-agent-observability1.3kMulti-agent 即時監控 dashboard
cs50victor/claude-code-teams-mcp229Agent teams 協議做成 MCP server
baryhuang/claude-code-by-agents826@mention 路由到本地/遠端實例
lst97/claude-code-sub-agents1.5k33 subagent 智能自動委派

參考資料