Claude Code 多代理工程團隊方法論

核心概念

1. Subagents（子代理）的本質：上下文隔離

Subagent 不是讓 Claude 換個語氣說話，而是給任務一個獨立的工作記憶。每個 subagent 有自己的 context window，不會被主代理或其他 subagent 的對話污染。這讓平行任務、大規模批次、或需要「只知道這件事就好」的專門任務得以可靠執行。

關鍵設定欄位（YAML frontmatter）：

description：說明 subagent 的能力，讓主代理知道何時召喚它
tools：allowlist 或 denylist，精確控制這個 agent 能碰什麼
執行模式：foreground（同步、可互動）vs background（非同步）

2. Hooks（鉤子）：流程攔截與品質閘

Hooks 是在特定事件點自動觸發的腳本或動作，不需要等用戶手動確認。常見觸發點包括：工具呼叫前後、特定檔案被修改時、session 結束時。

用途在於：

品質控制：每次修改程式後自動跑 linter 或測試
安全攔截：偵測到危險指令（如 rm -rf）時自動暫停
自動紀錄：每次執行完整任務後自動更新 processing-log 或 changelog

3. 角色設計：工程部門分工模型

my-claude-devteam（鍾均 / NYCU）示範了 12 個 agents 的分工，典型角色包括：

角色	職責	對應概念
Planner	把需求拆解成子任務，分配給各 agent	任務設計者
Fullstack Engineer	主要程式碼撰寫	執行者
Critic	審查輸出品質，回傳問題清單	品質守門
Vuln Verifier	安全漏洞掃描	安全閘
Debugger	專門處理錯誤與修復	修復專家

設計原則：角色越專門，context 越乾淨，輸出越穩定。

4. P7 / P9 / P10 方法論：任務規模決定工作紀律

不同複雜度的任務需要不同層級的流程管控：

層級	適用情境	典型特徵
P7	小型任務、單一功能	單 agent、單輪、快速完成
P9	中型任務、跨模組	主代理 + 1-3 個 subagents，有 review 環節
P10	大型任務、多系統整合	完整工程部門、hooks 全覆蓋、有 Critic 驗收

這個分級的意義不是說哪個比較好，而是讓你根據任務的風險與規模選擇對應的投入成本。

5. Resume 與 Auto-compaction：長任務的持久性

Resume：subagent 被中斷後，可以從最後的狀態繼續，而不是從頭開始
Auto-compaction：當 subagent 的 context 快滿時，系統自動壓縮歷史，保留關鍵狀態向前推進

這兩個機制讓長時間執行的工程任務（如重構整個模組）不再受限於單次 context 長度。

核心框架

何時需要多代理？判斷矩陣

任務有以下特徵 → 考慮 subagents

✅ 有重複性子任務（同一類動作執行 N 次）
✅ 子任務之間可以平行執行（無嚴格前後依賴）
✅ 某個子任務需要不同的工具集（限制 context 污染）
✅ 需要 Critic 或 Reviewer 角色做獨立驗收

任務有以下特徵 → 單一 agent 就夠

❌ 任務線性且步驟前後強依賴
❌ 總任務規模小（< 10 個子項）
❌ 協調成本大於執行成本

Hooks 部署決策

Hook 類型          觸發時機                建議用途
Pre-tool hook    工具呼叫前              危險指令攔截、參數驗證
Post-tool hook   工具呼叫後              自動測試、lint、格式化
Session hook     session 開始/結束時     自動讀取/寫入 handoff message
File hook        特定檔案被修改時        changelog 更新、index 同步

對 FLUX Vault 的應用

FLUX Vault 的批次整理任務（如多篇 raw 入庫、大量 frontmatter 補齊）是 subagents 最有機會帶來效益的場景：

我的觀點

更新：2026-05-22（多代理實測後修訂）

多代理的啟動判斷：任務類型優先，篇數次之——實測後確認，但需要精確化

在 Cowork 中實際並行召喚兩個 Wiki Builder subagent（各自處理一篇獨立 raw → wiki），得到以下實質觀察：

「任務類型」判斷仍然成立，但需要精確化：真正可並行的任務是「寫入獨立文件」的任務，也就是每個 subagent 只碰自己的輸出文件。Vault 整理流程中只有 wiki skeleton 建立符合這個條件；其他步驟（index 更新、processing-log 更新、raw status 更新）都涉及共用資源，本質上必須序列執行，由 orchestrator 統一處理。

