Claude Code Agent Teams：從穩定執行到自動化代碼審查的完整指南

Claude Code Agent Teams：從穩定執行到自動化代碼審查的完整指南

本文整合三部分內容：(1) Agent Teams 的穩定執行框架；(2) 全局代碼審查規則系統的設計與實施；(3) 自動化雙 Agent 審查機制（架構師 + PM）的完整實現方案。這是一份實踐導向的指南，涵蓋從資源評估、權限配置、到自動觸發流程的所有細節。

第一部分：Agent Teams 的三層穩定執行框架

1.1 評估層（Assessment）— 前置資源檢查

每次建立 Agent Team 前，必須執行三個評估動作：

1. 記憶體現狀：執行 free -h 或查看 Docker stats，確認可用容量
2. 計算容量：根據模型選擇計算最大並行 agent 數（opus ~1GB、sonnet ~600MB、haiku ~400MB）
3. 決策與確認：列出 agent 角色、模型、預估記憶體，取得用戶確認後才建立

模型選擇口訣：

• 需要「想」 → Opus（架構決策、安全設計、業務邏輯、複雜 SQL、Code Review）
• 需要「做」 → Sonnet（CRUD 實作、API 對接、測試撰寫、文件撰寫）
• 需要「找」 → Haiku（檔案掃描、配置對比、API 整合）

1.2 確認層（Confirmation）— 用戶決策前置

建立 Team 前，必須向用戶列出清晰的角色定義和資源計劃，包括：

• 各 agent 的角色名稱與職責
• 指定的 AI 模型及其預估記憶體
• 總計容量和系統可用容量
• 並行數量和預期執行順序

只有在用戶明確確認後，才啟動 TeamCreate 和後續任務建立。這一步防止了資源耗盡、權限誤配、以及 agent 之間通訊不暢的根本原因。

1.3 執行層（Staged Execution）— 分階段序列化

即使資源充足，也不應讓所有 agent 同時轟炸執行。分階段策略包括：

1. 第 1 階段：啟動基礎設施 agent（如資源管理、環境配置）
2. 第 2 階段：啟動 researcher agent，進行資訊搜集與分析
3. 第 3 階段：啟動 architect agent，設計方案
4. 第 4 階段：啟動 developer agent，進行實作
5. 第 5 階段：啟動驗證 agent，進行測試與審查

各階段 agent 完成任務後，主動進入「空閒」狀態並通知團隊。不進行「拉取」操作，而是由前置 agent 完成後才推進下一階段。這種設計確保：

• 前置依賴滿足後才啟動
• 消息傳遞清晰，無需輪詢
• 系統記憶體壓力均勻分散
• 故障範圍可控，易於除錯

第二部分：全局代碼審查規則系統架構

2.1 雙層規則設計

代碼審查規則分為兩層，確保通用性和專案適應性的平衡：

• 全局層（~/.claude/memory/）：所有項目共享的代碼品質標準（SOLID 原則、Design Pattern、代碼異味、測試規範、語言特定規範）
• 項目層（項目/.claude/code-review-rules.md）：專案特定的業務邏輯規則、設計稿映射、外部驗證清單

2.2 全局規則內容結構

code-review-global-rules.md（SOLID、Pattern、Code Smell、Testing）

• SOLID 五項原則的定義和違反示例
• Design Pattern 反面示例（God Object、Feature Envy 等）
• 代碼異味檢查清單（N+1、Magic Number、過長方法、過多參數、重複代碼、複雜邏輯）
• 單元測試最低標準（80%+ 覆蓋、邊界情況、Mock vs Real Dependency）

code-review-languages.md（Java、Python、JavaScript/TypeScript、SQL）

• 命名規範（類名、方法名、變數名、常數、包名）
• 包結構約定（分層架構：domain/service/repository/validator 等）
• 異常處理規範
• 語言特定工具規範（Lombok、OSGi、Type Hint、Docstring 等）

code-review-feedback.md（架構師與 PM Agent 職責和對焦框架）

• 架構師 Agent：SOLID 遵循度（1-5 分）、Design Pattern、Code Smell、測試覆蓋、異常處理、語言規範
• PM Agent：功能 vs 設計稿對齐、API 返回值、邊界情況、業務邏輯、用戶體驗、外部驗證需求
• 雙方對焦框架：架構師問「代碼設計能支持你檢查的功能嗎？」，PM 反問「這些功能需求會造成架構問題嗎？」

code-review-process.md（自動觸發、Agent 角色、聯合報告格式）

• 觸發點：Task marked as completed
• Agent 角色 Prompt（初版）：架構師評估、PM 評估、聯合對話
• 聯合報告格式：分離的評估 + 統一優先級排序 (P0/P1/P2)
• 最終判定：Pass / Needs Work / Fail

2.3 項目層規則（台灣發票系統範例）

