Claude Code 建立 SSDLC Agent Team 教學手冊

版本：1.4.0 ｜ 最後更新：2026-08-31 ｜ 作者：企業級 AI Agent 架構顧問團隊
適用對象：資深工程師、架構師、技術主管、DevSecOps、人員培訓
定位：企業級白皮書等級教學手冊，可直接作為團隊導入與治理規範

目錄

• Ch 0：文件資訊與閱讀指南
  • 0.1 文件基本資訊
  • 0.2 使用前提與先決條件
  • 0.3 閱讀地圖
  • 0.4 功能狀態標示規則
  • 0.5 核心名詞定義
  • 0.6 版本變更紀錄
  • 0.7 注意事項
• Ch 1：總覽：什麼是 Claude Code SSDLC Agent Team
  • 1.1 為什麼企業需要 SSDLC Agent Team
  • 1.2 與其他方法的差異比較
  • 1.3 Claude Code 在 SSDLC 各階段的角色
  • 1.4 新系統開發 vs. 舊系統逆向工程
  • 1.5 整體架構圖
  • 1.6 企業導入價值
  • 1.7 典型使用情境
  • 1.8 實務建議
• Ch 2：功能盤點與術語對照
  • 2.1 18 項功能概述
  • 2.2 功能矩陣表
  • 2.3 平台差異比較表
  • 2.4 概念差異比較表（容易混淆的概念兩兩比較）
  • 2.5 功能穩定性狀態對照表（Experimental / Beta / GA）
  • 2.6 容易混淆術語表
  • 2.7 Subagent 限制速查表
  • 2.8 Config Hierarchy 與 CLAUDE.md 載入順序速查
  • 2.9 實務建議
  • 2.10 版本門檻速查表
• Ch 3：Claude Code SSDLC Agent Team 企業架構設計
  • 3.1 Agent Team 整體架構圖
  • 3.2 Agent 間協作流程圖
  • 3.3 十個 Agent 角色詳細定義
  • 3.4 Subagents vs Agent Teams 比較圖
  • 3.5 Subagent vs Agent Team 決策矩陣
    • 3.5.1 Team 的建立、任務分派與通訊機制
  • 3.6 Agent 與 SSDLC 階段對應表
  • 3.7 Agent RACI 矩陣
  • 3.8 必須人工審核的清單
  • 3.9 權限過大的風險與防範
  • 3.10 實務建議
  • 3.11 Agent Teams 架構變更與遷移指引
    • 3.11.1 破壞性變更時間軸
    • 3.11.2 啟用 Agent Teams 會改變一般委派行為
    • 3.11.3 Subagent 定義轉為 Teammate 的欄位對應
    • 3.11.4 Agent Teams 專屬 Hook 事件
    • 3.11.5 安全提醒：計畫審批會被 Lead 自動代簽
    • 3.11.6 成本與規模建議
    • 3.11.7 遷移檢查清單
• Ch 4：平台安裝與環境建置
  • 4.1 安裝前提
  • 4.2 Windows 安裝
  • 4.3 macOS 安裝
  • 4.4 Linux 安裝
  • 4.5 VS Code Extension 安裝
    • 4.5.1 擴充功能設定（claudeCode.*）
    • 4.5.2 指令與快捷鍵
    • 4.5.3 Chrome 瀏覽器自動化（@browser）
    • 4.5.4 /usage 用量面板（v2.1.174+）
    • 4.5.5 IDE MCP Server 安全機制與第三方 Provider 設定
  • 4.6 CLI 認證方式
  • 4.7 Permission Mode 比較表
  • 4.8 公司允許模型設定
  • 4.9 最佳起始設定
  • 4.10 常見安裝錯誤與排除
  • 4.11 實務建議
  • 4.12 VS Code Extension 版本門檻與無障礙支援
    • 4.12.1 功能版本門檻速查
    • 4.12.2 無障礙（Accessibility）支援
    • 4.12.3 問題回報管道
• Ch 5：專案初始化與標準目錄設計
  • 5.1 標準目錄樹
  • 5.2 每個檔案與目錄用途說明
  • 5.3 核心設定檔範例
  • 5.4 命名規範
  • 5.5 版本控管策略
  • 5.6 .gitignore 建議
  • 5.7 Plugins 與 Marketplace 策略
  • 5.8 快速初始化腳本
  • 5.9 實務建議
• Ch 6：建立 Agent 與 Subagent
  • 6.1 概念總覽：Subagent、Custom Subagent 與 Agent Team Teammate
  • 6.2 Subagent 與主對話的差異
  • 6.3 Subagent vs. Agent Team 比較
  • 6.4 自動呼叫 vs. 明確呼叫
  • 6.5 前景 vs. 背景執行與 Fork Mode
  • 6.6 權限、Tools、Model 與 Isolation
  • 6.7 巢狀呼叫限制
  • 6.8 完整範例
  • 6.9 Worktree Isolation 範例
  • 6.10 Anti-Patterns（5 個常見錯誤）
  • 6.11 Agent Team Subagent Definition 正確說明
  • 6.12 內建 Subagents 與 Agent Team Hooks
  • 6.13 實務建議
  • 6.14 Subagent Frontmatter 完整參考（v2.1.251 基準）
  • 6.15 Subagent 載入失敗、錯誤處理與可靠性治理
    • 6.15.1 定義檔被跳過的五種情況
    • 6.15.2 API 錯誤與中途失敗的處理
    • 6.15.3 Subagent 的續跑與紀錄稽核
    • 6.15.4 Sibling Roster（同儕名冊）
    • 6.15.5 Hook 事件與匹配規則
    • 6.15.6 可靠性治理檢查清單
  • 6.16 Cross-Session Messaging（跨 Session 訊息協作）
    • 6.16.1 三種協作模型的選型
    • 6.16.2 運作方式與定址
    • 6.16.3 訊息投遞的三種結果
    • 6.16.4 安全邊界（企業必讀）
    • 6.16.5 企業治理設定
    • 6.16.6 Inbox Socket 與稽核接點
    • 6.16.7 版本需求與限制
    • 6.16.8 導入檢查清單
• Ch 7：建立 Prompt Library 與 Team Prompt SOP
  • 7.1 Prompt 在 Claude Code 生態系中的定位
  • 7.2 企業級 Prompt Catalog 架構
  • 7.3 版本管理策略
  • 7.4 Prompt 範本集（10 個）
  • 7.5 實務建議
• Ch 8：建立 Skills
  • 8.1 Skills 定義與核心概念
  • 8.2 Skills 與相關功能的差異
  • 8.3 自動觸發 vs. 手動觸發
  • 8.4 Supporting Files 與漸進式揭露（Progressive Disclosure）
  • 8.5 context:fork 與 Compaction 注意事項
  • 8.5.1 Skills 進階 Frontmatter 欄位
  • 8.5.2 Agent Skills 開放標準
  • 8.5.3 Dynamic Context Injection（動態 Context 注入）
  • 8.5.4 完整字串替換變數參考
  • 8.5.5 Skill 內容生命週期與 Compaction 後的重新附加
  • 8.5.6 內建 Skills（Bundled Skills）完整清單
  • 8.5.7 Skill 評測框架（skill-creator Plugin）
  • 8.5.8 Skill 疑難排解
  • 8.5.9 即時偵測、巢狀目錄與雲端 Session 中的 Skill
  • 8.5.10 Skill Listing Budget 與 Context 成本治理
    • 8.5.10.1 預算計算方式
    • 8.5.10.2 治理策略
    • 8.5.10.3 Skill Stacking（Skill 疊加，v2.1.199+）
    • 8.5.10.4 Skill 內容的生效期間
    • 8.5.10.5 動態 Context 注入的資安控管
  • 8.6 完整 Skill 範例（7 個）
  • 8.7 內建 Skills 的載入優先序與命名空間
  • 8.8 實務建議
  • 8.9 claude.ai 同步 Skills 的企業風險與封鎖策略
    • 8.9.1 同步機制與存放位置
    • 8.9.2 企業風險分析
    • 8.9.3 建議封鎖策略
    • 8.9.4 稽核檢查清單
• Ch 9：建立 Hooks 與 Guardrails
  • 9.1 Hooks 概述：確定性控制層
  • 9.2 Hook 類型
  • 9.3 Hook 事件
  • 9.4 Matcher 語法
    • 9.4.1 if 條件過濾（依工具參數細部匹配）
    • 9.4.2 環境變數展開
  • 9.5 Hook 設定結構
  • 9.6 Hooks 與 Permission Mode 的關係
  • 9.7 Hook 除錯方式
  • 9.8 範例 1：保護敏感檔案不可修改
  • 9.9 範例 2：只允許唯讀 SQL 查詢
  • 9.10 範例 3：變更後自動格式化
  • 9.11 範例 4：Teammate 完成任務前的品質 Gate
  • 9.12 範例 5：偵測設定檔變更並寫入 Audit Log
  • 9.13 範例 6：自動補充 Compact 後的關鍵上下文
  • 9.14 範例 7：HTTP Hook 串接企業稽核服務
  • 9.15 實務建議
  • 9.16 Hook 決策欄位與 Exit Code 完整參考
    • 9.16.1 Exit Code 語意
    • 9.16.2 stdout JSON 決策欄位
    • 9.16.3 Stop Hook 的無限迴圈防護
    • 9.16.4 非同步 Hook 與逾時
    • 9.16.5 Hook 設定的載入位置與優先序
    • 9.16.6 Hook 治理檢查清單
• Ch 10：建立 Plugins 與 Marketplace Strategy
  • 10.1 何時用 Plugin vs. Standalone Config
  • 10.2 Plugin 結構
  • 10.3 plugin.json Manifest 格式
  • 10.4 Plugin Subagent 限制
  • 10.5 安裝範圍
  • 10.6 Marketplace 差異
  • 10.7 安全與信任模型
  • 10.8 範例 1：plugin.json 完整範例
  • 10.9 範例 2：Skills 型 Plugin
  • 10.10 範例 3：Agents 型 Plugin
  • 10.11 範例 4：Hooks 型 Plugin
  • 10.12 範例 5：Team Marketplace 設定
  • 10.13 範例 6：Plugin 升級與版本控管策略
  • 10.14 官方 Marketplace 內容總覽
  • 10.15 Plugin 發現與管理指令
  • 10.16 Plugin 驗證、快取與相依性
  • 10.17 Skills 目錄型 Plugin
  • 10.18 實務建議
  • 10.19 Plugin CLI 工具鏈與本機開發流程
    • 10.19.1 claude plugin init — 快速建立 Skills 目錄型 Plugin
    • 10.19.2 本機載入：--plugin-dir 與 --plugin-url
    • 10.19.3 熱重載：/reload-plugins
    • 10.19.4 開發到發布的完整流程
    • 10.19.5 企業 Marketplace 的 CI 建議
• Ch 11：Memory、CLAUDE.md 與知識治理
  • 11.1 CLAUDE.md 的角色
  • 11.2 CLAUDE.md 載入順序
  • 11.3 Auto Memory
  • 11.4 Memory vs. CLAUDE.md vs. Skills
  • 11.5 Config Hierarchy 與記憶的關係
  • 11.6 與其他文件的分工
  • 11.7 記憶檔案避免膨脹與污染的方法
  • 11.8 CLAUDE.md 範本 1：通用專案
  • 11.9 CLAUDE.md 範本 2：Security 導向
  • 11.10 CLAUDE.md 範本 3：Reverse Engineering 導向
  • 11.11 記憶治理原則
  • 11.12 清理與維護策略
  • 11.13 實務建議
• Ch 11-A：Output Styles（輸出風格）
  • 11-A.1 概述
  • 11-A.2 內建風格
  • 11-A.3 自訂 Output Style
  • 11-A.4 Plugin 提供的 Output Styles
  • 11-A.5 keep-coding-instructions 欄位
  • 11-A.6 切換 Output Style
  • 11-A.7 SSDLC 建議
  • 11-A.8 企業導入檢查清單與疑難排解
    • 11-A.8.1 導入檢查清單
    • 11-A.8.2 常見問題排解
• Ch 11-B：Scheduled Tasks（排程任務）
  • 11-B.1 概述
  • 11-B.2 建立排程任務
  • 11-B.3 任務類型
  • 11-B.4 /loop Skill
    • 11-B.4.1 動態排程的底層機制：ScheduleWakeup
    • 11-B.4.2 loop.md 的載入位置與限制
    • 11-B.4.3 不要用輪詢解決的事：Channels 與 /goal
  • 11-B.5 管理排程任務
  • 11-B.6 搭配 Hooks
  • 11-B.7 SSDLC 應用場景
  • 11-B.8 治理建議
  • 11-B.9 排程機制選型與導入檢查清單
    • 11-B.9.1 三種機制的選型決策
    • 11-B.9.2 導入檢查清單
    • 11-B.9.3 常見誤解澄清
• Ch 12：MCP 與 Tools 整合架構
  • 12.1 什麼是 MCP（Model Context Protocol）
  • 12.2 MCP Scope 與設定檔層級
  • 12.3 Transport 機制：HTTP / stdio / SSE
  • 12.4 OAuth、Headers 與安全整合
  • 12.5 進階 MCP 功能
    • 12.5.1 Resources 與 @-mentions
    • 12.5.2 Channels（通道）
    • 12.5.3 Elicitation
    • 12.5.4 動態工具更新（list_changed）
    • 12.5.5 MCP 指令族與進階設定速查
    • 12.5.6 逾時階層、Tool Annotation 與開發輔助
  • 12.6 Claude Code 作為 MCP Server
  • 12.7 MCP 與 Plugins 的整合
  • 12.8 MCP 與企業治理
  • 12.9 MCP 安全風險
    • 12.9.1 Prompt Injection 風險
    • 12.9.2 資料外洩風險
  • 12.10 完整範例
  • 12.11 MCP 安裝與驗證
  • 12.12 list_changed Notification
  • 12.13 實務建議
  • 12.14 MCP v2 Runtime 遷移指南（v2.1.232+）
    • 12.14.1 v1 與 v2 Runtime 差異
    • 12.14.2 過渡期控制旗標
    • 12.14.3 相關的連線與快取旗標
    • 12.14.4 其他版本行為變更
    • 12.14.5 升級檢查清單
• Ch 13：Programmatic CLI、GitHub Actions 與 GitLab CI/CD
  • 13.1 CLI 互動模式 vs Programmatic CLI
  • 13.2 Programmatic CLI 用法
    • 13.2.1 基本語法
    • 13.2.2 --bare 模式
    • 13.2.3 結構化輸出與 JSON Schema
    • 13.2.4 工具與權限控制
    • 13.2.5 完整 CLI 參數速查
    • 13.2.6 stream-json 事件類型
    • 13.2.7 CI 治理：啟動事件檢查與程序終止行為
  • 13.3 Provider 差異說明
  • 13.4 GitHub Actions 整合 🟢 GA
    • 13.4.1 快速安裝
    • 13.4.2 核心參數
    • 13.4.3 完整 Workflow 範例：PR Review Bot
    • 13.4.4 完整 Workflow 範例：安全掃描 Gate
    • 13.4.5 GitHub App 設定與雲端 Provider 整合
    • 13.4.6 認證方式、觸發權限與組織級治理
  • 13.5 GitLab CI/CD 整合 🟡 Beta
    • 13.5.1 GitLab CI/CD 環境設定
    • 13.5.2 完整 GitLab CI/CD Job 範例
    • 13.5.3 GitHub Actions vs GitLab CI/CD 差異
    • 13.5.4 典型應用場景範例
    • 13.5.5 AWS Bedrock / GCP Vertex AI 整合（透過 OIDC）
    • 13.5.6 疑難排解
  • 13.6 API Key / OIDC / Secret 治理
  • 13.7 何時用互動式 vs CI 自動化
  • 13.8 CI/CD 與 Agent 自動化流程圖
  • 13.9 實務建議
• Ch 14：將 Agent、Prompt、Skills、Hooks、Memory、MCP 融入 SSDLC
  • 14.1 為什麼需要融入 SSDLC
  • 14.2 Agent 協作圖
  • 14.3 SSDLC 14 階段總覽
  • 14.4 各階段詳細設計
  • 14.5 SSDLC SOP 總覽表
  • 14.6 安全 Gate 建議
  • 14.7 KPI 建議
  • 14.8 實務建議
• Ch 15：舊系統逆向工程與現代化改造專章
  • 15.1 方法論總覽
  • 15.2 十一項任務說明
  • 15.3 Reverse Engineering Agent 設計
    • 15.3.1 Agent 定義檔（.claude/agents/reverse-engineering.md）
    • 15.3.2 Agent 設計重點
  • 15.4 專用 Prompt 範例
  • 15.5 專用 Skills 範例
  • 15.6 專用 Hooks / Guardrails 範例
  • 15.7 輸出範本：架構還原文件格式
  • 15.8 風險與注意事項
    • 15.8.1 幻覺風險（Hallucination Risk）
    • 15.8.2 不完整分析風險
    • 15.8.3 實務建議
• Ch 16：提供給其他團隊使用的共享 SOP
  • 16.1 Team Onboarding 流程
    • 16.1.1 導入路線圖（4 階段 + 時程）
    • 16.1.2 各階段詳細步驟
  • 16.2 Starter Repository 設計
    • 16.2.1 模板 Repo 結構
    • 16.2.2 使用方式
  • 16.3 共享 Plugins / Skills / Agents / Hooks 治理方式
    • 16.3.1 治理架構
    • 16.3.2 治理規範
    • 16.3.3 治理 vs. 即時協作：Cowork 與 Channels/Dispatch
  • 16.4 文件模板
    • 16.4.1 文件模板清單
  • 16.5 教育訓練計畫（4 階段）
  • 16.6 支援模式（L1/L2/L3）
  • 16.7 FAQ（團隊導入常見問題）
  • 16.8 變更公告機制
  • 16.9 例外申請流程
  • 16.10 成熟度模型（5 個等級）
  • 16.11 啟用 Checklist
  • 16.12 角色分工表
  • 16.13 常見阻力與解法
  • 16.14 實務建議
• Ch 17：安全、治理、稽核與成本控管
  • 17.1 最小權限原則
    • 17.1.1 Permission Mode 治理策略
    • 17.1.2 權限矩陣
    • 17.1.3 六層安全模型總覽
  • 17.2 Hooks Guardrails
    • 17.2.1 必備 Hooks 清單
  • 17.3 Secrets 管理
  • 17.4 敏感檔案保護
  • 17.5 Prompt Injection 風險
  • 17.6 MCP 風險
  • 17.7 Plugin Marketplace 風險
  • 17.8 Agent Teams 權限與成本風險
  • 17.9 CI 自動化風險
  • 17.10 Logs / Audit Trail / Compliance
    • 17.10.1 稽核紀錄建議
    • 17.10.2 合規對照
  • 17.11 風險矩陣表
  • 17.12 模型使用策略：Haiku、Fable、Sonnet、Opus 四級選型
  • 17.13 成本監控指標表
  • 17.14 控制點設計表
  • 17.15 不建議做法清單
  • 17.16 實務建議
• Ch 18：系統維護、升級與相容性管理
  • 18.1 維護總覽
    • 18.1.1 官方文件與版本追蹤機制
  • 18.2 各項升級 SOP
    • 18.2.1 Claude Code CLI 升級
    • 18.2.2 VS Code Extension 升級
    • 18.2.3 Subagents 升級
    • 18.2.4 Skills 升級
    • 18.2.5 Hooks 升級
    • 18.2.6 Plugins 升級
    • 18.2.7 MCP 配置升級
    • 18.2.8 Prompt Library 升級
    • 18.2.9 CLAUDE.md / Memory 清理
  • 18.3 相容矩陣範例
  • 18.4 回滾計畫
    • 18.4.1 回滾策略
    • 18.4.2 回滾決策樹
  • 18.5 版本管理建議
  • 18.6 Experimental → GA 調整
  • 18.7 文件更新流程
  • 18.8 例行巡檢
    • 18.8.1 巡檢 Checklist
    • 18.8.2 巡檢自動化腳本
  • 18.9 升級排程建議
  • 18.10 實務建議