協調成本是實質的：orchestrator 需要為每個 subagent 撰寫詳細且完整的 prompt（格式規格、raw 內容摘要、邊界限制），這個準備工作大約等於單 agent 處理一篇的時間。2 篇並行的時間節省幾乎被 orchestrator 成本抵消；估計需要 5-8 篇以上的獨立 wiki 任務才開始有明確時間優勢。

Context 隔離對品質有正面效果：兩個 agent 的輸出完全沒有被互相污染，格式合規率 100%，各自的「我的觀點」都有焦點且不重複。這反映了 wiki 中「每個 agent 只知道它需要知道的事」這個核心設計原則確實有效。

第一個值得試的 Vault 候選：批次入庫 5 篇以上獨立主題的 raw 文章（例如一次處理多篇 Facebook 儲存文章，各自建 wiki skeleton）。條件是：篇數 ≥ 5、主題互相獨立、不需要 cross-reference。

Hooks 對我目前的工作流是已被替代的解法 Hooks 解決的問題是「讓流程規則不依賴 AI 記住」，但我已經用規則檔文件 + Cowork ↔ Claude Code 相互檢視達到同樣效果。規則寫在文件裡，可讀、可被 AI 直接引用、不需要額外設定腳本。在這個前提下，hooks 是沒有空缺的解法——它解決的問題我目前沒有。未來若 Vault 規模變大、協作頻率提高，再評估是否值得投入 hooks 設定成本。

Vault 整理任務的規模感：都是 P7（實測後確認） 即使同時有 7 篇 queued-for-wiki，對我來說仍屬小事。實測後更確定：個人 PKM 的任務規模幾乎不會觸發 P9/P10。除非 Vault 變成團隊共用系統，或每週需要一次性處理幾十篇 raw，才需要重新評估分工設計。

AI 主動任務分派：從「被設計的角色」到「自主協商的協作者」（2026-05-28 補充）

Claude Taiwan 社群（羅仁宏，2026-05-28）的案例展示了多代理方法論一個尚未討論的維度：當 Claude Code 與 Codex 透過 Markdown 互相留言時，Claude 曾主動提議把工作交給 Codex，Codex 也反向將任務分回 Claude。這不是 orchestrator 預先設計好的角色分工，而是兩個 agent 在溝通過程中自發協商出來的任務邊界。

這個觀察與現有的「任務類型判斷矩陣」形成對話：現有框架假設「由人（或 orchestrator）決定哪個 agent 做什麼」，但這個案例暗示更進一步的可能：agent 本身有足夠的情境理解能力來識別「這部分不是我最適合的」並主動交接。若這個模式可複製，orchestrator 的角色可能不再是預先分工，而是設定邊界規則，讓 agent 自行在規則內協商。

目前 FLUX Vault 的工作流仍在「人工設計角色」層次，這個維度是未來值得觀察的演進方向，尚未觸發可操作的改變。

待深化的問題（更新）：

~~實際操作過 subagents 後，「任務類型」這個判斷依據是否還成立？~~ ✅ 已實測確認：成立，但需精確化為「寫入獨立文件 vs 共用資源」的區分。
~~哪些 Vault 任務是第一個值得試的候選？~~ ✅ 已確認：5 篇以上獨立主題的批次 wiki 建立。
如果 Vault 規模成長到每週都有批次入庫，規則檔文件規範的方式是否還夠用，還是到了需要 hooks 自動執行驗證的臨界點？（尚未觸發，持續觀察）

參照：第三方開源 Agent 框架

OpenClaw / Harness Engineering（出自資訊科技課程）是另一種實作 Agentic AI 的開源架構方向，與 Claude Code 的設計哲學高度平行：

ReAct（Reason + Act）：OpenClaw 採用的思考-行動循環，讓 Agent 在每步行動前先推理再執行，與 Claude Code 的 chain-of-thought 工作模式相同。這個設計讓 Agent 能自主規劃步驟，而非只是執行指令。

通則：Markdown 配置人格 + 技能 + 記憶的架構不是 Claude Code 獨有，而是 Agentic AI 設計的一種通用模式。規則檔 等檔案是這個模式的 Claude 具體實作。

Agency Agents（agencyagents.dev）

補入日期：2026-05-31｜來源：Codex 社群初篩

140+ role-based agent personas，可供 Claude Code / Cursor / Windsurf 載入使用。定位是 persona library（角色人格庫），而非 orchestration 框架本身。