項目規則分為三類：

A. 業務邏輯規則（優先級最高）

• 進項稅計算公式（進項稅金額 = 發票金額 × 5%，DECIMAL(19,2) 向下取整）
• 三聯式（不含稅）vs 二聯式（含稅）的會計處理邏輯
• 進項稅折讓的強制申報期限（當期內必須申報，無延後例外）
• 兼營營業人的比例扣抵公式（可扣抵進項稅 = 總進項稅 × (應稅銷售額 / 總銷售額)）
• 發票號碼連續性檢查和遺失空白發票記錄
• 發票開立日期 → 申報期間的映射（1-2月→第1期、3-4月→第2期 等，共六期）

B. 設計稿對齐規則（優先級次之）

• API 端點的返回格式和欄位定義
• 邊界情況的預期響應（零金額、負數、超大金額）
• 數據型態和範圍檢查

C. 外部驗證清單（優先級最低，但定期更新）

• 進項稅可扣抵期限是否仍為 10 年
• 電子發票強制規定的生效狀態
• 設計稿版本確認
• 技術規範（iDempiere PO 模型、OSGi Bundle）

第三部分：自動化雙 Agent 審查機制的實現

3.1 TaskCompleted Hook 配置

在 .claude/settings.local.json 中配置 TaskCompleted Hook，每當任務標記完成時，自動觸發架構師和 PM 兩個 agent 進行深度審查：

{
  "hooks": {
    "TaskCompleted": [
      {
        "hooks": [
          {
            "type": "agent",
            "prompt": "Conduct comprehensive code review: (1) Architecture: SOLID principles (1-5), design patterns, code smells (P0/P1/P2), testing, exceptions. (2) Functional: spec alignment, API contracts, boundary cases, business logic (Taiwan tax rules). Provide unified P0/P1/P2 priority with Pass/Needs Work/Fail decision and file:line recommendations.",
            "model": "opus",
            "statusMessage": "Running code review on completed task...",
            "timeout": 300
          }
        ]
      }
    ]
  }
}

3.2 架構師 Agent 職責細節

架構師 Agent 按以下維度進行評估，每項 1-5 分自評：

1. SOLID 原則遵循度：檢查 S（單一職責）、O（開閉）、L（里氏替換）、I（接口隔離）、D（依賴倒轉）五項是否遵循
2. Design Pattern 應用恰當性：是否應用了合適的設計模式，是否存在過度設計
3. 代碼異味程度：N+1 查詢、Magic Number、過長方法（>20 行）、過多參數（>3 個）、重複代碼、複雜邏輯（圈複雜度 > 10）
4. 測試覆蓋度：目標 80%+，是否涵蓋邊界情況（null、empty、max/min）
5. 異常處理完整性：是否避免過寬泛的異常捕捉，異常信息是否有意義，是否吞掉異常
6. 語言特定規範遵循度：根據 code-review-languages.md 檢查命名、包結構、工具使用規範

輸出：各維度評分 + 具體改進建議（標記優先級 P0/P1/P2 和代碼位置）

3.3 PM Agent 職責細節（含 QA）

PM Agent 進行務實檢查，確保功能實現和業務邏輯正確性：

1. 功能 vs 設計稿對齐：設計稿的所有功能點是否實現，是否有範圍蠕動
2. API 返回值對齐：返回欄位是否與文檔一致，資料型態是否正確，必需欄位是否都有
3. 邊界情況涵蓋：null 輸入、空集合、最大值/最小值、負數、零值是否處理
4. 業務邏輯正確性：根據項目規則（進項稅計算、發票號碼、申報期間映射等）是否正確
5. 用戶體驗：錯誤提示是否清楚，用戶流程是否順暢，是否有令人困惑的行為
6. 外部驗證需求：是否需要查證業務規定（優先 C）、設計稿（優先 A）、技術規範（優先 B）

輸出：功能層缺陷清單、QA 項目、待驗證項（註明 C/A/B 優先級）

3.4 聯合報告與優先級統一排序

架構師和 PM 分別完成評估後，進行深度對話：

• 架構師問 PM：「代碼結構能支持你檢查的功能嗎？」
• PM 反問架構師：「這些功能需求會造成架構問題嗎？」

基於對話結果，生成聯合報告：

• P0（Critical）：N+1 查詢、安全漏洞、死鎖風險、未處理的邊界情況、違反台灣稅務規則
• P1（Important）：過長方法、重複代碼、Magic Number、缺失測試、不清晰的錯誤提示
• P2（Nice to Have）：輔助方法提取、考慮設計模式、日誌增強

最終判定：

• ✅ Pass：P0 問題 0 個，P1 問題可接受（≤2 個或不影響核心功能）
• ⚠️ Needs Work：P0 問題 1-3 個，或 P1 問題 >3 個，或測試覆蓋度 <70%
• ❌ Fail：P0 問題 ≥3 個，或安全漏洞，或違反重要法規