• Ch 19：完整實戰案例
  • 19.1 案例一：新建 Spring Boot Web 專案
    • 19.1.1 專案背景
    • 19.1.2 Phase 1：環境準備（Sprint 0，Week 1-2）
    • 19.1.3 Phase 2：Agent Team 建立（Sprint 0，Week 2）
    • 19.1.4 Phase 3：開發流程（Sprint 1-5）
    • 19.1.5 Phase 4：CI/CD 整合（Sprint 1）
    • 19.1.6 Phase 5：交付成果清單
  • 19.2 案例二：舊系統逆向工程與現代化
    • 19.2.1 專案背景
    • 19.2.2 Phase 1：Legacy 系統探勘（Month 1）
    • 19.2.3 Phase 2：遷移規劃（Month 1-2）
    • 19.2.4 Phase 3：逐模組遷移（Month 2-5）
    • 19.2.5 Phase 4：驗證與切換（Month 5-6）
    • 19.2.6 交付成果清單
  • 19.3 案例一與案例二的共通學習
    • 19.3.1 關鍵成功因素
    • 19.3.2 常見陷阱與應對
  • 19.4 實務建議
  • 19.5 案例三：批次／排程工作現代化
    • 19.5.1 專案背景
    • 19.5.2 Phase 1：建立正確性基準（Week 1-3）
    • 19.5.3 Phase 2：效能剖析與改造（Week 4-8）
    • 19.5.4 Phase 3：以 Hook 強制稽核紀律（Week 4-8，與 Phase 2 並行）
    • 19.5.5 Phase 4：Scheduled Tasks 建立持續巡檢（Week 9-10）
    • 19.5.6 Phase 5：CI/CD 效能迴歸閘門（Week 10-11）
    • 19.5.7 交付成果清單
    • 19.5.8 本案例的關鍵學習
  • 19.6 案例四：以 Agent Team 進行大型 PR 平行審查
    • 19.6.1 專案背景
    • 19.6.2 為什麼這個場景適合 Agent Team
    • 19.6.3 環境準備
    • 19.6.4 Teammate 定義與模型指派
    • 19.6.5 執行流程
    • 19.6.6 實測數據與成本
    • 19.6.7 遭遇的問題與解法
    • 19.6.8 企業導入的護欄清單
    • 19.6.9 本案例的關鍵學習
• Ch 20：FAQ 與 Troubleshooting
  • 20.1 Agent Teams 為何無法啟動？
  • 20.2 Subagent 為何沒有被自動委派？
  • 20.3 Skills 為何沒有觸發？
  • 20.4 Hooks 為何沒有生效？
  • 20.5 MCP 為何沒有連上？
  • 20.6 Plugins 為何沒有載入？
  • 20.7 VS Code 與 CLI 為何行為不同？
  • 20.8 GitHub Actions 與 GitLab CI/CD 該怎麼選？
  • 20.9 Reverse Engineering 時如何降低幻覺？
  • 20.10 何時該用 subagent，何時該用 agent team？
  • 20.11 何時該用 hook，何時該用 skill？
  • 20.12 如何避免記憶污染與 context 膨脹？
  • 20.13 如何降低 token 成本？
  • 20.14 導入後如何量測 ROI／成效？
  • 20.15 升級 CLI 後 Subagent 突然無法委派或深度受限？
  • 20.16 GitHub Actions Workflow 升級到 @v1 後整個壞掉？
  • 20.17 MCP Server 升級後行為改變或連不上？
  • 20.18 安裝 Plugin 後 Hook 與 MCP Server 沒有生效？
  • 20.19 Skill 數量變多後，部分 Skill 從清單中消失？
  • 20.20 團隊成員的 claude.ai 個人 Skills 出現在企業專案中？
  • 20.21 /loop 建立的排程任務突然停止執行？
  • 20.22 切換 Output Style 後安全規範消失，且找不到 /output-style 指令？
  • 20.23 Subagent 執行到一半中斷，只拿到半截結果？
  • 20.24 CI 中背景執行的指令被提前砍掉？
  • 20.25 如何確認某項功能目前是 GA 還是 Experimental？
  • 20.26 實務建議
• Ch 21：最佳實務、Anti-Patterns 與 Checklist
  • 21.1 企業最佳實務（10 項）
  • 21.2 團隊最佳實務（8 項）
  • 21.3 開發者最佳實務（8 項）
  • 21.4 Reverse Engineering 最佳實務（6 項）
  • 21.5 常見錯誤 / Anti-Patterns（14 個）
  • 21.6 Checklist 1：新團隊導入 Checklist
  • 21.7 Checklist 2：專案初始化 Checklist
  • 21.8 Checklist 3：SSDLC 各階段 Checklist
  • 21.9 Checklist 4：上線前 Checklist
  • 21.10 Checklist 5：升級前 Checklist
  • 21.11 實務建議
• Ch 22：附錄 — 可直接複製使用的完整範本
  • 22.1 範本 1：CLAUDE.md 範本
  • 22.2 範本 2：.claude/settings.json 範本
  • 22.3 範本 3：.mcp.json 範本
  • 22.4 範本 4：Subagent 範本（.claude/agents/security-reviewer.md）
  • 22.5 範本 5：SKILL.md 範本（.claude/skills/security-check/SKILL.md）
  • 22.6 範本 6：Hook 設定範本（settings.json hooks 區塊）
  • 22.7 範本 7：plugin.json 範本
  • 22.8 範本 8：GitHub Actions Workflow 範本（完整 YAML）
  • 22.9 範本 9：GitLab CI/CD Job 範本（完整 YAML）
  • 22.10 範本 10：Reverse Engineering Prompt 範本
  • 22.11 範本 11：Onboarding Checklist 範本
  • 22.12 範本 12：Governance Policy 範本
  • 22.13 實務建議
  • 22.14 附錄：v1.2.0 → v1.3.0 差異對照
    • 22.14.1 必須立即處理的破壞性變更
    • 22.14.2 全新小節一覽（15 節）
    • 22.14.3 大幅擴充的既有小節
    • 22.14.4 建議的閱讀順序
    • 22.14.5 升版後的內部文件更新檢查清單
  • 22.15 附錄：v1.3.0 → v1.4.0 差異對照
    • 22.15.1 必須立即處理的事實性修正
    • 22.15.2 全新小節一覽
    • 22.15.3 擴充的既有小節
    • 22.15.4 目錄與格式
    • 22.15.5 升版後的內部文件更新檢查清單

Ch 0：文件資訊與閱讀指南

0.1 文件基本資訊

0.2 使用前提與先決條件

在閱讀本手冊前，請確認您已具備以下條件：

1. Claude Code 存取權限：已取得企業授權或 API Key，可使用 Claude Code CLI。
2. Claude Code CLI 版本門檻：本手冊以 v2.1.248 為基準。若使用舊版，部分功能將不可用，請對照「2.10 版本門檻速查表」確認最低需求。
3. VS Code v1.94.0+：Claude Code VS Code Extension 需此版本以上方可安裝。
4. Git 版本控制：本手冊所有範例皆假設在 Git 管理的專案中運作。
5. 基本 CLI 操作能力：熟悉終端機指令、環境變數設定。
6. SSDLC 基礎知識：了解安全軟體開發生命週期的基本概念與階段。
7. 公司允許使用之模型：Sonnet 4.6、Opus 4.6、Haiku 4.5（注意：Opus 4.7 雖存在，但不在公司允許清單內）。官方已推出 claude-opus-5、claude-sonnet-5 與 fable 模型別名，但尚未納入公司允許清單，待資安與採購評估後另行公告。

0.3 閱讀地圖

以下表格呈現各章主題、核心內容與建議閱讀順序。依據您的角色，可選擇性閱讀：

0.4 功能狀態標示規則

本手冊中所有功能均標示其穩定性狀態。以下為標示規則與含義：

標示範例：

• Agent Teams 🔴 Experimental — 需設定環境變數 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1，且不支援 -p / SDK 非互動模式
• Agent 類型 Hooks（"type": "agent"）🔴 Experimental — 行為與設定可能變更
• GitHub Actions 🟢 GA — anthropics/claude-code-action@v1（@beta 已停用）
• MCP v2 Runtime 🟢 GA — v2.1.232+，protocol revision 2026-07-28
• GitLab CI/CD 🟡 Beta — 非 GA，需注意破壞性變更風險
• MCP SSE Transport ⚫ Deprecated — 應遷移至 HTTP Transport
• /output-style 指令 ⚫ Deprecated — v2.1.73 棄用、v2.1.91 已移除，改用 /config

0.5 核心名詞定義

以下為本手冊中頻繁使用的核心術語，共 30 項：

0.6 版本變更紀錄

0.7 注意事項

1. 功能狀態可能變動：Experimental / Beta 功能隨版本更新可能升級或移除，請定期查閱官方 Release Notes。
2. 模型限制：公司允許使用之模型為 Sonnet 4.6、Opus 4.6、Haiku 4.5。Opus 4.7 雖已發布但不在允許清單內，切勿於正式環境使用。官方新世代（Opus 5 / Sonnet 5 / fable）同樣待評估。
3. 日期敏感：本手冊資訊基於 2026-08-31 之官方文件（Claude Code v2.1.248），後續功能變更請以官方為準。
4. 官方文件追蹤方式：建議以 https://code.claude.com/docs/llms.txt 取得文件索引，並將本手冊「2.10 版本門檻速查表」作為季度複核基準；每季至少重審一次 Experimental / Beta 項目的狀態變化。
5. 安全合規：所有範例均假設在企業安全政策允許範圍內執行，實際部署前請諮詢資安團隊。

Ch 1：總覽：什麼是 Claude Code SSDLC Agent Team

1.1 為什麼企業需要 SSDLC Agent Team

在現代軟體工程中，SSDLC（安全軟體開發生命週期）涵蓋從需求分析、架構設計、編碼實作、測試驗證、安全審查到部署維運的完整流程。每個階段都需要不同的專業知識與工具鏈。

單一 AI 助手的侷限

一個通用的 AI 助手就像一位「全端全能」的工程師——理論上什麼都能做，但在企業規模的專案中面臨三大瓶頸：

1. 上下文視窗限制：單一 Agent 無法同時載入所有 SSDLC 階段的 context（需求文件、架構圖、測試案例、安全規範）。
2. 角色衝突：同一 Agent 同時扮演「開發者」與「安全審查者」會產生角色衝突——自己寫的程式碼自己審，缺乏制衡。
3. 專業深度不足：每個 SSDLC 階段所需的 Prompt、Tools、Knowledge Base 不同，通用 Agent 無法在所有領域都達到專家水準。

Agent Team 的設計哲學

Agent Team 採用「分工協作」模式，如同真實的軟體開發團隊：

• 需求分析師 Agent：專注於需求拆解與使用者故事撰寫
• 架構師 Agent：負責系統設計與技術選型
• 開發者 Agent：執行編碼實作
• 測試工程師 Agent：撰寫並執行測試
• 安全工程師 Agent：進行安全審查與弱點掃描
• 維運工程師 Agent：處理部署、監控與事件回應

每個 Agent 有各自的 Prompt、Skills、Tools 與 Permission，確保專業分工與安全制衡。

1.2 與其他方法的差異比較

與單一 AI 助手的差異

與單純 Prompt Engineering 的差異

與一般 Code Assistant（如 GitHub Copilot）的差異

1.3 Claude Code 在 SSDLC 各階段的角色

Claude Code Agent Team 涵蓋 SSDLC 的六大核心階段，每個階段可指派一或多個 Agent：

1.4 新系統開發 vs. 舊系統逆向工程

Agent Team 不僅適用於新系統開發，在既有系統的逆向工程（RE）場景同樣有巨大價值：

1.5 整體架構圖

以下 Mermaid 圖呈現 Claude Code SSDLC Agent Team 的整體架構：

flowchart TB
    subgraph Enterprise["🏢 企業環境"]
        direction TB
        MS["Enterprise Managed Settings<br/>managed-settings.json"]
    end

    subgraph Config["⚙️ 設定層級 (Config Hierarchy)"]
        direction LR
        GC["Global Config<br/>~/.claude/"]
        PC["Project Config<br/>.claude/"]
        CM["CLAUDE.md<br/>managed → global → project → local<br/>全部累加"]
    end

    subgraph AgentTeam["🤖 Agent Team 🔴 Experimental"]
        direction TB
        ORC["Orchestrator Agent<br/>(主 Agent)"]

        subgraph Agents["Specialized Agents (Subagents)"]
            direction LR
            RA["需求分析師<br/>Agent"]
            AA["架構師<br/>Agent"]
            DA["開發者<br/>Agent"]
            TA["測試工程師<br/>Agent"]
            SA["安全工程師<br/>Agent"]
            OA["維運工程師<br/>Agent"]
        end
    end

    subgraph Capabilities["🔧 能力模組"]
        direction LR
        SK["Skills<br/>SKILL.md"]
        HK["Hooks<br/>command/http/<br/>mcp_tool/prompt"]
        PL["Plugins<br/>(Subagent 形式)"]
        MC["MCP<br/>HTTP Transport"]
        OS["Output Styles<br/>Default/Explanatory/<br/>Learning"]
    end

    subgraph Automation["🚀 自動化整合"]
        direction LR
        PCLI["Programmatic CLI<br/>🟢 GA"]
        GHA["GitHub Actions<br/>🟢 GA v1"]
        GLC["GitLab CI/CD<br/>🟡 Beta"]
        SCH["Scheduled Tasks<br/>session-scoped<br/>7天/最多50"]
    end

    subgraph SSDLC["📋 SSDLC 階段"]
        direction LR
        REQ["需求分析"]
        DES["架構設計"]
        DEV["編碼開發"]
        TST["測試驗證"]
        SEC["安全審查"]
        OPS["部署維運"]
    end

    Enterprise --> Config
    Config --> AgentTeam
    ORC --> RA & AA & DA & TA & SA & OA
    AgentTeam --> Capabilities
    Capabilities --> Automation
    Automation --> SSDLC
    REQ --> DES --> DEV --> TST --> SEC --> OPS

    style Enterprise fill:#1a1a2e,color:#fff
    style AgentTeam fill:#16213e,color:#fff
    style Capabilities fill:#0f3460,color:#fff
    style Automation fill:#533483,color:#fff
    style SSDLC fill:#e94560,color:#fff

1.6 企業導入價值

1.7 典型使用情境

以下為 Agent Team 最具價值的典型應用場景：

情境 1：全新微服務開發

需求分析師 Agent 將 Jira Ticket 拆解為 User Story → 架構師 Agent 設計 API 規格與 DB Schema → 開發者 Agent 產生 Spring Boot 程式碼 → 測試 Agent 撰寫 JUnit 測試 → 安全 Agent 執行 SAST 掃描 → 維運 Agent 產生 Dockerfile 與 K8s manifest。全程由 Hooks 在每個 Gate 自動品質攔截。

情境 2：舊系統逆向工程

面對一個缺乏文件的 15 年歷史 Java 系統，RE Agent 分析原始碼結構與資料庫 Schema → 自動產生架構理解文件與類別圖 → 測試 Agent 為關鍵模組補上 Characterization Test → 安全 Agent 掃描已知弱點 → 架構師 Agent 提出重構建議與遷移路徑。

情境 3：安全合規稽核自動化

安全 Agent 定期（透過 Scheduled Tasks）掃描 codebase 的依賴套件弱點、硬編碼密鑰、不安全 API 呼叫 → 透過 Hooks 自動建立 Issue → 開發者 Agent 產生修復 PR → 安全 Agent 審查修復結果。整合 GitHub Actions 🟢 GA 在每次 PR 自動觸發。

情境 4：跨團隊 Prompt Library 建設

技術主管透過 Skills + CLAUDE.md 建立公司級 Prompt Library → 不同團隊各自擴展領域專屬 Skills → 所有 Prompt 與 Skill 均 Git 版控 → 新成員 Onboarding 時直接繼承團隊累積的 AI 知識。

情境 5：多語言 / 多框架專案統一治理

一個企業同時有 Java Spring Boot、Node.js Express、Python FastAPI 專案 → 透過 Agent Team 為每種語言框架配置專屬 Subagent → 共用相同的安全 Agent 與 Gate 規則 → 透過 Managed Settings 在組織層級統一推送合規政策。

情境 6：DevSecOps Pipeline 自動化

GitLab CI/CD 🟡 Beta 整合 Programmatic CLI → 在 MR 建立時自動觸發 Code Review Agent → Hook 攔截不符規範的程式碼 → 安全 Agent 掃描後自動添加審查意見 → 通過所有 Gate 後自動 Merge 並部署。

1.8 實務建議

1. 從小處開始：不要一次導入所有 Agent，建議先從「開發 Agent + 測試 Agent + 安全 Agent」三角開始 POC。
2. Experimental 功能審慎評估：Agent Teams 🔴 Experimental 功能僅建議用於 Lab/POC 環境，待升級至 Beta/GA 再用於生產。
3. 版控一切：所有 CLAUDE.md、Skills、Hooks 設定檔皆應納入 Git 版控，不可僅存在於個人環境。
4. 權限最小化：每個 Agent 的 Permission Mode 應設為最小必要權限，避免使用 bypassPermissions。
5. 持續量測：導入後應持續追蹤缺陷率、開發週期、安全弱點數量等指標，用數據驗證效益。

Ch 2：功能盤點與術語對照

本章系統性盤點 Claude Code 生態系的 18 項核心功能，並提供多維度的比較表格，幫助讀者快速釐清各功能的定位、能力與限制。本章內容以 Claude Code v2.1.248（2026-08-31） 為基準。

2.1 18 項功能概述

2.2 功能矩陣表

以下矩陣表從多個維度比較 18 項功能的能力：

2.3 平台差異比較表

四大平台在使用 Claude Code 時的差異：

2.4 概念差異比較表（容易混淆的概念兩兩比較）

以下比較 10 組容易混淆的概念，幫助讀者精確區分：

2.5 功能穩定性狀態對照表（Experimental / Beta / GA）

⚠️ 注意第 23 項的預設值：Cross-Session Messaging 與 Agent Teams 不同，達到版本需求即自動啟用、不需設定任何旗標。企業若未主動評估，該功能會在升級後直接生效。建議在升級至 v2.1.224 之前先依 6.16.5 決定 crossSessionInbound 的組織基準值。

2.6 容易混淆術語表

2.7 Subagent 限制速查表

由於 Subagent 的行為限制在企業使用中極為重要，特此獨立整理：

2.8 Config Hierarchy 與 CLAUDE.md 載入順序速查

┌──────────────────────────────────────────┐
│  Enterprise Managed Settings             │ ← 最高優先（組織推送，不可覆蓋）
│  managed-settings / managed-mcp          │
├──────────────────────────────────────────┤
│  CLAUDE.md 載入（全部累加，非覆蓋）：     │
│  ① managed policy                        │ ← 組織強制
│  ② user global (~/.claude/CLAUDE.md)     │ ← 個人偏好
│  ③ project (.claude/CLAUDE.md)           │ ← 專案規範
│  ④ local (工作目錄 CLAUDE.md)            │ ← 當前目錄
├──────────────────────────────────────────┤
│  Config Files:                           │
│  Global: ~/.claude/                      │ ← 全域設定
│  Project: .claude/                       │ ← 專案設定
└──────────────────────────────────────────┘

2.9 實務建議

1. 優先掌握 GA 功能：22 項盤點項目中有 17 項已 🟢 GA，建議從這些穩定功能開始導入，避免在 Experimental 功能上投入過多架構承諾。
2. 嚴格區分術語：團隊內部應統一使用正確術語（如 Programmatic CLI 而非 Headless），避免溝通混亂。
3. 注意 Subagent 限制：架構設計時務必考慮 Subagent 自 v2.1.172 起雖可巢狀（目前預設深度上限 3，可調整）但 Agent Team teammate 仍不可巢狀、Plugin Subagent 不支援 hooks/mcpServers/permissionMode frontmatter 等限制（詳見 6.7、6.11 節）。
4. MCP Transport 遷移：若現有設定使用 SSE Transport，應儘速遷移至 HTTP Transport，因 SSE 已 ⚫ Deprecated。
5. Agent Team Teammate 設計：透過 Subagent definition 定義 Teammate 時，官方僅明確排除 skills 與 mcpServers 兩個欄位不帶入，其餘欄位（含 tools、model、disallowed-tools、memory 等）維持正常生效，不要誤以為只有 tools/model 有效（詳見 6.11 節）。
6. CLAUDE.md 累加機制：CLAUDE.md 的四層載入是「累加」而非「覆蓋」，因此要注意避免不同層級的指令衝突。
7. 模型選擇：公司允許的三個模型各有適用場景——Sonnet 4.6 平衡速度與品質、Opus 4.6 用於複雜推理、Haiku 4.5 用於高速低成本場景。切勿使用未經允許的 Opus 4.7。
8. GitLab CI/CD 謹慎使用：GitLab 整合仍為 🟡 Beta，用於非關鍵路徑可以，但關鍵 Pipeline 建議等待 GA 或做好回退方案。
9. 建立版本基準線：企業導入應明訂「組織核可的 Claude Code 版本」，並以 2.10 節的版本門檻速查表判斷升版是否會影響既有 Agent／Hook／Workflow 設定。

2.10 版本門檻速查表

Claude Code 採高頻率滾動更新，許多能力有明確的最低版本要求。以下速查表整理 v2.1.63 ~ v2.1.248 之間對 SSDLC Agent Team 架構有實質影響的變更，作為企業升版評估與本手冊季度複核的基準。