觀察：persona library 能讓 agent 更快進入「專家語氣」的思考模式，但不解決上下文隔離、工具 allowlist 設定等工程問題。兩者互補，不互相替代——先確定任務邊界和工具設定，再選擇合適的 persona，而非反過來。

Agent UI 空白：GUI 視覺 vs 終端循環

多代理協作中存在一個設計空白：

終端 agent（Claude Code / subagents）：有完整的「讀取 → 編輯 → 驗證 → 修正」閉環，但介面不直覺、狀態不易追蹤
GUI 客戶端（Conductor、各種 IDE 插件）：有視覺介面和交互，但多數缺乏真正的自動化循環能力

目前主流做法是「三窗口模擬分工」：一個 orchestrator terminal 追蹤狀態，多個 subagent terminal 各自執行，GUI 工具負責 review 與視覺判斷。這不是最優方案，但在統一方案出現前是最務實的折衷。

對本篇的意義：多代理方法論的下一個缺口不在「如何分派任務」（已有 Task tool / subagents），而在「如何直覺地追蹤多個 agent 狀態」——這是 Conductor 等工具試圖解決的問題。

7-role 軟體工廠：人類審核點與上下文漂移處置

補入：2026-06-15（來源：blocktempo 譯外部創作者「7 個 Agent 把 Vibe Coding 升級成軟體工廠」，2026-05-31；LINE 預篩選批次）

外部創作者的「軟體工廠」把單一 Claude Code 對話拆成 7 個只讀/限寫的專責 agent：研究員（Researcher，只讀，動工前先掃 codebase）→ 故事撰寫者（Story Writer，產使用者故事＋驗收標準）→ 規格撰寫者（Spec Writer，轉技術簡報）→ 後端建造者（限後端資料夾）→ 前端建造者（限前端資料夾，先讀後端 API 摘要、不發明端點）→ 測試驗證者（只寫驗收測試）→ 實作驗證員（只讀，拿實作對照故事/簡報回報落差）。和本篇既有的 12-agent devteam 是同一個「上下文隔離＋職責分離」骨架，但有三點是既有內容沒有、值得標的增量：

① 三個明確的人類審核點，織進流程而非附加：核准故事 → 核准簡報 → 核准 PR。其餘全自動。設計重點是「在錯誤最便宜的時候攔下」——簡報核准點抓「把 ID 存記憶體」這種架構錯誤，遠勝十個檔案改完才發現。這把本庫一直在做的「human-in-the-loop 閘」具體化成流程裡的固定停損點，而非籠統的「Critic review」。

② 上下文漂移（context drift）的處置規則：大多數對話不是戲劇性失敗，而是「一個錯假設進 context，模型在上面繼續疊」。處置二分法——小錯字 → inline 修正；架構假設錯 → 整段對話丟掉重來，把對的假設烙進第一個 prompt。理由：打補丁會留下 user.subscriptionId 與 company.subscriptionId 同時飄著的爛攤子，「一個有正確心智模型的乾淨對話，永遠勝過一個打補丁的對話」。這條最實用、可直接用在行動 App／教學管理系統 coding——也呼應本庫「系統設計 > 點對點修補」的傾向。

③ 驗證員「只看磁碟現實、不看自評」：實作驗證員從不修任何東西、只說真話，按 Critical/Important/Minor 分級附檔案路徑行號，「自評的成績單沒有價值」。這點與本批同時入庫的延伸方向 execution-proofs（zero-LLM 驗 agent 完工宣稱綁實體檔）同源，也與 Vault 用 Codex 複查「宣稱 vs 實際」的機制同構。

對我的定位：這套是 coding 工作流（行動 App／教學管理系統），不是 Vault 任務——本篇「我的觀點」已實測確認 Vault 整理皆 P7、不需要這種重編制。但 ②（上下文漂移處置）和 ③（驗證只看現實）是跨情境的判斷原則，值得在實際寫 code 時叫用。另注：該文獨立佐證「規則檔保持 100–300 行」，已回填延伸方向。

可連結的主題

延伸方向 — session 管理的基礎觀念，與 subagents 互補
延伸方向 — AI Agent 宏觀框架與商業應用
延伸方向 — 非工程師視角的 Claude Code 實作
延伸方向 — FLUX Vault 的 AI 協作規格，hooks 的潛在對應點