第四部分：審查流程與反覆迭代

4.1 外部驗證流程

當 PM Agent 提出待驗證項時，按優先級啟動查詢：

優先級 C（業務邏輯）— 需人工驗證

• 用戶透過稅務官網或法規文件進行人工查證（AI 查詢易出錯）
• 驗證結果更新到項目規則
• 重新審查涉及的代碼

優先級 A（設計稿）— 查閱項目文檔

• 查閱設計文件、API 文檔
• 如無對應文件，提示用戶補充
• 確認後更新 code-review-rules.md

優先級 B（技術規範）— 查詢官方文檔

• 查詢 iDempiere、OSGi 官方文檔
• 標記為參考（變動機會低）

4.2 修改與重審流程

當報告判定為 Needs Work 或 Fail 時：

1. 開發者查看報告，收到 P0/P1/P2 改進清單
2. 開發者修改代碼並完成新測試
3. 重新標記 Task 為 completed（或手動觸發 /code-review-force）
4. 自動重審（流程回到架構師 + PM 評估）
5. 迴圈進行，直到最終判定 Pass

第五部分：系統集成與迭代計劃

5.1 全局記憶結構

所有規則和流程信息保存在用戶的全局記憶庫中：

• ~/.claude/memory/code-review-global-rules.md — SOLID、Pattern、Code Smell、Testing
• ~/.claude/memory/code-review-languages.md — Java、Python、JS、SQL 規範
• ~/.claude/memory/code-review-feedback.md — 架構師/PM 職責與對焦框架
• ~/.claude/memory/code-review-process.md — 自動觸發、報告格式、判定標準

5.2 項目級別記憶結構

• 項目/.claude/code-review-rules.md — 業務邏輯規則 + 設計稿映射 + 外部驗證清單
• 項目/.claude/settings.local.json — TaskCompleted Hook 配置

5.3 三個迭代階段

Phase 1（現在）

• 建立全局規則知識庫（4 個記憶文件）
• 編寫項目層規則（code-review-rules.md）
• 配置 TaskCompleted Hook
• 在項目中試用審查機制

Phase 2（2-4 週後）

• 根據實際審查結果優化規則（哪些規則發現了 bug、哪些規則太寬泛）
• 改進 Agent Prompt（增加上下文、更清晰的指導）
• 補充項目層規則細節（特別是邊界情況和特殊規則）

Phase 3（1-2 月後）

• 考慮集成到 CI/CD（每次 PR 自動審查）
• 累積審查報告，形成項目代碼品質歷史
• 調整 Hook 超時和 Agent 模型選擇

第六部分：常見問題與實踐建議

Q1：如果審查花太長時間怎麼辦？

A：初版 timeout 設為 300 秒。如果超時，可調整為 600 秒，或簡化 Agent Prompt 去掉某些維度。對大型代碼改動，可分成多個小 Task，每個分別審查。

Q2：外部驗證項目誰負責查證？

A：初版由用戶或 PM 手動查證（特別是業務邏輯 C 項）。後續可考慮集成更多自動化（如 WebSearch for C 項、文檔連接 for A 項）。

Q3：PM Agent 如何知道設計稿的內容？

A：初版需在 code-review-rules.md 的 B 項中維護設計稿摘要（API 返回格式、欄位定義、邊界情況）。後續可考慮直接連接設計文件或 API 文檔鏈接。

Q4：審查報告輸出到哪裡？

A：初版直接輸出到對話（用戶可複製保存或導出）。後續可考慮存到 Task comment、Markdown 文件或項目文檔。

Q5：如何確保 Agent Teams 穩定運行？

A：遵循三層框架：

• 評估層：前置資源檢查和確認，不盲目建立 Team
• 確認層：列出角色、模型、容量，取得用戶確認
• 執行層：分階段序列化，避免並行轟炸，讓 agent 主動進入空閒狀態而不是被拉取

以及定期檢查記憶體、監控 agent 通訊、設置合理的超時時間。

結論

穩定可信的 Agent Teams 不是靠運氣，而是靠紮實的前置規劃、清晰的資源評估、以及精心設計的執行流程。本文提供的三層框架（評估→確認→分階段執行）確保了 Team 運行的穩定性。配合全局規則庫 + 項目規則 + 自動審查機制，可以建立一套完整的代碼品質保證體系，既有通用性，也有靈活性。

從 Phase 1 的試用開始，逐步優化規則和 Agent Prompt，經過 2-4 週的實踐，可以達到穩定的審查效果。最終目標是讓代碼審查成為自動化流程的一部分，開發者無需手動申請審查，系統自動評估和反饋，確保每個 Task 完成時都經過架構師和 PM 的雙重把關。