關於 Cross-Session Messaging 的版本門檻：此功能的版本需求較特殊（macOS／Linux／WSL 2 為 v2.1.224+、原生 Windows 為 v2.1.234+、主動跨機器發起對話為 v2.1.225+），完整對照表見 6.16.7。

升版評估建議：

1. 標示 ⚠️ 的項目為破壞性變更，升版前必須逐一檢查現有 .claude/ 設定與 CI Workflow。
2. 標示 🔒 的項目為安全強化，建議優先升版取得。
3. 企業應至少每季執行一次本表複核，並將結果記錄於 Ch 18 的維護紀錄。

Ch 3：Claude Code SSDLC Agent Team 企業架構設計

本章定義一個完整的企業級 SSDLC Agent Team，包含 10 個專業化 Agent 角色。每個 Agent 具有明確的職責邊界、工具集、權限策略與建議模型，實現安全軟體開發生命週期的全階段自動化與制衡。

3.1 Agent Team 整體架構圖

以下 Mermaid 圖呈現 10 個 Agent 的角色定位與協作關係：

flowchart TB
    subgraph Orchestrator["🎯 Orchestrator (主 Agent)"]
        ORC["主控制器<br/>負責任務分派與結果彙整<br/>Model: Opus 4.6"]
    end

    subgraph Planning["📋 規劃層"]
        REQ["① Requirements Agent<br/>需求分析 · User Story<br/>Model: Sonnet 4.6<br/>Mode: plan"]
        ARC["② Architect Agent<br/>系統設計 · API 規格<br/>Model: Opus 4.6<br/>Mode: plan"]
    end

    subgraph Development["💻 開發層"]
        BE["③ Backend Agent<br/>後端開發<br/>Model: Sonnet 4.6<br/>Mode: acceptEdits"]
        FE["④ Frontend Agent<br/>前端開發<br/>Model: Sonnet 4.6<br/>Mode: acceptEdits"]
    end

    subgraph Quality["✅ 品質層"]
        TST["⑤ Test Agent<br/>測試設計與執行<br/>Model: Sonnet 4.6<br/>Mode: acceptEdits"]
        SEC["⑥ Security Agent<br/>安全審查 · 弱掃<br/>Model: Opus 4.6<br/>Mode: plan"]
        CR["⑦ Code Review Agent<br/>Code Review · 品質把關<br/>Model: Opus 4.6<br/>Mode: plan"]
    end

    subgraph Operations["🚀 維運層"]
        REL["⑧ Release Agent<br/>部署 · 上線管理<br/>Model: Sonnet 4.6<br/>Mode: acceptEdits"]
    end

    subgraph Specialized["🔍 專業層"]
        RE["⑨ RE Agent<br/>逆向工程 · 現代化<br/>Model: Opus 4.6<br/>Mode: plan"]
        DOC["⑩ Documentation Agent<br/>文件產生 · 維護<br/>Model: Haiku 4.5<br/>Mode: acceptEdits"]
    end

    ORC --> REQ & ARC
    ORC --> BE & FE
    ORC --> TST & SEC & CR
    ORC --> REL
    ORC --> RE & DOC

    REQ -->|需求規格| ARC
    ARC -->|架構設計| BE & FE
    BE & FE -->|程式碼| CR
    CR -->|Review 通過| TST
    TST -->|測試通過| SEC
    SEC -->|安全通過| REL
    RE -->|理解文件| ARC
    DOC -.->|文件更新| REQ & ARC & BE & FE & TST

    style Orchestrator fill:#1a1a2e,color:#fff
    style Planning fill:#16213e,color:#fff
    style Development fill:#0f3460,color:#fff
    style Quality fill:#533483,color:#fff
    style Operations fill:#e94560,color:#fff
    style Specialized fill:#2d4059,color:#fff

3.2 Agent 間協作流程圖

以下流程圖展示典型新功能開發場景中 10 個 Agent 的端對端協作：

sequenceDiagram
    participant PM as Product Manager
    participant REQ as ① Requirements Agent
    participant ARC as ② Architect Agent
    participant BE as ③ Backend Agent
    participant FE as ④ Frontend Agent
    participant CR as ⑦ Code Review Agent
    participant TST as ⑤ Test Agent
    participant SEC as ⑥ Security Agent
    participant DOC as ⑩ Documentation Agent
    participant REL as ⑧ Release Agent

    PM->>REQ: 提交需求
    REQ->>REQ: 拆解 User Story + 驗收條件
    REQ->>ARC: 需求規格文件

    ARC->>ARC: 系統設計 + API 規格
    ARC->>BE: 後端設計文件 + API Contract
    ARC->>FE: 前端設計文件 + Component Spec

    par 平行開發
        BE->>BE: 實作後端程式碼
        FE->>FE: 實作前端程式碼
    end

    BE->>CR: 提交後端程式碼 Review
    FE->>CR: 提交前端程式碼 Review
    CR->>CR: Code Review + 品質檢查

    alt Review 未通過
        CR-->>BE: 回饋修改意見
        CR-->>FE: 回饋修改意見
    else Review 通過
        CR->>TST: 程式碼進入測試
    end

    TST->>TST: 單元測試 + 整合測試
    TST->>SEC: 測試通過，進入安全審查

    SEC->>SEC: SAST/DAST + 弱點掃描 + 合規檢查

    alt 安全未通過
        SEC-->>BE: 安全修復建議
        SEC-->>FE: 安全修復建議
    else 安全通過
        SEC->>REL: 安全審查通過
    end

    REL->>REL: 產生部署腳本 + 執行部署
    DOC->>DOC: 更新 API 文件 + 變更紀錄

    REL->>PM: 部署完成通知

3.3 十個 Agent 角色詳細定義

① Requirements Agent — 需求分析師

② Architect Agent — 架構師

③ Backend Agent — 後端開發

④ Frontend Agent — 前端開發

⑤ Test Agent — 測試工程師

⑥ Security Agent — 安全工程師

⑦ Code Review Agent — 程式碼審查

⑧ Release Agent — 部署管理

⑨ Reverse Engineering Agent — 逆向工程

⑩ Documentation Agent — 文件撰寫

3.4 Subagents vs Agent Teams 比較圖

flowchart LR
    subgraph SubagentModel["Subagent 模式 🟢 GA"]
        direction TB
        MA1["主 Agent"]
        SA1["Subagent A<br/>獨立任務"]
        SA2["Subagent B<br/>獨立任務"]
        SA3["Subagent C<br/>獨立任務"]
        MA1 --> SA1
        MA1 --> SA2
        MA1 --> SA3
        SA1 -.->|"✅ v2.1.172+ 可巢狀<br/>(預設深度 3、併發 20)"| X1["可再呼叫<br/>Subagent"]
    end

    subgraph AgentTeamModel["Agent Team 模式 🔴 Experimental"]
        direction TB
        MA2["Team Lead<br/>(agent type: team-lead)"]
        TA1["Teammate A<br/>skills 不帶入"]
        TA2["Teammate B<br/>skills 不帶入"]
        TA3["Teammate C<br/>skills 不帶入"]
        MA2 <--> TA1
        MA2 <--> TA2
        MA2 <--> TA3
        TA1 <-.-> TA2
        TA2 <-.-> TA3
        TA1 -.->|❌ 不可巢狀 Team| X2["Teammate 無法<br/>再建子 Team"]
    end

    style SubagentModel fill:#1a472a,color:#fff
    style AgentTeamModel fill:#4a1a2e,color:#fff

3.5 Subagent vs Agent Team 決策矩陣

決策流程：

1. 是否為生產環境？ → 是：使用 Subagent
2. 是否需要多 Agent 對話？ → 否：使用 Subagent
3. 是否需在 CI/CD（-p 或 SDK）執行？ → 是：只能用 Subagent（Agent Teams 不支援非互動模式）
4. 是否為 POC/Lab 且需要複雜協作？ → 是：可考慮 Agent Team

3.5.1 Team 的建立、任務分派與通訊機制

自動建立團隊（v2.1.178+）：早期版本需先請 Claude 以 TeamCreate 工具明確建立並命名團隊；v2.1.178 起，TeamCreate/TeamDelete 工具已完全移除，Lead 第一次產生 Teammate 時會自動建立團隊，團隊名稱固定為 session-<session ID 前 8 碼>，且會話結束時自動清理。團隊設定、信箱與任務狀態分別儲存於：

~/.claude/teams/{team-name}/config.json          # 團隊成員（members 陣列：session ID、Agent 類型）
~/.claude/teams/{team-name}/inboxes/{agent}.json # 各 Agent 的郵件信箱
~/.claude/tasks/{team-name}/                     # 共享任務清單與狀態

保留期間：~/.claude/teams/ 下的團隊設定於會話結束時移除；~/.claude/tasks/ 下的任務清單則保留，依 cleanupPeriodDays（預設 30 天）回收。Agent Teams 沒有專案層級的團隊設定，全部存於使用者 home 目錄下。

共享 Task List（任務清單）：Team 內所有 Teammate 共用一份任務清單，每個任務有明確狀態（pending／in-progress／completed），可標註相依關係（任務 B 需等待任務 A 完成）；面板內可用 Ctrl+T 切換任務清單顯示。多個 Teammate 同時修改同一檔案時，採檔案層級鎖定避免競爭寫入衝突。

郵件信箱容錯（v2.1.207+）：若信箱檔案出現格式損壞的項目，Claude Code 會將其回報並自動移除，而非阻斷整個 Team 的訊息傳遞（舊版會卡住）。

Teammate 間的訊息傳遞：Teammate 之間可分享發現、互相挑戰彼此的結論，而非僅單向回報給 Lead；in-process 模式下可用方向鍵切換到目標 Teammate 後按 Enter 直接對其發訊息，按 x 可直接停止指定 Teammate。

Subagent 定義作為 Teammate：Lead 可指示「以 security-reviewer 這個 Subagent 定義啟動一個 Teammate」，直接複用 .claude/agents/*.md 既有定義，無需重新撰寫角色描述。

Effort Level 繼承（v2.1.186+）：Teammate 預設繼承 Lead 當前的 effort level 設定，不需逐個指定（split-pane 模式自 v2.1.186 起一併適用）。

模型決定順序（v2.1.251+）：teammateDefaultModel 設定鍵已於 v2.1.234 移除，若舊設定檔仍保留此鍵將被忽略。現行決定順序（自 v2.1.251 起）為：

1. 產生 Teammate 的 spawn prompt 中為該 Teammate 指名的模型
2. 由 Subagent 定義產生 Teammate 時，該定義檔的 model（值為 inherit 時代表沿用 Lead 的模型）
3. CLAUDE_CODE_SUBAGENT_MODEL（設為 inherit 以外的值時）
4. Lead 當前的模型

⚠️ 破壞性變更：v2.1.251 之前，CLAUDE_CODE_SUBAGENT_MODEL 排在此順序的第一位，會蓋過 spawn prompt 與 Subagent 定義中指定的模型。若企業曾以此環境變數強制統一 Teammate 模型（例如「一律 Sonnet」），升級至 v2.1.251 後該強制效果會被 spawn prompt 或定義檔的 model 覆寫。需要維持強制統一者，應改以 availableModels 允許清單（見 4.8）從組織層限制，而非仰賴環境變數的優先序。

模型允許清單的替換規則：Claude Code 會將選定的模型與組織的 availableModels 允許清單比對。若被封鎖，處理方式為：

Plan Approval（計畫審批）：可在團隊設定中開啟「Teammate 提交計畫後需 Lead／使用者審批才能繼續執行」，適合風險較高的協作任務，在 Teammate 動手修改前多一道把關。

完整限制清單：除「不可巢狀」「skills/mcpServers 不帶入」外，Agent Team 目前還有以下限制：

疑難排解：Teammate 未出現 → 確認 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 已設定且為互動式會話（-p 不支援）；指定的模型沒生效 → 確認是否仍在使用已移除的 teammateDefaultModel；權限提示異常頻繁 → 檢查是否誤用較嚴格的 Permission Mode 但未對應放寬 Teammate 的 tools；發現孤兒 tmux session 殘留 → 確認 Team 結束流程是否被中斷，必要時手動 tmux kill-session 清理。

3.6 Agent 與 SSDLC 階段對應表

3.7 Agent RACI 矩陣

R = Responsible（執行）、A = Accountable（當責）、C = Consulted（諮詢）、I = Informed（通知）

3.8 必須人工審核的清單

以下場景中 Agent 的輸出必須經過人工審核，不可完全自動化：

📌 若以 Agent Team 實作上述多角色協作，TaskCompleted/TeammateIdle 這兩個 Agent Team 專屬 Hook 事件可作為「人工審核前」的自動化第一道關卡（如檢查是否已標記待審核項目），但不能取代上表所列的人工審核本身，詳見 6.12 節。

3.9 權限過大的風險與防範

最小權限原則設計表：

📌 * 實作方式依機制而異，並非直接設定一個 permissionMode frontmatter 欄位：

• 以 Subagent（.claude/agents/*.md）實作（建議做法）：Subagent frontmatter 本身沒有 permissionMode 欄位（見 6.11 節完整欄位表）。「唯讀規劃」效果應透過 tools/disallowed-tools 排除 Write/Edit/Bash 等寫入類工具達成，而不是設定權限模式；「可編輯」則正常給予 Write/Edit 等工具。
• 以 Agent Team Teammate 實作：Teammate 建立當下一律繼承 Lead 的 permission mode，無法在建立時逐一指定不同模式；若需要不同模式，只能在 Teammate 啟動之後個別調整。因此本表「每個角色各自不同權限模式」的設計，若要在建立當下就生效，應以 Subagent + 精確的 tools/disallowed-tools 組合實作，而非寄望 Agent Team 在 spawn 時就能分派差異化權限。

3.10 實務建議

1. 角色分離是核心：開發、審查、安全三大角色必須由不同 Agent 擔任且使用不同 Permission Mode，絕不可合併。
2. Opus 4.6 用於高推理任務：架構設計、安全審查、Code Review 等需要深度推理的角色使用 Opus 4.6；編碼、測試等標準任務使用 Sonnet 4.6；文件撰寫使用 Haiku 4.5 降低成本。
3. Agent Team 暫限 Lab：Agent Teams 🔴 Experimental 目前不建議用於生產流程，使用 Subagent 模式即可滿足大多數場景。
4. 人工閘門不可省略：需求確認、架構決策、安全報告審核、生產部署這四個閘門必須保留人工審核。
5. 定期審查 Agent 權限：每季審查各 Agent 的工具與 MCP 配置，移除不再需要的權限。
6. RACI 矩陣隨組織調整：上述 RACI 矩陣為建議，各團隊應依據組織結構與合規要求調整。

3.11 Agent Teams 架構變更與遷移指引

Agent Teams 自推出以來歷經多次破壞性變更，若團隊在 v2.1.178 之前已建立 Lab 流程，升級後多半無法直接沿用。本節整理變更軌跡、欄位對應與遷移步驟。

3.11.1 破壞性變更時間軸

重要：官方文件已不再宣稱特定的「最低啟用版本」，僅要求開啟 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1。本手冊建議企業以 v2.1.251 以後為基準線，以避免上述任一破壞性變更造成落差。

3.11.2 啟用 Agent Teams 會改變一般委派行為

這是最容易被忽略的副作用：只要環境變數 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 存在，Claude 原本要以「一般 Subagent」啟動的委派，會改以「Teammate」啟動。

因此在生產或 CI 環境中，不應把該環境變數寫進共用的 shell profile 或 Dockerfile，否則會意外改變既有 Subagent 流程的語意（例如 skills 不再帶入）。正確做法是：

# ❌ 錯誤：全域開啟，污染所有 session
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

# ✅ 正確：僅在需要的單次 Lab session 開啟
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 claude

# ✅ 需要臨時關閉時
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=0 claude

3.11.3 Subagent 定義轉為 Teammate 的欄位對應

複用 .claude/agents/*.md 作為 Teammate 時，並非所有 frontmatter 欄位都會生效，且 in-process 與 split-pane（tmux/iterm2）兩種模式行為不同：

實務結論：SSDLC 十個角色中，凡是依賴 Skills 封裝檢核程序（例如 ⑤ Security、⑥ Test、⑩ Documentation）的角色，轉為 Teammate 時必須把 Skill 內容重寫進 Subagent 本文，否則會出現「角色看起來啟動了，但檢核步驟完全沒執行」的靜默失效。

3.11.4 Agent Teams 專屬 Hook 事件

{
  "hooks": {
    "TaskCompleted": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/verify-task-done.sh",
            "timeout": 120
          }
        ]
      }
    ]
  }
}

上述 verify-task-done.sh 若偵測到測試未通過即 exit 2，Claude Code 會拒絕將任務標記為完成，並把腳本的 stderr 內容回饋給 Teammate 要求修正。這是 Agent Teams 目前唯一能程式化強制的品質閘門。

3.11.5 安全提醒：計畫審批會被 Lead 自動代簽

Agent Teams 的權限模型有一個必須寫入風險登錄的特性：

1. Teammate 產生時繼承 Lead 的 Permission Mode，無法在產生當下逐一指定較嚴格的模式。
2. Teammate 觸發的權限提示會浮現在 Lead 的 session 中，由 Lead／使用者統一回應。
3. Teammate 提交的計畫（plan）由 Lead 自動核准，並不會逐一詢問使用者。
4. Auto Permission Mode 的分類器會把「經由 Lead 轉傳的核准」視為不可信來源，因此不會據此放寬後續判斷。

換言之，若 Lead 以 bypassPermissions 或過寬的 dontAsk 啟動，整個 Team 的所有 Teammate 都會繼承該寬鬆權限。企業導入時應於管理式設定（Managed Settings）中設定 permissions.disableBypassPermissionsMode，從組織層面阻斷此路徑（詳見 Ch 12）。

3.11.6 成本與規模建議

{
  "subagentPromptCacheTtl": "1h",
  "teammateMode": "in-process"
}

3.11.7 遷移檢查清單

• 移除所有腳本／文件中對 TeamCreate、TeamDelete 的呼叫與說明
• 移除設定檔中的 teammateDefaultModel 鍵，改用 CLAUDE_CODE_SUBAGENT_MODEL 或 Subagent model
• 移除 Hook 邏輯中對 team_name 的相依，改用 agent name 或 session ID
• 確認 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS 未寫入全域 profile 或容器映像檔
• 對每個要轉為 Teammate 的 Subagent，檢查是否依賴 skills／mcpServers，並依 3.11.3 補救
• 於 Managed Settings 設定 permissions.disableBypassPermissionsMode: true
• 建立 TaskCompleted Hook 作為程式化品質閘門
• 確認 CI/CD 流程未使用 Agent Teams（-p 不支援）

Ch 4：平台安裝與環境建置

本章涵蓋 Claude Code 在 Windows、macOS、Linux 三大平台的完整安裝流程，以及 VS Code Extension、CLI 認證、權限模式設定與企業環境的最佳起始配置。

4.1 安裝前提

在安裝 Claude Code 之前，請確認以下前提已滿足：

4.2 Windows 安裝

Windows 提供三種安裝方式，任選其一即可：

方式一：PowerShell 安裝（推薦）

# 需以系統管理員身份執行 PowerShell
# 前提：已安裝 Git for Windows (https://git-scm.com/download/win)

# 安裝 Claude Code
irm https://claude.ai/install.ps1 | iex

方式二：CMD 安裝

REM 需以系統管理員身份執行 CMD
REM 前提：已安裝 Git for Windows

curl -fsSL https://claude.ai/install.cmd | cmd

方式三：WinGet 安裝

# 使用 Windows Package Manager
winget install Anthropic.ClaudeCode

Windows 安裝驗證

# 驗證安裝成功
claude --version

# 驗證 Git 可用
git --version

⚠️ Windows 特別注意：三種安裝方式皆需要 Git for Windows 作為前提。若尚未安裝 Git，請先至 https://git-scm.com/download/win 下載安裝，或使用 winget install Git.Git。

4.3 macOS 安裝

方式一：Homebrew 安裝（推薦）

# 安裝 Claude Code
brew install claude-code

# 驗證安裝
claude --version

方式二：npm 安裝

# 需已安裝 Node.js 18+
npm install -g @anthropic-ai/claude-code

# 驗證安裝
claude --version

4.4 Linux 安裝

方式一：npm 安裝

# 需已安裝 Node.js 18+
npm install -g @anthropic-ai/claude-code

# 驗證安裝
claude --version

方式二：二進位下載

# 下載最新版二進位
# 請至 Claude Code 官方頁面取得最新下載連結
# 安裝後確認可執行
claude --version

4.5 VS Code Extension 安裝

1. 確認 VS Code 版本 ≥ v1.94.0（Help → About 查看）。
2. 開啟 VS Code → Extensions（Ctrl+Shift+X）。
3. 搜尋 Claude Code 或 Anthropic。
4. 安裝官方 Claude Code Extension。
5. 安裝後重新載入 VS Code。

VS Code Extension 功能：

4.5.1 擴充功能設定（claudeCode.*）

在 VS Code 設定（settings.json）中可調整以下 Extension 行為，企業導入時建議統一管控：

⚠️ 企業治理建議：allowDangerouslySkipPermissions、claudeProcessWrapper 建議透過 VS Code 的 Workspace/Managed Settings 鎖定，避免個別開發者自行開啟高風險模式。

4.5.2 指令與快捷鍵

📌 以上 5 項目前僅提供命令選單（Cmd/Ctrl+Shift+P）觸發方式，未預設快捷鍵；可依團隊習慣自行綁定。

4.5.3 Chrome 瀏覽器自動化（@browser）

VS Code Extension 可搭配「Claude in Chrome」瀏覽器擴充功能（需 v1.0.36 以上），讓 Claude Code 直接操作瀏覽器分頁：

# 在對話中以 @browser 引用目前開啟的瀏覽器分頁
@browser 幫我檢查這個頁面的 Console 錯誤訊息

常見用途：驗證前端頁面渲染結果、讀取瀏覽器 Console/Network 錯誤、輔助 E2E 除錯。企業環境導入前須評估瀏覽器擴充功能的資安政策是否允許安裝第三方擴充功能。

4.5.4 /usage 用量面板（v2.1.174+）

在面板輸入 /usage 可開啟用量儀表板：

• 顯示當前 Session 與本週的用量條（Usage bar）
• 可切換 Day / Week 檢視
• 依 Skill、Subagent、Plugin、MCP Server 分別列出 token 歸因，便於找出高成本來源

企業導入建議定期請團隊成員檢視 /usage，作為 Ch17 成本監控指標表的補充資料來源。

VS Code URI Handler 使用：

# 在瀏覽器或終端機開啟以下 URI，會自動在 VS Code 中開啟 Claude Code
vscode://anthropic.claude-code/open

# 開啟並預填提示詞
vscode://anthropic.claude-code/open?prompt=分析目前專案的技術債

# 開啟並續接指定的 session
vscode://anthropic.claude-code/open?session=<session-id>

4.5.5 IDE MCP Server 安全機制與第三方 Provider 設定

VS Code Extension 內建的 IDE MCP Server（見上方功能表）採以下安全設計，企業導入前應了解：

• 綁定與傳輸：僅綁定 127.0.0.1（本機迴環位址）的隨機埠（10000–65535 範圍），使用未加密的 ws:// WebSocket；由於僅本機可連線，未加密風險可控。
• 認證 Token：連線 Token 存於 ~/.claude/ide/<port>.lock 檔案，權限設為僅擁有者可讀寫（Unix 上為 0600/0700），並透過自訂的 X-Claude-Code-Ide-Authorization Header 驗證每次連線請求。
• Jupyter 執行確認：透過 mcp__ide__executeCode 在 Jupyter Notebook 執行程式碼前，會跳出 Quick Pick 選單要求使用者明確按下「Execute」或「Cancel」，不會靜默執行。

第三方 Provider（Bedrock / Vertex / Foundry）登入設定：企業若統一透過 AWS Bedrock、GCP Vertex AI 或 Microsoft Foundry 存取模型（而非 Anthropic 帳號登入），可將 claudeCode.disableLoginPrompt 設為 true，停用未登入時彈出的 Anthropic 登入提示，改由環境變數或雲端憑證鏈完成認證。

其他企業部署相關設定：

• autoInstallIdeExtension（Claude Code CLI 設定）：控制是否在偵測到支援的 IDE 時自動安裝對應擴充功能；設定環境變數 CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL=1 可停用此自動安裝行為。
• VS Code Restricted Mode：在不受信任的工作區中，建議搭配 VS Code 本身的 Restricted Mode 使用，降低 Extension 在未知專案中執行的風險。
• 移除與重設：解除安裝 Extension 前，可透過命令選單的 Logout 登出帳號；若需完全清除本機殘留設定與快取，需另外手動清除 ~/.claude/ 下的相關檔案。

4.6 CLI 認證方式

Claude Code CLI 支援多種認證方式：

方式一：互動式登入（推薦）

# 開啟瀏覽器進行 OAuth 認證
claude login

方式二：API Key 環境變數

# Linux / macOS
export ANTHROPIC_API_KEY="sk-ant-xxxxxxxxxxxxx"

# Windows PowerShell
$env:ANTHROPIC_API_KEY = "sk-ant-xxxxxxxxxxxxx"

# Windows CMD
set ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxx

方式三：設定檔（企業環境推薦）

# 全域設定
# ~/.claude/settings.json 中設定認證相關資訊

⚠️ 安全提醒：API Key 不應硬編碼在任何版控檔案中。使用環境變數或安全的 Secret 管理工具（如 HashiCorp Vault、AWS Secrets Manager）。

4.7 Permission Mode 比較表

Claude Code 提供六種權限模式，控制 Agent 的操作範圍（manual 為 default 的別名，不另立一列）：

📌 版本與治理提醒：auto 與 dontAsk 是較晚加入的模式，早期文件或教材若仍只列出 default/plan/acceptEdits/bypassPermissions 四種，屬於過時資訊。企業可透過 [permissions.disableBypassPermissionsMode](Managed Settings) 完全鎖死 bypassPermissions，此時即使 Subagent frontmatter 指定該模式也會被忽略、改用主對話的模式執行。

Permission Mode 選用決策：

是否為唯讀分析/規劃任務？
├── 是 → plan
└── 否 → 是否需要寫入檔案？
    ├── 否 → default
    └── 是 → 是否需要自動執行 Shell 指令？
        ├── 否 → acceptEdits
        └── 是 → 是否在 CI/CD 環境？
            ├── 是 → acceptEdits（CI/CD 中通常搭配 --allowedTools 限制）
            └── 否 → ⚠️ 除非有強烈理由，否則不建議使用 bypassPermissions

4.8 公司允許模型設定

在 .claude/settings.json 中設定公司允許使用的模型：

{
  "model": "sonnet",
  "permissions": {
    "allow": [],
    "deny": []
  }
}

公司允許模型清單：

⚠️ Opus 4.7 雖已發布，但不在公司允許清單內，切勿使用。使用未經允許的模型可能違反企業合規政策。

4.9 最佳起始設定

全域設定 ~/.claude/settings.json

{
  "model": "sonnet",
  "permissions": {
    "allow": [
      "Read",
      "Edit",
      "Bash(git *)",
      "Bash(npm *)",
      "Bash(mvn *)",
      "Bash(dotnet *)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(sudo *)",
      "Bash(curl * | sh)",
      "Bash(curl * | bash)"
    ]
  }
}

專案設定 .claude/settings.json

{
  "model": "sonnet",
  "permissions": {
    "allow": [
      "Read",
      "Edit",
      "Bash(npm run *)",
      "Bash(npm test)",
      "Bash(mvn compile)",
      "Bash(mvn test)"
    ],
    "deny": [
      "Bash(rm -rf /)",
      "Bash(git push --force)",
      "Bash(DROP TABLE *)",
      "Bash(curl * | sh)"
    ]
  }
}

個人本地設定 .claude/settings.local.json

{
  "model": "sonnet",
  "permissions": {
    "allow": [
      "Bash(docker *)",
      "Bash(kubectl *)"
    ],
    "deny": []
  }
}

💡 settings.local.json 不應加入版控（應列入 .gitignore），用於個人特有的工具授權。

4.10 常見安裝錯誤與排除

4.11 實務建議

1. Git for Windows 是 Windows 必要前提：所有三種 Windows 安裝方式都依賴 Git。請在安裝 Claude Code 之前先安裝 Git for Windows。
2. VS Code 版本必須 ≥ v1.94.0：低於此版本的 VS Code 無法安裝或使用 Claude Code Extension 的完整功能。
3. API Key 安全管理：永遠不要將 API Key 寫入 .claude/settings.json 或任何版控檔案。使用環境變數或企業 Secret 管理工具。
4. Permission Mode 預設用 default 或 plan：除非有明確需求，否則不要使用 bypassPermissions。日常開發使用 acceptEdits 即可。
5. 模型選擇影響成本：Opus 4.6 的成本顯著高於 Sonnet 4.6，僅在需要深度推理時使用。Haiku 4.5 成本最低，適合文件產生等輕量任務。
6. 企業環境統一管理：建議由 IT 或架構團隊統一發布安裝指引與 settings.json 範本，確保全公司設定一致。

4.12 VS Code Extension 版本門檻與無障礙支援

VS Code Extension 的功能大量綁定底層 Claude Code CLI 版本。企業在鎖定 CLI 版本時，必須同時確認團隊所需的 Extension 功能是否已可用，否則會出現「功能在文件上有、實際卻找不到」的落差。

4.12.1 功能版本門檻速查

⚠️ v2.1.225 的權限模式行為變更值得特別注意：許多團隊原本以 Workspace 層級 settings.json 為特定高風險專案設定較嚴格的 claudeCode.initialPermissionMode。自 v2.1.225 起此做法不再生效，Extension 一律讀取使用者層級設定。專案層級的權限收緊必須改由 .claude/settings.json 的 permissions 規則與 Managed Settings 承擔（見 Ch 16）。

4.12.2 無障礙（Accessibility）支援

自 v2.1.236 起，Extension 強化了螢幕閱讀器支援。企業在導入時建議一併確認以下配套：

4.12.3 問題回報管道

自 v2.1.229 起，面板內建兩個回報指令，可在遇到問題時直接送出，不需另外開瀏覽器：

📌 企業合規提醒：回報內容可能包含當前對話的上下文。在處理敏感專案時，送出前應確認內容不含機密程式碼、憑證或個資；受規範環境建議改走內部 IT 服務台流程，並於教育訓練中明確說明（呼應 Ch 16 的資料分級政策）。

Ch 5：專案初始化與標準目錄設計

本章設計一個可複製的企業級 Claude Code 專案骨架，涵蓋所有必要的設定檔、目錄結構、命名規範與版本控管策略。此骨架可作為企業內所有新專案的起始範本（Starter Repository）。

5.1 標準目錄樹

project-root/
├── CLAUDE.md                          # 專案級記憶與規範（Claude Code 自動載入）
├── .claude/                           # Claude Code 設定根目錄
│   ├── settings.json                  # 專案級設定（進版控）
│   ├── settings.local.json            # 個人本地設定（不進版控）
│   ├── agents/                        # 自訂 Subagent 定義
│   │   ├── requirements-agent.md      # ① 需求分析 Agent
│   │   ├── architect-agent.md         # ② 架構師 Agent
│   │   ├── backend-agent.md           # ③ 後端開發 Agent
│   │   ├── frontend-agent.md          # ④ 前端開發 Agent
│   │   ├── test-agent.md              # ⑤ 測試 Agent
│   │   ├── security-agent.md          # ⑥ 安全 Agent
│   │   ├── code-review-agent.md       # ⑦ Code Review Agent
│   │   ├── release-agent.md           # ⑧ 部署 Agent
│   │   ├── re-agent.md                # ⑨ 逆向工程 Agent
│   │   └── documentation-agent.md     # ⑩ 文件 Agent
│   ├── skills/                        # 可重用 Skill 定義
│   │   ├── code-generation/           # 程式碼產生相關 Skill
│   │   │   └── SKILL.md
│   │   ├── testing/                   # 測試相關 Skill
│   │   │   └── SKILL.md
│   │   ├── security-scan/             # 安全掃描 Skill
│   │   │   └── SKILL.md
│   │   └── documentation/             # 文件撰寫 Skill
│   │       └── SKILL.md
│   ├── hooks/                         # Hook 腳本
│   │   ├── pre-commit-check.sh        # commit 前品質檢查
│   │   ├── security-gate.sh           # 安全閘門腳本
│   │   ├── lint-check.sh              # Lint 檢查
│   │   └── notify-webhook.sh          # 通知 Webhook
│   ├── output-styles/                 # 自訂輸出風格
│   │   ├── concise.md                 # 精簡風格
│   │   ├── detailed.md                # 詳細風格
│   │   └── learning.md                # 教學風格
│   └── loop.md                        # 持續任務指引（/loop 使用）
├── .mcp.json                          # MCP Server 設定
├── prompt-library/                    # Prompt 範本庫
│   ├── requirements/                  # 需求分析 Prompt
│   │   └── user-story-template.md
│   ├── architecture/                  # 架構設計 Prompt
│   │   └── system-design-template.md
│   ├── development/                   # 開發 Prompt
│   │   └── code-generation-template.md
│   ├── testing/                       # 測試 Prompt
│   │   └── test-case-template.md
│   ├── security/                      # 安全 Prompt
│   │   └── security-review-template.md
│   └── release/                       # 部署 Prompt
│       └── release-checklist-template.md
├── governance/                        # 治理文件
│   ├── agent-policy.md                # Agent 使用政策
│   ├── model-usage-policy.md          # 模型使用規範
│   ├── data-handling-policy.md        # 資料處理規範
│   └── audit-log-policy.md            # 稽核日誌規範
├── security/                          # 安全基線
│   ├── security-baseline.md           # 安全基線文件
│   ├── owasp-checklist.md             # OWASP Top 10 檢核表
│   ├── dependency-policy.md           # 依賴套件安全政策
│   └── secret-management.md           # 密鑰管理規範
├── re-baseline/                       # 逆向工程基線
│   ├── system-inventory.md            # 系統清冊
│   ├── architecture-snapshot.md       # 架構快照
│   ├── dependency-map.md              # 依賴關係圖
│   └── tech-debt-register.md          # 技術債登記表
├── .gitignore                         # Git 忽略規則
└── src/                               # 專案原始碼（依語言/框架調整）
    └── ...

5.2 每個檔案與目錄用途說明

5.3 核心設定檔範例

CLAUDE.md（專案級記憶）

# Project: enterprise-web-app

## 專案概述
這是一個企業級 Web 應用程式，使用 Java Spring Boot 後端 + React 前端。

## 編碼規範
- Java: 使用 Google Java Style Guide
- React: 使用 ESLint + Prettier
- 命名: 類別 PascalCase、方法 camelCase、常數 UPPER_SNAKE_CASE
- 測試: 每個 Service 類別必須有對應的單元測試，覆蓋率 ≥ 80%
- 日誌: 使用 SLF4J + Logback，禁止 System.out.println

## 架構原則
- 分層架構: Controller → Service → Repository
- API 設計: RESTful，版本控制 /api/v1/
- 錯誤處理: 統一 GlobalExceptionHandler
- 安全: 禁止硬編碼密鑰，使用環境變數或 Vault

## 禁止事項
- 不可使用 Opus 4.7 模型
- 不可在程式碼中硬編碼任何密鑰、密碼、Token
- 不可使用 bypassPermissions 權限模式
- 不可跳過單元測試直接提交
- 不可使用 MCP SSE Transport（已 Deprecated）

## Git 工作流
- 分支策略: GitFlow (main / develop / feature/ / hotfix/)
- Commit Message: Conventional Commits (feat: / fix: / docs: / test:)
- PR: 必須通過 Code Review Agent 審查

.claude/settings.json（專案設定）

{
  "model": "sonnet",
  "permissions": {
    "allow": [
      "Read",
      "Edit",
      "Bash(mvn compile)",
      "Bash(mvn test)",
      "Bash(mvn verify)",
      "Bash(npm run build)",
      "Bash(npm test)",
      "Bash(npm run lint)",
      "Bash(git status)",
      "Bash(git diff *)",
      "Bash(git log *)",
      "Bash(git add *)",
      "Bash(git commit *)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(sudo *)",
      "Bash(git push --force *)",
      "Bash(git reset --hard *)",
      "Bash(curl * | sh)",
      "Bash(curl * | bash)",
      "Bash(DROP TABLE *)",
      "Bash(DELETE FROM * WHERE 1=1)",
      "Bash(chmod 777 *)"
    ]
  }
}

.claude/settings.local.json（個人本地設定，不進版控）

{
  "permissions": {
    "allow": [
      "Bash(docker build *)",
      "Bash(docker run *)",
      "Bash(kubectl apply *)",
      "Bash(kubectl get *)"
    ],
    "deny": []
  }
}

.mcp.json（MCP Server 設定）

{
  "mcpServers": {
    "database": {
      "type": "http",
      "url": "http://localhost:3100/mcp",
      "headers": {
        "Authorization": "Bearer ${DB_MCP_TOKEN}"
      }
    },
    "jira": {
      "type": "http",
      "url": "http://localhost:3200/mcp",
      "headers": {
        "Authorization": "Bearer ${JIRA_MCP_TOKEN}"
      }
    }
  }
}

⚠️ MCP 使用 HTTP Transport（"type": "http"），勿使用已 ⚫ Deprecated 的 SSE Transport。

.claude/agents/security-agent.md（Subagent 定義範例）

---
name: security-agent
description: 安全工程師 Agent，負責 SAST/DAST 掃描、弱點檢查與合規驗證
model: opus
allowed-tools:
  - Read
  - "Bash(npm audit)"
  - "Bash(mvn dependency-check:check)"
  - "Bash(trivy *)"
  - "Bash(semgrep *)"
---

# Security Agent

你是一位企業級安全工程師 Agent，專門負責：

1. **SAST 掃描**：使用 Semgrep 進行靜態程式碼安全分析
2. **依賴弱點檢查**：使用 npm audit / OWASP Dependency-Check 掃描依賴套件
3. **容器掃描**：使用 Trivy 掃描 Docker Image 弱點
4. **合規驗證**：檢查 OWASP Top 10 合規性

## 行為規範
- 僅產出安全報告與修復建議，**不直接修改程式碼**
- 弱點嚴重性分級：Critical > High > Medium > Low > Info
- Critical 與 High 弱點必須標記為「阻塞」（blocking），阻止進入下一階段
- 所有發現必須包含 CWE/CVE 編號（若適用）

.claude/skills/security-scan/SKILL.md（Skill 定義範例）

---
name: security-scan
description: 執行全面的安全掃描，包含 SAST、依賴弱點與容器掃描
allowed-tools:
  - Read
  - "Bash(semgrep *)"
  - "Bash(npm audit *)"
  - "Bash(trivy *)"
paths:
  - "src/**"
  - "package.json"
  - "pom.xml"
  - "Dockerfile"
---

# Security Scan Skill

## 執行步驟

1. 使用 Semgrep 對 src/ 目錄執行 SAST 掃描
2. 檢查 package.json / pom.xml 的依賴弱點
3. 若有 Dockerfile，使用 Trivy 掃描容器映像
4. 彙整所有發現，按嚴重性排序

## 輸出格式

以 Markdown 表格輸出掃描結果：
- 弱點 ID (CWE/CVE)
- 嚴重性 (Critical/High/Medium/Low)
- 檔案路徑與行號
- 說明與修復建議

.claude/hooks/ 設定（在 settings.json 中定義 Hook）

Hook 的觸發規則定義在 settings.json 或 .claude/settings.json 中：

{
  "hooks": {
    "preCommit": [
      {
        "type": "command",
        "command": ".claude/hooks/pre-commit-check.sh"
      }
    ],
    "postResponse": [
      {
        "type": "command",
        "command": ".claude/hooks/lint-check.sh"
      }
    ]
  }
}

Hook 腳本範例 — .claude/hooks/pre-commit-check.sh：

#!/bin/bash
# Pre-commit 品質檢查 Hook
# Exit code 2 = 阻止操作（block operation）

echo "🔍 Running pre-commit checks..."

# 檢查是否有硬編碼密鑰
if grep -rn "password\s*=\s*['\"]" src/ --include="*.java" --include="*.ts" --include="*.js"; then
    echo "❌ 發現硬編碼密鑰！禁止提交。"
    exit 2  # Exit code 2 = block operation
fi

# 檢查是否有 TODO/FIXME 未處理
TODO_COUNT=$(grep -rn "TODO\|FIXME" src/ --include="*.java" --include="*.ts" | wc -l)
if [ "$TODO_COUNT" -gt 10 ]; then
    echo "⚠️ 發現 $TODO_COUNT 個 TODO/FIXME，超過閾值 10。"
    exit 2
fi

echo "✅ Pre-commit checks passed."
exit 0

.claude/output-styles/concise.md（自訂輸出風格範例）

---
name: concise
description: 精簡輸出風格，適用於資深工程師
---

## 輸出規則
- 直接給出答案，不需要解釋基礎概念
- 程式碼區塊不加額外說明，除非有非直覺的設計
- 錯誤訊息只顯示關鍵資訊與修復步驟
- 不使用 emoji
- 最多 3 個要點

.claude/loop.md（持續任務指引）

# Loop Task Configuration

## 持續監控任務
- 監控 src/ 目錄的檔案變更
- 每次變更後自動執行 lint 檢查
- 發現問題時輸出建議修復方案

## 終止條件
- 使用者明確停止
- 連續 3 次無變更
- 達到 Scheduled Task 上限（最多 50 個）

5.4 命名規範

5.5 版本控管策略

5.6 .gitignore 建議

# ==============================
# Claude Code 個人與暫存
# ==============================
.claude/settings.local.json
.claude/cache/
.claude/tmp/

# ==============================
# 機敏資訊
# ==============================
*.key
*.pem
*.env
.env
.env.local
.env.*.local

# ==============================
# IDE 與編輯器
# ==============================
.vscode/settings.json
.idea/
*.swp
*.swo
*~

# ==============================
# 建置產出
# ==============================
target/
dist/
build/
node_modules/
*.class
*.jar
*.war

# ==============================
# 日誌與暫存
# ==============================
logs/
*.log
tmp/

5.7 Plugins 與 Marketplace 策略

Plugins 以 Subagent 形式執行，需注意其限制：

5.8 快速初始化腳本

以下腳本可一鍵初始化標準目錄結構：

#!/bin/bash
# init-claude-project.sh — 初始化 Claude Code SSDLC 專案骨架
# 使用方式: bash init-claude-project.sh <project-name>

PROJECT_NAME=${1:-"my-project"}

echo "🚀 Initializing Claude Code SSDLC project: $PROJECT_NAME"

# 建立目錄結構
mkdir -p "$PROJECT_NAME"/.claude/{agents,skills,hooks,output-styles}
mkdir -p "$PROJECT_NAME"/prompt-library/{requirements,architecture,development,testing,security,release}
mkdir -p "$PROJECT_NAME"/governance
mkdir -p "$PROJECT_NAME"/security
mkdir -p "$PROJECT_NAME"/re-baseline
mkdir -p "$PROJECT_NAME"/src

# 建立核心檔案
touch "$PROJECT_NAME"/CLAUDE.md
touch "$PROJECT_NAME"/.claude/settings.json
touch "$PROJECT_NAME"/.claude/settings.local.json
touch "$PROJECT_NAME"/.claude/loop.md
touch "$PROJECT_NAME"/.mcp.json
touch "$PROJECT_NAME"/.gitignore

# 建立 Agent 定義檔
for agent in requirements-agent architect-agent backend-agent frontend-agent \
             test-agent security-agent code-review-agent release-agent \
             re-agent documentation-agent; do
    touch "$PROJECT_NAME"/.claude/agents/"$agent".md
done

echo "✅ Project skeleton created at: $PROJECT_NAME/"
echo "📁 Next steps:"
echo "   1. Edit CLAUDE.md with project-specific rules"
echo "   2. Configure .claude/settings.json"
echo "   3. Define agents in .claude/agents/"
echo "   4. Set up MCP servers in .mcp.json"

Windows PowerShell 版本：

# init-claude-project.ps1 — 初始化 Claude Code SSDLC 專案骨架
# 使用方式: .\init-claude-project.ps1 -ProjectName "my-project"

param(
    [string]$ProjectName = "my-project"
)

Write-Host "🚀 Initializing Claude Code SSDLC project: $ProjectName" -ForegroundColor Cyan

# 建立目錄結構
$dirs = @(
    "$ProjectName\.claude\agents",
    "$ProjectName\.claude\skills",
    "$ProjectName\.claude\hooks",
    "$ProjectName\.claude\output-styles",
    "$ProjectName\prompt-library\requirements",
    "$ProjectName\prompt-library\architecture",
    "$ProjectName\prompt-library\development",
    "$ProjectName\prompt-library\testing",
    "$ProjectName\prompt-library\security",
    "$ProjectName\prompt-library\release",
    "$ProjectName\governance",
    "$ProjectName\security",
    "$ProjectName\re-baseline",
    "$ProjectName\src"
)

foreach ($dir in $dirs) {
    New-Item -ItemType Directory -Path $dir -Force | Out-Null
}

# 建立核心檔案
$files = @(
    "$ProjectName\CLAUDE.md",
    "$ProjectName\.claude\settings.json",
    "$ProjectName\.claude\settings.local.json",
    "$ProjectName\.claude\loop.md",
    "$ProjectName\.mcp.json",
    "$ProjectName\.gitignore"
)

foreach ($file in $files) {
    New-Item -ItemType File -Path $file -Force | Out-Null
}

# 建立 Agent 定義檔
$agents = @(
    "requirements-agent", "architect-agent", "backend-agent", "frontend-agent",
    "test-agent", "security-agent", "code-review-agent", "release-agent",
    "re-agent", "documentation-agent"
)

foreach ($agent in $agents) {
    New-Item -ItemType File -Path "$ProjectName\.claude\agents\$agent.md" -Force | Out-Null
}

Write-Host "✅ Project skeleton created at: $ProjectName\" -ForegroundColor Green
Write-Host "📁 Next steps:" -ForegroundColor Yellow
Write-Host "   1. Edit CLAUDE.md with project-specific rules"
Write-Host "   2. Configure .claude\settings.json"
Write-Host "   3. Define agents in .claude\agents\"
Write-Host "   4. Set up MCP servers in .mcp.json"

5.9 實務建議

1. CLAUDE.md 是專案的「靈魂」：這是 Claude Code 啟動時第一個載入的檔案，務必認真撰寫。載入順序為 managed policy → user global → project → local，全部累加。
2. settings.local.json 絕對不進版控：此檔案包含個人授權與偏好，必須列入 .gitignore。
3. MCP Token 使用環境變數：.mcp.json 中的認證 Token 必須使用 ${ENV_VAR} 語法引用環境變數，不可硬編碼。
4. Hook 腳本 Exit Code 2：Hook 腳本回傳 exit code 2 會**阻止（block）**操作，這是安全閘門的核心機制。
5. Skill 必須命名為 SKILL.md：Claude Code 約定 Skill 定義檔必須為大寫的 SKILL.md，放在以 Skill 名稱命名的子目錄中。
6. Plugin Subagent 的 frontmatter 限制：Plugin 不支援 hooks、mcpServers、permissionMode 等 frontmatter，若需要這些能力，應使用一般 Subagent 而非 Plugin。
7. 初始化後立即 Git Init：建立骨架後應立即 git init 並建立首次 commit，確保所有設定從一開始就有版本紀錄。
8. Starter Repository 策略：建議將此骨架做成 GitHub/GitLab Template Repository，每個新專案直接 fork 或 create from template。

Ch 6：建立 Agent 與 Subagent

6.1 概念總覽：Subagent、Custom Subagent 與 Agent Team Teammate

Claude Code 提供三種「子代理」機制，各自有不同的隔離等級、觸發方式與適用場景。理解它們的差異是設計 Agent 架構的基礎。

graph TD
    subgraph MainConversation["主對話 (Main Conversation)"]
        User["👤 使用者"] --> Lead["🤖 Lead Agent / Main Claude"]
    end

    subgraph SubagentExecution["Subagent 執行 (隔離 Context)"]
        Lead -->|"委派任務"| SA1["🔧 Subagent A"]
        Lead -->|"委派任務"| SA2["🔧 Subagent B"]
        SA1 -->|"回傳摘要"| Lead
        SA2 -->|"回傳摘要"| Lead
    end

    subgraph AgentTeam["Agent Team (Experimental)"]
        Lead2["🎯 Lead Agent"] -->|"持續協作"| TM1["🧑‍💻 Teammate 1"]
        Lead2 -->|"持續協作"| TM2["🛡️ Teammate 2"]
        TM1 -->|"回報 + 可被再次呼叫"| Lead2
        TM2 -->|"回報 + 可被再次呼叫"| Lead2
    end

    style MainConversation fill:#e8f5e9
    style SubagentExecution fill:#fff3e0
    style AgentTeam fill:#fce4ec

6.2 Subagent 與主對話的差異

核心差異：Context 隔離

Subagent 擁有完全獨立的 context window，這意味著：

1. 不共享對話歷史：Subagent 看不到主對話中先前的討論內容。
2. 不共享檔案讀取快取：Subagent 必須自行讀取所需檔案。
3. 僅回傳摘要：任務完成後，Subagent 將結果壓縮為摘要回傳給主對話，細節不會帶回。
4. 不繼承 MCP 連線狀態：若 Subagent 需要 MCP 工具，必須在 frontmatter 中明確指定。

何時使用 Subagent vs. 直接在主對話處理？

6.3 Subagent vs. Agent Team 比較

6.4 自動呼叫 vs. 明確呼叫

自動呼叫：Claude 根據 subagent 的 description 欄位判斷是否適合委派。description 越精確，自動匹配越準確。

明確呼叫：使用 @agent-name 語法直接指定。適用於需要確定性的場景。

# 自動呼叫 — Claude 根據 description 決定是否委派
> 請審查這段程式碼的安全性

# 明確呼叫 — 直接指定 Agent
> @security-reviewer 請審查 src/auth/login.java 的安全性

6.5 前景 vs. 背景執行與 Fork Mode

• 前景執行（預設）：主對話等待 Subagent 完成才繼續。適用於結果影響後續步驟的場景。
• 背景執行：Subagent 在背景獨立運作，主對話可繼續進行。適用於獨立任務（如跑測試、產報告）。

Fork Mode（/subtask，v2.1.212+）

Fork Mode 與一般具名 Subagent 的 context 隔離方向恰好相反，容易誤解，需特別釐清：

• Forked Subagent：以「複製主對話」的方式啟動，繼承目前為止的完整對話——相同的 system prompt、tools、model 與訊息歷史，如同在主對話上開一個分支繼續深入處理。透過 /subtask 指令或 fork 這個內建 subagent type 觸發（也可用 CLAUDE_CODE_FORK_SUBAGENT 環境變數控制），並非透過 frontmatter 欄位設定；巢狀的 context: 加 fork: true 寫法不是有效語法。
• 一般具名 Subagent（.claude/agents/*.md，預設）：啟動時是全新、獨立的 context，只會收到委派時提供的任務描述，看不到主對話的歷史訊息。

指令改名與預設值變更（重要）：

自 v2.1.232 起，互動式會話預設啟用 Fork Mode——Claude 會在判斷有利時自動以 fork 方式展開子任務，不需要使用者手動下 /subtask。-p（headless）與 Agent SDK 模式不受影響，仍預設關閉。

# 以 fork 方式延續目前對話的完整 context 去做深入分析
/subtask 請深入分析目前討論的 auth 模組，列出所有可能的安全風險

# 一般具名 Subagent：全新 context，只知道被指派的任務描述
claude --agent heavy-analyzer  # heavy-analyzer.md 內容見 6.8 節範例

明確控制 Fork Mode：

# 強制開啟（例如在 -p 模式想要 fork 行為）
CLAUDE_CODE_FORK_SUBAGENT=1 claude -p "..."

# 強制關閉（例如企業要求所有委派都必須是乾淨 context）
CLAUDE_CODE_FORK_SUBAGENT=0 claude

若需在組織層面全面禁止，可於權限設定加入 deny 規則：

{
  "permissions": {
    "deny": ["Agent(fork)"]
  }
}

Fork Mode 注意事項：

• 兩種模式回傳的摘要都會注入主對話 context，因此串接過多 Subagent 仍可能造成主對話 context 膨脹
• Forked Subagent 共用主對話的 prompt cache，因此 token 成本遠低於重新載入完整系統提示的一般 Subagent
• Forked Subagent 不能再產生下一層 fork，也不受 CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH 的巢狀深度計算影響
• 一般具名 Subagent 的獨立 context 特性，適合用來隔離大量檔案讀取、避免污染主對話（例如 RE 分析、大型模組掃描）
• Subagent 支援自動壓縮（auto-compaction）：當 context 接近上限時自動摘要壓縮

企業合規提醒：由於 Fork 會完整繼承主對話內容，若主對話已載入敏感資料（客戶個資、金鑰片段），該內容會一併進入 Forked Subagent。處理受規範資料的專案應以 Agent(fork) deny 規則或 CLAUDE_CODE_FORK_SUBAGENT=0 明確關閉此行為。

側問題請用 /btw 而非開 Subagent

若只是想在工作進行中問一個與當前任務無關的小問題（例如「這個指令的參數是什麼意思」），使用 /btw 提問，Claude 會在不污染主任務 context、也不產生 Subagent 成本的情況下回答，比開一個 Subagent 更省成本也更不易打斷工作流。

–agent Flag（CLI 模式）

透過 CLI 可直接啟動特定 Agent：

# 直接以特定 Agent 啟動 Claude Code
claude --agent security-reviewer

# 搭配 Programmatic CLI 使用
claude -p "分析 src/auth/ 的安全性" --agent re-analyzer

6.6 權限、Tools、Model 與 Isolation

權限控制：

• allowed-tools / tools：白名單，僅列出的工具可用。
• disallowed-tools：黑名單，排除特定工具。
• 未指定時，繼承主對話的工具權限。
• ⚠️ v2.1.208+：若 tools 列表內的名稱全數無法解析到實際工具（常見於 MCP 工具名拼錯或伺服器未連線），Claude Code 會拒絕啟動該 Subagent 而非静默退回「無工具可用」，以避免形成假性通過。

Model 覆寫：

• 透過 model frontmatter 可讓 Subagent 使用不同模型，可填 sonnet / opus / haiku 等別名、完整模型 ID，或 inherit（跟隨主對話）。
• 常見策略：主對話用 Sonnet 4.6（快速），安全審查用 Opus 4.6（深度分析）。
• ⚠️ 公司允許模型：Sonnet 4.6、Opus 4.6、Haiku 4.5。
• 另可以 CLAUDE_CODE_SUBAGENT_MODEL 環境變數統一指定所有 Subagent 的模型；設為 inherit 等同於未設定。

Isolation 設定（v2.1.117+）：

• isolation: worktree：Subagent 在獨立的 Git worktree 中運作，檔案修改完全隔離。
• 適用於大規模重構等具破壞性的操作。

---
name: refactor-agent
description: "Large-scale refactoring in isolated worktree"
model: claude-sonnet-5
isolation: worktree    # ← 自動建立 Git worktree 隔離
tools:
  - Read
  - Write
  - Edit
  - Bash
---

Persistent Memory（持久記憶）：

Subagent 可透過 memory frontmatter 啟用跨 session 保留的持久記憶。memory 欄位是一個 scope enum（user / project / local），對應到固定的儲存目錄，而非任意路徑：

---
name: re-analyzer
memory: project    # ← 持久化至 .claude/agent-memory/re-analyzer/，跨 session 保留分析結果
---

📌 若需要讓 Subagent 讀取既有的基線資料（如前次 RE 分析產出），直接在 Prompt 或 body 中以相對路徑引用即可（例如「請參考 re-baseline/ 目錄下的既有分析結果」），不需要額外的 frontmatter 欄位。

Permission Mode 與 disallowed-tools 的互動：

Subagent 的 disallowed-tools 與主對話的 Permission Mode 是兩道獨立的限制，取交集中最嚴格者：

• 若主對話為 acceptEdits（編輯自動核准），但 Subagent frontmatter 設定 disallowed-tools: [Edit]，則該 Subagent 在執行期間仍不可使用 Edit——disallowed-tools 不會被父層較寬鬆的權限模式覆寫。
• 反之，若主對話為 plan（不執行任何操作），即使 Subagent 未設定 disallowed-tools，該 Subagent 仍只能規劃、不能實際執行——父層的限制一樣會套用到 Subagent。
• 實務建議：安全審查、唯讀分析類 Subagent 應同時設定 disallowed-tools 排除寫入類工具，而非只依賴主對話的 Permission Mode，避免主對話模式被切換後 Subagent 權限跟著放寬。

MCP Server 繼承規則：

• Subagent 不會自動繼承主對話已連線的 MCP Server；需在 frontmatter 中明確以 mcpServers 欄位指定才能使用。
• 例外：以 Agent Team Teammate 身分執行時，skills frontmatter 一律不生效、mcpServers 僅 split-pane 模式生效（見 3.11.3 與 6.11）。
• 內嵌 MCP 伺服器的信任門檻（v2.1.238+）：定義於專案 .claude/agents/ 下的 Subagent，若 frontmatter 內嵌 mcpServers 設定，**需該資料夾已通過信任（workspace trust）**才會啟動，避免 clone 外部專案即自動連線不明伺服器。
• --strict-mcp-config、--bare、管理式設定的 allowedMcpServers / deniedMcpServers（v2.1.153+）同樣適用於 Subagent 內嵌的 MCP 設定。
• 設計原則：明確宣告而非隱性繼承，可避免 Subagent 意外取得超出其任務範圍的外部系統存取權。

背景 Subagent 完成後的結果整合：

• 以背景模式（frontmatter background: true、CLI -bg/--background，或互動式中按 Ctrl+B 轉入背景）啟動的 Subagent 完成後，其最終輸出會以一則系統訊息插入主對話歷史，主 Claude 在下一輪回應前會讀到該結果。
• 背景 Subagent 的工具集被大幅收斂，僅保留 Read、Grep、Glob、Bash、PowerShell、Edit、Write、NotebookEdit、WebFetch、WebSearch、TodoWrite、Skill、ToolSearch、EnterWorktree、ExitWorktree、Monitor、TaskStop、SendMessage、Artifact 等工具，因此不適合需要互動確認的任務。
• 背景 Subagent 觸發的權限提示自 v2.1.186 起會浮現於主對話，不再静默卡住。
• 若背景 Subagent 尚未完成而使用者已送出新訊息，主 Claude 可選擇先處理新訊息、稍後再讀取背景結果，兩者不會互相阻塞。
• 背景 Subagent 存活時間上限與 Ch13.2.6 所述的 10 分鐘規則一致（v2.1.182+），逾時會被強制終止並回報逾時訊息。

6.7 巢狀呼叫限制

版本差異需特別留意：Subagent 巢狀呼叫自 v2.1.172 起開放，但深度上限本身也隨版本多次調整，並非固定不變的「5 層」——若團隊文件或教材仍寫死「上限 5 層」，多半是引用了 v2.1.172–216 這個舊區間的數字，企業導入前務必以 claude --version 核對實際版本對應的預設值：

自 v2.1.217 起，可用 CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH 環境變數調整此深度上限（設為主對話以下允許的巢狀層數），例如設為 2 代表 Subagent 可再委派一層、該層不可繼續往下委派；設為 1 等同關閉巢狀：

{
  "env": {
    "CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH": "2"
  }
}

到達深度上限時，Claude Code 會從該層 Subagent 移除 Agent 工具（Forked Subagent 除外——它仍保留 Agent 於工具清單中，但呼叫會直接回傳錯誤而非真的產生新的 Subagent）。

• Subagent：v2.1.172+ 支援巢狀呼叫——一個 Subagent 可以再委派給另一個 Subagent，深度依上表版本對應的預設值（目前為 3 層），且可透過環境變數調整。
• Agent Team Teammate：仍不支援巢狀，且不受上述環境變數影響——Teammate 不能再產生自己的 Team 或委派給其他 Teammate，in-process Teammate 也不能再啟動自己的背景 Subagent（該限制與深度上限無關，是 Agent Team 架構本身的硬性限制）。

graph TD
    Main["🤖 Main Claude"] -->|"✅ 可以"| Sub1["🔧 Subagent A"]
    Main -->|"✅ 可以"| Sub2["🔧 Subagent B"]
    Sub1 -->|"✅ v2.1.172+ 可以<br/>(目前預設深度上限 3，可調整)"| Sub3["🔧 Subagent C"]

    Lead["🤖 Team Lead"] -->|"✅ 可以"| TM1["👥 Teammate A"]
    Lead -->|"✅ 可以"| TM2["👥 Teammate B"]
    TM1 -->|"❌ 不可以"| TM3["👥 Teammate C"]

    style TM3 fill:#ffcdd2,stroke:#c62828

影響：舊版環境（< v2.1.172）或使用 Agent Team 時，若需要「A 的結果餵給 B」，仍須由主對話（或 Lead Agent）串接；v2.1.172+ 的 Subagent 巢狀呼叫雖然可行，但每多一層巢狀就多一層獨立 context 與委派延遲，企業實務上仍建議優先由主對話明確編排委派順序，僅在確實需要動態、遞迴式委派時才依賴巢狀呼叫，並留意目前預設 3 層的深度上限。

併發數上限：巢狀深度之外，同一 Session 內同時執行中的 Subagent 數量預設上限為 20，超過時以 Agent 工具新增的委派會失敗並回報 Concurrent subagent limit reached（提示不要重試），待執行中數量降到上限以下才會再成功；可用 CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS 環境變數調整，啟用 ultracode 的 Session 則不受此上限限制。此上限只計入透過 Agent 工具動態產生的 Subagent；/subtask 產生的 Fork 與 Resume 既有 Subagent 不受限。

Subagent 輸出安全掃描（v2.1.210+）：Subagent 可能讀取了未經人工檢視的檔案、網頁或指令輸出，其中可能夾帶意圖影響主對話的注入文字。Claude Code 在主對話讀取 Subagent 最終回報前會先掃描內容：偵測到模仿 <system-reminder> 等內部標籤、或提及 bypassPermissions／--dangerously-skip-permissions 等權限設定字樣時，會插入反斜線使其失去標籤效力，並在回報開頭加註 [harness: subagent output matched instruction-shaped pattern(s): ...] 提示行。此機制不會判斷內容是否惡意、也不會改變回報中的指令實際可執行的範圍——後續若因此觸發任何工具呼叫，仍須通過正常的權限與沙箱檢查，因此不能取代「限制 Subagent 可存取的工具與資料」這個根本防線（見 6.6 節）。

6.8 完整範例

範例 1：Security Reviewer Subagent

用途：對指定程式碼進行 OWASP Top 10 安全審查，回報漏洞與修復建議。

---
name: security-reviewer
description: "Performs OWASP Top 10 security review on source code. Analyzes authentication, injection, XSS, CSRF, and other common vulnerabilities. Reports findings with severity levels and fix recommendations."
model: claude-opus-5
tools:
  - Read
  - Grep
  - Glob
  - LS
disallowed-tools:
  - Write
  - Edit
  - Bash
---

# Security Reviewer Agent

## 角色定義
你是資深資安工程師，專精 OWASP Top 10、SANS CWE Top 25 與企業安全標準。

## 任務流程
1. 使用 Glob 找出所有目標原始碼檔案
2. 使用 Read 逐一讀取，分析以下安全面向：
   - **A01 Broken Access Control**：權限檢查、路徑穿越
   - **A02 Cryptographic Failures**：硬編碼密鑰、弱加密演算法
   - **A03 Injection**：SQL/NoSQL/LDAP/OS Command Injection
   - **A04 Insecure Design**：業務邏輯缺陷
   - **A05 Security Misconfiguration**：預設密碼、不必要的服務
   - **A06 Vulnerable Components**：已知 CVE 套件
   - **A07 Authentication Failures**：弱密碼策略、Session 管理
   - **A08 Data Integrity Failures**：反序列化、未驗證更新
   - **A09 Logging Failures**：敏感資料洩露至日誌
   - **A10 SSRF**：Server-Side Request Forgery
3. 使用 Grep 搜尋已知危險模式（如 `eval(`, `exec(`, `Runtime.exec`）

## 輸出格式
以 Markdown 表格輸出，包含：
| 嚴重度 | CWE ID | 檔案:行號 | 漏洞描述 | 修復建議 |

嚴重度等級：🔴 Critical / 🟠 High / 🟡 Medium / 🟢 Low / ⚪ Info

## 限制
- 此 Agent 為唯讀，不可修改任何檔案
- 僅報告問題，不自動修復
- 若發現 🔴 Critical 漏洞，必須在報告最前方標示警告

範例 2：Test Runner Subagent

用途：執行測試套件，分析測試結果，回報覆蓋率與失敗測試詳情。

---
name: test-runner
description: "Executes test suites (JUnit/pytest/Jest), analyzes results, reports coverage metrics and failure details. Supports Java Maven/Gradle, Python pytest, and Node.js Jest projects."
model: claude-sonnet-5
tools:
  - Read
  - Grep
  - Glob
  - Bash
  - LS
disallowed-tools:
  - Write
  - Edit
---

# Test Runner Agent

## 角色定義
你是 QA 自動化工程師，負責執行測試並分析結果。

## 任務流程
1. **偵測專案類型**：
   - 檢查 `pom.xml` → Maven (Java)
   - 檢查 `build.gradle` → Gradle (Java)
   - 檢查 `package.json` → Node.js (Jest/Mocha)
   - 檢查 `pytest.ini` / `pyproject.toml` → Python (pytest)

2. **執行測試**：
   ```bash
   # Java Maven
   mvn test -Dmaven.test.failure.ignore=true

   # Java Gradle
   ./gradlew test --continue

   # Node.js
   npx jest --coverage --json --outputFile=test-results.json

   # Python
   python -m pytest --tb=short --junitxml=test-results.xml -v
   ```

3. **分析結果**：
   - 讀取測試報告
   - 計算通過率、失敗率
   - 分析覆蓋率（若有）

## 輸出格式
```
📊 測試報告摘要
═══════════════════════════════
✅ 通過: XX 個
❌ 失敗: XX 個
⏭️ 略過: XX 個
📈 覆蓋率: XX%

❌ 失敗測試詳情：
1. [TestClass#methodName] — AssertionError: expected X but was Y
   📍 檔案: src/test/java/...
   💡 可能原因: ...
```

## 限制
- 不可修改原始碼或測試程式碼
- 若測試需要外部服務（DB、API），應標示為 ⚠️ 需環境依賴

範例 3：Code Reviewer Subagent

用途：執行程式碼品質審查，涵蓋命名慣例、SOLID 原則、複雜度分析、效能問題。

---
name: code-reviewer
description: "Performs comprehensive code review covering naming conventions, SOLID principles, cyclomatic complexity, performance issues, error handling, and maintainability. Outputs structured review report."
model: claude-sonnet-5
tools:
  - Read
  - Grep
  - Glob
  - LS
disallowed-tools:
  - Write
  - Edit
  - Bash
---

# Code Reviewer Agent

## 角色定義
你是資深軟體工程師，具備 10 年以上的 Code Review 經驗。你的審查嚴謹但建設性。

## 審查維度

### 1. 命名與慣例
- 類別名稱：PascalCase
- 方法/變數：camelCase
- 常數：UPPER_SNAKE_CASE
- 命名是否表達意圖（避免 `temp`, `data`, `result` 等無意義命名）

### 2. SOLID 原則
- **S** — 單一職責：每個類別/方法是否只做一件事？
- **O** — 開放封閉：是否對擴展開放、對修改封閉？
- **L** — 里氏替換：子類別是否可無副作用替換父類別？
- **I** — 介面隔離：介面是否過於龐大？
- **D** — 依賴反轉：是否依賴抽象而非具體實作？

### 3. 複雜度
- 方法行數（建議 ≤ 30 行）
- 圈複雜度（建議 ≤ 10）
- 巢狀深度（建議 ≤ 3 層）

### 4. 錯誤處理
- 是否有空的 catch 區塊
- 是否吞掉例外（catch + ignore）
- 是否提供有意義的錯誤訊息

### 5. 效能
- N+1 查詢問題
- 不必要的物件建立
- 可使用 Stream/集合操作優化的迴圈

## 輸出格式
| 優先級 | 類別 | 檔案:行號 | 問題描述 | 建議修正 |

優先級：P0（必須修正）/ P1（強烈建議）/ P2（建議）/ P3（可選）

範例 4：Reverse Engineering Subagent

用途：分析舊系統程式碼，產出架構文件、類別關係圖與技術債清單。

---
name: re-analyzer
description: "Reverse engineers legacy codebases to produce architecture documentation, class relationship diagrams (Mermaid), dependency maps, and technical debt inventory. Supports Java, C#, Python, and COBOL."
model: claude-opus-5
tools:
  - Read
  - Grep
  - Glob
  - Bash
  - LS
disallowed-tools:
  - Write
  - Edit
memory: project    # 持久化至 .claude/agent-memory/re-analyzer/，跨 session 保留既有基線
---

# Reverse Engineering Analyzer Agent

> 📌 若需參考既有的 RE 基線資料，直接在 Prompt 中以相對路徑引用（例如「請比對 `re-baseline/` 目錄下的既有分析結果」）即可，不需額外的 frontmatter 欄位。

## 角色定義
你是舊系統現代化專家，專精大型企業系統的逆向工程與文件產出。

## 分析流程

### Phase 1: 結構探索
1. 掃描專案目錄結構（LS + Glob）
2. 識別框架與技術棧（pom.xml, build.gradle, web.xml, applicationContext.xml）
3. 統計程式碼規模（行數、檔案數、模組數）

### Phase 2: 架構分析
1. 識別分層架構（Controller → Service → Repository → Entity）
2. 繪製模組依賴圖（Mermaid）
3. 標示進入點（main、Servlet、Controller endpoints）

### Phase 3: 資料流追蹤
1. 追蹤 API 端點 → 業務邏輯 → 資料庫操作
2. 識別跨模組呼叫
3. 標示外部整合點（第三方 API、MQ、File I/O）

### Phase 4: 技術債盤點
1. 過時依賴（已 EOL 的框架/函式庫）
2. 已知 CVE 漏洞
3. 硬編碼設定（magic numbers, 硬編碼 URL/IP）
4. 無測試覆蓋的核心模組
5. 違反 SOLID 的嚴重案例

## 輸出格式
產出以下文件內容：
1. **架構總覽**：系統邊界、模組列表、技術棧
2. **類別關係圖**：Mermaid classDiagram
3. **資料流圖**：Mermaid sequenceDiagram
4. **技術債清單**：表格，含嚴重度、影響範圍、建議處置
5. **現代化建議**：遷移優先順序與策略

## 限制
- 此 Agent 不修改任何原始碼
- 使用 Opus 模型以確保深度分析品質
- 大型專案（> 500 檔案）應分模組逐一分析

範例 5：Coordinator Agent（用於 Agent Team Lead）

用途：作為 Agent Team 的 Lead Agent，協調多個 Teammate 完成複雜的 SSDLC 流程。

---
name: ssdlc-coordinator
description: "Lead Agent for SSDLC Agent Team. Coordinates security review, testing, code review, and documentation teammates. Orchestrates the full secure development workflow."
model: claude-sonnet-5
tools:
  - Read
  - Write
  - Edit
  - Bash
  - Grep
  - Glob
  - LS
---

# SSDLC Coordinator (Lead Agent)

## 角色定義
你是 SSDLC 流程的總協調者（Lead Agent），負責：
1. 接收使用者需求
2. 拆解任務並委派給適當的 Teammate
3. 整合各 Teammate 的回報
4. 確保流程順序與品質門檻

## 協作流程

```text
使用者需求
    ↓
[1] 委派 @architect-teammate → 架構評估
    ↓
[2] 委派 @code-reviewer → 程式碼審查（依據架構評估結果）
    ↓
[3] 委派 @security-reviewer → 安全審查
    ↓
[4] 委派 @test-runner → 測試執行
    ↓
[5] 整合所有結果 → 產出綜合報告
```

## 品質門檻（Gate Criteria）
- 🔴 Critical 安全漏洞：**阻止**流程，必須修復
- 測試覆蓋率 < 60%：**警告**，需補充測試
- P0 Code Review issue：**阻止**流程，必須修復
- 所有 Gate 通過 → 允許進入下一階段

## 重要限制
- Agent Team 為 🔴 Experimental，需 v2.1.32+
- 需設定環境變數：`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`
- 一個 session 只能有一個 Agent Team
- 不支援 session resumption
- Teammate 的 frontmatter 僅 skills、mcpServers 不帶入；其餘欄位（tools、model、hooks、permissionMode 等）正常生效

範例 6：Architect Teammate

用途：作為 Agent Team 中的架構師 Teammate，提供架構評估與設計建議。

---
name: architect-teammate
description: "Architecture evaluation teammate. Analyzes system design, evaluates architectural decisions, produces C4 diagrams, and provides improvement recommendations. Used as Agent Team teammate."
model: claude-opus-5
tools:
  - Read
  - Grep
  - Glob
  - LS
---

# Architect Teammate

## 角色定義
你是軟體架構師，專精微服務架構、領域驅動設計（DDD）與企業整合模式。

## ⚠️ Agent Team Teammate 限制
此檔案作為 Agent Team Teammate 使用時，僅以下 frontmatter 生效：
- ✅ `tools`（工具白名單）
- ✅ `model`（模型選擇）
- ❌ `skills` — 不帶入
- ❌ `mcpServers` — 不帶入
- ❌ `hooks` — 不帶入

若需要 MCP 或 Hooks 功能，應在 Lead Agent 層級設定。

## 評估維度

### 1. 架構風格評估
- 是否為 Monolith / Modular Monolith / Microservices
- 是否適合目前團隊規模與業務複雜度

### 2. 分層清晰度
- 各層職責是否明確
- 是否有跨層直接呼叫（如 Controller 直接存取 DB）

### 3. 耦合度分析
- 模組間的依賴方向是否正確（依賴反轉）
- 是否有循環依賴

### 4. 可觀測性
- 是否有結構化日誌
- 是否有健康檢查端點
- 是否有度量指標匯出

## 輸出格式
1. **架構概況**：風格、分層、技術棧
2. **C4 Context Diagram**（Mermaid）
3. **改善建議清單**：表格，含優先級、現況、建議、影響範圍

6.9 Worktree Isolation 範例

Worktree 隔離有兩種使用方式：

1. 自動隔離（v2.1.117+ 建議方式）：使用 isolation: worktree frontmatter，Claude Code 自動建立並管理 Git worktree。
2. 手動隔離：在 Agent body 中手動執行 git worktree add 指令。

方式一：自動隔離（建議）

---
name: refactor-agent
description: "Performs large-scale code refactoring in an isolated Git worktree"
model: claude-sonnet-5
isolation: worktree    # ← 自動建立隔離環境
tools:
  - Read
  - Write
  - Edit
  - Bash
  - Grep
  - Glob
  - LS
argument-hint: "Specify the refactoring scope, e.g., 'Refactor all DAO classes to use Repository pattern'"
---

# Refactor Agent (Worktree Isolated)

## 工作流程
1. **Claude Code 自動建立 Worktree**（無需手動操作）
2. **在隔離環境中進行重構**
3. **驗證**：執行測試確認無破壞
4. **回報結果**：列出所有變更檔案與修改摘要
5. **由使用者決定是否合併**

## 優勢
- 主工作目錄不受影響
- 可隨時放棄
- 變更可透過 PR 審查後再合併

方式二：手動隔離（適用於需要完全控制的場景）

6.10 Anti-Patterns（5 個常見錯誤）

❌ Anti-Pattern 1：Agent Team Teammate 巢狀呼叫

# ❌ 錯誤：試圖讓 Agent Team Teammate 呼叫另一個 Teammate 或建立子 Team
---
name: orchestrator-teammate
description: "Orchestrates other teammates"
---

請呼叫 @security-reviewer 檢查安全性，然後呼叫 @test-runner 跑測試。
# ↑ 這不會生效！Agent Team Teammate 不可再呼叫其他 Teammate 或建立子 Team

✅ 正確做法：由 Lead Agent 串接多個 Teammate。

📌 版本提醒：一般 Subagent（.claude/agents/*.md，非 Agent Team Teammate 身分）自 v2.1.172 起支援巢狀呼叫（目前預設深度上限 3，可調整，詳見 6.7），上述限制僅適用於 Agent Team Teammate。即便如此，架構設計上仍建議優先由主對話明確編排委派順序，避免過深的巢狀委派鏈增加延遲與除錯難度。

❌ Anti-Pattern 2：Agent Team Teammate 依賴 Skills/MCP

# ❌ 錯誤：在 Teammate 中設定 skills 和 mcpServers
---
name: my-teammate
description: "Does analysis"
model: claude-sonnet-5
skills:
  - security-check    # ❌ 不會生效！
mcpServers:
  - jira-server       # ❌ 不會生效！
---

✅ 正確做法：skills 和 mcpServers 需在 Lead Agent 層級設定，或直接在 Teammate body 中以指令方式描述工作流程。

❌ Anti-Pattern 3：Subagent 擁有過多工具

# ❌ 錯誤：安全審查 Agent 卻有 Write/Edit/Bash 權限
---
name: security-reviewer
description: "Security audit"
tools:
  - Read
  - Write     # ❌ 安全審查不應有寫入權限
  - Edit       # ❌ 安全審查不應有編輯權限
  - Bash       # ❌ 安全審查不應有執行指令權限
  - Grep
  - Glob
---

✅ 正確做法：遵循最小權限原則。安全審查 Agent 只需 Read、Grep、Glob、LS。

❌ Anti-Pattern 4：Agent Team 用於生產環境關鍵路徑

# ❌ 錯誤：將 Agent Team 用於 CI/CD pipeline 的 blocking gate
# Agent Team 為 🔴 Experimental，不保證穩定性
steps:
  - name: Agent Team Security Gate
    run: |
      CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 \
      claude --agent-team ssdlc-team "review and approve" # ❌ 不適合作為 blocking gate

✅ 正確做法：生產環境的 blocking gate 應使用穩定的 Hooks（exit code 2 阻止）或 Programmatic CLI。

❌ Anti-Pattern 5：Subagent 無明確 description

# ❌ 錯誤：description 過於模糊
---
name: helper
description: "Helps with stuff"  # ❌ Claude 無法判斷何時該委派
---

✅ 正確做法：description 應精確描述能力、輸入與輸出，讓 Claude 能準確判斷自動委派時機。

6.11 Agent Team Subagent Definition 正確說明

當 .claude/agents/*.md 檔案被用作 Agent Team Teammate 時，其 frontmatter 的行為與一般 Custom Subagent 不同：

📌 官方文件僅明確排除 skills 與 mcpServers 兩個欄位「不帶入 Teammate」；其餘 frontmatter 欄位（包含 disallowed-tools、memory、context、argument-hint、isolation）均維持與一般 Custom Subagent 相同的生效行為。

teammateMode 與 Team Display Mode（v2.1.32+，預設值已於 v2.1.179+ 調整）

Agent Team 支援多種 Teammate 顯示/執行模式，透過 teammateMode 設定或 --teammate-mode CLI 旗標指定：

也可以 CLI 旗標 --teammate-mode <mode> 單次覆寫設定檔中的 teammateMode。

⚠️ 版本注意：v2.1.178 之前，需先由使用者要求 Claude 以 TeamCreate 工具明確建立並命名團隊；v2.1.178 起，TeamCreate/TeamDelete 工具已移除，首次產生 Teammate 時自動建立團隊。Split pane 模式（tmux/iterm2）在 VS Code 內建終端機、Windows Terminal、Ghostty 中不受支援，請改用 in-process。完整的破壞性變更時間軸見 3.11.1。

# 設定 Agent Team 使用 tmux 模式
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
claude --agent ssdlc-coordinator  # Teammate 依據 teammateMode 設定執行

Plan Approval for Teammates

Agent Team 支援 Teammate 操作前的計畫審批機制：

• Teammate 在執行重大操作前，可先提交執行計畫
• Lead Agent 或使用者可審核計畫後批准或拒絕
• 此機制搭配 permission-mode: plan 使用，提供額外的安全保障

設計建議：若同一個 .md 檔案需要同時支援一般 Subagent 和 Agent Team Teammate 兩種用法，建議將 Skills 封裝的檢核程序直接寫在 body 的指令中，而非依賴 skills frontmatter；需要 MCP 的角色則必須使用 split-pane 模式（mcpServers 在 in-process Teammate 不生效）。完整欄位對應見 3.11.3。

Team 規模建議與跨 Agent 訊息的信任邊界

團隊規模：官方文件並未對 Teammate 數量設硬性上限，但建議多數場景以 3–5 個 Teammate 為起點——過少無法發揮平行探索的價值，過多則協調成本（溝通、任務指派、衝突處理）會抵銷平行化帶來的效益，且 Token 成本隨 Teammate 數量線性增加（每個 Teammate 都是獨立的 Claude Code 實例）。若任務可拆成 15 個獨立子任務，3 個 Teammate、每人負責 5–6 個任務通常優於一次開 15 個 Teammate。

Mailbox 可靠性：每個 Agent 的信箱是 ~/.claude/teams/{team-name}/inboxes/{agent-name}.json 檔案，Claude Code 讀取時會驗證每筆訊息格式，格式不符的項目會被記錄為錯誤並從檔案中移除，其餘合法訊息仍正常送達（v2.1.207 前，單一格式錯誤的訊息會導致整個信箱每秒重複報錯且完全無法送達，須手動刪除檔案排除；此問題已修復）。訊息（含一般文字與 Plan Approval／Shutdown 等結構化協定訊息）僅在成功寫入收件者信箱檔案後才視為送達成功，寫入失敗（如磁碟已滿、目錄不可寫）時寄件 Agent 會收到錯誤，訊息不會憑空消失也不會誤判送達。

跨 Agent 訊息不能替代使用者授權：Teammate 之間透過 SendMessage 互傳訊息時，Claude Code 會明確告知接收方「這則訊息來自另一個 Claude Session，而非使用者本人」——任何 Agent 都不能代替使用者核准權限提示，也不能將自己被拒絕的操作轉發給另一個 Teammate 藉此繞過權限檢查。啟用 auto 權限模式時，分類器會將轉發而來的「已核准」宣稱視為未驗證的外部輸入，並在每則跨 Agent 訊息送達前先行審查，判定有風險的訊息不會送達收件者。

6.12 內建 Subagents 與 Agent Team Hooks

內建 Subagents

Claude Code 內建數個現成的 Subagent，不需自行定義即可使用：

重要行為差異：

• Explore 與 Plan 不會載入 CLAUDE.md，也不會讀取 git 狀態，因此其結論可能缺少專案慣例脈絡；需要遵循團隊規範的任務應改用自訂 Subagent。
• v2.1.198+：Subagent 一併繼承主對話的 extended thinking 設定；CLAUDE_CODE_SUBAGENT_MODEL=inherit 等同於未設定該變數。
• v2.1.198+：/agents 指令不再開啟互動式建立精靈，Subagent 定義改為直接編輯 .claude/agents/*.md 檔案，或請 Claude 代為產生。

企業若需限制團隊只能使用自訂 Subagent、不可呼叫內建 Subagent，可設定環境變數 CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1（v2.1.198+）停用 Explore/Plan，Agent SDK 環境則可用 CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1 停用全部內建 Subagent；亦可在 permissions.deny 中加入 Agent(<name>) 規則個別停用（見下）。

Subagent 定義檔的載入優先序

同名 Subagent 依下列優先序決定實際生效的定義（由高至低）：

1. 管理式設定（Managed Settings） — 由 IT 部署，使用者不可覆寫
2. --agents CLI 旗標 — 單次執行覆寫
3. 專案 .claude/agents/ — 隨專案版控，v2.1.178+ 支援巢狀目錄，離目前工作目錄最近者勝出
4. 使用者 ~/.claude/agents/ — 個人跨專案定義
5. Plugin 的 agents/ — 命名空間為 plugin:subfolder:name，且 Plugin Subagent 會忽略 hooks、mcpServers、permissionMode 三個欄位

限制可委派的 Subagent 類型

透過 permission 規則的 Agent(<agent_type>) 語法，可白名單／黑名單限制主對話能委派給哪些 Subagent（無論內建或自訂）：

{
  "permissions": {
    "deny": ["Agent(general-purpose)"],
    "allow": ["Agent(security-reviewer)", "Agent(test-runner)"]
  }
}

指定 Subagent 使用的模型

預設 Subagent 會沿用主對話的模型（除非 frontmatter 明確指定 model）。可透過環境變數 CLAUDE_CODE_SUBAGENT_MODEL 統一覆寫所有未指定 model 的 Subagent 使用的模型，適合企業想強制「所有委派任務一律使用 Sonnet」之類的成本管控場景：

export CLAUDE_CODE_SUBAGENT_MODEL=claude-sonnet-5

模型解析順序（v2.1.251 基準）：

⚠️ v2.1.251 破壞性變更：per-invocation model 參數由最後順位提升為最高順位。這代表企業若僅以 CLAUDE_CODE_SUBAGENT_MODEL 做成本管控，呼叫端仍可在單次委派時指定更貴的模型而蓋過設定。要真正封住此缺口，須於組織層設定 availableModels 允許清單（見 4.8）。此變更與 3.5.1 節的 Teammate 模型順序調整為同一版次、同一方向的設計調整。

其他相關行為：

• model: inherit 自 v2.1.251 起與「省略該欄位」完全等價。
• 被 availableModels 封鎖的家族別名（如 opus）會被替換為該家族中允許清單內最新的版本；其他被封鎖的值則回退為繼承的模型。
• per-invocation 覆寫的持續性（v2.1.211+）：續跑或對 Subagent 發送後續訊息時，單次指定的 model 參數會被保留；此版本之前會在 resume 時被丟棄。

Agent Team Hooks：TeammateIdle / TaskCreated / TaskCompleted

除了 9.x 節介紹的一般 Hook 事件，Agent Team 額外提供三個專屬 Hook 事件，用於在 Teammate 生命週期的關鍵時刻插入確定性的品質關卡——這是實作 SSDLC Gate（見 3.6、3.8 節）時，比僅靠 Prompt 指示更可靠的做法：

{
  "hooks": {
    "TaskCompleted": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/hooks/teammate-quality-gate.sh",
            "description": "Teammate 任務完成前的品質 Gate"
          }
        ]
      }
    ]
  }
}

📌 這三個事件僅在 Agent Team（🔴 Experimental）情境下觸發；一般 Subagent 委派完成後由主對話自行判斷後續動作，不會觸發這些事件。

6.13 實務建議

1. 從 Custom Subagent 開始：先以單一 Subagent 驗證效果，確認穩定後再考慮 Agent Team。
2. 最小權限原則：每個 Subagent 只給予完成任務所需的最少工具。唯讀任務不給 Write/Edit/Bash。
3. description 是自動委派的關鍵：花時間撰寫精確的 description，這決定了 Claude 是否能正確自動匹配。
4. Worktree 用於破壞性操作：大規模重構、跨模組修改等，務必使用 Worktree 隔離。
5. Agent Team 僅限 POC/Lab：🔴 Experimental 功能不應用於生產環境，且一個 session 只能有一個 Team、不支援 session resumption。
6. 監控 context 大小：Subagent 的 context 是獨立的，但回傳摘要會佔用主對話 context。若串接過多 Subagent，主對話可能 context 溢出。
7. Plugin Subagent 的限制：Plugin 以 Subagent 形式執行，但不支援 hooks、mcpServers、permissionMode frontmatter。需要這些功能時，應使用一般 Custom Subagent。

6.14 Subagent Frontmatter 完整參考（v2.1.251 基準）

前面各節分散介紹了 tools、model、memory、isolation 等欄位，本節提供單一權威參考表，供企業建立 Subagent 定義檔範本時對照。

企業範本（十角色共用骨架）：

---
name: security-reviewer
description: "對指定程式碼執行 OWASP Top 10 安全審查並輸出風險清單與修復建議。當使用者要求安全檢視、弱點掃描或合規查核時使用。"
model: opus
effort: high
permissionMode: plan
tools:
  - Read
  - Grep
  - Glob
disallowedTools:
  - Write
  - Edit
  - Bash
memory: project
color: red
experimental:
  cacheTtl: 1h
---

你是資深應用程式安全審查員……

附加系統提示（v2.1.205+）：企業可用 --append-subagent-system-prompt 對所有 Subagent 統一追加組織層級的規範（例如「所有輸出必須標註資料分級」），而不需逐一修改定義檔：

claude --append-subagent-system-prompt "所有分析輸出必須於開頭標註資料分級（Public/Internal/Confidential）。"

6.15 Subagent 載入失敗、錯誤處理與可靠性治理

企業導入 Subagent 最常見的問題不是「跑錯」，而是「沒跑但沒人發現」。本節整理靜默失效的成因與治理方式。

6.15.1 定義檔被跳過的五種情況

Claude Code 在載入 .claude/agents/*.md 時，遇到下列情況會直接跳過該檔案，且預設不會顯示明顯錯誤：

驗證指令（v2.1.233+）：

# 驗證 Subagent 定義目錄
claude plugin validate .claude/agents

# 驗證 Skills 目錄
claude plugin validate .claude/skills

# 嚴格模式（警告亦視為失敗，建議納入 CI）
claude plugin validate .claude/agents --strict

建議納入 CI：在 Pull Request 流程中加入 claude plugin validate .claude/agents --strict，可在合併前攔截所有會被靜默跳過的定義檔。

另一類失敗：定義檔載入成功、但啟動時工具集為空

上述五種情況是載入階段被跳過；還有一種情況是定義檔本身合法、能被載入，卻在啟動階段失敗：

這在企業環境特別容易發生，因為 tools 中常引用 MCP 工具（如 mcp__github），而該 MCP Server 可能只在部分開發者的環境中設定。建議防範方式：

• 定義檔中至少保留一個內建工具（如 Read），避免整份清單依賴外部 MCP
• 於 CI 中以 claude plugin validate --strict 搭配實際的 MCP 設定執行，及早發現
• 在 §13.2.7 的 CI 閘門中檢查 system/init 事件的 mcp_server_errors，確認 MCP Server 確實載入

6.15.2 API 錯誤與中途失敗的處理

自 v2.1.199 起，Subagent 遭遇 API 錯誤時的行為明確化：

治理要點：由於「部分輸出」在外觀上與正常完成極為相似，安全審查、合規檢核類 Subagent 的輸出必須包含明確的完成標記（例如結尾固定輸出 === REVIEW COMPLETE ===），並由 SubagentStop Hook 檢查該標記是否存在，否則不得視為通過閘門。

6.15.3 Subagent 的續跑與紀錄稽核

• 續跑：可用 SendMessage 搭配 Agent ID 或名稱與既有 Subagent 繼續對話；已完成的 Subagent 會自動續跑。v2.1.199 起會檢查名稱一致性，避免誤送到同名但不同實例的 Subagent；v2.1.191 起，被使用者手動停止的 Subagent不會自動續跑。
• 交談紀錄路徑：~/.claude/projects/{project}/{sessionId}/subagents/agent-{agentId}.jsonl，是稽核 Subagent 實際行為的一手證據。
• 保留期：依 cleanupPeriodDays 設定回收，預設 30 天。若合規要求較長保留期，應調高此值或由備份機制另行歸檔。

{
  "cleanupPeriodDays": 180
}

6.15.4 Sibling Roster（同儕名冊）

自 v2.1.206 起，每個 Subagent 都會收到一則系統提醒，列出目前 session 中的 main 與其他具名 Agent。這讓 Subagent 知道「還有誰在工作」，可減少重複勞動；但同時也代表Subagent 能得知其他角色的名稱，因此角色命名不應包含敏感資訊（例如客戶名稱、專案代號）。

6.15.5 Hook 事件與匹配規則

v2.1.195+：含連字號的 matcher 採完全比對，security-reviewer 不會再誤匹配到 security-reviewer-lite。

{
  "hooks": {
    "SubagentStop": [
      {
        "matcher": "security-reviewer",
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/assert-review-complete.sh"
          }
        ]
      }
    ]
  }
}

6.15.6 可靠性治理檢查清單

• CI 中執行 claude plugin validate .claude/agents --strict
• 所有品質閘門類 Subagent 皆輸出固定完成標記，並以 SubagentStop Hook 驗證
• tools 清單中的 MCP 工具名稱已驗證可解析（v2.1.208 後會拒絕啟動）
• description 長度受控，未接近 15,000 tokens 警告門檻
• cleanupPeriodDays 已依合規保留期調整
• Subagent 角色命名不含敏感資訊（因會出現在同儕名冊中）
• 已設定 CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS 與 CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH 的組織基準值

6.16 Cross-Session Messaging（跨 Session 訊息協作）

除了 Subagent（單一 Session 內的委派）與 Agent Team（Lead 統籌的團隊）之外，Claude Code 還提供第三種多代理協作模型：讓「你自己開的多個獨立 Session」互相傳遞訊息。這對 SSDLC 情境相當實用——例如後端 Session 改了 API schema，可主動通知正在改前端的 Session；或讓長時間執行的遷移 Session 在完成時回報給你正在看的 Session。

本節內容對應官方 cross-session-messaging 文件，是本手冊 v1.4.0 新增的主題。

6.16.1 三種協作模型的選型

選型原則：需要「一個結果」用 Subagent；需要「多角度討論」用 Agent Team；需要「兩個你自己在顧的工作流互相通氣」用 Cross-Session Messaging。CI/CD 中不可用 Agent Team（不支援 -p），但 Cross-Session Messaging 可用。

6.16.2 運作方式與定址

Claude 使用兩個工具完成此事，使用者不需直接呼叫：

同一個 SendMessage 也用於對 Subagent 與 Agent Team Teammate 發訊息，因此在權限規則中封鎖 SendMessage 會一併關閉那兩者的訊息能力（見 6.16.5）。

查看可觸及對象：執行 /list-agents（別名 /peers）。輸出的第一行是本 Session 自己的名稱（其他 Session 用此名稱找到你），其下才是可觸及的對象：

• Subagents：本 Session 內執行中的子代理
• Teammates：本 Session 的 Agent Team 成員（v2.1.239+ 才會列出）
• 本機其他 Session：包含背景 Session；需該 Session 已綁定 inbox socket
• 雲端 Session：Claude Code on the web 的 Session，標示為 cloud（需連線 Remote Control）
• 其他機器上的 Session：標示為 Remote Control；連線中斷者顯示 offline

指名定址：在提示詞中輸入 @ 加上 Session 名稱前幾個字，從 typeahead 選取（v2.1.232+）。名稱含空白或特殊字元時需加雙引號，例如 @"release notes"。

讓 @api-worker 知道 schema 遷移已完成

Session 名稱可用 --name 啟動參數或 /rename 指令設定；未設定時由 Claude Code 自動命名。同名衝突時，既有 Session 保留該名稱，新的會被改名為變體。

6.16.3 訊息投遞的三種結果

接收端會以自己的「入站控制」檢查每一則訊息，結果必為三者之一：

送達後，該訊息如同你親手輸入的提示詞一樣計入用量。

發送端會被拒絕的情況：訊息超過大小上限（本機約 100 萬字元）、短時間內對同一 Session 連發超量、回覆目標未通過安全檢查（如 symlink 目標）、或把訊息寄給自己。

6.16.4 安全邊界（企業必讀）

Claude Code 明確告知接收端「這則訊息來自另一個 Claude Session，不是使用者本人」，並強制以下限制：

⚠️ 這是 Prompt Injection 的新面向：跨 Session 訊息是一條「模型對模型」的輸入通道。雖然上述限制已封住權限提升路徑，但訊息內容本身仍是不可信輸入。若某 Session 正在處理外部不可信資料（如分析使用者上傳的檔案），它送出的訊息可能夾帶被注入的內容。高敏感專案應依 6.16.5 收斂或關閉此功能，並與 12.9.1 節的 Prompt Injection 防護一併評估。

auto 模式的額外檢查：在 auto 模式下，分類器會將「另一個代理轉述的核准聲明」視為不可信輸入，並在投遞前逐則審查訊息，被擋下的訊息不會送達收件者。

6.16.5 企業治理設定

入站控制 crossSessionInbound：

{
  "crossSessionInbound": "accept"
}

未設定時的預設行為：Claude Code 依收發雙方的 Permission Mode 分類決定。它把「略過權限提示」的 Session（bypassPermissions，以及具備該能力時的 plan 模式）歸為一類，其餘（auto、acceptEdits、dontAsk 皆算「會提示」）歸為另一類：

• 接收端會提示權限 → 逐則投遞；僅當發送端自稱略過權限提示時才暫留待你核准
• 接收端略過權限提示 → 逐則暫留待你核准；僅當發送端也自稱略過時才直接投遞

暫留時會跳出核准對話框，逾 dialogExpiry（預設 5 分鐘）未回應則關閉並丟棄該訊息。設為 "never" 可保留至 Session 結束。

跨機器訊息需核准 isolatePeerMachines：

{
  "isolatePeerMachines": true
}

設為 true 後，任何送往本機以外 Session 的訊息都需你明確核准，即使處於 bypassPermissions 模式亦然。任一設定層級設為 true 即生效——也就是說專案設定檔可以打開這道限制，但不能關閉它。同機器 Session 之間不受影響。

組織層完全關閉（managed settings）：

{
  "permissions": {
    "deny": ["SendMessage", "ListAgents"]
  },
  "crossSessionInbound": "refuse"
}

注意兩件事：① 兩個 deny 規則都使用裸工具名稱、不帶參數；② 封鎖 SendMessage 會連帶關閉對 Subagent 與 Agent Team Teammate 的訊息能力，若貴組織仍需使用 Agent Team，請改為僅設 crossSessionInbound: "refuse"（只擋入站，不影響團隊內部通訊）。

此設定生效後，Claude Code 仍會綁定各 Session 的 inbox socket，只是將所有到達的訊息丟棄。拒收中的 Session 在自己的 /status 或其他 Session 的清單中看不出任何差異，因此稽核時須直接檢查該 Session 適用的設定檔，而非觀察其狀態。

6.16.6 Inbox Socket 與稽核接點

每個啟用此功能的 Session 都會綁定一個收件通道：macOS／Linux（含 WSL 2）為 Unix domain socket，原生 Windows 為 named pipe。

查看方式：/status 的 Peer address 欄（路徑帶 uds: 前綴）；或讀取環境變數：

讓腳本／Hook 回送訊息到自己的 Session：連線後將 {"type":"auth","token":"<token>"} 作為第一行送出。原生 Windows 為必要（缺少即斷線且不投遞任何內容），macOS／Linux 為選用。連線後 30 秒內未送出完整一行即會被關閉，因此應先取得輸出、再開連線。

SSDLC 應用：這是把外部事件（如長時間跑的安全掃描、夜間批次結果）推進既有 Session 的低成本管道，可與 Ch 9 的 Hook 及 11-B 的排程機制搭配。但請注意：能寫入該 socket 的程序等同能對 Claude 下指令，該 token 應比照機敏資訊管理，不可寫入日誌或版控。

安全性：macOS／Linux 上 socket 僅限你的作業系統使用者存取；原生 Windows 則要求每條連線先以只有你能讀取的金鑰認證。共用主機上，其他使用者的 Session 無法投遞訊息給你。

沙箱環境：Bash 指令能否觸及 socket，由沙箱的 sandbox.network.allowAllUnixSockets 與 sandbox.network.allowUnixSockets 控制。

6.16.7 版本需求與限制

閒置通知：可請本機某個 Session 在下次閒置或結束時回報一次，適合等待長任務。此訂閱為一次性，12 小時未觸發即自動取消。僅主對話的 Claude 可訂閱，且僅限本機 Session——Subagent 與 Teammate 發出的訂閱一律不成立。

已知限制：

6.16.8 導入檢查清單

• 已確認團隊 CLI 版本達 v2.1.224+（Windows 為 v2.1.234+）
• 已於組織層決定 crossSessionInbound 基準值，而非仰賴預設行為
• 高敏感專案已評估是否設定 isolatePeerMachines: true
• 若決定關閉，已確認是否連帶影響 Agent Team 內部通訊（見 6.16.5 注意事項）
• CLAUDE_CODE_MESSAGING_TOKEN 已納入機敏資訊管理範圍，且未出現在日誌或版控中
• 已將跨 Session 訊息列入 12.9.1 Prompt Injection 的風險評估範圍
• 已向團隊說明「跨 Session 訊息不等於使用者授權」的安全邊界

Ch 7：建立 Prompt Library 與 Team Prompt SOP

7.1 Prompt 在 Claude Code 生態系中的定位

Prompt 並非孤立存在，而是與 Claude Code 的多項功能交織運作：

graph LR
    subgraph UserInput["使用者輸入"]
        Prompt["📝 Prompt"]
    end

    subgraph ClaudeCodeRuntime["Claude Code Runtime"]
        CLAUDE_MD["📄 CLAUDE.md<br/>(Memory/Context)"]
        Skills["🛠️ Skills<br/>(SKILL.md)"]
        Agents["🤖 Agents<br/>(Subagent .md)"]
        Hooks["⚡ Hooks<br/>(Pre/Post Actions)"]
    end

    Prompt --> CLAUDE_MD
    Prompt --> Skills
    Prompt --> Agents
    CLAUDE_MD -->|"注入 system context"| Skills
    CLAUDE_MD -->|"注入 system context"| Agents
    Skills -->|"觸發工作流程"| Hooks
    Agents -->|"觸發工作流程"| Hooks

    style UserInput fill:#e3f2fd
    style ClaudeCodeRuntime fill:#f1f8e9

各元件與 Prompt 的關係：

核心差異：

• Prompt = 使用者意圖的表達
• Skill = 可重用的工作流程 + 知識注入（自動/手動觸發）
• Hook = 確定性的攔截與控制（事件驅動，不依賴 LLM 判斷）
• Agent = 具備特定角色的執行者（隔離 context）

7.2 企業級 Prompt Catalog 架構

prompt-library/
├── README.md                          # Catalog 索引與使用指南
├── requirements/                       # 需求分析階段
│   ├── requirement-analysis.md
│   └── user-story-generation.md
├── architecture/                       # 架構設計階段
│   ├── architecture-review.md
│   └── tech-stack-evaluation.md
├── development/                        # 開發階段
│   ├── coding-standard.md
│   ├── refactor-guidance.md
│   └── migration-planning.md
├── testing/                            # 測試階段
│   ├── test-strategy.md
│   └── test-case-generation.md
├── security/                           # 安全審查階段
│   ├── security-audit.md
│   └── threat-modeling.md
├── release/                            # 發佈階段
│   ├── pr-review.md
│   └── incident-analysis.md
└── reverse-engineering/                # 逆向工程
    └── legacy-analysis.md

7.3 版本管理策略

Prompt 版本管理原則：

1. Git 追蹤：所有 Prompt 範本納入版本控制。
2. 語意化版號：在 Prompt 檔案頂部標注版本（如 v1.2.0）。
3. Changelog：重大修改需記錄變更原因與日期。
4. Review 流程：Prompt 修改需經過 Code Review（PR）。
5. A/B 測試：重要 Prompt 可保留新舊版本，比較產出品質。

<!-- Prompt 版本標頭範例 -->
<!-- Version: 1.2.0 | Updated: 2026-04-24 | Author: security-team -->
<!-- Changelog:
  - v1.2.0 (2026-04-24): 新增 A08/A09 檢查項目
  - v1.1.0 (2026-03-15): 改善輸出格式，增加 CWE ID
  - v1.0.0 (2026-02-01): 初始版本
-->

7.4 Prompt 範本集（10 個）

Prompt 1：需求分析 (Requirements Analysis)

範本：

# Prompt: Requirements Analysis
<!-- Version: 1.0.0 | Category: requirements -->

## 指令
請分析以下需求文件/使用者故事，產出結構化的需求分析報告。

## 輸入
- 需求來源：{需求文件/JIRA Issue/使用者口述}
- 專案背景：{簡述專案目標與現有系統}
- 利害關係人：{列出相關角色}

## 分析維度
1. **功能需求**：拆解為獨立、可測試的功能項目
2. **非功能需求**：效能、安全、可用性、可維護性
3. **約束條件**：技術限制、法規要求、時程
4. **假設與風險**：隱含假設與潛在風險
5. **優先排序**：MoSCoW 分類（Must/Should/Could/Won't）

## 輸出格式
| # | 需求描述 | 類型 | MoSCoW | 驗收條件 | 風險 |

使用時機：Sprint Planning 前、PRD 評審時、使用者訪談後的需求整理。

輸入要素：需求原文、專案 context、利害關係人清單。

輸出格式：結構化表格 + 風險清單 + 後續行動建議。

風險與限制：LLM 可能遺漏隱含需求；無法替代與使用者的直接溝通；建議結果必須經 PO 確認。

Prompt 2：架構評審 (Architecture Review)

範本：

# Prompt: Architecture Review
<!-- Version: 1.0.0 | Category: architecture -->

## 指令
請對以下系統架構進行全面評審，涵蓋設計原則、可擴展性、安全性與可維護性。

## 輸入
- 架構文件/圖：{C4 diagram / 系統架構圖 / 文字描述}
- 技術棧：{語言、框架、資料庫、雲平台}
- 預期規模：{使用者數、TPS、資料量}
- 團隊規模：{開發人員數、團隊結構}

## 評審維度
1. **架構風格適切性**：Monolith vs. Microservices vs. Serverless
2. **分層清晰度**：各層職責、介面定義
3. **耦合與內聚**：模組間依賴方向、循環依賴
4. **可擴展性**：水平/垂直擴展能力
5. **韌性**：容錯、重試、斷路器
6. **安全架構**：認證/授權、網路隔離、機密管理
7. **可觀測性**：日誌、度量、追蹤
8. **資料管理**：資料一致性策略、備份/復原

## 輸出格式
- 架構評分卡（每維度 1-5 分）
- 風險清單（含嚴重度與影響範圍）
- 改善建議（含優先級）
- 替代方案比較（若有）

使用時機：新專案架構設計完成後、重大架構變更前、技術債盤點時。

輸入要素：架構圖、技術棧資訊、規模與團隊資訊。

輸出格式：評分卡 + 風險清單 + 改善建議。

風險與限制：LLM 無法驗證架構的實際執行效能；建議需結合 POC 驗證。

Prompt 3：程式碼撰寫指引 (Coding Standard)

範本：

# Prompt: Coding Standard Implementation
<!-- Version: 1.0.0 | Category: development -->

## 指令
請根據以下規範撰寫 {語言} 程式碼，實作 {功能描述}。

## 輸入
- 語言/框架：{Java 17 + Spring Boot 3.x / Python 3.12 + FastAPI / etc.}
- 功能需求：{具體功能描述}
- 介面規格：{API spec / 方法簽名 / DTO 定義}
- 相關檔案：{需參考的現有程式碼路徑}

## 品質要求
1. **命名**：遵循語言慣例（Java: camelCase 方法、PascalCase 類別）
2. **註解**：公開方法使用 JavaDoc/docstring，複雜邏輯加行內註解
3. **錯誤處理**：使用具體例外類別，提供有意義的錯誤訊息
4. **日誌**：關鍵操作加入 INFO 日誌，錯誤加入 ERROR 日誌（含 context）
5. **安全**：輸入驗證、輸出編碼、參數化查詢
6. **測試**：同時產出對應的單元測試

## 輸出
- 實作程式碼（含完整 import）
- 對應單元測試
- 需要新增的依賴（若有）

使用時機：新功能開發、技術需求實作。

輸入要素：語言/框架版本、功能規格、相關程式碼路徑。

輸出格式：完整原始碼 + 測試 + 依賴清單。

風險與限制：產出的程式碼必須經人工審查；LLM 可能產生看似合理但有隱含 bug 的程式碼。

Prompt 4：重構指引 (Refactoring Guidance)

範本：

# Prompt: Refactoring Guidance
<!-- Version: 1.0.0 | Category: development -->

## 指令
請分析以下程式碼並提供重構建議，確保重構後行為不變（Behavior Preservation）。

## 輸入
- 目標程式碼：{檔案路徑或程式碼片段}
- 重構目標：{提高可讀性 / 降低複雜度 / 抽取共用模組 / 套用設計模式}
- 約束：{不可更改公開 API / 必須向下相容 / 時間限制}

## 分析步驟
1. **現況評估**：目前的問題（圈複雜度、重複碼、耦合度）
2. **重構策略**：建議的重構手法（Extract Method / Introduce Interface / etc.）
3. **風險評估**：可能影響的其他模組、需要更新的測試
4. **逐步計畫**：可分階段執行的重構步驟，每步可獨立驗證
5. **驗證方式**：重構前後的等價驗證方法

## 輸出格式
1. 現況分析（含指標數據）
2. 重構計畫（步驟化）
3. 重構後的程式碼
4. 更新後的測試
5. 注意事項

使用時機：Code Review 發現品質問題時、技術債清理 Sprint、大型功能修改前。

輸入要素：目標程式碼路徑、重構目標、約束條件。

輸出格式：分析報告 + 逐步計畫 + 重構後程式碼 + 測試。

風險與限制：大範圍重構建議使用 Worktree 隔離；重構後必須跑完整測試套件。

Prompt 5：測試策略與用例產生 (Testing)

範本：

# Prompt: Test Strategy & Case Generation
<!-- Version: 1.0.0 | Category: testing -->

## 指令
請為以下程式碼/功能建立完整的測試策略與測試案例。

## 輸入
- 目標程式碼：{檔案路徑或方法簽名}
- 測試框架：{JUnit 5 / pytest / Jest}
- 測試層級：{Unit / Integration / E2E}
- 外部依賴：{需要 Mock 的服務}

## 測試策略
1. **Happy Path**：正常流程的驗證
2. **Edge Cases**：邊界值（null、空集合、最大值、最小值）
3. **Error Cases**：異常輸入、外部服務故障
4. **Security Cases**：注入攻擊、權限繞過
5. **Concurrency Cases**：並發存取（若適用）

## 每個測試案例需包含
- 測試名稱（描述性，given_when_then 格式）
- 前置條件 (Arrange)
- 操作 (Act)
- 驗證 (Assert)
- 說明為何此測試重要

## 輸出格式
1. 測試策略概述
2. 可執行的測試程式碼
3. 需要的 Mock/Stub 設定
4. 測試資料準備

使用時機：新功能開發完成後、Code Review 前、提高測試覆蓋率時。

輸入要素：目標程式碼、測試框架、外部依賴清單。

輸出格式：可直接執行的測試程式碼 + 測試資料 + Mock 設定。

風險與限制：LLM 產生的測試可能遺漏重要場景；建議搭配 mutation testing 驗證測試品質。

Prompt 6：安全審查 (Security Audit)

範本：

# Prompt: Security Audit
<!-- Version: 1.0.0 | Category: security -->

## 指令
請對以下程式碼進行 OWASP Top 10（2021）安全審查，並檢查 SANS CWE Top 25 中的常見弱點。

## 輸入
- 審查範圍：{檔案路徑 / 模組 / 整個專案}
- 應用類型：{Web API / 前端 SPA / 後端服務 / CLI 工具}
- 認證機制：{JWT / Session / OAuth2 / API Key}
- 資料敏感度：{PII / 金融 / 醫療 / 一般}

## 檢查項目
### OWASP Top 10 (2021)
- A01: Broken Access Control
- A02: Cryptographic Failures
- A03: Injection（SQL/NoSQL/OS Command/LDAP）
- A04: Insecure Design
- A05: Security Misconfiguration
- A06: Vulnerable and Outdated Components
- A07: Identification and Authentication Failures
- A08: Software and Data Integrity Failures
- A09: Security Logging and Monitoring Failures
- A10: Server-Side Request Forgery (SSRF)

### 額外檢查
- 硬編碼 credentials（API key、password、token）
- 不安全的反序列化
- 敏感資料暴露於日誌
- CORS 設定不當
- HTTP Security Headers 缺失

## 輸出格式
| 嚴重度 | OWASP/CWE | 檔案:行號 | 漏洞描述 | 攻擊向量 | 修復建議 | 修復範例 |

使用時機：PR Review 安全檢查、Release 前安全審計、Security Sprint。

輸入要素：審查範圍、應用類型、認證機制、資料敏感度。

輸出格式：漏洞報告表格 + 修復範例程式碼。

風險與限制：LLM 安全審查不可替代專業滲透測試；需搭配 SAST/DAST 工具；🔴 Critical 漏洞需人工確認。

Prompt 7：逆向工程分析 (Reverse Engineering)

範本：

# Prompt: Reverse Engineering Analysis
<!-- Version: 1.0.0 | Category: reverse-engineering -->

## 指令
請對以下舊系統進行逆向工程分析，產出架構文件與現代化建議。

## 輸入
- 專案路徑：{root path}
- 已知技術棧：{若已知，列出語言、框架、DB}
- 分析深度：{概覽 / 模組級 / 方法級}
- 重點關注：{核心業務邏輯 / 資料流 / 整合點 / 安全性}

## 分析流程
1. **技術棧偵測**：掃描 build 設定、依賴宣告、框架特徵
2. **目錄結構分析**：識別分層架構與模組劃分
3. **進入點識別**：main()、Servlet、Controller、Scheduled Tasks
4. **資料流追蹤**：API → Service → DAO → DB
5. **外部整合盤點**：第三方 API、MQ、File I/O、LDAP
6. **資料模型分析**：Entity/Table 關係、ER Diagram
7. **組態分析**：設定檔、環境變數、Feature Flag
8. **安全態勢**：認證/授權機制、已知 CVE

## 輸出格式
1. 技術棧摘要
2. 架構概覽圖（Mermaid C4 Context）
3. 模組清單與職責
4. 類別關係圖（Mermaid classDiagram，核心模組）
5. 關鍵資料流圖（Mermaid sequenceDiagram）
6. 技術債清單
7. 現代化建議與優先順序

使用時機：接手舊系統維護、規劃系統重寫/重構、評估併購標的技術資產。

輸入要素：專案路徑、已知技術資訊、分析深度。

輸出格式：多份 Mermaid 圖表 + 技術債清單 + 現代化路線圖。

風險與限制：大型專案（> 500 檔案）應分模組逐一分析；LLM 可能遺漏動態載入/反射機制的依賴。

Prompt 8：PR Review (Pull Request Review)

範本：

# Prompt: Pull Request Review
<!-- Version: 1.0.0 | Category: release -->

## 指令
請對以下 Pull Request 進行全面審查，產出結構化的 Review 報告。

## 輸入
- PR 描述：{PR title + description}
- 變更檔案清單：{files changed}
- 關聯 Issue：{JIRA/GitHub Issue ID}
- 審查重點：{全面 / 安全聚焦 / 效能聚焦}

## 審查維度
1. **功能正確性**：是否符合 Issue 需求？是否有遺漏？
2. **程式碼品質**：命名、結構、複雜度、重複碼
3. **安全性**：OWASP Top 10 相關檢查
4. **效能**：N+1 查詢、不必要的記憶體配置、阻塞操作
5. **測試**：是否有對應測試？測試是否充分？
6. **向下相容**：API 變更是否向下相容？
7. **文件**：API 文件是否更新？Changelog 是否記錄？

## 輸出格式
### 總體評價
- ✅ Approve / ⚠️ Request Changes / ❌ Reject

### 詳細 Review
| 類型 | 檔案:行號 | 問題描述 | 嚴重度 | 建議修正 |

類型：🐛 Bug / 🔒 Security / ⚡ Performance / 📝 Style / 💡 Suggestion

使用時機：PR Review 時、自動化 Code Review 流程。

輸入要素：PR 差異、關聯 Issue、審查重點。

輸出格式：總體評價 + 逐項 Review 表格。

風險與限制：LLM Review 不可替代人工 Review；建議作為第一輪篩選，人工做最終決定。

Prompt 9：事故分析 (Incident Analysis)

範本：

# Prompt: Incident Analysis
<!-- Version: 1.0.0 | Category: release -->

## 指令
請根據以下事故資訊進行根因分析（Root Cause Analysis），並產出事故報告。

## 輸入
- 事故描述：{什麼壞了、影響範圍、持續時間}
- 時間軸：{發現時間、處理過程、恢復時間}
- 錯誤日誌：{相關 log 片段}
- 監控資料：{異常指標、告警}
- 變更記錄：{事故前的 deploy/config 變更}

## 分析框架（5 Whys + Fishbone）
1. **直接原因**：觸發事故的直接技術原因
2. **5 Whys 深掘**：逐層追問根本原因
3. **魚骨分析**：
   - 人員：操作錯誤、知識不足
   - 流程：SOP 缺陷、審核不足
   - 技術：程式碼 bug、架構缺陷
   - 環境：基礎設施、第三方故障

## 輸出格式
1. 事故摘要（一段話）
2. 時間軸（表格）
3. 根因分析（5 Whys 鏈）
4. 影響評估（使用者數、財務、聲譽）
5. 短期修復（已執行/待執行）
6. 長期改善（防止再發）
7. Action Items 清單（含負責人與期限）

使用時機：P1/P2 事故發生後、Post-mortem 會議準備。

輸入要素：事故描述、時間軸、日誌、監控資料、變更記錄。

輸出格式：事故報告（含根因分析 + Action Items）。

風險與限制：LLM 無法存取即時監控資料，需人工提供；根因分析需團隊共同驗證。

Prompt 10：遷移規劃 (Migration Planning)

範本：

# Prompt: Migration Planning
<!-- Version: 1.0.0 | Category: development -->

## 指令
請根據以下現況與目標，規劃系統/框架/語言遷移方案。

## 輸入
- 現況：{目前技術棧、版本、規模}
- 目標：{目標技術棧、版本}
- 約束：{時程、預算、團隊能力、不可中斷的服務}
- 優先級：{全部一次遷移 / 漸進式遷移}

## 規劃維度
1. **差異分析**：現況 vs. 目標的 breaking changes
2. **依賴影響**：受影響的第三方套件與版本
3. **資料遷移**：Schema 變更、資料轉換
4. **API 相容性**：公開 API 的向下相容策略
5. **漸進式策略**：Strangler Fig / Branch by Abstraction / Feature Toggle
6. **驗證計畫**：每階段的驗證方式與 rollback 計畫
7. **風險矩陣**：機率 × 影響的風險評估

## 輸出格式
1. 遷移概述（一頁摘要）
2. 差異分析表
3. 階段化遷移計畫（甘特圖邏輯）
4. 風險矩陣
5. Rollback 計畫
6. 驗證 Checklist

使用時機：框架大版本升級、語言遷移、雲平台搬遷、資料庫遷移。

輸入要素：現況技術棧、目標、約束條件。

輸出格式：遷移計畫書（含階段化步驟 + 風險矩陣 + Rollback 計畫）。

風險與限制：LLM 可能不了解特定框架版本的所有 breaking changes；建議搭配官方 migration guide 交叉驗證。

7.5 實務建議

1. Prompt 是團隊資產：將 Prompt Library 視為與原始碼同等重要的團隊資產，納入 Git 管理並嚴格 Review。
2. 版本管理不可少：每次修改 Prompt 都應更新版本號並記錄 Changelog，方便追溯產出品質變化。
3. 情境化而非通用化：好的 Prompt 應包含具體的輸入要素、輸出格式與品質標準，避免過於通用導致產出不穩定。
4. 搭配 CLAUDE.md 使用：將專案級的 context（命名慣例、技術棧、禁用清單）放在 CLAUDE.md，Prompt 只需專注於任務邏輯。
5. 測試你的 Prompt：定期以相同輸入測試 Prompt，檢查產出一致性。若發現品質下降，可能需要調整 Prompt 或 CLAUDE.md。
6. 分享最佳實踐：建立團隊 Prompt Review 機制，定期分享高效 Prompt 的撰寫技巧。
7. 安全審查 Prompt 不可替代工具：Security Audit Prompt 的產出應作為第一層篩選，仍需搭配 SAST/DAST 工具與專業滲透測試。
8. Prompt 與 Skill 的選擇：若一個 Prompt 被頻繁使用且流程固定，考慮將其轉為 Skill（SKILL.md），以獲得自動觸發與工具控制能力。

Ch 8：建立 Skills

8.1 Skills 定義與核心概念

Skills 是 Claude Code 中以 SKILL.md 檔案定義的可重用能力模組，結合工作流程指引與知識注入，讓 Claude 能執行標準化的專業任務。

📌 與舊版 Commands 的關係：早期版本的「Custom Commands」已併入 Skills——.claude/commands/deploy.md 與 .claude/skills/deploy/SKILL.md 兩種寫法都會建立 /deploy 指令，行為完全相同。.claude/commands/ 路徑為向下相容保留，新建議一律使用 .claude/skills/<name>/SKILL.md 的目錄形式，方便附加 Supporting Files。

Skill 的本質：Skill = 工作流程指引 + 知識注入 + 工具控制

graph TD
    subgraph SkillDefinition["SKILL.md 結構"]
        FM["YAML Frontmatter<br/>name, description,<br/>allowed-tools, context"]
        Body["Markdown Body<br/>角色定義、流程、<br/>輸出格式、規則"]
        SF["Supporting Files<br/>範本、規則集、<br/>checklist"]
    end

    subgraph Trigger["觸發方式"]
        Auto["自動觸發<br/>（Claude 依 description 匹配）"]
        Manual["手動觸發<br/>（/skill-name 指令）"]
    end

    subgraph Runtime["執行時"]
        Context["Context 注入<br/>SKILL.md + supporting files"]
        Tools["工具限制<br/>allowed-tools 白名單"]
        Model["模型行為<br/>disable-model-invocation"]
    end

    Trigger --> SkillDefinition
    SkillDefinition --> Runtime

    style SkillDefinition fill:#e8f5e9
    style Trigger fill:#e3f2fd
    style Runtime fill:#fff3e0

8.2 Skills 與相關功能的差異

8.3 自動觸發 vs. 手動觸發

自動觸發：當使用者的請求與 Skill 的 description 匹配時，Claude 會自動載入並套用該 Skill。

手動觸發：使用 /skill-name 指令明確呼叫。

# 自動觸發 — Claude 判斷 "security" 關鍵字匹配 security-check skill
> 請檢查 src/auth/ 的安全性

# 手動觸發 — 明確指定
> /security-check src/auth/

disable-model-invocation: true：設定此選項後，Skill 不會被自動觸發，只能手動呼叫。適用於有副作用或高成本的 Skill。

8.4 Supporting Files 與漸進式揭露（Progressive Disclosure）

Skill 可在同一目錄下放置輔助檔案（supporting files），如規則集、範本、checklist 等。

⚠️ 常見誤解：輔助檔案不會在 Skill 觸發時一併載入 context。Claude Code 只會載入 SKILL.md 的內容，輔助檔案則是 Claude 判斷需要時才用 Read 工具讀取。這正是 Skills 的核心成本優勢——大型參考資料在用到之前幾乎不花 token。

.claude/skills/
└── security-check/
    ├── SKILL.md                    # Skill 主定義（僅此檔會在觸發時載入）
    ├── owasp-rules.md              # OWASP 規則集（需要時才讀取）
    ├── cwe-top-25.md               # CWE Top 25 清單（需要時才讀取）
    ├── security-report-template.md # 報告範本（需要時才讀取）
    └── scripts/
        └── scan.py                 # 工具腳本（被「執行」而非「載入」）

三層成本模型：