Claude Code 生態圈教學手冊

• 📖 版本：v3.5（企業技術白皮書版）
• 📅 最後更新：2026 年 9 月 24 日
• 🔎 查證基準：Claude Code v2.1.281（2026-09-23），逐頁比對 code.claude.com 官方文件
• 👥 目標讀者：資深軟體工程師、技術主管、架構師、平台／DevOps 工程師、資安與 IT 管理員
• ✍️ Created by：Eric Cheng

文件資訊

適用範圍

本手冊涵蓋 Claude Code 在 Terminal CLI、VS Code／JetBrains、Desktop App、Web（claude.ai/code）、CI/CD 等介面上的使用方式，以及 Subagents、Agent Teams、Skills、Plugins、Hooks、MCP、Output Styles、排程任務、Remote Control、Channels 等擴充與協作機制，並提供企業部署、治理、成本與安全的實務建議。

閱讀指引

標示說明

v3.5 修訂重點

🆕 v3.5（2026-09-24）：以 v2.1.281 為基準，逐頁比對使用者指定的 17 個官方頁面與約 40 個延伸頁面（完整清單見附錄 H）。

1. 修正會造成安全漏洞的錯誤範例：約 25 處 hook 範例依賴不存在的 $CLAUDE_FILE_PATH 等環境變數、阻擋型 hook 誤用 exit 1；Subagent 誤用 allowed-tools（會繼承全部工具）；把 Skill 的 allowed-tools 誤解為限制；權限規則比對順序寫反；不存在的 .claudeignore。
2. 移除虛構的設定與指令：scheduledTasks、managed-mcp 的 policy 物件、plugins.allowed、/plugin marketplace search、/install-plugin、claude-code.* VS Code 設定、@anthropic/mcp-server-* 套件、plugin manifest 的 tools[]、細分的退出碼等。
3. 同步 2026 年 8–9 月的功能：Opus 5.5 成為預設模型與 effort、Fable 5.1、AGENTS.md 原生支援、auto mode 起始模式與伺服器端分類器、fork mode、Dynamic Workflows、Agent view、Cross-session messaging、Projects、/skill-doctor、Plugin Evals、MCP 2026-07-28 協定、/output-style 恢復、Concise 風格、Routines 觸發、Self-hosted Environments、--restricted、版本範圍強制等。
4. 白皮書化：新增文件資訊、各部摘要、企業導入檢核要點、沙箱、成本治理、Code Review 三種做法、功能演進時間軸（附錄 G）與查證記錄（附錄 H）。
5. 格式與目錄：依實際標題重新產生三層目錄，並以 Hugo 實際建置驗證所有錨點連結。

📜 v3.4（2026-08-13）：修正 Auto Memory、Agent Teams 工作目錄、managed-settings 路徑；移除虛構的 Remote Control WebSocket API、ClaudeCode SDK 類別與多個不存在的 CLI 旗標；同步 6–8 月約 30 個版本的變更。

目錄

• 文件資訊
• 第一部分：基礎概念 (Foundation)
  • 1.1 Claude Code 簡介
    • 1.1.1 產品定位與核心價值
    • 1.1.2 多平台支援總覽
    • 1.1.3 適用場景與限制
    • 1.1.4 安裝與環境配置
    • 1.1.5 Claude Code 的運作原理
    • 1.1.6 Desktop App 與 Web 介面
    • 1.1.7 Channels 與 Dispatch
    • 1.1.8 模型陣容與推理投入程度（Effort）
  • 1.2 核心架構概覽
    • 1.2.1 系統架構圖
    • 1.2.2 各組件之間的關係
    • 1.2.3 資料流與執行流程
    • 1.2.4 記憶體與設定架構
    • 1.2.5 權限與安全模型
    • 1.2.6 工具系統詳解
    • 1.2.7 Agentic Loop 深入解析
  • 1.3 快速上手實戰
    • 1.3.1 第一次對話
    • 1.3.2 建立 CLAUDE.md
    • 1.3.3 常見操作範例
    • 1.3.4 效率提升技巧
• 第二部分：核心功能詳解
  • 2.1 Subagents (子代理)
    • 2.1.1 概念說明
    • 2.1.2 內建子代理類型
    • 2.1.3 自訂子代理
    • 2.1.4 使用場景與實作範例
    • 2.1.5 進階技巧
    • 2.1.6 Subagent 完整實戰範例
  • 2.2 Agent Teams（多代理協作）
    • 2.2.1 Agent Teams 概述
    • 2.2.2 啟動與使用 Agent Teams
    • 2.2.3 Agent Teams 的協調機制
    • 2.2.4 應用場景與最佳實踐
    • 2.2.5 Agent Teams 進階模式
    • 2.2.6 Agent Teams 搭配 Hooks
    • 2.2.7 Teammate 權限、安全與成本
    • 2.2.8 官方平行執行方式分類與新型協作機制
  • 2.3 Skills（技能系統）
    • 2.3.1 Skills 概述
    • 2.3.2 內建 Skills（Slash Commands）
    • 2.3.3 SKILL.md 檔案格式
    • 2.3.4 Agent Skills（附加在 Agent 上的 Skills）
    • 2.3.5 開發自訂 Skills
    • 2.3.6 Skills 最佳實踐
    • 2.3.7 Skill 進階範例集
    • 2.3.8 Skill 來源、優先順序與雲端同步
  • 2.4 Plugins（插件系統）
    • 2.4.1 Plugin 概述
    • 2.4.2 Plugin 目錄結構
    • 2.4.3 Plugin 的發現與安裝
    • 2.4.4 開發自訂 Plugin
    • 2.4.5 Plugin 安全與信任
    • 2.4.6 Plugin 實戰範例
    • 2.4.7 Plugin 與其他機制的關係
  • 2.5 Hooks（鉤子機制）
    • 2.5.1 Hooks 系統概述
    • 2.5.2 Hook 事件類型（33 種）
    • 2.5.3 Hook 類型（5 種）
    • 2.5.4 Hook 配置詳解
    • 2.5.5 實用 Hook 範例
    • 2.5.6 Hook 執行規則與最佳實踐
    • 2.5.7 進階 Hook 架構模式
    • 2.5.8 Hook 進階控制機制
    • 2.5.9 非同步 Hook、一次性 Hook 與企業治理
  • 2.6 MCP（Model Context Protocol）
    • 2.6.1 MCP 概述
    • 2.6.2 配置 MCP Server
    • 2.6.3 工具搜尋（Tool Search）
    • 2.6.4 MCP 認證
    • 2.6.5 企業級 MCP 管理
    • 2.6.6 常見 MCP Server 推薦
    • 2.6.7 自行開發 MCP Server
    • 2.6.8 MCP 進階機制
    • 2.6.9 MCP 除錯與疑難排解
    • 2.6.10 MCP 2026-07-28 協定、claude.ai Connectors 與新增控制
  • 2.7 Output Styles（輸出風格）
    • 2.7.1 Output Styles 概述
    • 2.7.2 配置 Output Styles
    • 2.7.3 自訂輸出範本
    • 2.7.4 場景化輸出風格
    • 2.7.5 Output Styles 覆寫機制
    • 2.7.6 與 Agent/Skill 結合
  • 2.8 Scheduled Tasks（排程任務）
    • 2.8.1 Scheduled Tasks 概述
    • 2.8.2 配置排程任務
    • 2.8.3 應用場景
    • 2.8.4 排程任務搭配 Headless 模式
    • 2.8.5 排程任務監控與通知
    • 2.8.6 排程任務最佳實踐
• 第三部分：整合與最佳實踐
  • 3.1 VS Code Extension 整合
    • 3.1.1 安裝與啟用
    • 3.1.2 核心功能
    • 3.1.3 Checkpoints（檢查點）
    • 3.1.4 Worktree 整合
    • 3.1.5 第三方 AI Provider
    • 3.1.6 VS Code 快捷鍵與命令總覽
    • 3.1.7 Plan Mode（規劃模式）詳解
    • 3.1.8 🆕 URI Handler 與 Plugin 管理 UI
    • 3.1.9 VS Code 多實例與 Terminal 整合
  • 3.2 Remote Control（遠端控制）
    • 3.2.1 概述
    • 3.2.2 啟動與連接
    • 3.2.3 連線安全與 Trusted Devices
    • 3.2.4 應用場景：如何在「不在電腦前」的情境中選擇合適機制
    • 3.2.5 手機推播通知與限制
    • 3.2.6 自動連線、Session 恢復與已連線裝置的行為
  • 3.3 Headless 模式與 SDK
    • 3.3.1 Headless 模式
    • 3.3.2 Agent SDK 整合
    • 3.3.3 應用場景
    • 3.3.4 Headless 模式進階用法
  • 3.4 整合工作流程
    • 3.4.1 端到端開發流程
    • 3.4.2 多元件協作實例
    • 3.4.3 自動化配置組合範例
    • 3.4.4 完整工作流程範例：從 Issue 到 PR
    • 3.4.5 完整配置檔整合範例
  • 3.5 團隊協作指南
    • 3.5.1 共享配置管理
    • 3.5.2 協作模式
    • 3.5.3 知識共享
    • 3.5.4 新人入職（Onboarding）工作流程
    • 3.5.5 Code Review 工作流程
    • 3.5.6 團隊開發標準化流程
    • 3.5.7 社群與業界導入實務（社群建議）
  • 3.6 效能優化
    • 3.6.1 Token 使用優化
    • 3.6.2 Context 管理優化
    • 3.6.3 執行效率優化
    • 3.6.4 成本控制策略
    • 3.6.5 企業成本治理
  • 3.7 疑難排解
    • 3.7.1 常見問題與解決方案
    • 3.7.2 診斷方法
    • 3.7.3 效能問題排查
    • 3.7.4 取得幫助
  • 3.8 Cowork 協同開發實戰
    • 3.8.1 Cowork 概念與模式
    • 3.8.2 團隊共享 CLAUDE.md 策略
    • 3.8.3 多人協作工作流程
    • 3.8.4 Agent Teams 協同開發
    • 3.8.5 跨團隊 Plugin Marketplace
    • 3.8.6 Remote Control 遠端協作
    • 3.8.7 Channels 與 Dispatch 即時協作
    • 3.8.8 Cowork 最佳實踐與防踩坑指南
• 第四部分：進階主題
  • 4.1 企業級部署
    • 4.1.1 企業管理架構
    • 4.1.2 安全性配置
    • 4.1.3 SSO 與認證整合
    • 4.1.4 稽核日誌與合規性
    • 4.1.5 企業部署架構模式
    • 4.1.6 企業級配置管理策略
    • 4.1.7 Managed Settings 傳遞機制、版本控管與 Self-hosted Environments
  • 4.2 CI/CD 整合
    • 4.2.1 GitHub Actions 整合
    • 4.2.2 GitLab CI/CD 整合
    • 4.2.3 通用 CI/CD 整合模式
    • 4.2.4 CI/CD 最佳實踐
    • 4.2.5 進階 CI/CD 場景
    • 4.2.6 AI Code Review 的三種官方做法
  • 4.3 自訂開發
    • 4.3.1 開發自訂 MCP Server
    • 4.3.2 開發自訂 Skill
    • 4.3.3 開發自訂 Plugin
    • 4.3.4 自訂開發整合模式
  • 4.4 Channels 與 Dispatch 深入解析
    • 4.4.1 Channels 架構與協定
    • 4.4.2 支援的通訊管道
    • 4.4.3 Dispatch 行動端整合
    • 4.4.4 自建 Channel MCP Server
    • 4.4.5 企業級 Channel 部署
  • 4.5 Agent Skills Open Standard
    • 4.5.1 開放標準概述
    • 4.5.2 agentskills.io 規範
    • 4.5.3 跨工具互通性
    • 4.5.4 社群生態與未來發展
• 第五部分：附錄
  • 附錄 A：CLI 命令參考
    • A.1 啟動與基本操作
    • A.2 Slash Commands（互動式模式）
    • A.3 Custom Slash Commands
    • A.4 CLI 配置命令
    • A.5 進階 CLI 選項
    • A.6 CLI 環境變數
    • A.7 退出碼（Exit Codes）
    • A.8 CLI 使用範例集
  • 附錄 B：配置檔案參考
    • B.1 配置檔案一覽
    • B.2 settings.json 完整結構
    • B.3 .mcp.json 完整結構
    • B.4 CLAUDE.md 建議結構
    • B.5 managed-settings.json（企業管理員配置）
    • B.6 managed-mcp.json（企業 MCP 管理）
    • B.7 敏感檔案與大型檔案排除（取代 .claudeignore）
    • B.8 配置優先級完整圖
  • 附錄 C：Hook Events 完整參考
    • C.1 所有事件
    • C.2 Hook 類型
    • C.3 環境變數
    • C.4 各事件詳細範例
    • C.5 常見 Hook 配方集
    • C.6 Hook 執行流程與錯誤處理
  • 附錄 D：常見 MCP Servers 一覽
    • D.1 官方 MCP Servers
    • D.2 社群熱門 MCP Servers
    • D.3 依場景選擇 MCP Server
    • D.4 MCP Server 配置範本
    • D.5 MCP Server 開發快速入門
    • D.6 MCP Server 除錯與監控
    • D.7 MCP Server 安全最佳實踐
  • 附錄 E：術語表
  • 附錄 F：常見問題 FAQ
    • F.1 安裝與設定
    • F.2 使用技巧
    • F.3 企業使用
    • F.4 成本與效能
    • F.5 MCP 整合
    • F.6 Agent Teams 與協作
    • F.7 Skills 與 Plugins
    • F.8 安全與隱私
  • 附錄 G：2026 功能演進時間軸
    • G.1 如何使用這份時間軸
    • G.2 季度重點總覽
    • G.3 逐週對照表
    • G.4 週報之後（v2.1.270–281，2026-09-12 至 09-23）
  • 附錄 H：v3.5 查證記錄與變更摘要
    • H.1 查證資訊
    • H.2 已逐頁覆核的官方頁面
    • H.3 v3.4 → v3.5 重大更正
    • H.4 v3.5 新增章節
    • H.5 待覆核項目
    • H.6 建議覆核節奏
• 結語
  • 學習路徑建議
  • 持續學習

第一部分：基礎概念 (Foundation)

📌 本部摘要：說明 Claude Code 的定位、各介面、安裝與認證（1.1），agentic loop、context、記憶、權限模式與沙箱等核心架構（1.2），以及第一次使用的實作流程（1.3）。讀完本部應能判斷「Claude 在哪裡執行、看得到什麼、能做什麼、如何被限制」。

1.1 Claude Code 簡介

1.1.1 產品定位與核心價值

Claude Code 是 Anthropic 推出的 AI 輔助程式開發工具，定位為開發者的智慧協作夥伴，而非單純的程式碼生成器。

graph TD
    A[Claude Code] --> B[程式碼生成]
    A --> C[程式碼理解]
    A --> D[重構建議]
    A --> E[除錯協助]
    A --> F[文件生成]
    A --> G[測試生成]
    
    style A fill:#6366f1,stroke:#4f46e5,color:#fff
    style B fill:#f0f9ff,stroke:#0ea5e9
    style C fill:#f0f9ff,stroke:#0ea5e9
    style D fill:#f0f9ff,stroke:#0ea5e9
    style E fill:#f0f9ff,stroke:#0ea5e9
    style F fill:#f0f9ff,stroke:#0ea5e9
    style G fill:#f0f9ff,stroke:#0ea5e9

核心價值主張

✨ 最佳實踐

Claude Code 不是要取代開發者，而是要成為開發者的「智慧副駕駛」。將 AI 視為協作者，而非工具，才能發揮最大效益。

1.1.2 多平台支援總覽

Claude Code 已從純 CLI 工具發展為跨平台智慧開發生態系統，支援多種使用界面與存取方式：

graph TB
    subgraph "開發平台"
        CLI["Terminal CLI<br/>macOS / Linux / Windows"]
        VSC["VS Code Extension<br/>v1.94.0+"]
        JB["JetBrains Plugin<br/>IntelliJ / WebStorm 等"]
        DA["Desktop App<br/>macOS / Windows / Linux(beta)"]
        WEB["Web 介面<br/>claude.ai/code"]
    end
    
    subgraph "擴展接入"
        SDK["Agent SDK<br/>Python / TypeScript"]
        CH["Channels<br/>Telegram / Discord / iMessage"]
        DISP["Dispatch<br/>行動裝置 → Desktop"]
        CHROME["Chrome Extension<br/>@browser 整合"]
        SLACK["Slack 整合"]
    end
    
    CLI --> CORE[Claude Code<br/>Core Engine]
    VSC --> CORE
    JB --> CORE
    DA --> CORE
    WEB --> CORE
    SDK --> CORE
    CH --> CORE
    DISP --> CORE
    CHROME --> CORE
    SLACK --> CORE
    
    style CORE fill:#6366f1,stroke:#4f46e5,color:#fff
    style DA fill:#10b981,stroke:#059669,color:#fff
    style WEB fill:#10b981,stroke:#059669,color:#fff
    style CH fill:#f59e0b,stroke:#d97706,color:#fff
    style DISP fill:#f59e0b,stroke:#d97706,color:#fff

與傳統 IDE 的差異

1.1.3 適用場景與限制

✅ 適用場景

1. 快速原型開發
   - 從需求文字快速生成初版程式碼
   - 產生 API 骨架與資料模型

2. 遺留系統維護
   - 解讀複雜的舊程式碼
   - 漸進式重構建議

3. 程式碼審查輔助
   - 自動檢測潛在問題
   - 提供改善建議

4. 文件與測試生成
   - 自動產生 API 文件
   - 生成單元測試案例

5. 學習與教學
   - 解釋程式碼邏輯
   - 示範設計模式

⚠️ 注意事項：不適用場景

1. 高度機密的商業邏輯
   - 需評估資料外洩風險
   - 考慮使用私有部署版本

2. 即時系統的關鍵路徑
   - AI 回應延遲不確定
   - 不適合作為線上服務依賴

3. 需要 100% 正確性的場景
   - AI 可能產生「看似正確但有缺陷」的程式碼
   - 永遠需要人工審查

4. 複雜的演算法開發
   - AI 擅長套用模式，但創新能力有限
   - 核心演算法仍需人工設計

1.1.4 安裝與環境配置

系統需求

📌 Windows 原生支援（v3.5 更正）：自 2026 年 4 月底（v2.1.120 起）起，原生 Windows 不再強制需要 Git Bash。有安裝 Git for Windows 時，Claude Code 使用 Bash 工具；沒有安裝時，改用 PowerShell 工具作為 shell。WSL 環境則不需要 Git for Windows。如需指定 bash 路徑，可在 settings.json 的 env 設定 CLAUDE_CODE_GIT_BASH_PATH。

安裝步驟

方法 1：原生安裝程式（推薦）

# macOS / Linux
curl -fsSL https://claude.ai/install.sh | bash

# Windows PowerShell（原生安裝）
irm https://claude.ai/install.ps1 | iex

# Windows CMD
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

# 更新到最新版本
claude update

方法 2：使用套件管理器安裝

# macOS / Linux — Homebrew（有兩個 cask：claude-code 是穩定通道，落後約一週且會跳過重大回歸版本；
# claude-code@latest 則是最新通道，新版釋出即可安裝）
brew install --cask claude-code
# 或
brew install --cask claude-code@latest

# Windows — WinGet
winget install Anthropic.ClaudeCode

# Debian / Fedora / RHEL / Alpine — 系統套件管理器
apt install claude-code      # Debian / Ubuntu
dnf install claude-code      # Fedora / RHEL
apk add claude-code          # Alpine

⚠️ 原生安裝程式（方法 1）會自動在背景更新至最新版；Homebrew 與 WinGet 安裝不會自動更新，須自行定期執行 brew upgrade claude-code（或 @latest）／winget upgrade Anthropic.ClaudeCode。

方法 3：IDE 擴充功能

# VS Code：從 Marketplace 搜尋 "Claude Code by Anthropic"，或命令列安裝
code --install-extension anthropic.claude-code
# Cursor 使用者可用相同方式安裝（擴充功能相容）

# 安裝完成後以 Cmd+Shift+P (macOS) 或 Ctrl+Shift+P (Windows/Linux) 開啟命令面板，
# 輸入 "Claude Code" 並選擇「Open in New Tab」

# JetBrains（IntelliJ IDEA / PyCharm / WebStorm 等）：
# 從 JetBrains Marketplace 安裝 "Claude Code" 外掛，重啟 IDE
# 仍需另外安裝 Claude Code CLI（外掛透過 CLI 運作）

方法 4：Desktop App（無需命令列）

• macOS: 從 claude.ai 下載 DMG 安裝（支援 Intel 與 Apple Silicon）
• Windows: 從 claude.ai 下載 EXE 安裝（x64 與 ARM64）

💡 Desktop App 提供圖形化安裝介面，可視覺化檢視 diff、同時並行多個工作階段、排程重複性任務，並可一鍵發起雲端工作階段，適合不熟悉命令列的使用者。需要付費訂閱方案。

步驟 2：認證

# 方法 A：互動式登入（推薦，使用 OAuth）——首次執行 claude 會自動引導；
# 也可在 session 內輸入 /login，或在 shell 使用 auth 子命令
claude auth login              # --sso 強制 SSO、--console 改用 Console（API 計費）
claude auth status --text      # 查看目前登入狀態（未登入時 exit code 為 1）

# 方法 B：使用 API 金鑰（互動模式首次會詢問是否核准此金鑰）
export ANTHROPIC_API_KEY="sk-ant-..."

# 方法 C：CI／腳本使用長效 OAuth token
claude setup-token             # 產生 token 後設為 CLAUDE_CODE_OAUTH_TOKEN

# 方法 D：雲端供應商（Amazon Bedrock／Google Cloud Agent Platform／Microsoft Foundry）
export CLAUDE_CODE_USE_BEDROCK=1   # 或 CLAUDE_CODE_USE_VERTEX=1 / CLAUDE_CODE_USE_FOUNDRY=1

📝 認證優先順序（v3.5 依官方 authentication 頁更正）：同時存在多組憑證時，Claude Code 依下列順序選用第一個成立者：

1. 雲端供應商憑證（設定了 CLAUDE_CODE_USE_BEDROCK／CLAUDE_CODE_USE_VERTEX／CLAUDE_CODE_USE_FOUNDRY 時）
2. ANTHROPIC_AUTH_TOKEN（以 Authorization: Bearer 送出，適用 LLM gateway／proxy）
3. ANTHROPIC_API_KEY（以 X-Api-Key 送出）
4. apiKeyHelper 腳本輸出（適合從 vault 取得的短效憑證）
5. CLAUDE_CODE_OAUTH_TOKEN（claude setup-token 產生的長效 token）
6. Anthropic profile／Workload Identity Federation 憑證
7. /login 取得的訂閱 OAuth 憑證（Pro／Max／Team／Enterprise 的預設）

已登入的 Claude apps gateway session 不在此清單內，它的優先權高於上述所有來源。

⚠️ 注意：如果有舊的 ANTHROPIC_API_KEY 環境變數殘留，核准後會優先於訂閱登入，若該金鑰所屬組織已停用就會認證失敗。使用 unset ANTHROPIC_API_KEY 退回訂閱，並在 /status 確認目前生效的認證方式。雲端 session 永遠使用訂閱憑證，在雲端環境設定 API key 不會覆蓋。

🔐 憑證儲存位置：macOS 存放在加密的 Keychain（Keychain 拒絕寫入時，例如 SSH 下鎖定，退回 ~/.claude/.credentials.json，權限 0600）；Linux 為 ~/.claude/.credentials.json（0600）；Windows 為 %USERPROFILE%\.claude\.credentials.json。設定 CLAUDE_CONFIG_DIR 時會改存到該目錄。

配置檔案結構

Claude Code 使用多層級配置系統，從全域到專案層層覆蓋：

全域配置
~/.claude/
├── settings.json          # 使用者設定（hooks、permissions、plugins…）
├── CLAUDE.md              # 全域指引（所有專案共用）
├── agents/  skills/       # 個人 Subagent 與 Skill
├── projects/<project>/    # 對話紀錄（明文 JSONL）與 Auto Memory
└── .credentials.json      # 認證資訊（Linux／Windows；macOS 存於 Keychain）
~/.claude.json             # 偏好、OAuth session、user／local 範圍的 MCP 設定

專案配置
專案根目錄/
├── .claude/
│   ├── settings.json      # 專案共享設定（提交至 Git）
│   ├── settings.local.json# 個人本地設定（自動加入 git 排除）
│   ├── agents/ skills/ rules/  # 專案 Subagent、Skill、路徑規則
├── .mcp.json              # 專案範圍 MCP Server 配置（提交至 Git）
├── CLAUDE.md              # 專案級指引（或 .claude/CLAUDE.md）
├── CLAUDE.local.md        # 個人專案指引（不進版控）
└── AGENTS.md              # 跨工具共用的專案指引；沒有 CLAUDE.md 時會直接讀取（v2.1.277+）

企業配置（系統目錄，需管理員權限）
/Library/Application Support/ClaudeCode/   # macOS
/etc/claude-code/                          # Linux / WSL
C:\Program Files\ClaudeCode\               # Windows
├── managed-settings.json  # 企業強制設定
├── managed-settings.d/    # 多團隊分檔維護的 drop-in 設定（與上者合併）
├── managed-mcp.json       # 企業級 MCP 配置
└── CLAUDE.md              # 組織層級指引

⚠️ v3.5 更正：Claude Code 沒有 .claudeignore 機制，官方文件從未定義這個檔案，寫了也不會生效。要讓 Claude 讀不到特定檔案，請使用 permissions.deny 的 Read(...) 規則（例如 Read(./.env)、Read(./secrets/**)）；Read deny 規則也會一併阻擋同路徑的 Edit／Write。檔案選擇器（@ 提及）預設會遵守 .gitignore，可用設定 respectGitignore 調整。詳見 B.7。

settings.json 基本範例：

{
  "permissions": {
    "allow": [
      "Read(*)",
      "Edit(*)",
      "Bash(npm test)",
      "Bash(npm run lint)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(git push --force)"
    ]
  },
  "env": {
    "NODE_ENV": "development",
    "CLAUDE_CODE_MAX_TURNS": "50"
  }
}

CLAUDE.md 團隊指引範例：

# 專案指引

## 程式碼規範
- 使用 TypeScript strict mode
- 所有 public function 需要 JSDoc 註解
- 遵循 ESLint 配置的規則

## 測試要求
- 新功能必須有單元測試
- 測試覆蓋率不低於 80%
- 使用 vitest 作為測試框架

## 專案結構
- src/ — 原始碼
- tests/ — 測試檔案
- docs/ — 文件

## 常用命令
- `npm test` — 執行測試
- `npm run build` — 建構專案
- `npm run lint` — 程式碼檢查

💡 小技巧

• 將 CLAUDE.md、.mcp.json 與 .claude/settings.json 提交至版本控制，讓團隊共享權限、hooks 與 plugins；個人偏好放在 .claude/settings.local.json（Claude Code 建立時會自動排除於 git；手動建立者須自行加入 .gitignore）
• 在 session 內用 /status 查看生效的設定來源（Setting sources），用 /config 調整設定；claude doctor（互動模式為 /doctor）可檢查被忽略或無效的設定
• ⚠️ claude config list、claude config set 等指令不存在（v3.4 已更正），請勿寫進團隊文件
• 敏感資訊（如 API 金鑰）應使用環境變數或 apiKeyHelper 管理，不要寫在設定檔中

1.1.5 Claude Code 的運作原理

Claude Code 是一個代理式程式設計系統 (agentic coding system)，其核心運作方式與傳統的程式碼補全工具有本質差異。官方文件將 Claude Code 定位為圍繞 Claude 模型打造的「agentic harness（代理式執行殼層）」——由它提供工具、context 管理與執行環境，把單純會推理的語言模型變成真正能動手做事的程式開發代理人。

代理式迴圈 (Agentic Loop)

graph TD
    A[使用者輸入] --> B[Claude 分析意圖]
    B --> C{需要使用工具?}
    C -->|是| D[選擇與執行工具]
    D --> E[觀察工具結果]
    E --> C
    C -->|否| F[生成回應]
    F --> G[呈現給使用者]
    
    style A fill:#6366f1,stroke:#4f46e5,color:#fff
    style B fill:#8b5cf6,stroke:#7c3aed,color:#fff
    style D fill:#10b981,stroke:#059669,color:#fff
    style F fill:#f59e0b,stroke:#d97706,color:#fff

官方文件將 Agentic Loop 定義為三個交織進行的階段：蒐集上下文（gather context）→ 採取行動（take action）→ 驗證結果（verify results），並依任務動態調整——單純的程式碼提問可能只需要蒐集上下文，Bug 修復會反覆經歷三個階段，大型重構則可能需要密集驗證。這三階段可再拆解為更細的實務步驟：

1. 讀取 (Read) — 解析使用者意圖，蒐集專案上下文（CLAUDE.md、Auto Memory、相關檔案、Git 歷史）
2. 規劃 (Plan) — 擬定執行策略，拆解任務為多步驟
3. 行動 (Act) — 透過工具呼叫執行操作（讀寫檔案、執行命令、搜尋程式碼）
4. 驗證 (Verify) — 檢查執行結果，確認是否需要進一步操作

你隨時可以在迴圈執行中插話：按 Esc 立即中斷並取消目前的工具呼叫，或直接輸入修正內容並按 Enter——不會中斷正在執行的動作，Claude 會在目前步驟完成後讀取你的訊息再決定下一步。

內建工具集

Claude Code 的內建工具依「能動性層級」分為五大類（File operations／Search／Execution／Web／🆕 Code intelligence），完整分類與逐一工具說明見 1.2.6 工具系統詳解。核心心法：Claude 依提示與過程中蒐集到的資訊自主決定用哪個工具、以什麼順序使用，例如「修好失敗的測試」通常會依序觸發「跑測試 → 讀錯誤輸出 → 搜尋相關原始碼 → 讀取理解 → 編輯修正 → 重跑測試驗證」——每一步的結果都會回饋進迴圈、影響下一步決策。

上下文載入順序

啟動時，Claude Code 先解析設定，再組裝模型看到的 context。兩者要分開看：設定（settings.json、hooks、權限）決定「能做什麼」，不佔 context；context 決定「知道什麼」，會消耗 token。

【啟動時解析（不佔 context）】
A. 設定合併：Managed → CLI 旗標 → .claude/settings.local.json → .claude/settings.json → ~/.claude/settings.json
B. Hooks 註冊、權限規則與權限模式決定
C. MCP Server 連線（背景連線；Claude 可用 WaitForMcpServers 等待尚未就緒者）

【載入 context（佔用 token）】
1. 系統提示與內建工具定義
2. 組織 managed CLAUDE.md → ~/.claude/CLAUDE.md
3. 工作目錄與所有上層目錄的 CLAUDE.md／CLAUDE.local.md／.claude/rules/*.md
   └── 沒有任何 CLAUDE.md 時，改讀 AGENTS.md（v2.1.277+）
4. Auto Memory：MEMORY.md 前 200 行或 25KB（取先達到者）
5. Skills 的名稱與描述（完整內容用到才載入）
6. MCP：預設只載入工具名稱與 server instructions，完整 schema 經 Tool Search 隨需載入
7. Git 狀態（目前分支、未提交變更、近期 commit）
8. 使用者對話
   └── 子目錄的 CLAUDE.md 會在 Claude 讀取該目錄檔案時才隨需注入

💡 用 /context 可看到上述各項實際佔用的 token；官方另提供互動式的 Explore the context window 頁面，逐步說明各項目在何時載入。

Token 管理與 Context Window

Context window 裝載對話歷史、檔案內容、命令輸出、CLAUDE.md、Auto Memory、已載入的 Skills 與系統指令。當對話接近上限時，Claude Code 會自動先清除較舊的工具輸出，若仍不夠才對對話做摘要壓縮：

• 自動摘要壓縮 — 使用 /compact 命令或自動觸發；你的請求與關鍵程式碼片段會保留，但對話早期的細節指示可能遺失——因此持久性規則應寫進 CLAUDE.md，而不是依賴對話記憶
• 選擇性載入 — 只載入與當前任務相關的檔案內容
• 工具結果截斷 — 過長的工具輸出會自動截斷
• 可控摘要焦點 — 在 CLAUDE.md 中加入「Compact Instructions」段落，或直接對 /compact 附帶焦點說明

# 手動壓縮上下文
/compact

# 帶有自訂摘要指示的壓縮
/compact 保留所有與 API 設計相關的討論

# 檢視目前 context window 各項目的用量佔比
/context

⚠️ 🆕 Thrashing 保護：若單一檔案或工具輸出過大，導致每次摘要後 context 又立刻被同一內容填滿，Claude Code 會在嘗試幾次後自動停止 auto-compact 並回報錯誤，而不會無限迴圈消耗 token。

💡 Skills 採隨需載入（只有描述常駐 context，實際內容用到才載入），Subagent 則擁有完全獨立的 context——這兩者是除了壓縮之外，控制 context 用量的主要手段，詳見 2.1 Subagents 與 2.3 Skills。

🆕 Session、Checkpoint 與執行環境

🆕 v3.5 新增：依官方 how-claude-code-works 頁補齊。

Session 是本機的明文紀錄：每則訊息、工具呼叫與結果都寫入 ~/.claude/projects/ 下的 明文 JSONL 檔案，這是 rewind、resume、fork 的基礎。企業須把這個目錄納入端點資料保護與保存政策（可能含程式碼片段與命令輸出中的敏感資訊）。

• Session 彼此獨立：新 session 從全新 context 開始，跨 session 的延續只靠 CLAUDE.md 與 Auto Memory。
• Session 綁定目錄：切換 git 分支後，Claude 會看到新分支的檔案，但對話歷史不變；要真正平行工作，請用 git worktree（claude --worktree）。

Checkpoint 只保護檔案編輯：Claude 編輯檔案前會先快照，按兩次 Esc（或 /rewind）可回到先前狀態。Checkpoint 獨立於 git、resume 後仍可使用，但：

• 不涵蓋資料庫、API、部署等遠端副作用，也不涵蓋 symlink／hard link 的檔案
• 由 Bash 命令造成的檔案變更同樣不在保護範圍內
• 這些風險要靠權限模式與權限規則控管，而不是 checkpoint

三種執行環境：Agentic loop 與工具在任何介面都相同，差別在於程式碼在哪裡執行。

1.1.6 Desktop App 與 Web 介面

🆕 v3.0 新增章節

Claude Code 現在提供圖形化桌面應用程式和雲端 Web 介面，大幅降低使用門檻。

Desktop App

Desktop App（Claude 桌面應用程式的 Code 分頁）與 CLI 共用同一個 Claude Code 引擎、同一套 CLAUDE.md／settings／MCP，但功能並非完全相同（v3.5 更正）：Desktop 多了視覺化 diff、Browser 預覽窗格、Computer use、Dispatch、SSH session 與檔案附件；CLI 則獨有 dontAsk 模式、第三方供應商原生設定、--print 腳本化與 Agent Teams。

安裝方式：

安裝後登入並點選 Code 分頁即可開始；Desktop App 已內含 Claude Code，不需要另外安裝 CLI，但需要付費訂閱。

核心功能：

• 內建 Terminal 窗格、檔案編輯器與視覺化 diff view（可逐行留言請 Claude 修改）
• Browser 窗格：Claude 可啟動 dev server 並在窗格中預覽、驗證變更，也能開啟外部網站（Cmd/Ctrl+Shift+B）
• 圖形化 Connectors（MCP）與 Plugin 管理 UI
• 可配置排程任務（Desktop Scheduled Tasks）
• 同時並排檢視、操作多個工作階段（側邊欄分頁），可選擇 worktree 隔離，或一鍵發起雲端工作階段
• SSH sessions：以 Desktop 為介面，在遠端 VM／dev container 上執行 Claude Code
• Side chat（Cmd/Ctrl+; 或 /btw）：提問但不寫回主對話
• Computer use（研究預覽，macOS／Windows，限 Pro／Max）：操作沒有 CLI 的桌面應用程式
• 🆕 Session Groups：在側邊欄以右鍵將多個工作階段歸類分組管理
• 🆕 可用 /resume 接續在終端機開始的 session；面板可彈出為獨立視窗；額度重置後可自動續跑
• 自動更新

⚠️ Desktop 不支援的項目：Agent Teams（僅 CLI；Desktop 內多代理協作請改用 Dynamic Workflows）、dontAsk 模式、--print 腳本化；/permissions 這類需要終端機互動面板的指令在 Code 分頁會回覆 isn't available in this environment。企業可透過 Admin console、managed settings 與 MDM policy 管控 Desktop。

💡 Desktop 排程任務: 與 CLI 的 session-scoped /loop 不同，Desktop 排程任務持久存在，可在 app 重啟後繼續執行；雲端執行的 Routines 則連電腦關機也不受影響，三者的完整比較見 2.8 Scheduled Tasks。

🔀 跨裝置接續工作：在 Terminal 中執行 /desktop 可將目前 CLI 工作階段交接到 Desktop App（需 claude.ai 訂閱，支援 macOS 與 x64 Windows），改用圖形化介面檢視 diff；反向操作則可用 claude --teleport 把手機或 Web 上發起的雲端工作階段拉回本機終端機繼續（需 claude.ai 訂閱）。

Web 介面 (claude.ai/code)

Web 介面讓你在瀏覽器中使用 Claude Code 的完整功能，程式碼在 Anthropic 的雲端沙箱中執行；也可透過 Claude 行動應用程式（iOS / Android）存取。

適用場景：

• 沒有本機開發環境時快速嘗試
• 在平板或共用電腦上操作
• 快速原型驗證
• 程式碼審查（不需本機 clone）
• 同時平行執行多個長時間任務，完成後再回來查看

運作方式：

瀏覽器 → claude.ai/code → 雲端虛擬機（沙箱）→ 執行程式碼
                                                  ↓
                                           可 clone GitHub repo
                                           可安裝依賴、執行測試
                                           可將變更推回 GitHub

與本機工作階段互轉：

# 從本機終端機把目前任務丟到雲端執行
claude --cloud

# 之後可在 Claude 行動應用程式接續查看/操作
# 或反向：在雲端／行動裝置發起的任務，用 --teleport 拉回本機終端機繼續
claude --teleport

⚠️ 注意: Web 介面在雲端沙箱中執行，無法存取你的本機檔案系統。需要操作本機檔案請使用 CLI、Desktop App 或 IDE 擴充功能。

1.1.7 Channels 與 Dispatch

🆕 v3.0 新增章節

Channels 和 Dispatch 是 Claude Code 的外部事件推送與行動端控制機制，讓 Claude Code 不再受限於終端機前的操作。

Channels — 外部事件推送

Channels 讓外部服務（Telegram、Discord、iMessage 等）可以主動推送訊息到你的 Claude Code 工作階段中，Claude 會自動回應。

graph LR
    TG[Telegram] -->|推送訊息| CH[Channel MCP Server]
    DC[Discord] -->|推送訊息| CH
    IM[iMessage] -->|推送訊息| CH
    WH[Webhook] -->|推送訊息| CH
    CH -->|注入 session| CC[Claude Code]
    CC -->|自動回應| CH
    
    style CH fill:#f59e0b,stroke:#d97706,color:#fff
    style CC fill:#6366f1,stroke:#4f46e5,color:#fff

使用方式：

# 1. 安裝 channel plugin（官方 Telegram／Discord／iMessage／fakechat 皆以 Bun 執行）
#    在 Claude Code session 內執行：/plugin install fakechat@claude-plugins-official

# 2. 重新啟動並「逐 session 明確選用」channel（可空白分隔多個）
claude --channels plugin:fakechat@claude-plugins-official

# 3. 開發自建 channel 時（未列入允許清單），改用開發旗標（會要求確認）
claude --dangerously-load-development-channels server:webhook

⚠️ 研究預覽（Research preview）限制：Channels 需以 claude.ai 或 Console API key 認證，不支援 Bedrock／Vertex（Agent Platform）／Foundry；--channels 在預覽期間不會出現在 claude --help，且只接受 Anthropic 維護的允許清單（或組織以 allowedChannelPlugins 取代的清單）。Team／Enterprise 預設封鎖，需由 Owner 在 Admin settings 啟用或在 managed settings 設 channelsEnabled: true。僅寫在 .mcp.json 不足以推送訊息，必須在 --channels 中列名。

應用場景：

🔐 安全模型：每個官方 channel plugin 都維護寄件者允許清單，Telegram／Discord 以配對碼（pairing code）加入，iMessage 以 /imessage:access allow 加入，其他寄件者的訊息會被靜默丟棄。若 channel 宣告了 permission relay 能力，任何能透過該 channel 回覆的人都能核准或拒絕你 session 的工具呼叫，只應加入你信任的對象。

📌 Slack 的 @Claude 不是 Channel：它會開一個新的雲端 session（Claude in Slack），而 Channel 是把事件推進你已開啟的本機 session。

Dispatch — 行動端控制

Dispatch 讓你從手機發送指令到運行中的 Claude Code Desktop App。

📱 手機
  ↓ (Dispatch 指令)
💻 Desktop App (本機)
  ↓
🤖 Claude Code 執行任務
  ↓
📱 結果回傳手機

工作流程：

1. Dispatch 是位於 Claude 桌面應用程式 Cowork 分頁中的一段持續對話；依 Anthropic 說明文件完成手機配對
2. 從手機傳訊給 Dispatch（如「開一個 Claude Code session 修好登入 bug」）
3. Dispatch 自行判斷任務類型：開發類工作（修 bug、更新依賴、跑測試、開 PR）會產生一個 Code session；研究、文件、試算表則留在 Cowork
4. 產生的 Code session 會出現在 Code 分頁側邊欄並帶有 Dispatch 標記；完成或需要核准時，手機會收到推播

⚠️ 方案限制（v3.5 補充）：Dispatch 需要 Pro 或 Max 方案，Team／Enterprise 無法使用。若 Dispatch 產生的 session 啟用了 Computer use，應用程式核准在 30 分鐘後失效並重新詢問。企業情境要「離開電腦仍能繼續工作」，請改用 Remote Control。

📖 詳細設定與進階用法: 請參閱 4.4 Channels 與 Dispatch 深入解析

1.1.8 模型陣容與推理投入程度（Effort）

🆕 v3.5 新增：依官方 model-config 頁整理（基準版本 v2.1.281）。模型與預設值在 2026 年變動極快（Sonnet 5 → Opus 5 → Opus 5.5 相繼成為預設），企業應把本節列入每季覆核項目。

目前的模型別名與解析結果

⚠️ 供應商差異：opus／sonnet 解析結果依供應商而不同，例如 Bedrock 與 Google Cloud Agent Platform 的 sonnet 仍是 Sonnet 4.5，Microsoft Foundry 的 default 是 Sonnet 4.5、opus 是 Opus 4.6。第三方供應商部署務必以 ANTHROPIC_DEFAULT_OPUS_MODEL 等變數釘選模型 ID，避免版本升級時模型被悄悄替換。

Fable 模型的特殊規則：Fable 不是任何方案的預設模型，必須以 /model fable 或 --model fable 明確選用；依方案與席次，Fable 用量可能改計入 usage credits，互動模式會先顯示同意提示，但 -p 與 Agent SDK 不會詢問、直接計費。觸發安全分類器（常見於資安、生物領域）時會自動換模型（automatic model fallback）。

模型設定的優先順序

1. Session 中 /model <別名>（Enter 儲存為預設、s 僅限本次 session）
2. 啟動時 claude --model <別名>
3. 環境變數 ANTHROPIC_MODEL
4. 設定檔的 model 欄位
5. ANTHROPIC_DEFAULT_MODEL（新 session 的預設）

Enterprise 管理員可在 claude.ai Admin console 設定組織預設模型（可依自訂角色設定，需 v2.1.196+），並可選擇是否覆寫使用者選擇；要「限制」可選模型則使用 availableModels（搭配 enforceAvailableModels）或組織模型限制。modelPicker 設定可自訂 /model 選單列出的模型、順序與標籤。

Effort：控制每一步要想多深

• 設定方式（先成立者優先）：CLAUDE_CODE_EFFORT_LEVEL 環境變數、--effort 旗標或 /effort → 設定檔中依模型儲存的等級（modelSettings）或 effortLevel → 模型預設值。
• ⚠️ 頂層 effortLevel 對 Opus 5.5 不生效，Opus 5.5 會從自己的預設 medium 開始，需要以 /effort 為該模型另存等級。
• max 只套用於當次 session（除非用環境變數設定）；/effort 選單中的 ultracode 不是模型等級，而是送出 xhigh 並讓 Claude 對實質任務自動編排 Dynamic Workflows。
• 企業上限：maxEffortLevel managed setting 可在所有供應商（含 Bedrock／Vertex／Foundry）限制最高 effort，也能依模型個別設定；Enterprise 方案另可在 Admin console 依角色設定上限。

Fallback model chain（備援模型鏈）

主模型過載或無法使用時，可依序改用備援模型（最多 3 個，只影響當次 turn）：

# 單次 session
claude --fallback-model sonnet,haiku

{
  "fallbackModel": ["claude-sonnet-5", "claude-haiku-4-5"]
}

📌 認證、計費、rate limit 與組織政策拒絕不會觸發備援；不在 availableModels 允許清單內的模型會先被剔除；/status 不會顯示備援鏈，第一次切換時的提示才是唯一可見訊號。

企業導入檢核要點

• 第三方供應商已釘選 ANTHROPIC_DEFAULT_OPUS_MODEL／ANTHROPIC_DEFAULT_SONNET_MODEL／ANTHROPIC_DEFAULT_HAIKU_MODEL
• 以 availableModels + enforceAvailableModels 限制可用模型，並決定是否開放 Fable（usage credits 成本）
• 以 maxEffortLevel 設定 effort 上限，避免 max／xhigh 造成成本失控
• 在 CI（-p）中明確指定 --model 與 --effort，不依賴會隨版本改變的預設值
• 每季比對官方 model-config 頁，確認預設模型與預設 effort 是否改變

1.2 核心架構概覽

1.2.1 系統架構圖

graph TB
    subgraph "使用者介面層"
        U[開發者] --> CLI[Terminal CLI]
        U --> VSC[VS Code Extension]
        U --> JB[JetBrains Plugin]
        U --> DA[Desktop App]
        U --> WEB[Web 介面]
        U --> SDK[Agent SDK / Headless]
        U --> CH[Channels / Dispatch]
    end
    
    subgraph "Claude Code 核心引擎"
        CLI --> AL[Agentic Loop]
        VSC --> AL
        JB --> AL
        DA --> AL
        WEB --> AL
        SDK --> AL
        CH --> AL
        
        AL --> TM[Tool Manager]
        AL --> HM[Hook Manager]
        AL --> CM[Context Manager]
        AL --> PM[Plugin Manager]
        
        TM --> BT[內建工具<br/>Read/Edit/Bash/Search]
        TM --> MCPc[MCP Client]
        TM --> SA[Subagent Spawner]
        
        CM --> CLAUDE[CLAUDE.md / MEMORY.md<br/>指引與記憶]
        CM --> SETTINGS[settings.json<br/>設定載入]
        CM --> RULES[.claude/rules/*.md<br/>規則檔]
        
        PM --> PLG[Plugins<br/>Skills + Agents + Hooks + MCP + LSP]
    end
    
    subgraph "擴展層"
        MCPc --> MCP1[MCP Server A]
        MCPc --> MCP2[MCP Server B]
        MCPc --> MCP3[MCP Server C]
        SA --> SA1[子代理 1]
        SA --> SA2[子代理 2]
    end
    
    subgraph "外部服務"
        AL --> API[Anthropic API<br/>Claude Sonnet / Opus]
        MCP1 --> EXT1[GitHub API]
        MCP2 --> EXT2[資料庫]
        MCP3 --> EXT3[第三方服務]
    end
    
    style AL fill:#6366f1,stroke:#4f46e5,color:#fff
    style MCPc fill:#10b981,stroke:#059669,color:#fff
    style API fill:#f59e0b,stroke:#d97706,color:#fff
    style SA fill:#8b5cf6,stroke:#7c3aed,color:#fff
    style PM fill:#ec4899,stroke:#db2777,color:#fff

1.2.2 各組件之間的關係

graph LR
    subgraph "核心組件關係"
        S[Subagents] -->|委派任務| T[Tools]
        S -->|觸發| H[Hooks]
        H -->|監聽事件| AL[Agentic Loop]
        SK[Skills] -->|增強指引| AL
        P[Plugins] -->|打包提供| SK
        P -->|打包提供| AG[Agents]
        P -->|打包提供| H
        MCP[MCP Servers] -->|提供外部工具| T
        CM[CLAUDE.md] -->|注入上下文| AL
    end
    
    style S fill:#8b5cf6,stroke:#7c3aed
    style SK fill:#06b6d4,stroke:#0891b2
    style H fill:#f97316,stroke:#ea580c
    style MCP fill:#22c55e,stroke:#16a34a
    style P fill:#ec4899,stroke:#db2777
    style AL fill:#6366f1,stroke:#4f46e5,color:#fff

組件職責說明

1.2.3 資料流與執行流程

sequenceDiagram
    participant U as 開發者
    participant CC as Claude Code
    participant HM as Hook Manager
    participant Tools as Tool Manager
    participant MCP as MCP Server
    participant API as Anthropic API
    
    U->>CC: 發送請求 (Prompt)
    CC->>CC: 載入 CLAUDE.md + 上下文
    CC->>HM: 觸發 UserPromptSubmit Hook
    HM-->>CC: Hook 處理結果
    
    CC->>API: 發送對話 + 上下文
    API-->>CC: Claude 回應（可能含工具呼叫）
    
    loop Agentic Loop（直到任務完成）
        CC->>HM: 觸發 PreToolUse Hook
        HM-->>CC: 允許 / 拒絕
        CC->>Tools: 執行工具（Read/Edit/Bash/MCP）
        Tools-->>CC: 工具結果
        CC->>HM: 觸發 PostToolUse Hook
        CC->>API: 發送工具結果
        API-->>CC: 下一步指令或最終回應
    end
    
    CC->>HM: 觸發 Stop Hook
    CC-->>U: 返回最終結果

執行流程詳解

階段 1：請求接收與前處理

1. 使用者輸入 → UserPromptSubmit Hook 觸發
2. 載入上下文：
   - CLAUDE.md（全域 → 專案 → 目錄層級）
   - 對話歷史
   - 活動檔案內容
3. 組裝完整 prompt 發送至 Anthropic API

階段 2：Agentic Loop 執行

迴圈開始：
├── Claude 模型分析任務
├── 選擇並呼叫工具
│   ├── PreToolUse Hook → 權限檢查
│   ├── 執行工具（讀檔/寫檔/命令/搜尋）
│   ├── PostToolUse Hook → 結果處理
│   └── 將結果回傳模型
├── Claude 分析結果，決定下一步
└── 重複直到任務完成或達到 turn 上限

階段 3：結果後處理

1. Stop Hook 觸發 → 可執行最終清理
2. 若該輪有工作項目被標記完成，另會觸發 TaskCompleted Hook（任務清單／Agent Teams 共用任務）
3. 結果呈現給使用者
4. 等待下一個使用者輸入或結束對話

1.2.4 記憶體與設定架構

Claude Code 用兩套互補機制在無狀態的對話之間傳遞知識：CLAUDE.md（你寫的指引）與 Auto Memory（Claude 自己寫的筆記）。兩者都會在每次會話開始時載入，且都被 Claude 當作「情境（context）」參考，而非強制生效的設定——若需要不論 Claude 判斷結果都強制阻擋的規則，應改用 PreToolUse Hook（見 2.5 Hooks）。

graph TD
    subgraph "CLAUDE.md（人寫，指令與規範）"
        MP[Managed Policy<br/>MDM 部署，組織全員強制]
        US[User<br/>~/.claude/CLAUDE.md]
        PS[Project<br/>./CLAUDE.md 或 ./.claude/CLAUDE.md]
        LS[Local<br/>./CLAUDE.local.md，不進版控]
    end

    subgraph "Auto Memory（Claude 寫，學習與心得）"
        AM["~/.claude/projects/&lt;project&gt;/memory/<br/>MEMORY.md（索引，前 200 行/25KB）<br/>+ 主題檔案（依需要讀取）"]
    end

    MP --> US --> PS --> LS

    style MP fill:#ef4444,stroke:#dc2626,color:#fff
    style US fill:#3b82f6,stroke:#2563eb,color:#fff
    style PS fill:#22c55e,stroke:#16a34a,color:#fff
    style LS fill:#8b5cf6,stroke:#7c3aed,color:#fff
    style AM fill:#f59e0b,stroke:#d97706,color:#fff

CLAUDE.md：你寫的持久指引

載入順序：從工作目錄往上層層尋找 CLAUDE.md／CLAUDE.local.md，全部串接進 context——不是互相覆蓋，而是「離工作目錄越近的內容排在越後面」（更容易被 Claude 記住）；子目錄中的 CLAUDE.md 則採隨需載入，只在 Claude 實際讀取該目錄下的檔案時才注入。也支援 @path/to/file 匯入語法（最深 4 層遞迴、程式碼區塊中的 @ 不會被當成匯入），與 .claude/rules/（可用 YAML frontmatter 的 paths 欄位，將規則限定在符合 glob 樣式的檔案才載入，減少不必要的 context 消耗）。🆕 v3.5 更正：自 v2.1.277 起，若工作目錄與所有上層目錄都沒有 CLAUDE.md／.claude/CLAUDE.md／CLAUDE.local.md，Claude Code 會直接讀取 AGENTS.md；v3.4 所述「不會直接讀取、需以 @AGENTS.md 匯入」已過時，詳見下方「AGENTS.md 原生支援」。

📌 官方建議長度：CLAUDE.md 沒有強制行數上限、會完整載入，但官方建議控制在 200 行以內——檔案越長，指令遵循度越低。內容持續變多時，優先拆成 .claude/rules/*.md（依檔案路徑觸發）或 Skills（依任務觸發），而不是無限堆疊 CLAUDE.md。

Auto Memory：Claude 自己寫的學習筆記

Auto Memory 預設開啟，Claude 會在工作中自行判斷值得記住的資訊（建置指令、除錯心得、你的糾正與偏好），主動寫入 ~/.claude/projects/<project>/memory/（依 Git repository 自動命名，同一個 repo 的所有 worktree 共用一份）：

• MEMORY.md 是索引檔，每次會話僅載入前 200 行或 25KB（取先達到者），超出部分不會載入——因此 Claude 會把明細移到主題檔案，索引只留精簡摘要。
• 主題檔案（如 debugging.md）不會自動載入，Claude 會在需要時才用一般讀檔工具查閱。
• 可用 /memory 指令瀏覽 / 編輯 / 開啟記憶資料夾，或關閉 Auto Memory（對應 autoMemoryEnabled 設定，也可用環境變數 CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 停用）。
• Auto Memory 僅存在本機（不跨機器 / 雲端環境同步），且不會自動套用到 Subagent 的獨立 context（/fork 例外，會繼承主對話的記憶）。

# 開啟 /memory 選單：可瀏覽 CLAUDE.md、CLAUDE.local.md、Auto Memory 資料夾
/memory

# 確認目前會話實際載入了哪些記憶檔案
/context

💡 判斷準則：CLAUDE.md 用來下指令（「一律使用 pnpm」「commit 前先跑 lint」），Auto Memory 用來記心得（「這個專案的 API 測試需要本機 Redis」）。想強制要求就寫進 CLAUDE.md 或直接說「加進 CLAUDE.md」；讓 Claude 自然累積經驗則交給 Auto Memory。

🆕 AGENTS.md 原生支援（v2.1.277+）

多數團隊同時使用多種 coding agent，AGENTS.md 已是跨工具的共用指引格式。Claude Code 的讀取規則如下：

⚠️ ~/.claude/CLAUDE.md、組織 managed CLAUDE.md 與 .claude/rules/*.md 不影響上述判定；但 CLAUDE.local.md 會。在依賴 AGENTS.md 的 repo 中新增個人 CLAUDE.local.md，會讓 Claude 從此不再讀 AGENTS.md。

/config 的 Project instructions 可改變預設：

也可以寫入設定檔（含 managed settings），統一全公司行為：

{
  "pluginConfigs": {
    "agents-md@builtin": {
      "options": { "instructionFiles": "claude-md-and-agents-md" }
    }
  }
}

舊做法的處置：CLAUDE.md 中的 @AGENTS.md 匯入可以保留（不會讀兩次）；以文字要求「請讀 AGENTS.md」者應刪除或改為匯入；用 SessionStart hook 印出 AGENTS.md 的做法必須移除，否則會在 context 中出現兩份。另外，InstructionsLoaded hook 對經由此設定讀取的 AGENTS.md 不會觸發，以此 hook 做稽核的企業需注意。

設定（settings.json）優先順序

CLAUDE.md／Auto Memory 管的是「情境」，settings.json 管的是「權限與行為的強制設定」，兩者是互補的兩條軸線（見 B.8 配置優先級完整圖）：

（由高到低；同一個 key 以最高層級的值為準）
1. Managed Settings（managed-settings.json／managed-settings.d／MDM／claude.ai 伺服器端管理設定，無法被覆寫）
2. 命令列參數（含 --settings 傳入的 JSON，僅限本次 session）
3. .claude/settings.local.json（個人專案設定，不進版控）
4. .claude/settings.json（專案共享設定，Git 共享）
5. ~/.claude/settings.json（使用者全域設定）

📌 環境變數不是這個堆疊中的一層：同時有環境變數與設定鍵時，依「每一組」各自決定，例如 shell 中的 ANTHROPIC_MODEL 會蓋過任何檔案的 model。權限規則則例外地跨層合併：任何一層的 deny 都會擋下其他層的 allow。

1.2.5 權限與安全模型

Claude Code 採用分層權限模型：權限模式決定基準行為，權限規則在其上做細部放行或封鎖，Hook 與沙箱再提供可程式化與作業系統層級的防線。

graph TD
    A[工具呼叫請求] --> PH{PreToolUse Hook<br/>exit 2 / deny?}
    PH -->|阻擋| F[❌ 拒絕]
    PH -->|通過| D1{deny 規則匹配?}
    D1 -->|是| F
    D1 -->|否| K1{ask 規則匹配?}
    K1 -->|是| I[🔔 詢問使用者<br/>或 PermissionRequest Hook]
    K1 -->|否| AL{allow 規則匹配?}
    AL -->|是| OK[✅ 自動允許]
    AL -->|否| MODE{依權限模式處理}
    MODE -->|Manual| I
    MODE -->|Accept Edits| AE[檔案編輯自動允許<br/>其他命令詢問]
    MODE -->|Auto| CL[分類器審查<br/>高風險者封鎖]
    MODE -->|dontAsk| F

    style OK fill:#22c55e,stroke:#16a34a,color:#fff
    style F fill:#ef4444,stroke:#dc2626,color:#fff
    style I fill:#f59e0b,stroke:#d97706,color:#fff

⚠️ v3.5 更正：v3.4 的流程圖把 allow 放在 deny 之前檢查，這是錯誤的。官方規則是依 deny → ask → allow 的順序比對，第一個命中者決定結果，與規則寫得多具體無關；而且 deny 規則跨所有設定層級生效（使用者層級的 deny 也會擋下專案層級的 allow）。回傳 exit 2 的 PreToolUse hook 會在權限規則評估之前就擋下呼叫。

權限模式（Permission Modes）

除了 allow／deny／ask 規則清單，Claude Code 還有一組會話層級的「權限模式」，決定規則沒有明確匹配時的預設行為。互動模式按 Shift+Tab 循環切換：

🆕 v3.5 更新：新 session 從哪個模式開始

依序取第一個成立者：--permission-mode 旗標（或 --dangerously-skip-permissions）→ 設定檔的 permissions.defaultMode → 內建預設。內建預設依環境而不同：

執行方式	內建起始模式
任一設定檔將 disableAutoMode 設為 "disable"	Manual
claude -p 或 Agent SDK	Manual
Bedrock／Agent Platform／Foundry／Claude Platform on AWS／Claude apps gateway	Manual
Pro／Max／Team，終端機或 VS Code（v2.1.228+，原生 Windows 為 v2.1.233+）	Auto
Enterprise 方案或 Console API key	Manual

另外兩個重點：在專案層級的 .claude/settings.json／settings.local.json 中把 defaultMode 設為 "auto" 不會生效（會退回內建預設），設為 "bypassPermissions" 也不會生效（會從 Manual 開始），用意是避免 clone 下來的 repo 自行提升權限。v3.4 中「Auto 適用於 CI/CD」的說法不正確，-p 預設是 Manual，CI 請改用 dontAsk 搭配明確的 allow 清單。

🆕 Auto mode 的伺服器端分類器（v2.1.278+）：Enterprise、Claude API、Bedrock／Agent Platform／Foundry／Claude Platform on AWS，以及把 ANTHROPIC_BASE_URL 指向 LLM gateway 的環境，auto mode 預設請伺服器端審查要送交分類器的動作。企業若經由 gateway 部署，需確認 gateway 會轉送這類審查請求。

任何模式都不會自動核准的動作

以下動作在所有模式（包含 bypassPermissions）都不會自動放行：

• 明確的 ask 規則所匹配的工具
• 需要使用者互動的工具（AskUserQuestion、標記為 requiresUserInteraction 的 MCP 工具）
• 對 critical path 執行的 rm／rmdir，allow 規則或 PreToolUse hook 回傳 "allow" 都無法放行
• 開啟 permissions.blockReadsOutsideWorkingDirectories 時，讀取工作目錄以外的檔案

另有一組 protected paths（如 .git、.claude 等 Claude 自身設定目錄），寫入時除了 bypassPermissions 之外都不會自動核准；permissions.allow 中的 Edit(.claude/**) 也無法預先放行。以 --restricted（v2.1.248+）啟動的 session，分類器也不能核准 protected path 的寫入。

權限配置格式

{
  "permissions": {
    "defaultMode": "acceptEdits",
    "allow": [
      "Edit(/src/**)",
      "Bash(npm test)",
      "Bash(npm run *)",
      "Bash(git status)",
      "Bash(git diff *)",
      "mcp__github__*"
    ],
    "ask": [
      "Bash(git push *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./secrets/**)",
      "Bash(rm -rf *)",
      "Bash(curl * | bash)",
      "Agent(model:opus)"
    ]
  }
}

權限規則語法

⚠️ v3.5 更正三處常見誤解：

1. v3.4 的 Tool(pattern1, pattern2) 多參數寫法不存在，每條規則只能寫一個樣式，需要多個就寫多條。
2. 檔案權限只會比對 Edit(path) 與 Read(path)。寫成 Write(src/**)、NotebookEdit(...) 或舊的 MultiEdit(...) 的路徑規則會被接受但永遠不會被檢查（啟動時會警告）；Edit 規則已涵蓋所有會修改檔案的內建工具。
3. Read deny 規則也會阻擋同路徑的 Edit／Write（含建立新檔），但不涵蓋 NotebookEdit，也不涵蓋未指名檔案的命令（例如在該目錄執行 grep -r）；需要作業系統層級的保證時，請搭配下方的 Bash 沙箱。

安全最佳實踐

✅ 推薦做法：
- 使用 allowlist 模式，明確列出允許的命令；deny 規則優先處理敏感檔案（.env、金鑰目錄）
- 對不可逆操作（git push、部署）使用 ask 規則，而不是 allow
- 在 .claude/settings.json 設定專案權限並提交版控；個人例外放 settings.local.json
- 以 Managed Settings 強制安全政策，並用 allowManagedPermissionRulesOnly 鎖定只採用組織規則
- 真正的隔離邊界交給沙箱（sandbox）或容器，不要只依賴權限規則

❌ 避免做法：
- 不要在 allow list 中使用 Bash 或 Bash(*)（允許任何命令）
- 不要使用 Bash(git *) 這類把 * 放在子命令之前的寫法（會放行 git -c 執行任意程式）
- 不要將 API 金鑰寫在 CLAUDE.md 或 settings.json 中
- 不要在未隔離的主機上使用 bypassPermissions

🆕 Bash 沙箱（Sandboxing）

權限規則是「Claude Code 層級」的檢查；沙箱則由作業系統強制執行，範圍涵蓋 Bash／PowerShell／Monitor 命令及其所有子行程的檔案系統與網路存取。以 /sandbox 開啟設定面板：

企業強制啟用沙箱的 managed settings：

{
  "sandbox": {
    "enabled": true,
    "failIfUnavailable": true,
    "allowUnsandboxedCommands": false
  }
}

• failIfUnavailable：缺少依賴（如 Linux 的 bubblewrap）時拒絕啟動，而不是警告後退回無沙箱執行
• allowUnsandboxedCommands: false：關閉逃生口，只有列在 excludedCommands 的命令可在沙箱外執行
• 陣列型設定（excludedCommands、allowRead）會跨層合併，開發者可以自行追加而放寬政策；請以 allowManagedReadPathsOnly、allowManagedDomainsOnly 鎖定，並把 excludedCommands 維持在最小範圍
• 預設讀取政策仍允許讀取 ~/.aws、~/.ssh 等憑證目錄，應加上 sandbox.credentials 設定

⚠️ 沙箱不是完整的隔離邊界：內建 proxy 預設不檢查 TLS 內容，允許 github.com 這類廣泛網域可能成為資料外洩管道（domain fronting）；allowUnixSockets 若開放 /var/run/docker.sock 等同交出主機權限；enableWeakerNestedSandbox 會大幅削弱 Linux 隔離；使用者在 ! shell 模式自己輸入的命令預設不在沙箱內。高風險情境（處理不受信任的程式碼、bypassPermissions）請改用 dev container、VM 或官方 self-hosted／雲端環境。

1.2.6 工具系統詳解

Claude Code 透過內建工具（built-in tools）與外部工具（MCP tools）與系統互動。以下是完整的工具分類：

內建工具一覽

graph TB
    subgraph "Claude Code 工具系統（v2.1.281）"
        subgraph "檔案操作"
            R[Read<br>讀取檔案]
            W[Write<br>寫入檔案]
            E[Edit<br>精確編輯]
            NB[NotebookEdit<br>Jupyter]
        end

        subgraph "搜尋與程式碼智能"
            G[Grep / Glob<br>Windows 預設提供]
            LSP[LSP<br>定義 / 參照 / 型別錯誤]
        end

        subgraph "執行"
            B[Bash / PowerShell<br>Shell 命令]
            MON[Monitor<br>背景輸出串流]
        end

        subgraph "代理協作"
            SA[Agent<br>子代理]
            WF[Workflow<br>Dynamic Workflows]
            SM[SendMessage<br>跨代理傳訊]
        end

        subgraph "MCP 工具"
            TS[ToolSearch<br>隨需載入]
            MCP1[mcp__server__tool]
        end
    end

    style R fill:#dbeafe,stroke:#3b82f6
    style W fill:#dcfce7,stroke:#22c55e
    style E fill:#dcfce7,stroke:#22c55e
    style NB fill:#dcfce7,stroke:#22c55e
    style G fill:#fef3c7,stroke:#f59e0b
    style LSP fill:#fef3c7,stroke:#f59e0b
    style B fill:#fce7f3,stroke:#ec4899
    style MON fill:#fce7f3,stroke:#ec4899
    style SA fill:#e0e7ff,stroke:#6366f1
    style WF fill:#e0e7ff,stroke:#6366f1
    style SM fill:#e0e7ff,stroke:#6366f1

官方五大工具分類

官方文件將內建工具歸納為五大類，每一類代表一種不同層次的「能動性（agency）」：

📌 Claude 依照你的提示與過程中發現的資訊自主選擇要用哪個工具；上面五類是「能力範疇」，下方表格則是實際會用到的具體工具名稱。

工具詳細說明

🆕 v3.5 依官方 tools-reference 更新：工具名稱以官方清單為準。MultiEdit 已是舊版工具、LS 與 Think 不在現行清單中；子代理的工具名稱是 Agent（不是 SubAgent）。在 macOS／Linux／WSL 上，Glob 與 Grep 預設不提供，Claude 改透過 Bash 執行內嵌版的 bfs（find）與 ugrep（grep），因此這類搜尋會以 Bash 呼叫的形式經過你的 hooks 與權限規則；Windows 則仍預設提供 Glob／Grep。

工具執行生命週期

sequenceDiagram
    participant U as 使用者
    participant C as Claude Code
    participant P as Permission System
    participant H as Hook System
    participant T as Tool Engine

    U->>C: 發送指令
    C->>C: 分析需求，選擇工具
    C->>P: 權限檢查
    P-->>C: 允許/拒絕/需確認
    
    alt 需要使用者確認
        C->>U: 顯示權限請求
        U->>C: 允許/拒絕
    end
    
    C->>H: 觸發 PreToolUse Hook
    H-->>C: 通過/阻止
    
    alt Hook 通過
        C->>T: 執行工具
        T-->>C: 回傳結果
        C->>H: 觸發 PostToolUse Hook
        H-->>C: 後處理完成
        C->>C: 評估結果
        C-->>U: 回覆使用者
    else Hook 阻止
        C-->>U: 告知操作被 Hook 攔截
    end

1.2.7 Agentic Loop 深入解析

Claude Code 的核心是 Agentic Loop（代理執行迴圈）。與傳統的「一問一答」不同，Agentic Loop 讓 Claude 能夠自主規劃和執行多步驟任務。

graph TB
    START[使用者輸入] --> ANALYZE[分析任務<br>理解需求]
    ANALYZE --> PLAN[規劃步驟<br>分解子任務]
    PLAN --> SELECT[選擇工具<br>決定下一步動作]
    SELECT --> EXEC[執行工具<br>Read/Write/Bash/etc.]
    EXEC --> EVAL{評估結果}
    EVAL -->|需要更多步驟| SELECT
    EVAL -->|遇到錯誤| FIX[錯誤修復<br>調整策略]
    FIX --> SELECT
    EVAL -->|任務完成| OUTPUT[輸出結果<br>回覆使用者]
    
    style START fill:#6366f1,stroke:#4f46e5,color:#fff
    style ANALYZE fill:#dbeafe,stroke:#3b82f6
    style PLAN fill:#dbeafe,stroke:#3b82f6
    style SELECT fill:#fef3c7,stroke:#f59e0b
    style EXEC fill:#fce7f3,stroke:#ec4899
    style EVAL fill:#dcfce7,stroke:#22c55e
    style FIX fill:#fee2e2,stroke:#ef4444
    style OUTPUT fill:#6366f1,stroke:#4f46e5,color:#fff

Agentic Loop 的關鍵特性

Agentic Loop 範例：Bug 修復流程

使用者: "修復 UserService.ts 中 getUserById 回傳 null 的問題"

Claude Code Agentic Loop:
┌─ Step 1: Read src/services/UserService.ts
│   → 找到 getUserById 方法
│
├─ Step 2: Grep "getUserById" in src/
│   → 找到相關呼叫位置
│
├─ Step 3: Read src/repositories/UserRepository.ts  
│   → 發現 Repository 的查詢有問題
│
├─ Step 4: Read tests/UserService.test.ts
│   → 確認原本的測試案例
│
├─ Step 5: Edit src/repositories/UserRepository.ts
│   → 修復查詢邏輯
│
├─ Step 6: Edit src/services/UserService.ts
│   → 增加 null check 和錯誤處理
│
├─ Step 7: Edit tests/UserService.test.ts
│   → 新增針對 null 的測試案例
│
├─ Step 8: Bash "npm test -- UserService"
│   → 測試通過 ✅
│
└─ Step 9: 回覆使用者修復結果和變更摘要

1.3 快速上手實戰

1.3.1 第一次對話

安裝完成後，在專案目錄開啟 Claude Code：

cd ~/projects/my-web-app
claude

以下是從零開始的典型互動流程：

╭───────────────────────────────────────────────────╮
│ Claude Code v2.1.x                                 │
│ Project: my-web-app                               │
│ Memory: CLAUDE.md loaded ✓                        │
╰───────────────────────────────────────────────────╯

You: 幫我了解這個專案的架構

Claude: 我來分析這個專案...
[Read] package.json
[Read] tsconfig.json
[Glob] src/**/*.ts
[Read] src/index.ts
[Read] src/routes/index.ts

這是一個 Express.js + TypeScript 的 REST API 專案，結構如下：
┌─────────────────────────────────────────┐
│ src/                                    │
│ ├── index.ts          # 應用程式入口     │
│ ├── routes/           # API 路由定義     │
│ ├── controllers/      # 控制器邏輯       │
│ ├── services/         # 業務邏輯層       │
│ ├── models/           # 資料模型         │
│ └── middleware/        # 中介軟體        │
└─────────────────────────────────────────┘
技術棧：Node.js 20, Express 4.18, TypeScript 5.4, Prisma ORM
資料庫：PostgreSQL 15
...

1.3.2 建立 CLAUDE.md

每個新專案的第一步，建議直接執行內建的 /init 命令，讓 Claude Code 分析程式碼庫並自動生成 CLAUDE.md（若檔案已存在，/init 會改為提出改善建議，不會覆寫）：

You: /init

Claude: 我先仔細分析專案結構...
[Read] package.json
[Read] tsconfig.json
[Read] .eslintrc.js
[Read] prisma/schema.prisma
[Bash] git log --oneline -10
[Write] CLAUDE.md

已建立 CLAUDE.md，包含：
- 專案概述與技術棧
- 編碼規範（從 eslint 配置推斷）
- 常用命令（build, test, lint, migrate）
- 架構說明
- 禁止事項

🆕 設定環境變數 CLAUDE_CODE_NEW_INIT=1 可啟用互動式多階段 /init 流程：先詢問要建立哪些產出物（CLAUDE.md／Skills／Hooks），用 Subagent 探索程式碼庫、以追問補足缺口，最後給出可複核的提案再落地寫入檔案，而不是一次到位直接產生。若專案已有其他工具的規則檔（.cursor/rules/、.github/copilot-instructions.md，開啟該旗標後還支援 AGENTS.md、.windsurfrules 等），/init 會自動讀取並整合進生成的 CLAUDE.md。也可以直接用 /import [codex|gemini|cursor] 一次性搬入 OpenAI Codex、Google Gemini CLI 或 Cursor 在本機的指令檔、MCP Server、commands、Subagent 與 Skills 設定（可加 --dry-run 先預覽）；/init 偵測到 Codex／Gemini CLI 設定時也會主動提議執行 /import。至於 AGENTS.md，v2.1.277 起已可直接讀取，不需要匯入（見 1.2.4）。

建議的 CLAUDE.md 結構：

# My Web App

## 技術棧
- Runtime: Node.js 20 LTS
- Framework: Express.js 4.18
- Language: TypeScript 5.4 (strict mode)
- ORM: Prisma 5.x with PostgreSQL 15
- Testing: Jest + Supertest
- Linter: ESLint + Prettier

## 編碼規範
- 使用 camelCase 命名變數和函式
- 使用 PascalCase 命名類別和介面
- 所有函式必須有明確的回傳型別
- 不使用 any 型別
- 錯誤處理使用自訂 AppError 類別

## 常用命令
- `npm run dev` — 啟動開發伺服器
- `npm run build` — 編譯 TypeScript
- `npm test` — 執行全部測試
- `npm run test:watch` — 測試 watch 模式
- `npx prisma migrate dev` — 執行資料庫遷移
- `npx prisma generate` — 重新生成 Prisma Client

## 架構規範
- Controller 只負責解析請求和回傳回應
- Service 處理業務邏輯，不直接操作 HTTP
- Repository 模式封裝資料存取（透過 Prisma）
- 中介軟體處理認證、日誌、錯誤處理

## 禁止事項
- 不要修改 prisma/migrations/ 中的已存在遷移檔案
- 不要在 Controller 中直接操作資料庫
- 不要提交 .env 檔案
- 不要使用 console.log，請使用專案的 Logger

1.3.3 常見操作範例

新增 API Endpoint

You: 新增一個 GET /api/v1/products 端點，支援分頁和搜尋

Claude: 我來實作這個端點...

[Read] src/routes/index.ts          # 了解現有路由結構
[Read] src/controllers/userController.ts  # 參考現有模式
[Read] prisma/schema.prisma         # 確認資料模型

需要建立/修改以下檔案：

1. 資料模型（如果不存在）
[Edit] prisma/schema.prisma           # 新增 Product model

2. 路由定義
[Edit] src/routes/index.ts            # 註冊 product 路由
[Write] src/routes/productRoutes.ts   # 產品路由

3. 控制器
[Write] src/controllers/productController.ts

4. 服務層
[Write] src/services/productService.ts

5. 測試
[Write] src/__tests__/products.test.ts

[Bash] npx prisma migrate dev --name add-product  # 執行遷移
[Bash] npm test                                     # 執行測試

✅ 所有測試通過。新增了 GET /api/v1/products 端點：
- 支援 ?page=1&limit=20 分頁
- 支援 ?search=keyword 全文搜尋
- 支援 ?category=electronics 過濾

修復 Bug

You: 使用者回報登入後有時候 session 會遺失，幫我查一下

Claude: 我來調查這個問題...

[Grep] session|cookie|auth  # 搜尋相關程式碼
[Read] src/middleware/auth.ts
[Read] src/config/session.ts
[Bash] git log --all -20 --oneline -- src/middleware/ src/config/

找到可能的原因：

問題：在 src/config/session.ts 第 23 行
cookie.secure 設為 true，但在開發環境使用 HTTP
導致 session cookie 未被瀏覽器儲存

[Edit] src/config/session.ts   # 修正：根據環境設定 secure

修正內容：
- cookie.secure 改為 process.env.NODE_ENV === 'production'
- 新增 sameSite: 'lax' 屬性
- 確保 cookie.maxAge 與 session TTL 一致

[Bash] npm test  # 確認修正未破壞其他功能
✅ 測試全部通過

重構程式碼

You: 把 userService.ts 裡重複的驗證邏輯抽取成獨立的 validator

Claude: 我先分析 userService.ts 中的重複模式...

[Read] src/services/userService.ts
[Grep] validate|check|verify  # 搜尋驗證邏輯

發現 3 處重複的驗證邏輯：
1. createUser() — email 格式、密碼強度
2. updateUser() — email 格式（重複）
3. resetPassword() — 密碼強度（重複）

重構計畫：
1. 建立 src/validators/userValidator.ts
2. 抽取共用驗證函式
3. 更新 userService.ts 使用新的 validator
4. 新增 validator 測試

[Write] src/validators/userValidator.ts
[Edit] src/services/userService.ts     # 移除重複邏輯，改用 validator
[Write] src/__tests__/userValidator.test.ts

[Bash] npm test
✅ 所有測試通過（15 passed, 0 failed）
程式碼減少 47 行，消除了 3 處重複

1.3.4 效率提升技巧

📌 第一部分重點摘要

1. Claude Code 定位為「智慧協作夥伴」，核心是 Agentic Loop 循環
2. 使用 CLAUDE.md 作為專案指引，多層級載入
3. settings.json 管理權限與配置，依 Managed → CLI → Local → Project → User 的優先順序合併
4. 六大核心組件：Subagents、Skills、Plugins、Hooks、MCP、CLAUDE.md
5. 分層權限模型：規則依 deny → ask → allow 比對，搭配六種權限模式與作業系統層級沙箱
6. 記憶體系統：CLAUDE.md（人寫）＋ Auto Memory（Claude 寫），v2.1.277 起亦可直接讀取 AGENTS.md
7. 🆕 模型與 Effort：v2.1.280 起預設為 Opus 5.5（預設 effort medium），企業應以 availableModels／maxEffortLevel 治理

第二部分：核心功能詳解

📌 本部摘要：逐一解析八大擴充與協作機制：Subagents（2.1）、Agent Teams 與官方五種平行方式（2.2）、Skills（2.3）、Plugins（2.4）、Hooks（2.5）、MCP（2.6）、Output Styles（2.7）與排程任務（2.8）。每章都區分「官方行為」與「企業導入建議」，並標出 v3.5 的更正處。

2.1 Subagents (子代理)

2.1.1 概念說明

什麼是 Subagents？

Subagents（子代理） 是 Claude Code 中的核心任務分解機制。當主代理 (main agent) 需要執行一項獨立的子任務時，它會啟動一個 subagent — 一個擁有獨立 context window 的 Claude 實例。

📌 關鍵特性: Subagent 擁有獨立的 context window，不會佔用主代理的 context 空間。這意味著即使子任務處理了大量檔案，主代理的 context 仍然保持清爽。

graph TB
    subgraph "主代理 (Main Agent)"
        MA[Claude Code<br/>完整 Context Window]
    end
    
    subgraph "子代理層 (Subagents)"
        SA1[Subagent 1<br/>獨立 Context]
        SA2[Subagent 2<br/>獨立 Context]
        SA3[Subagent 3<br/>獨立 Context]
    end
    
    MA -->|委派任務| SA1
    MA -->|委派任務| SA2
    MA -->|委派任務| SA3
    
    SA1 -->|返回摘要結果| MA
    SA2 -->|返回摘要結果| MA
    SA3 -->|返回摘要結果| MA
    
    style MA fill:#6366f1,stroke:#4f46e5,color:#fff
    style SA1 fill:#10b981,stroke:#059669,color:#fff
    style SA2 fill:#10b981,stroke:#059669,color:#fff
    style SA3 fill:#10b981,stroke:#059669,color:#fff

Subagent vs 主代理的差異

觸發時機

Claude Code 在以下情況自動啟動 subagent：

✅ 自動觸發場景：
- 搜尋大量檔案（避免搜尋結果佔滿主 context）
- 處理獨立的子任務（如：修改模組 A 時順便修模組 B 的相依）
- 並行探索多個方案
- 分析大型程式碼庫

💡 手動觸發方式：
- 在 CLAUDE.md 中指引使用 subagent
- 透過自訂 Agent 定義
- 以 @-mention 或直接要求「用 xxx subagent 做…」
- 🆕 使用 /subtask 命令 — 以目前完整對話為基礎分叉出背景子代理（fork）
- 🆕 使用 --agents CLI JSON 旗標傳入 Agent 定義

🆕 v3.5 更正：/subtask 與 /fork 的分工：v2.1.212 起，分叉子代理的指令是 /subtask <任務>，它會繼承完整對話歷史（不是摘要），在背景執行，結果完成後以訊息回到主對話。/fork 則改為把整個 session 複製成一個新的背景 session（出現在 agent view），本視窗繼續工作；只有在關閉 agent view 時，/fork 才退回舊行為。Fork mode 自 v2.1.232 起在互動 session 預設開啟，-p 與 Agent SDK 預設關閉；可用 CLAUDE_CODE_FORK_SUBAGENT=1／0 覆寫。

🆕 Managed Subagents：組織管理員可把 Agent 定義檔放在 managed settings 系統目錄下的 .claude/agents/（格式與專案 Agent 相同），優先順序最高；同名時依序為 Managed → --agents CLI → .claude/agents/ → ~/.claude/agents/ → Plugin agents/。

2.1.2 內建子代理類型

Claude Code 提供多種內建子代理，自動根據任務類型啟用：

內建代理總覽

🆕 v2.1.198 變更：Explore 過去固定使用 Haiku，現在改為繼承主對話所用的模型（在 Claude API 上限制最高為 Opus，確保不會比你當前工作階段選用的模型更貴）；若想固定讓 Explore 使用低成本模型，可在專案或使用者層級自訂一個同名為 Explore 的 Agent 並指定 model: haiku，會覆蓋內建版本。內建代理預設在互動式會話中即已註冊；若要停用內建的 Explore/Plan，可設定 CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1。

Explore Agent — 快速探索

用途: 在大型程式碼庫中快速搜尋與閱讀檔案，不修改任何內容。

特性：
- 模型繼承自主對話（Claude API 上限為 Opus），而非固定使用 Haiku
- 只有唯讀工具，Write/Edit 一律禁用
- 呼叫時 Claude 會指定徹底程度：quick（快速定位）/ medium（均衡探索）/ very thorough（全面分析）
- 不會修改任何檔案

自動觸發場景：
- 需要搜尋符號定義位置
- 需要了解程式碼結構
- 需要找到相關檔案

Plan Agent — 策略規劃

用途: 分析複雜任務，制定詳細的執行計畫。

特性：
- 使用 Sonnet 或 Opus 模型
- 可讀取檔案和搜尋程式碼
- 產出結構化的任務計畫
- 適合大型重構、架構變更

自動觸發場景：
- 複雜任務需要前期規劃
- 使用者明確要求 "先規劃再執行"

2.1.3 自訂子代理

Agent 定義檔格式

自訂 Agent 使用 Markdown 檔案 + YAML frontmatter 定義，放置在以下位置：

建議放置位置：
├── .claude/agents/          # 專案級 Agent 定義
├── ~/.claude/agents/        # 全域 Agent 定義
└── AGENTS.md                # 在專案根目錄定義（簡易方式）

YAML Frontmatter 格式：

---
name: "security-reviewer"
description: "專責安全審查的代理，檢查 OWASP Top 10 和常見漏洞"
model: "claude-sonnet-5"
tools:
  - Read
  - Grep
  - Glob
  - Bash(npm audit)
  - Bash(semgrep *)
context:
  - "docs/security-guidelines.md"
  - "CLAUDE.md"
hooks:
  agent:
    - event: "Stop"
      type: "command"
      command: "echo 'Security review completed' >> .claude/security-log.txt"
---

# Security Reviewer Agent

你是一位資深資安審查專家。你的任務是：

## 審查範圍
1. 檢查 OWASP Top 10 漏洞
2. 審查認證與授權邏輯
3. 檢查敏感資料處理
4. 驗證輸入驗證機制
5. 審查 SQL 注入和 XSS 防護

## 輸出格式
使用以下格式回報：
- 🔴 **嚴重**: [問題描述] — [修復建議]
- 🟡 **警告**: [問題描述] — [修復建議]  
- 🟢 **良好**: [已正確實作的部分]

## 規則
- 不修改任何檔案，只產出審查報告
- 優先檢查面向外部的 API 端點
- 特別注意第三方依賴的已知漏洞

YAML Frontmatter 參數詳解

🆕 v3.5 依官方 Frontmatter reference 全面更正：只有 name 與 description 必填；多字欄位一律使用 camelCase，無法辨識的欄位會被靜默忽略（不會報錯）。v3.4 表格中的 argument-hint、allowed-tools、context、agent 是 Skill 的欄位，不是 Subagent 欄位，已移除。

💡 修改 .claude/agents/、~/.claude/agents/ 中的檔案不需重啟，幾秒內即生效；例外是 session 啟動時該目錄尚不存在、經 --add-dir 加入的目錄，或以 --disable-slash-commands 啟動的 session。目錄會遞迴掃描，可用子資料夾（如 agents/review/）分類，但識別只看 name。

使用 /agents 命令

⚠️ v2.1.198 起行為變更：/agents 不再開啟互動式建立精靈（含 Running／Library 分頁的舊版 UI）；執行後只會提示改用「請 Claude 建立」或直接編輯 .claude/agents/ 目錄。Agent 檔案格式與存放位置（.claude/agents/、~/.claude/agents/）完全不變，只移除了終端機精靈介面。v2.1.197（含）以前的版本仍保留舊版精靈。

# v2.1.197 及更早版本：開啟互動式精靈
/agents

# v2.1.198 之後：直接請 Claude 建立/編輯，或手動管理檔案
你: 幫我在 ~/.claude/agents/ 建立一個 code-improver agent，
    負責掃描程式碼並提出可讀性、效能、最佳實踐的改善建議，唯讀、使用 Sonnet

# 查看目前生效的自訂 Agent：於對話中執行 /context，在 "Custom Agents" 區塊確認

完整自訂 Agent 範例：API Designer

---
name: "api-designer"
description: "RESTful API 設計專家，負責設計符合 OpenAPI 規範的 API"
model: "claude-sonnet-5"
tools:
  - Read
  - Write
  - Edit
  - Grep
  - Glob
context:
  - "docs/api-conventions.md"
  - "openapi.yaml"
---

# API Designer Agent

你是 API 設計專家，專門設計符合團隊標準的 RESTful API。

## 設計原則
1. 遵循 RESTful 設計最佳實踐
2. 使用 OpenAPI 3.0 規範
3. 統一的錯誤回應格式
4. 版本化 API（URI 版本 /v1/）
5. 使用 HTTP 標準狀態碼

## 命名慣例
- 資源名稱使用複數形式（/users, /orders）
- 使用 kebab-case（/order-items）
- 查詢參數使用 camelCase（?pageSize=20）

## 回應格式
統一使用：
{
  "data": { ... },
  "meta": { "page": 1, "total": 100 },
  "errors": []
}

## 輸出要求
1. OpenAPI YAML 定義
2. 端點清單與說明
3. 請求/回應範例
4. 認證需求說明

2.1.4 使用場景與實作範例

場景一：大型程式碼庫的探索與分析

# Claude Code 對話中：
使用者: 找出所有直接操作資料庫的 Controller，這違反了分層架構原則

# Claude Code 自動啟動 Explore subagent：
# → 使用 Grep 搜尋 Controller 中的 Repository/EntityManager 引用
# → 使用 Read 讀取可疑檔案
# → 回傳摘要結果給主代理
# 
# 主代理根據摘要提供完整分析報告

場景二：並行修改多個模組

# Claude Code 對話中：
使用者: 將所有 API 端點從 /api/v1 遷移到 /api/v2，同時更新對應的測試

# Claude Code 可能的執行策略：
# 主代理: 規劃遷移策略
# → Subagent 1: 修改路由定義
# → Subagent 2: 更新整合測試
# → Subagent 3: 更新 API 文件
# 主代理: 整合所有變更，驗證一致性

場景三：搭配自訂 Agent 進行安全審查

# 呼叫自訂的 security-reviewer agent
使用者: @security-reviewer 請審查 src/auth/ 目錄下所有認證相關程式碼

# security-reviewer agent 執行：
# 1. 讀取 src/auth/ 下所有檔案
# 2. 使用 Grep 搜尋常見漏洞模式
# 3. 分析認證流程
# 4. 產出安全審查報告

2.1.5 進階技巧

技巧一：在 CLAUDE.md 中指引 Subagent 使用

# CLAUDE.md

## Subagent 使用指引

### 搜尋策略
- 搜尋超過 3 個檔案時，使用 subagent 進行探索
- 大型程式碼分析任務優先使用 Explore agent

### Agent 分工
- API 相關修改：使用 api-designer agent 先設計，再實作
- 安全相關變更：完成後必須使用 security-reviewer agent 審查
- 資料庫遷移：使用 Plan agent 先規劃遷移策略

技巧二：Subagent 工具限制

限制 subagent 的工具存取可以提升安全性與效率：

---
name: "read-only-analyzer"
description: "唯讀分析器，只進行程式碼分析不做任何修改"
tools:
  - Read
  - Grep
  - Glob
  # 注意：不包含 Edit、Write、Bash —— 完全唯讀
---

技巧三：模型選擇策略

技巧四：Subagent Hook 整合

可以在 Agent 定義中設定專屬的 Hook，在 Agent 啟動/完成時自動執行操作：

---
name: "code-generator"
description: "程式碼生成代理"
hooks:
  agent:
    - event: "SubagentStart"
      type: "command"
      command: "echo '[$(date)] Code generator started' >> .claude/agent-log.txt"
    - event: "SubagentStop"
      type: "command"
      command: |
        echo '[$(date)] Code generator completed' >> .claude/agent-log.txt
        npm run lint --fix 2>/dev/null || true
---

技巧五：Subagent 進階 YAML 欄位

🆕 v3.5 更正：v3.4 範例中的 allowed-tools、context: fork、hex 色碼、permissionMode: "ask"／"deny" 都不是有效的 Subagent 設定，已改為官方欄位。

---
name: heavy-analyzer
description: 深度程式碼分析代理。重大重構或安全審查前主動使用。
tools: Read, Grep, Glob, Bash
disallowedTools: Edit, Write
model: opus
effort: xhigh
maxTurns: 50
permissionMode: plan
isolation: worktree
color: purple
omitClaudeMd: true
skills:
  - owasp-checker
  - dependency-auditor
mcpServers:
  - sonarqube
---

📌 分叉（fork）不是 frontmatter 欄位：要讓子代理繼承完整對話，請使用 /subtask 或讓 Claude 請求 fork 子代理類型；Skill 的 context: fork 則是「把 Skill 放到子代理中執行」，兩者不同。

技巧六：前景與背景執行模式

Subagent 支援兩種執行模式：

🆕 v2.1.198 重大變更：Subagent 現在預設在背景執行。v3.5 補充目前的判定順序：（1）由 in-process Agent Teams 隊友生成的子代理一律前景；（2）設定 CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 時一律前景；（3）fork mode 開啟時（互動 session 預設開啟）一律背景，Claude 無法要求前景；（4）fork mode 關閉時（-p、Agent SDK 預設），Claude 預設背景、需要結果時才用前景，background: true 可強制背景。背景子代理的權限提示會浮現在主 session 並標示是哪個子代理提出；若你選擇「本 session 持續允許」，該授權會套用到整個 session（含主對話）。若要整體停用背景任務功能，設定環境變數 CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1。也可以手動介入：請 Claude 明確以背景/前景執行任務，或按 Ctrl+B 把執行中的任務轉為背景。

# 前景執行（Claude 判斷需要立即拿到結果時）
Claude: 我委派 security-reviewer 分析這段程式碼...
（等待 security-reviewer 完成）
Claude: 安全審查結果顯示...

# 背景執行（🆕 現在是預設行為）
Claude: 我在背景啟動了 doc-generator 來產生文件，同時繼續處理你的修改需求...
（doc-generator 在背景執行，可用 /tasks 查看狀態）
Claude: 修改已完成。文件生成也在背景完成了，結果如下...

技巧七：Subagent 持久記憶

透過 Agent frontmatter 的 memory 欄位，可讓 Subagent 擁有跨會話持久保存的記憶目錄（屬於 Auto Memory 機制的一部分，若整體停用 Auto Memory，此欄位就不生效）：

---
name: code-reviewer
description: 審查程式碼品質與最佳實踐
memory: project
---

你是程式碼審查專家。審查過程中，請把發現的模式、慣例與常見問題更新到你的記憶中。

啟用後，Subagent 的系統提示會自動包含記憶目錄中 MEMORY.md 的前 200 行（或 25KB，取先達到者），並自動取得 Read/Write/Edit 工具以維護自己的記憶檔案。建議明確請 Subagent「先查閱記憶再開始」與「完成後把學到的存回記憶」，才能真正累積效果。

技巧八：Subagent 自動壓縮與恢復

• 自動壓縮：長時間執行的 Subagent 在接近 context window 上限時會自動壓縮對話歷史
• 恢復執行：🆕 使用 SendMessage 工具可以向已存在的 Subagent 發送後續訊息，無需重新啟動

# 恢復之前的 Subagent 會話
Claude 使用 SendMessage 工具：
- target: "security-reviewer"  
- message: "請繼續檢查 controllers/ 目錄"
→ security-reviewer 在之前的 context 基礎上繼續工作

🆕 技巧九：Agent(agent_type) 限制子代理生成

在 YAML frontmatter 的 tools 欄位中，可使用 Agent(agent_type) 語法限制該 Subagent 只能生成特定類型的子代理，防止 Subagent 無限擴展代理鏈：

---
name: "team-lead"
description: "團隊領導，只能委派給 analyzer 和 implementer"
tools:
  - Read
  - Edit
  - Bash
  - Agent(analyzer)
  - Agent(implementer)
  # 只能生成 analyzer 和 implementer 兩種子代理
  # 不能生成其他類型的子代理
---

📌 使用情境：在多層代理架構中，透過 Agent(agent_type) 限制代理間的委派關係，可建立嚴格的分工邊界。例如 team-lead 只能委派給 analyzer 和 implementer，而 analyzer 本身則設為唯讀，不具備委派能力。

🆕 技巧十：Resume 子代理（接續先前的工作）

每次委派預設都會建立新的子代理實例。要讓它接著做，只要直接要求 Claude「接續剛才的 code review，再分析授權邏輯」，Claude 會以 SendMessage 工具（to 填 agent ID 或名稱）喚醒該子代理，它保有完整的歷史（含所有工具呼叫與結果），並在背景接續執行。

Use the code-reviewer subagent to review the authentication module
[子代理完成，Claude 取得其 agent ID]
Continue that code review and now analyze the authorization logic
[Claude 以 SendMessage 喚醒同一個子代理，接續完整 context]

⚠️ v3.5 更正 Resume 限制：v3.4 所述「僅支援 context: fork 或 isolation: worktree」不正確。實際限制是：內建 Explore 與 Plan 是一次性代理、不回傳 agent ID，無法 resume（需要接續時改用 general-purpose 或自訂子代理）；你用 /tasks 的 x 或 SDK stop_task 手動停止的子代理不會自動恢復。SendMessage 不需要啟用 Agent Teams。

🆕 併發與巢狀上限

📌 版本差異：v2.1.172–v2.1.216 預設可巢狀 5 層且不可調整；v2.1.217–218 預設 1 層；v2.1.219 起預設 3 層。在較舊的文章看到「5 層」屬於舊版行為。

🆕 技巧十一：/btw 旁支提問（side question）

/btw <問題> 讓你針對目前 session 提問，答案不會寫回主對話，因此不會污染 context、也不會讓 Claude 偏離手上的工作。適合「順便確認一下這個函式的用途」這類問題；不帶參數執行 /btw 可瀏覽先前的旁支問答。

> /btw 這個專案的 Logger 是在哪裡初始化的？

# Claude 在側邊回答，主對話的任務與 context 不受影響

⚠️ v3.5 更正：/btw 不是用來「告訴 Claude 一件要記住的事」。要讓規則持續生效，請寫進 CLAUDE.md；要在執行中修正方向，直接輸入訊息並按 Enter（會排入佇列，在目前工具呼叫完成後被讀取）。

⚠️ 注意事項

1. Context 隔離: Subagent 有獨立 context，它看不到主代理的完整對話歷史。確保在委派任務時提供足夠的背景信息
2. 成本考量: 每個 subagent 都會產生獨立的 API 呼叫費用。適當使用 Haiku 模型可降低成本
3. 結果摘要: Subagent 回傳的是摘要結果，不是完整 context。如果需要詳細資訊，在指引中要求詳細輸出
4. maxTurns 防護: 🆕 對於可能長時間執行的 Subagent，建議設定 maxTurns 避免 Token 消耗失控
5. permissionMode: 🆕 唯讀型代理（審查、探索）建議 plan 或以 tools 限制為唯讀工具；CI 中的代理建議 dontAsk 搭配明確的 allow 規則。背景子代理的「持續允許」授權會擴及整個 session，核准前請確認提出者

2.1.6 Subagent 完整實戰範例

範例一：全棧功能開發 Subagent 群

以下展示如何為一個全棧專案設計完整的 Subagent 協作體系：

.claude/agents/
├── api-designer.md          # API 設計師
├── db-migration.md          # 資料庫遷移專家
├── frontend-component.md    # 前端元件開發
├── test-writer.md           # 測試撰寫專家
├── security-reviewer.md     # 安全審查員
└── performance-analyzer.md  # 效能分析師

api-designer.md

---
name: "api-designer"
description: "設計 RESTful API 端點，產出 OpenAPI 規格"
tools:
  - Read
  - Grep
  - Glob
  - Write
---

# API 設計專家

## 工作流程
1. 分析需求描述
2. 檢查現有 API 端點（src/routes/ 和 src/controllers/）
3. 設計新的 API 端點，遵循現有命名慣例
4. 產出 OpenAPI 3.0 規格片段
5. 撰寫 Controller 和 Route 程式碼

## 設計規範
- URL 使用 kebab-case 命名
- 使用 RESTful 動詞：GET（查詢）、POST（建立）、PUT（完整更新）、PATCH（部分更新）、DELETE（刪除）
- 分頁使用 cursor-based pagination
- 錯誤回應使用 RFC 7807 Problem Details 格式
- 所有端點需要驗證 JWT Token

## 回應格式
```json
{
  "方案摘要": "...",
  "新增端點": [
    {
      "method": "POST",
      "path": "/api/v1/...",
      "description": "...",
      "request_body": "...",
      "response": "..."
    }
  ],
  "需要修改的檔案": ["..."],
  "OpenAPI 規格": "..."
}
```

test-writer.md

---
name: "test-writer"
description: "為指定模組撰寫完整的單元測試和整合測試"
tools:
  - Read
  - Grep
  - Glob
  - Write
  - Bash
---

# 測試撰寫專家

## 測試策略
1. 先讀取目標原始碼，理解所有公開方法
2. 為每個公開方法撰寫測試案例
3. 測試案例包含：正常路徑、邊界條件、錯誤處理
4. 執行測試確認全部通過

## 測試模板
- 使用 describe/it 結構
- 採用 AAA（Arrange-Act-Assert）模式
- Mock 外部依賴（資料庫、API 呼叫）
- 測試檔案放在 __tests__/ 或 *.test.ts 中

## 覆蓋率要求
- 行覆蓋率 > 80%
- 分支覆蓋率 > 70%
- 所有公開方法 100% 覆蓋

performance-analyzer.md

---
name: "performance-analyzer"
description: "分析程式碼效能瓶頸，提供具體優化建議"
tools:
  - Read
  - Grep
  - Glob
---

# 效能分析專家

## 分析重點
1. **資料庫查詢**：N+1 問題、缺少索引、不必要的 JOIN
2. **記憶體使用**：大陣列操作、記憶體洩漏、不必要的物件複製
3. **API 效能**：回應時間、Payload 大小、快取策略
4. **前端效能**：Bundle 大小、渲染效能、圖片優化

## 輸出格式
| 問題 | 位置 | 嚴重度 | 建議修復 | 預期改善 |
|------|------|--------|---------|---------|
| ... | file:line | 高/中/低 | ... | ~30% 改善 |

範例二：Subagent 工作流程編排

在 CLAUDE.md 中定義完整的 Subagent 工作流程：

# CLAUDE.md

## 功能開發標準流程

當要開發新功能時，按以下順序執行：

### Step 1: 設計
- 使用 `api-designer` agent 設計 API
- 輸出 OpenAPI 規格和程式碼架構

### Step 2: 實作
- 主 Agent 根據設計結果實作程式碼
- 包含 Controller、Service、Repository、Model

### Step 3: 測試
- 使用 `test-writer` agent 撰寫測試
- 確保覆蓋率達標

### Step 4: 資料庫
- 如需 DB 變更，使用 `db-migration` agent
- 產出 migration 檔案

### Step 5: 安全審查
- 使用 `security-reviewer` agent 進行安全掃描
- 修復所有「高」嚴重度問題

### Step 6: 效能分析
- 使用 `performance-analyzer` agent 分析效能
- 修復所有效能瓶頸

Subagent 選擇決策流程

flowchart TB
    START[收到任務] --> Q1{需要搜尋程式碼?}
    Q1 -->|是| EXPLORE[使用 Explore Agent<br>快速搜尋]
    Q1 -->|否| Q2{需要專業知識?}
    EXPLORE --> Q2
    Q2 -->|是| Q3{哪個領域?}
    Q2 -->|否| MAIN[主 Agent 直接處理]
    Q3 -->|API 設計| API[api-designer]
    Q3 -->|測試| TEST[test-writer]
    Q3 -->|安全| SEC[security-reviewer]
    Q3 -->|效能| PERF[performance-analyzer]
    Q3 -->|遷移| DB[db-migration]
    API --> INTEGRATE[整合結果]
    TEST --> INTEGRATE
    SEC --> INTEGRATE
    PERF --> INTEGRATE
    DB --> INTEGRATE
    MAIN --> DONE[完成]
    INTEGRATE --> DONE
    
    style START fill:#dbeafe,stroke:#3b82f6
    style EXPLORE fill:#fef3c7,stroke:#f59e0b
    style MAIN fill:#d1fae5,stroke:#10b981
    style DONE fill:#f3f4f6,stroke:#9ca3af

2.2 Agent Teams（多代理協作）

2.2.1 Agent Teams 概述

什麼是 Agent Teams？

Agent Teams 是 Claude Code 的多代理協作功能：一個「領導代理（Lead Agent，也就是你的主對話）」同時協調多個「隊友代理（Teammate）」，各自擁有獨立的 context window、直接互相通訊，而不像 Subagent 只能向主代理回報。

⚠️ 重要修正：Teammate 預設共用同一個工作目錄，並不會自動幫每個 Teammate 建立獨立的 git worktree——官方文件明確提醒「兩個 Teammate 同時編輯同一檔案會互相覆寫，務必把工作拆成每人負責不同檔案」。若確實需要檔案系統層級的隔離，須自行手動搭配 Git Worktree（屬於「你自己手動管理的平行 session」，官方文件將其列為 Agent Teams 之外的替代方案，而非 Agent Teams 內建行為）。

🧪 Agent Teams 仍是實驗性功能，預設關閉。啟用方式是設定環境變數（可放在 settings.json 的 env 區塊，或直接匯出）：

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
claude

未設定此環境變數時，Claude Code 完全不會建立團隊目錄，也不會生成或提議 Teammate。

graph TB
    subgraph "Agent Teams 架構"
        U[使用者以自然語言請求] -->|例如：Spawn 3 teammates to review this PR| LA[Lead Agent<br>= 你的主對話]

        LA -->|生成| T1[Teammate 1<br>獨立 context window]
        LA -->|生成| T2[Teammate 2<br>獨立 context window]
        LA -->|生成| T3[Teammate 3<br>獨立 context window]

        T1 <-->|Mailbox 直接互通| T2
        T2 <-->|Mailbox 直接互通| T3
        T1 <-->|Mailbox 直接互通| T3

        T1 -->|認領/更新| TL[共享 Task List]
        T2 -->|認領/更新| TL
        T3 -->|認領/更新| TL

        T1 -->|完成通知| LA
        T2 -->|完成通知| LA
        T3 -->|完成通知| LA

        LA -->|綜整結果| R[彙整回報給使用者]
    end

    style LA fill:#6366f1,stroke:#4f46e5,color:#fff
    style T1 fill:#dbeafe,stroke:#3b82f6
    style T2 fill:#dcfce7,stroke:#22c55e
    style T3 fill:#fef3c7,stroke:#f59e0b
    style R fill:#f0fdf4,stroke:#16a34a

📌 這裡刻意不畫 worktree：Teammate 預設就在你啟動 Claude Code 的同一個工作目錄下讀寫檔案，彼此看到的是同一份程式碼；隔離的是each Teammate 的 context window，不是檔案系統。

Lead Agent 與 Teammate 的角色差異

2.2.2 啟動與使用 Agent Teams

啟動 Agent Teams

⚠️ 修正：目前官方文件中沒有 claude --cowork、/leaders、/teammates 這些指令。啟用方式只有「設定環境變數」，之後直接用自然語言描述任務與想要的隊友即可，Claude 會自動生成 Teammate；若判斷任務適合平行處理，Claude 也可能主動提議組隊，但一定會等你確認才會真的生成 Teammate。

# 先啟用實驗性功能旗標（一般會話即可，不需要特殊模式）
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
claude

你: 我在設計一個追蹤程式碼庫 TODO 註解的 CLI 工具，請生成三位隊友從
    不同角度探索：一位負責 UX、一位負責技術架構、一位負責唱反調找漏洞。

Claude 會據此生成對應的 Teammate、建立共享任務清單，並在完成後綜整所有人的發現。若明確要求「用 Agent Team」但 Claude 只生成了 Subagent，代理面板本身無法直接分辨兩者（介面相同），需重新明確要求「用 Agent Team」。

🆕 共享任務清單（Shared Task List）

Lead Agent 與 Teammates 透過共享任務清單協調工作進度：

Agent Teams 共享任務清單：
┌────┬────────────────────────┬───────────┬──────────┐
│ ID │ 任務描述                │ 負責人     │ 狀態      │
├────┼────────────────────────┼───────────┼──────────┤
│ 1  │ 重構 UserService 認證   │ Teammate 1│ ✅ 完成   │
│ 2  │ 新增 BatchOrderAPI      │ Teammate 2│ 🔄 進行中 │
│ 3  │ 更新單元測試            │ Teammate 3│ ⏳ 等待中 │
│ 4  │ 整合測試                │ Lead Agent│ ⏳ 等待中 │
└────┴────────────────────────┴───────────┴──────────┘

• Lead Agent 在建立任務時會自動產生共享任務清單
• Teammates 完成任務後會更新狀態
• 透過 TaskCreated 和 TaskCompleted Hook 事件追蹤進度

🆕 信箱訊息（Mailbox Messaging）

Lead Agent 與 Teammates 透過非同步信箱溝通（而非直接對話）：

Lead Agent → [Mailbox] → Teammate 1
  "請優先處理認證中介層的重構"

Teammate 1 → [Mailbox] → Lead Agent
  "認證重構完成，middleware/auth.ts 已同步更新"

Teammate 1 → [Mailbox] → Teammate 2（可直接互傳，不需經過 Lead）
  "auth middleware 介面有變更，你負責的 OrderAPI 呼叫記得對應調整"

實際上每個 Agent 的信箱是磁碟上的一個 JSON 檔案：~/.claude/teams/{team-name}/inboxes/{agent-name}.json，只有成功寫入該檔案，Claude Code 才會回報「訊息已送達」；格式不合法的訊息項目會被記錄為錯誤並從檔案中移除，其餘合法訊息仍正常送達。

顯示模式（Display Modes）

Agent Teams 只有兩種顯示模式（沒有獨立的「多視窗」第三種）：

// ~/.claude/settings.json — 變更預設顯示模式
{
  "teammateMode": "auto"   // "in-process"（預設）｜"auto"｜"tmux"｜"iterm2"
}

# 或針對單一 session 指定（實驗性旗標，--help 不會列出）
claude --teammate-mode auto

"auto" 模式會在偵測到你已身處 tmux，或終端機是裝有 it2 CLI 的 iTerm2 時自動切為分割面板，否則退回 in-process。

團隊規模與檔案分工建議

• 官方建議 3–5 位 Teammate：協調成本會隨人數線性增加，超過一定規模後邊際效益遞減；15 個獨立任務時，3 個 Teammate 通常就是不錯的起點。
• 依「檔案所有權」而非任務名稱拆分工作：因為 Teammate 共用同一份工作目錄，兩人同時改同一個檔案會互相覆寫，務必讓每位 Teammate 負責彼此不重疊的檔案集合。
• 若某個 Teammate 確實需要檔案系統層級的完全隔離（例如要做破壞性實驗），可在生成時指名使用一個設有 isolation: worktree 的 Subagent 定義 作為該 Teammate 的類型，讓它在獨立 git worktree 中執行；這是需要另外設定的進階做法，並非預設行為。

2.2.3 Agent Teams 的協調機制

任務分配策略

Lead Agent 使用智慧型任務分配，考量以下因素：

flowchart TD
    T[使用者任務] --> A[分析任務依賴關係]
    A --> B{是否可並行?}

    B -->|是| P[拆成互不重疊的任務<br>依檔案所有權分工]
    B -->|否| S[建立序列工作流]

    P --> P1[Teammate A<br>認領獨立任務 1]
    P --> P2[Teammate B<br>認領獨立任務 2]

    S --> S1[Teammate C<br>前置任務]
    S1 -->|完成後解除依賴| S2[Teammate D<br>依賴任務]

    P1 --> M[Lead Agent 整合]
    P2 --> M
    S2 --> M

    M --> V[驗證與彙整回報]

    style T fill:#6366f1,stroke:#4f46e5,color:#fff
    style M fill:#f0fdf4,stroke:#16a34a
    style V fill:#dcfce7,stroke:#22c55e

📌 任務之間可設定相依關係：有未完成依賴的任務無法被認領，等依賴任務完成後才會自動解鎖，全程由 Claude Code 用檔案鎖定機制避免多個 Teammate 搶認領同一任務。

通訊與狀態管理

Teammate 透過以下機制與 Lead Agent、彼此協調：

⚠️ WorktreeCreate／WorktreeRemove 是通用的 Hook 事件，會在任何 git worktree 建立/移除時觸發——包括 --worktree 旗標、Subagent 的 isolation: worktree，或背景 session——但不是 Agent Teams 專屬機制，Agent Teams 預設共用工作目錄時完全不會觸發它們。

相關 Hook 事件

Agent Teams 提供三個可用於監控與品管的專屬 Hook 事件：

{
  "hooks": {
    "TeammateIdle": [
      {
        "hooks": [
          { "type": "command", "command": "echo '[$(date)] Teammate idle' >> .claude/team-log.txt" }
        ]
      }
    ],
    "TaskCompleted": [
      {
        "hooks": [
          { "type": "command", "command": "./scripts/verify-task-tests-pass.sh" }
        ]
      }
    ]
  }
}

2.2.4 應用場景與最佳實踐

場景一：全棧功能開發

任務：實作「使用者通知偏好設定」功能

Lead Agent 計劃（依檔案所有權分工，共用同一份工作目錄）：
├── Teammate 1（負責 src/models/、src/api/notification-preference*、migrations/）
│   ├── 建立 NotificationPreference 模型
│   ├── 實作 CRUD API 端點
│   └── 新增資料庫 migration
├── Teammate 2（負責 src/components/notification-settings/）
│   ├── 建立偏好設定頁面元件
│   ├── 實作表單驗證邏輯
│   └── 串接後端 API
└── Teammate 3（任務設有依賴：等 Teammate 1 & 2 的任務完成才解鎖）
    ├── 撰寫後端 API 整合測試
    └── 撰寫前端元件測試

場景二：大規模重構

任務：將 Monolith 中的 Payment 模組拆分為獨立微服務

Lead Agent 計劃（依任務依賴排序，各自負責不重疊的檔案）：
├── Teammate 1（負責 src/services/payment/ 抽離）
│   └── 抽離 Payment 相關程式碼到新模組
├── Teammate 2（負責 src/gateway/ 路由設定，依賴 Teammate 1 完成）
│   └── 更新 API Gateway 路由配置
├── Teammate 3（負責 db/payment-schema/，可與 Teammate 1 平行進行）
│   └── 建立獨立的 Payment 資料庫 schema
└── 認領順序（由任務相依關係自動控制）：Teammate 3 與 Teammate 1 平行 → Teammate 2

場景三：跨團隊程式碼審查

任務：對 PR #1234 進行全面審查

Lead Agent 計劃：
├── Teammate 1: 安全性審查（SQL Injection、XSS、認證）
├── Teammate 2: 效能審查（N+1 查詢、記憶體洩漏、索引）
├── Teammate 3: 架構合規審查（設計模式、SOLID 原則）
└── Lead Agent: 彙整所有審查意見並生成統一報告

⚠️ 注意事項與最佳實踐

1. 任務獨立性：分配給不同 Teammate 的任務務必修改不同的檔案——因為預設共用同一個工作目錄，同檔案的並行修改會直接互相覆寫，不是靠合併機制化解
2. 給足上下文：Teammate 不會繼承 Lead 的對話歷史，生成時務必把必要背景（受影響的檔案、限制條件、既有約定）寫進 prompt
3. 依賴排序：有依賴關係的任務應設定正確的 Task 相依，避免在不完整的程式碼上工作
4. 持續盯場：放著團隊長時間無人看管，出錯或做白工的風險會提高；定期檢查進度、視需要即時導正方向
5. 成本考量：每個 Teammate 都是獨立的 Claude Code 會話，會產生對應的 API 費用，且用量隨人數線性增加
6. 實驗性功能：Agent Teams 目前仍是實驗性功能，預設關閉，需設定 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 環境變數才會啟用
7. Teammate 數量：官方建議 3–5 個 Teammate 為佳，過多會讓協調成本抵銷平行效益
8. 已知限制：一個 session 僅能有一個團隊、Teammate 不能再生出自己的 Teammate（無巢狀團隊）、In-process 模式的 Teammate 無法隨 /resume 還原（session 恢復後需請 Lead 重新生成）、關閉團隊時 Teammate 會等目前這輪任務做完才真正結束（可能需要一點時間）

Agent Teams 專屬 Hook 事件

📌 WorktreeCreate／WorktreeRemove 也是可用的 Hook 事件，但屬於通用的 worktree 生命週期事件（--worktree、isolation: worktree、背景 session 都會觸發），並非 Agent Teams 專屬——除非你額外指定 Teammate 使用 isolation: worktree 的 Subagent 定義，否則預設共用工作目錄的 Agent Teams 不會觸發它們。

2.2.5 Agent Teams 進階模式

模式一：Pipeline 模式（串聯）

當任務有明確的先後依賴關係時，使用 Pipeline 模式：

graph LR
    subgraph "Pipeline 模式"
        T1["Teammate 1<br>設計 API Schema"] --> T2["Teammate 2<br>實作 Backend"]
        T2 --> T3["Teammate 3<br>實作 Frontend"]
        T3 --> T4["Lead Agent<br>整合測試"]
    end
    
    style T1 fill:#dbeafe,stroke:#3b82f6
    style T2 fill:#dcfce7,stroke:#22c55e
    style T3 fill:#fef3c7,stroke:#f59e0b
    style T4 fill:#fce7f3,stroke:#ec4899

You: 使用 pipeline 模式實作使用者認證功能：
     1. 先設計 API 規格（OpenAPI）
     2. 按照規格實作後端
     3. 按照規格實作前端
     4. 整合測試

模式二：Fan-out/Fan-in 模式（扇出扇入）

獨立任務平行處理，最後彙整：

graph TB
    L[Lead Agent<br>分配任務] --> T1[Teammate 1<br>掃描安全漏洞]
    L --> T2[Teammate 2<br>檢查效能問題]
    L --> T3[Teammate 3<br>驗證程式風格]
    L --> T4[Teammate 4<br>分析測試覆蓋率]
    
    T1 --> R[Lead Agent<br>彙整報告]
    T2 --> R
    T3 --> R
    T4 --> R
    
    style L fill:#6366f1,stroke:#4f46e5,color:#fff
    style R fill:#10b981,stroke:#059669,color:#fff

模式三：Specialist 模式（專家分工）

每個 teammate 是不同領域的專家：

You: 使用專家模式重新設計購物車系統

Lead Agent 分配：
├── 架構師 Agent（使用 opus 模型）
│   └── 設計整體架構、定義介面
├── 後端專家 Agent  
│   └── 實作 API 和業務邏輯
├── 前端專家 Agent
│   └── 實作 UI 元件和狀態管理
├── DBA 專家 Agent
│   └── 設計 database schema 和最佳化查詢
└── QA 專家 Agent
    └── 撰寫測試計畫和自動化測試

模式選擇指南

2.2.6 Agent Teams 搭配 Hooks

透過 Hooks 可以在 Agent Teams 的關鍵時刻自動執行操作，以下範例用 TaskCompleted 強制在任務被標記完成前先跑測試，並用 TeammateIdle 記錄每次有 Teammate 閒置：

{
  "hooks": {
    "TaskCompleted": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "./scripts/verify-tests-pass.sh"
          }
        ]
      }
    ],
    "TeammateIdle": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "echo '[Teammate idle] $(date)' >> .claude/team-log.txt"
          }
        ]
      }
    ]
  }
}

./scripts/verify-tests-pass.sh 讀取 stdin 的 JSON 輸入判斷任務內容，若驗證失敗以 exit code 2 回傳，Claude Code 就會阻止該任務被標記完成，並把腳本的錯誤訊息回饋給嘗試結案的 Teammate。

2.2.7 Teammate 權限、安全與成本

🆕 v3.5 新增：依官方 agent-teams 頁補齊企業導入時最常被忽略的權限與成本細節。

啟用條件與隱性行為

• 需設定 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1，而且只在互動 session 生效：-p 與 Agent SDK 不會生成 Teammate，Claude 命名的子代理會退回一般 Subagent。
• ⚠️ 啟用後會改變一般委派行為：Claude 可能自行替子代理命名，而被命名的子代理會以 Teammate 身分啟動，因此即使你沒有要求，也可能形成團隊。若只想用 Subagent，請不要在全域設定中常駐開啟此變數。
• 團隊設定（~/.claude/teams/{team-name}/config.json）是執行期狀態，不要手動編輯或預先撰寫；專案中的 .claude/teams/teams.json 之類檔案不會被識別為設定。要重複使用角色，請以 Subagent 定義 生成 Teammate。

以 Subagent 定義生成 Teammate 時套用哪些欄位

權限模型

• Teammate 繼承 Lead 的權限模式，但 dontAsk 不會被繼承；若 Lead 以 --dangerously-skip-permissions 啟動，所有 Teammate 也會跳過權限檢查。
• 生成後可個別調整 Teammate 的權限模式，但無法在生成時就指定每個 Teammate 的模式。
• Teammate 的權限提示都出現在 Lead session，由你核准；唯一例外是 plan approval，由 Lead 直接核准。
• Agent 之間的訊息不等於你的同意：Teammate 不能代你核准權限，被拒絕的動作也不能轉給其他 Teammate 繞過。Auto mode 下，分類器會把其他代理轉述的「已核准」視為不受信任輸入，並在投遞前審查每則訊息。

成本與規模

• Token 用量隨 Teammate 數量線性成長；In-process Teammate 的 prompt cache 預設只保留 5 分鐘（含訂閱方案），可用 subagentPromptCacheTtl 設為 1 小時。
• 官方建議從 3–5 個 Teammate 開始；15 個獨立任務用 3 個 Teammate 起步即可。「三個專注的 Teammate 往往勝過五個分散的」。
• Split-pane 模式不支援 VS Code 內建終端機、Windows Terminal 與 Ghostty，這些環境請使用預設的 in-process 模式。

企業導入檢核要點

• 只在需要的專案或 session 開啟 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS，避免意外形成團隊
• 禁止 Lead 以 --dangerously-skip-permissions 啟動（會擴散到全體 Teammate）
• 以 TeammateIdle／TaskCreated／TaskCompleted hooks 建立品質閘門（見 2.2.6）
• 以檔案分工或 isolation: worktree 的 Subagent 定義避免同檔衝突
• 在 /usage 中追蹤 Agent Teams 的 token 用量，訂定團隊規模上限

2.2.8 官方平行執行方式分類與新型協作機制

🆕 v3.5 新增：2026 年官方把「平行執行」整理成五種方式（官方 agents 頁），另有跨 session 傳訊作為輕量的協調管道。本節協助你依任務特性選擇，避免「什麼都用 Agent Teams」。

五種平行方式比較

Dynamic Workflows：把「編排邏輯」寫成程式

Subagents、Skills、Agent Teams 都由 Claude 逐輪決定下一步；Workflow 則把迴圈、分支與中間結果放進 JavaScript 腳本，由 runtime 在背景執行，session 保持可互動。

💡 Workflow 的品質價值不只是「更多代理」：腳本可以讓多個獨立代理對抗式地互相審查發現，或從多個角度草擬計畫再比較，得到比單次處理更可信的結果。先在小範圍（單一目錄）試跑以估算成本。

Agent view 與背景 session

• claude agents 開啟 agent view，依「需要輸入／執行中／已完成」分組列出背景 session；可 peek、回覆或 attach 進入完整對話。也可在 session 內用 /bg、/background 或 claude --bg 把工作送到背景。
• 檔案隔離：背景 session 在編輯檔案前，會自動移入 .claude/worktrees/ 下的 git worktree；非 git repo、已在 worktree 中或寫入工作目錄以外時例外。可用 worktree.bgIsolation: "none" 關閉。
• 背景 session 由 supervisor 行程託管，關閉終端機後仍會繼續；閒置約一小時的未附著 session 會被暫停（對話仍保存在磁碟）。
• 企業可用 disableAgentView: true（或 CLAUDE_CODE_DISABLE_AGENT_VIEW）透過 managed settings 整體停用。

Cross-session messaging：讓你的 session 互相通知

v2.1.224 起（原生 Windows v2.1.234 起）預設開啟。Claude 以 ListAgents 找到可聯絡的 session，再用 SendMessage 傳送純文字訊息，例如「schema 遷移完成，新欄位是 tenant_id，現在可以 rebase main」。/list-agents（別名 /peers）可檢查可達的 session。

收到的訊息有嚴格限制：不能核准任何權限、不能要求修改設定或 CLAUDE.md、訊息中的 /compact 等指令不會被執行，需要的權限仍照常詢問。

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

• isolatePeerMachines: true：訊息要送往其他機器或雲端 session 前必須經你核准（即使在 bypassPermissions）
• crossSessionInbound: "refuse"：丟棄所有收到的 session 訊息
• Deny SendMessage／ListAgents：停止傳送與列出。⚠️ 這也會一併停用對 Subagent 與 Agent Teams 隊友的傳訊

Claude Projects（雲端長期專案協調）

Project 是一段持續的對話，Claude 為每個任務開一個 thread（雲端 session），每個 thread 都帶有專案的 repo、指示與記憶，可在電腦關機後繼續，並在 Overview 顯示哪些需要你。企業導入前須注意：

• 目前為 Pro／Max 公開 Beta，Team／Enterprise 尚不可用，且 Beta 期間沒有組織層級控制
• 不支援終端機 CLI，也不支援 Bedrock／Agent Platform／Foundry
• Thread 的沙箱在兩輪之間會暫停，若無法恢復會從新的 clone 繼續，未 commit 的變更可能遺失，長任務應要求 Claude 定期 commit 與 push
• Project 屬於單一使用者，無法分享

如何選擇：決策流程

graph TD
    Q1{任務能在一次對話內<br/>由 Claude 逐步完成?} -->|是| Q2{側支工作會塞滿 context?}
    Q2 -->|是| SA[Subagents]
    Q2 -->|否| MAIN[主對話直接做]
    Q1 -->|否| Q3{需要數十個以上代理<br/>或交叉驗證?}
    Q3 -->|是| WF[Dynamic Workflows]
    Q3 -->|否| Q4{工作者之間<br/>需要彼此協調?}
    Q4 -->|是| AT[Agent Teams]
    Q4 -->|否| Q5{要在電腦關機後<br/>持續數天?}
    Q5 -->|是| PJ[Projects / Routines]
    Q5 -->|否| AV[Agent view 背景 session<br/>+ Cross-session messaging]

2.3 Skills（技能系統）

2.3.1 Skills 概述

什麼是 Skills？

Skills 是 Claude Code 中可重用、可組合的能力模組。每個 Skill 透過 SKILL.md 檔案定義，使用 Markdown 格式搭配 YAML frontmatter 描述其用途、觸發條件與行為指引。Skills 可以被 Agents、Subagents 或使用者直接調用，用來封裝特定領域的專業知識和操作流程。

📌 Custom Commands 已併入 Skills：.claude/commands/deploy.md（舊式扁平檔案）與 .claude/skills/deploy/SKILL.md（新式目錄）現在是同一套機制，兩者都會產生 /deploy 指令、行為完全相同；既有的 .claude/commands/ 檔案不需遷移也能繼續運作。Skill 目錄形式多出的優勢是：可搭配同目錄下的輔助檔案、frontmatter 可控制「誰能觸發它」（見下方 disable-model-invocation），以及 Claude 可依任務自動判斷是否要使用它——這是與純指令最大的差異：Skill 內容只有在被使用時才載入 context，比起把等量內容塞進 CLAUDE.md 幾乎不佔用額外 token。

graph TB
    subgraph "Skills 系統架構"
        U[使用者請求] --> CC[Claude Code 核心]
        CC --> SD{Skill 匹配}
        
        SD --> BS[內建 Skills<br>/simplify, /batch, /debug...]
        SD --> AS[Agent Skills<br>在 .agent.md 中定義]
        SD --> PS[Plugin Skills<br>在 .claude-plugin/ 中打包]
        SD --> CS[自訂 Skills<br>SKILL.md 檔案]
        
        BS --> E[執行 Skill 邏輯]
        AS --> E
        PS --> E
        CS --> E
        
        E --> R[回傳結果]
    end
    
    style CC fill:#6366f1,stroke:#4f46e5,color:#fff
    style BS fill:#dbeafe,stroke:#3b82f6
    style AS fill:#dcfce7,stroke:#22c55e
    style PS fill:#fef3c7,stroke:#f59e0b
    style CS fill:#f3e8ff,stroke:#a855f7

Skill 類型總覽

2.3.2 內建 Skills（Slash Commands）

🆕 v3.5 更正：官方把「以 prompt 驅動、讓 Claude 用工具編排工作」的指令稱為 Bundled skills，在 commands 參考中標示為 Skill；/compact、/memory、/skills、/agents 等則是執行固定邏輯的內建命令，不是 Skill。可用 disableBundledSkills 設定整體關閉 bundled skills。

使用範例：

# 在 Claude Code 會話中直接使用
> /debug 這個 API 調用總是回傳 401，但 token 是有效的

Claude Code 會啟動系統化偵錯流程：
1. 檢查 HTTP 請求 headers
2. 驗證 token 格式與過期時間
3. 追蹤認證中介層邏輯
4. 識別出 Bearer prefix 缺失問題

> /batch 將所有 .java 檔案中的 javax.persistence 改為 jakarta.persistence

Claude Code 會：
1. 掃描所有 .java 檔案
2. 列出受影響的檔案清單
3. 逐一執行替換
4. 驗證編譯是否通過

2.3.3 SKILL.md 檔案格式

基本結構

自訂 Skills 使用 SKILL.md 檔案定義，遵循 Markdown + YAML frontmatter 格式：

---
name: java-entity-generator
description: >
  根據資料庫 Schema 描述或 DDL 語句，自動生成符合 JPA 規範的
  Java Entity 類別，支援 Lombok、Builder Pattern 等選項。
---

# Java Entity Generator

## 使用時機

當使用者需要：
- 從資料庫表結構生成 Java Entity
- 建立新的 JPA 實體類
- 將 DDL 轉換為 Java 程式碼

## 操作步驟

1. 分析使用者提供的表結構資訊或 DDL
2. 確認目標套件路徑和命名規範
3. 生成 Entity 類別，包含：
   - 適當的 JPA 註解（@Entity, @Table, @Column 等）
   - 主鍵策略（@Id, @GeneratedValue）
   - 關聯映射（@OneToMany, @ManyToOne 等）
   - Auditing 欄位（@CreatedDate, @LastModifiedDate）
4. 如啟用 Lombok，加入 @Data, @Builder 等註解
5. 生成對應的 Repository 介面

## 輸出格式

- 使用專案現有的程式碼風格
- 遵循專案的套件結構慣例
- 包含必要的 import 陳述式

## 範例

輸入：使用者表，包含 id、username、email、created_at
輸出：User.java Entity + UserRepository.java

YAML Frontmatter 參數說明

🆕 v3.5 依官方 Frontmatter reference 更正：所有欄位都是選填（description 為建議填寫）；欄位名稱使用小寫加連字號（when_to_use 例外），拼錯的欄位會被靜默忽略。YAML 解析失敗時 Skill 仍會載入，但所有欄位都不生效。

🔐 安全警示：專案 Skill 的 allowed-tools 不受 workspace trust 管控，即使在從未信任過的資料夾中以 -p 執行，只要 Skill 被呼叫就會生效。Skill 可以替自己授予廣泛的工具權限，因此審查 repo 中 Skill 的 allowed-tools 應列入 code review 清單。

🆕 進階 Frontmatter 範例

---
name: spring-migration
description: 將 Spring Boot 2.x 專案遷移至 3.x
argument-hint: "指定目標 Spring Boot 版本（如 3.2.0）"
allowed-tools:
  - Read
  - Edit
  - Bash(mvn *)
  - Bash(./gradlew *)
model: opus
effort: max
paths:
  - "src/main/java/**"
  - "pom.xml"
  - "build.gradle"
shell: bash
---

🆕 特殊變數與替換

---
name: test-file
description: 為指定檔案生成測試
---

# 為 $1 生成測試

讀取 $1 的內容，並使用 ${CLAUDE_SKILL_DIR}/templates/test-template.ts 
作為模板生成對應的測試檔案。

🆕 Skill 權限規則

在 settings.json 中可以為特定 Skill 配置獨立的權限規則：

{
  "permissions": {
    "allow": [
      "Skill(spring-migration)",
      "Skill(security-review)"
    ],
    "deny": [
      "Skill(dangerous-skill)"
    ]
  }
}

🆕 Skill 清單預算

SLASH_COMMAND_TOOL_CHAR_BUDGET 環境變數控制的是 Skill 清單（名稱＋描述）佔用的字元預算，而不是 Skill 的輸出大小（v3.5 更正）。清單超出預算時，名稱一定保留，但較不重要的描述會被截短，可能讓 Claude 找不到觸發關鍵字。建議改用下方 2.3.6 的 skillListingBudgetFraction 設定。

$ARGUMENTS 動態參數

在 SKILL.md 內容中使用 $ARGUMENTS 佔位符，會在使用者呼叫時被替換為實際參數：

---
name: explain
description: 解釋指定的程式碼或概念
---

請詳細解釋以下內容：$ARGUMENTS

使用者呼叫方式：

/explain React useEffect 的 cleanup 機制

!command 動態 Context

使用 !`command` 語法可在 SKILL.md 中嵌入動態 context：

---
name: review-changes
description: 審查目前的 git 變更
---

# 審查目前變更

以下是目前的 git diff：
!`git diff --staged`

請根據以上變更進行程式碼審查。

2.3.4 Agent Skills（附加在 Agent 上的 Skills）

Skills 可以透過 Agent 的 YAML frontmatter 進行關聯，讓特定 Agent 在執行時自動載入相關的 Skills：

---
# .claude/agents/security-reviewer.md
name: security-reviewer
description: 安全性程式碼審查代理
skills:
  - name: owasp-checker
    description: 檢查 OWASP Top 10 安全漏洞
    file: .claude/skills/owasp-checker/SKILL.md
  - name: dependency-auditor
    description: 檢查第三方依賴的已知漏洞
    file: .claude/skills/dependency-auditor/SKILL.md
tools:
  - Bash
  - Read
  - Grep
---

# Security Reviewer Agent

## 審查流程
1. 載入 owasp-checker 和 dependency-auditor Skills
2. 掃描目標程式碼
3. 依照 OWASP Top 10 逐項檢查
4. 執行 npm audit / mvn dependency-check
5. 生成統一安全報告

Agent Skills 的載入流程：

sequenceDiagram
    participant U as 使用者
    participant CC as Claude Code
    participant A as Agent
    participant S as Skill

    U->>CC: 調用 security-reviewer Agent
    CC->>A: 載入 Agent 定義
    A->>A: 解析 YAML frontmatter
    A->>S: 載入 owasp-checker SKILL.md
    A->>S: 載入 dependency-auditor SKILL.md
    A->>A: 將 Skill 指引注入 context
    A->>CC: 開始執行審查任務
    CC->>U: 回傳審查結果

2.3.5 開發自訂 Skills

步驟一：規劃 Skill 範圍

設計 Skill 時，遵循「單一職責」原則：

✅ 好的 Skill 設計：
├── api-endpoint-generator    → 專注於生成 REST API 端點
├── unit-test-writer          → 專注於撰寫單元測試
├── sql-optimizer             → 專注於 SQL 查詢優化
└── changelog-generator       → 專注於生成變更日誌

❌ 不好的 Skill 設計：
└── do-everything-skill       → 範圍太廣，什麼都做

步驟二：建立 SKILL.md 檔案

專案結構：
.claude/
└── skills/
    ├── api-endpoint-generator/
    │   └── SKILL.md
    ├── unit-test-writer/
    │   └── SKILL.md
    └── sql-optimizer/
        └── SKILL.md

完整範例 — Spring Boot API 端點產生器：

---
name: spring-boot-api-generator
description: >
  根據業務需求描述，生成完整的 Spring Boot REST API 端點，
  包含 Controller、Service、Repository 三層架構程式碼，
  以及對應的 DTO、Exception Handler 和 Swagger 文件註解。
---

# Spring Boot API 端點產生器

## 觸發條件

當使用者請求以下操作時啟動：
- 建立新的 REST API 端點
- 為現有 Entity 新增 CRUD API
- 生成 Spring Boot Controller + Service + Repository

## 生成規範

### Controller 層
- 使用 @RestController 和 @RequestMapping
- 實作標準 HTTP 方法（GET/POST/PUT/DELETE）
- 加入 @Operation (Swagger) 註解
- 使用 @Valid 進行請求驗證
- 回傳適當的 HTTP 狀態碼

### Service 層
- 定義 Service 介面和實作類
- 實作業務邏輯和資料轉換
- 使用 @Transactional 管理交易
- 處理業務例外

### Repository 層
- 繼承 JpaRepository
- 定義自訂查詢方法
- 使用 @Query 處理複雜查詢

### DTO 層
- 建立 Request/Response DTO
- 使用 Jakarta Validation 註解
- 實作 Entity ↔ DTO 轉換

## 命名規範
- 遵循專案現有的命名慣例
- Controller: XxxController
- Service: XxxService / XxxServiceImpl
- Repository: XxxRepository
- DTO: XxxRequest / XxxResponse

步驟三：在 Agent 中引用 Skill

---
# .claude/agents/backend-developer.md
name: backend-developer
description: Spring Boot 後端開發代理
skills:
  - name: spring-boot-api-generator
    description: 生成 Spring Boot REST API
    file: .claude/skills/api-endpoint-generator/SKILL.md
  - name: java-entity-generator
    description: 生成 JPA Entity
    file: .claude/skills/java-entity-generator/SKILL.md
---

# Backend Developer Agent
（Agent 的詳細指引...）

2.3.6 Skills 最佳實踐

設計原則

graph LR
    subgraph "SKILL.md 設計四原則"
        P1[🎯 精確描述<br>description 決定匹配品質]
        P2[📋 步驟明確<br>操作步驟要可執行]
        P3[📐 範圍適中<br>不過大也不過小]
        P4[📝 範例豐富<br>提供輸入輸出範例]
    end
    
    P1 --> P2 --> P3 --> P4

🆕 Skill 內容生命週期與自動壓縮

🆕 v3.2 新增，v3.3 補充 token 預算細節

Skill 內容在載入到 context 後，會受到 Claude Code 的 context 管理機制影響：

1. 載入時機：Skill 在使用者呼叫 /name 或 AI 自動匹配時載入到 context
2. 常駐 context：渲染後的 SKILL.md 以單一訊息進入對話，之後各輪都會保留；但 allowed-tools 的授權在下一則訊息後就失效
3. 重複呼叫：內容相同時只加一段「已載入」的註記，不會重複放入；參數或動態 context 不同時才會放入新版本
4. 壓縮後保留規則：auto-compaction 會在摘要後重新附上每個 Skill 最近一次的呼叫內容：
   • 單一 Skill 上限：保留前 5,000 tokens
   • 所有 Skills 總預算：合計 25,000 tokens，超出的較舊 Skill 會被捨棄
5. ⚠️ 不會自動重讀檔案（v3.5 更正）：Claude Code 不會在後續輪次重新讀取 SKILL.md；若 Skill 看似「失效」，通常內容仍在，只是模型選擇了其他做法，請強化 description 或改用 hooks 強制執行

📌 設計建議：將 Skill 最重要的操作步驟放在檔案前段，確保壓縮時關鍵資訊被保留。可使用 /doctor 命令檢查 Skill 的 token 使用量，診斷預算分配問題。

🆕 即時變更偵測

Claude Code 會監視 SKILL.md 檔案的變更：

• 修改 SKILL.md 檔案後，無需重啟會話即可生效
• 新增或刪除 SKILL.md 檔案也會即時反映在 /skills 清單中
• 透過 ConfigChange Hook 可以監聽 skills 設定變更

🆕 skillOverrides 設定

skillOverrides 用來在設定檔中控制 Skill 的可見性，適合你不想修改 SKILL.md 的情況（例如共享 repo 中的 Skill）。在 /skills 選單中選取 Skill、按 Space 循環切換狀態、Esc 儲存，即會自動寫入：

{
  "skillOverrides": {
    "legacy-context": "name-only",
    "deploy": "off"
  }
}

⚠️ v3.5 更正：v3.4 範例中以 skillOverrides 覆寫 model、effort、allowed-tools 的寫法不存在，此設定只接受上述四種狀態字串。Plugin 的 Skill 不受 skillOverrides 影響，請改用 /plugin 管理。在 managed settings 中可透過別名（如 checkup → /doctor）進一步限制，但只能收緊、不能放寬。

🆕 skillListingBudgetFraction 與 skillListingMaxDescChars 設定

每一輪 Claude 都會看到 Skills 清單，Claude Code 會把清單限制在 context window 的一定比例內：

{
  "skillListingBudgetFraction": 0.02,
  "skillListingMaxDescChars": 800
}

⚠️ v3.5 更正：v3.4 記載的預設值 0.05 與 maxSkillDescriptionChars 設定鍵皆不正確，官方鍵名為 skillListingMaxDescChars。

📌 調校流程：先執行 /doctor 看清單的 context 成本與最大貢獻者 → 執行 /skill-doctor 找出從未被呼叫、成本最高的 Skill → 以 skillOverrides 設為 "name-only" 或 "off" → 仍不足才提高預算。/context 的 Skills 列顯示的是套用預算後、模型實際收到的大小。

組織管理

推薦的 Skills 目錄結構：

.claude/
├── skills/                          # 專案級 Skills
│   ├── code-generation/
│   │   ├── SKILL.md                 # API 產生器
│   │   └── templates/               # 可選：模板檔案
│   ├── testing/
│   │   └── SKILL.md                 # 測試產生器
│   └── documentation/
│       └── SKILL.md                 # 文件產生器
├── agents/                          # Agent 定義
│   └── backend-developer.md         # 引用上述 Skills
└── CLAUDE.md                        # 專案級指引

~/.claude/
└── skills/                          # 全域 Skills（所有專案共用）
    ├── personal-style/
    │   └── SKILL.md                 # 個人程式碼風格
    └── review-checklist/
        └── SKILL.md                 # 個人 code review 清單

⚠️ 注意事項

1. Description 品質：SKILL.md 的 description 是 Claude Code 判斷是否啟用該 Skill 的核心依據。模糊的描述會導致 Skill 無法正確觸發
2. 不要重複造輪子：使用 /skills 命令查看現有 Skills，避免建立功能重複的 Skill
3. 與 Agent 搭配：Skills 最佳使用方式是透過 Agent 的 skills 欄位引用，這樣可以確保在正確的上下文中被觸發
4. 版本管理：將 SKILL.md 納入 Git 版本控制，確保團隊成員使用一致的 Skills 定義

2.3.7 Skill 進階範例集

以下提供多個實戰級 Skill 範例，可直接複製使用或作為開發參考：

資料庫遷移審查 Skill

---
name: migration-review
description: 審查資料庫遷移腳本的安全性、效能影響和向後相容性。
  支援 Prisma、TypeORM、Flyway、Liquibase 等遷移框架。
allowed-tools: Read Grep Glob
---

# Database Migration Review

## 審查清單

### 安全性
- 是否有資料遺失風險？（DROP TABLE, DROP COLUMN）
- 大表變更是否使用 online DDL？
- 是否需要資料回填（backfill）？

### 效能
- 是否在大表上建立索引？（需要 CONCURRENTLY）
- 是否有鎖表風險？
- 預估執行時間

### 向後相容性
- 新舊版本程式碼能否同時運行？
- 是否需要分階段部署？
  1. 先部署相容的程式碼
  2. 執行遷移
  3. 部署使用新 schema 的程式碼

## 輸出格式
| 項目 | 狀態 | 說明 |
|------|------|------|
| 資料安全 | ✅/⚠️/❌ | 詳細說明 |
| 效能影響 | ✅/⚠️/❌ | 預估影響 |
| 向後相容 | ✅/⚠️/❌ | 相容性分析 |
| 回滾方案 | 有/無 | 如何回滾 |

Git Commit 訊息生成 Skill

---
name: commit-message
description: 根據已暫存的變更生成 Conventional Commit 格式的 commit 訊息。
  支援 feat/fix/refactor/docs/test/chore 等類型。
tools: bash
---

# Commit Message Generator

## 分析步驟
1. 執行 `git diff --staged --stat` 查看變更摘要
2. 執行 `git diff --staged` 查看詳細變更
3. 根據變更內容判斷 commit 類型

## Commit 訊息格式
type(scope): 簡短描述

詳細說明（如果需要）

## 類型判斷規則
- feat: 新功能
- fix: Bug 修復
- refactor: 重構（不改變功能）
- docs: 文件變更
- test: 測試相關
- chore: 建置/工具改動
- perf: 效能改善
- style: 程式碼格式

## 範例
feat(auth): 新增 OAuth 2.0 Google 登入支援

- 實作 Google OAuth2 flow
- 新增 /api/auth/google callback endpoint
- 整合現有的 JWT token 系統

依賴升級 Skill

---
name: dependency-upgrade
description: 分析和執行專案依賴升級，包含安全漏洞修復、
  breaking changes 檢查、和升級路徑規劃。
allowed-tools: Read Grep Glob Bash(npm outdated *) Bash(npm audit *)
---

# Dependency Upgrade Skill

## 升級流程
1. 執行 `npm outdated` 或 `mvn versions:display-dependency-updates`
   了解哪些依賴有新版本
2. 檢查每個依賴的 CHANGELOG 和 breaking changes
3. 分類為：patch（安全）、minor（通常安全）、major（需要檢查）
4. 逐步升級，每次只升級一個 major 版本
5. 每次升級後執行測試

## 優先順序
1. 🔴 有已知 CVE 的依賴 → 立即升級
2. 🟡 Major 版本落後 2+ 的依賴 → 規劃升級
3. 🟢 Minor/Patch 更新 → 批量升級

## 輸出格式
| 套件 | 目前版本 | 最新版本 | 類型 | Breaking Changes | 建議 |
|------|---------|---------|------|-----------------|------|

2.3.8 Skill 來源、優先順序與雲端同步

🆕 v3.5 新增：依官方 skills 頁補齊 Skill 的載入來源、同名衝突規則，以及 claude.ai 同步機制，這些都是企業治理擴充來源時必須掌握的細節。

七種載入來源

📌 .claude/commands/*.md 是舊格式，仍可使用，支援與 Skill 相同的 frontmatter（name 與 paths 除外）；同名時 Skill 優先。資料夾名稱不可使用 synced（保留給同步 Skill）。

同名衝突時執行哪一個

claude.ai 同步 Skill（企業需特別注意）

以 claude.ai 帳號登入終端機時，Claude Code 會在背景把帳號啟用的 Skills 下載到 ~/.claude/skills/synced/，並約每 10 分鐘檢查更新；同步只下載、不上傳，本機修改會被下次同步覆寫。以下情況不會同步：API key／ANTHROPIC_AUTH_TOKEN／CLAUDE_CODE_OAUTH_TOKEN／apiKeyHelper 認證、Bedrock 或 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC、bare mode 或 --safe-mode、managed settings 以 strictPluginOnlyCustomization 鎖定 Skill 來源。

🔐 治理重點：同步 Skill 是一條繞過私有 plugin marketplace 的擴充來源。若企業只允許經審核的 Skill，請在 managed settings 設定 syncClaudeAiSkills: false，或以 strictPluginOnlyCustomization 將 Skills／Agents／Hooks／MCP 限定為 plugin 與 managed 來源。

Cowork、雲端 session 與 Routines

Cowork 與雲端 session（含 Routines）不會讀取你本機的 ~/.claude/skills/。Routine 呼叫只存在於個人目錄的 Skill 時，會回報 skill not found。解法：在 claude.ai 帳號啟用該 Skill，或把 Skill 提交到 repo 的 .claude/skills/。Desktop 排程任務在本機執行，因此會讀取 ~/.claude/skills/。

企業導入檢核要點

• 核心 Skill 以 Enterprise 來源或內部 plugin marketplace 發佈，避免個人版本意外覆蓋專案版本（Personal 優先於 Project）
• Code review 清單加入「檢查 Skill 的 allowed-tools 與 ! 動態命令」
• 有副作用的 Skill（部署、發佈、傳訊）一律設 disable-model-invocation: true
• 每季執行 /skill-doctor，以 skillOverrides 關閉從未使用的高成本 Skill
• 決定是否允許 claude.ai 同步 Skill（syncClaudeAiSkills）

2.4 Plugins（插件系統）

2.4.1 Plugin 概述

什麼是 Plugin？

Plugin 是 Claude Code 的功能擴展封裝單元。每個 Plugin 是一個目錄（manifest 放在其中的 .claude-plugin/plugin.json），可以包含 Skills、Agents、Hooks、MCP／LSP Server、Output Styles、Workflows、Monitors 與 bin/ 執行檔，作為一個整體進行分發和安裝。Plugin 讓開發者可以將一組相關的功能打包成可重用的擴展包。

graph TB
    subgraph "Plugin 架構"
        P[Plugin 根目錄]
        
        P --> M[plugin.json<br>清單檔]
        P --> A[agents/<br>Agent 定義]
        P --> S[skills/<br>SKILL.md 檔案]
        P --> C[commands/<br>Slash Commands]
        P --> I[hooks/ .mcp.json<br>monitors/ bin/]
        
        M --> D[名稱、版本、描述<br>元件路徑、userConfig、依賴]
        A --> A1[agent-1.md]
        A --> A2[agent-2.md]
        S --> S1[skill-1/SKILL.md]
        S --> S2[skill-2/SKILL.md]
    end
    
    style P fill:#6366f1,stroke:#4f46e5,color:#fff
    style M fill:#dbeafe,stroke:#3b82f6
    style A fill:#dcfce7,stroke:#22c55e
    style S fill:#fef3c7,stroke:#f59e0b
    style C fill:#fce7f3,stroke:#ec4899
    style I fill:#f3e8ff,stroke:#a855f7

Plugin vs 其他擴展機制比較

2.4.2 Plugin 目錄結構

plugin.json 清單檔

.claude-plugin/plugin.json 定義 Plugin 的元資料與設定。Manifest 是選填的：省略時 Claude Code 會在預設位置自動探索元件，並以目錄名稱作為 plugin 名稱；有 manifest 時，只有 name 必填（kebab-case）。

{
  "name": "spring-boot-toolkit",
  "displayName": "Spring Boot Toolkit",
  "version": "1.0.0",
  "description": "Spring Boot 開發工具包，包含 API 生成器、Entity 生成器和測試輔助",
  "author": { "name": "DevTeam", "email": "devteam@example.com" },
  "homepage": "https://docs.example.com/spring-boot-toolkit",
  "repository": "https://github.com/example/claude-spring-boot-toolkit",
  "license": "MIT",
  "keywords": ["spring-boot", "java"],
  "agents": ["./agents/spring-boot-developer.md", "./agents/spring-test-writer.md"],
  "hooks": "./hooks/hooks.json",
  "mcpServers": "./.mcp.json",
  "userConfig": {
    "api_endpoint": {
      "type": "string",
      "title": "API endpoint",
      "description": "團隊 API 端點"
    }
  },
  "dependencies": [
    { "name": "java-lsp", "version": "~1.2.0" }
  ]
}

⚠️ v3.5 更正：v3.4 範例中以物件陣列列舉 agents[].file、skills[].file、commands[].name 的寫法不是官方 schema。元件路徑欄位接受路徑字串或路徑陣列：skills 是附加到預設 skills/ 掃描；commands、agents、outputStyles、workflows 則會取代預設目錄；hooks、mcpServers、lspServers 可以是路徑或內嵌設定。其他重要欄位：userConfig（啟用時詢問使用者，sensitive: true 的值存入安全儲存區）、dependencies（其他 plugin 與 semver 限制）、channels、experimental.monitors／themes／evals。

完整的 Plugin 目錄結構

🆕 v3.5 依官方 Standard plugin layout 更新：manifest 為選填；除 plugin.json 外，所有目錄都必須放在 plugin 根目錄，不可放進 .claude-plugin/。

my-plugin/
├── .claude-plugin/
│   └── plugin.json                  # Plugin 清單檔（選填）
├── settings.json                    # 預設設定（僅支援 agent、subagentStatusLine）
├── .mcp.json                        # Plugin 提供的 MCP Server 配置
├── .lsp.json                        # Plugin 提供的 LSP Server 配置
├── agents/
│   ├── spring-boot-developer.md     # Agent 定義（YAML frontmatter + 指引）
│   └── spring-test-writer.md
├── skills/
│   ├── api-generator/
│   │   └── SKILL.md                 # Skill 定義
│   └── entity-generator/
│       └── SKILL.md
├── hooks/
│   └── hooks.json                   # Plugin 提供的 Hook 定義
├── monitors/                        # 🆕 背景監控器設定
│   └── monitors.json
├── workflows/                       # 🆕 Dynamic Workflow 腳本
├── output-styles/                   # Output Style 定義
├── bin/                             # 🆕 可執行工具
│   └── lint-check                   #     Plugin 附帶的 CLI 工具
└── commands/
    └── spring-init.md               # 扁平 .md 格式的 Skill（新 plugin 建議改用 skills/）

⚠️ v3.5 更正：plugin 根目錄的 CLAUDE.md 不會被載入成 context。Plugin 要提供會進入 context 的指引，請寫成 Skill（或 Agent 的本文、hooks）。

📌 重要：plugin.json 放在 .claude-plugin/ 子目錄中，而 settings.json、.mcp.json、.lsp.json 放在 Plugin 根目錄（非 .claude-plugin/ 中）。

🆕 Plugin MCP Server 配置

Plugin 可以自帶 MCP Server，使用特殊路徑變數：

// .mcp.json（Plugin 根目錄）
{
  "mcpServers": {
    "my-plugin-server": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/mcp-server/dist/index.js"],
      "env": {
        "DATA_DIR": "${CLAUDE_PLUGIN_DATA}"
      }
    }
  }
}

🆕 Plugin LSP Server 配置

Plugin 可以提供 LSP（Language Server Protocol）整合，為特定語言提供增強的程式碼智能：

// .lsp.json（Plugin 根目錄）
{
  "servers": {
    "java": {
      "command": "jdtls",
      "args": ["--data", "${CLAUDE_PLUGIN_DATA}/jdtls-data"]
    }
  }
}

🆕 Namespaced Skills（命名空間技能）

Plugin 的 Skills 使用 plugin-name:skill-name 的命名空間格式，避免跨 Plugin 名稱衝突：

# 呼叫 Plugin 的 Skill
> /spring-boot-toolkit:api-generator 建立使用者管理 API

# 不帶命名空間時，Claude Code 會自動匹配最相關的 Skill
> /api-generator 建立使用者管理 API

2.4.3 Plugin 的發現與安裝

🆕 v3.5 依官方 discover-plugins 與 plugin-marketplaces 頁全面改寫：v3.4 中的 /plugin marketplace search、/plugin marketplace browse、/plugins search、/plugins list、/install-plugin、--scope 參數、.claude-plugins/ 目錄、陣列格式的 extraKnownMarketplaces，以及 managed settings 的 plugins.allowed／blocked／required 物件，皆不是官方語法，已全部更正。

Plugin Marketplace（插件市集）

Marketplace 是 plugin 的目錄，使用分兩步：先加入 marketplace（只註冊目錄，不安裝任何東西）→ 再安裝個別 plugin。

📌 應用程式內的提交表單會把 plugin 加入社群 marketplace，而不是官方 marketplace；是否收錄進官方由 Anthropic 決定。

瀏覽、安裝與管理

# 開啟互動式 plugin 管理器（Discover／Installed／Marketplaces／Errors／Stats 分頁）
> /plugin

# 從官方 marketplace 安裝
> /plugin install github@claude-plugins-official

# 加入 marketplace（來源可為 GitHub owner/repo、任一 Git URL、本機路徑、marketplace.json 的 URL）
> /plugin marketplace add anthropics/claude-plugins-community
> /plugin marketplace add https://gitlab.example.com/team/plugins.git
> /plugin marketplace add ./my-marketplace

# 加入 marketplace 並安裝，一次完成（v2.1.275+，會先顯示來源並要求確認）
> /plugin install quality-review-plugin --marketplace your-org/plugins

# 管理 marketplace（可簡寫為 /plugin market、rm）
> /plugin marketplace list
> /plugin marketplace update marketplace-name
> /plugin marketplace remove marketplace-name   # ⚠️ 會一併解除安裝來自它的 plugin

# 套用 plugin 變更而不重啟
> /reload-plugins

# 非互動（shell）安裝：預設安裝到 user scope
claude plugin install github@claude-plugins-official --scope project

# 從 claude.ai 列出的組織 plugin library 加入 marketplace
claude plugin marketplace add --claudeai claudeai-organization-library

📌 自 v2.1.221 起，從 /plugin 介面安裝後通常會立即生效（摘要顯示 Plugin is now active.）；若啟用會讓 prompt cache 失效，則顯示 Run /reload-plugins to activate. 並自動執行重新載入。在 Desktop App 請使用 plugin browser，在 VS Code 請使用 Manage plugins 對話框。

安裝範圍（Installation Scopes）

⚠️ 自 v2.1.195 起，只由專案 .claude/settings.json 啟用、且來自外部來源（GitHub repo、npm 等）的 plugin，不會因為加入 marketplace 就自動安裝，需要使用者自己安裝；這是為了防止 clone 下來的 repo 偷偷帶入第三方程式碼。

Plugin 開發與測試

# 以本機目錄載入 plugin（僅限本次 session，不需安裝）
claude --plugin-dir ./my-plugin-dev

# 以 URL 載入 .zip 格式 plugin（僅限本次 session）
claude --plugin-url https://example.com/plugins/my-plugin.zip

Plugin 自動更新

Claude Code 在 session 啟動後（隨機延遲最多 10 分鐘）於背景更新 marketplace 與已安裝 plugin，執行中的 session 仍使用啟動時載入的版本，更新後會提示執行 /reload-plugins。

# 停用 Claude Code 與 plugin 的自動更新
export DISABLE_AUTOUPDATER=1
# 只保留 plugin 自動更新
export FORCE_AUTOUPDATE_PLUGINS=1

團隊 Marketplace（內部插件分發）

在專案 .claude/settings.json 宣告 marketplace 與要啟用的 plugin；成員信任該資料夾後，Claude Code 會自動加入這些 marketplace：

{
  "extraKnownMarketplaces": {
    "my-team-tools": {
      "source": { "source": "github", "repo": "your-org/claude-plugins" },
      "autoUpdate": true
    }
  },
  "enabledPlugins": {
    "code-standards@my-team-tools": true
  }
}

安裝後，Plugin 的 Skills 以 plugin-name:skill-name 命名空間出現在 /skills，Agents 以 plugin-name:agent-name 識別。

企業級 Plugin 管理

組織透過 managed settings 控制 plugin 來源，常用的設定鍵如下：

{
  "strictKnownMarketplaces": [
    { "source": "github", "repo": "anthropics/claude-plugins-official" },
    { "source": "github", "repo": "acme-corp/*" }
  ],
  "extraKnownMarketplaces": {
    "acme-approved": {
      "source": { "source": "github", "repo": "acme-corp/approved-plugins" },
      "autoUpdate": true
    }
  },
  "syncClaudeAiPlugins": false
}

⚠️ strictKnownMarketplaces 比對的是 plugin 來自哪個 marketplace，而不是 marketplace 內的條目，因此允許的 marketplace 中若有 command 來源的 plugin，仍可被安裝；要一併封鎖請參考官方 plugin-marketplaces 頁的 command source 相關設定。另外，Anthropic 不控制 plugin 內含的 MCP server、檔案或其他軟體，安裝前務必確認來源可信。

2.4.4 開發自訂 Plugin

🆕 claude plugin init（腳手架命令）

claude plugin init <name>（別名 claude plugin new）會在 ~/.claude/skills/<name>/ 建立 plugin 骨架；下次啟動 session 時自動以 <name>@skills-dir 載入，出現在 /plugin 與 claude plugin list 中，不需要安裝步驟。

# 最小骨架（manifest + 預設 Skill）
claude plugin init my-helper

# 同時建立其他元件：skills、agents、hooks、mcp、lsp、output-style、channel
claude plugin init my-helper --with skills hooks mcp --description "團隊共用工具"

# 產生的結構（依 --with 而定）
~/.claude/skills/my-helper/
├── .claude-plugin/
│   └── plugin.json          # manifest（author 預設取自 git config）
├── SKILL.md                 # 預設 Skill（以 my-helper 為命名空間）
├── agents/                  # --with agents
├── hooks/hooks.json         # --with hooks
├── .mcp.json                # --with mcp（含 HTTP 與 stdio 範例）
└── .lsp.json                # --with lsp

⚠️ v3.5 更正：--dir 選項不存在，骨架固定建立在 ~/.claude/skills/ 下。Skills-directory plugin 適合個人或小型團隊快速分享，但管理員可以用 strictKnownMarketplaces 或在 blockedMarketplaces 加入 {"source": "skills-dir"} 封鎖此來源；放在專案 .claude/skills/ 的 skills-directory plugin 需要先信任資料夾。

🆕 驗證 Plugin 結構

# 驗證 manifest 與目錄結構；--strict 讓警告也視為錯誤
claude plugin validate ./my-awesome-plugin --strict

# 沒有 manifest 的 plugin：直接驗證 agents 目錄（v2.1.233+）
claude plugin validate ./my-plugin/agents

# 在會話中重新載入已變更的 Plugin
> /reload-plugins

📌 claude plugin validate 會把無法辨識的欄位列為警告；多數欄位型別錯誤（例如 keywords 寫成字串而不是陣列）則會讓 plugin 無法載入。

🆕 Plugin Evals：以測試套件驗證 plugin 行為

🆕 v3.5 新增（需 v2.1.269+）

claude plugin eval 會用一組測試案例執行你的 plugin 並評分。每個案例是一段真實的 prompt 加上一或多個 grader（對結果的通過／不通過檢查，例如回覆的 regex、是否呼叫了某個工具，或交給第二個模型依 rubric 判定）。

# 讓 Claude 訪談你並提出案例、graders，試跑後寫入檔案
claude plugin eval init

# 在 plugin 根目錄執行全部案例，並授予必要工具
claude plugin eval . --allow-tools Write Edit "Bash(npm test *)"

# 只跑特定案例或標籤
claude plugin eval . --case "security-*" --tag regression

💰 每次 eval 執行與每個 judge grader 都是真實的模型呼叫，會計入方案用量或 API 帳單。企業建議：內部 plugin 上架前必須通過 eval 並顯示正向 Δ；模型升級時重跑 eval 以抓出回歸。

手動建立 Plugin 結構

若需要更精細控制，也可手動建立 Plugin 結構：

# 建立 Plugin 目錄
mkdir -p .claude-plugin/{agents,skills,commands}

# 建立 plugin.json
cat > .claude-plugin/plugin.json << 'EOF'
{
  "name": "my-custom-plugin",
  "version": "0.1.0",
  "description": "我的自訂 Plugin",
  "author": "My Team"
}
EOF

步驟二：加入 Agent 定義

<!-- .claude-plugin/agents/my-agent.md -->
---
name: my-custom-agent
description: 自訂的開發輔助代理
skills:
  - name: my-skill
    description: 自訂能力
    file: skills/my-skill/SKILL.md
tools:
  - Read
  - Edit
  - Write
  - Bash
---

# My Custom Agent

## 角色
你是一個專門處理 [特定領域] 的開發代理。

## 工作流程
1. 分析使用者需求
2. 搜尋相關程式碼
3. 執行變更
4. 驗證結果

步驟三：加入 SKILL.md

<!-- .claude-plugin/skills/my-skill/SKILL.md -->
---
name: my-custom-skill
description: 專門處理 [特定任務] 的能力模組
---

# My Custom Skill

## 使用時機
（描述何時應該使用此 Skill）

## 操作步驟
（詳細的操作指引）

步驟四：加入 Plugin 級指引

Plugin 根目錄的 CLAUDE.md 不會被載入，因此「使用此 plugin 時要遵循的原則」應寫成一個只由 Claude 觸發的背景知識型 Skill：

<!-- skills/plugin-guidelines/SKILL.md -->
---
name: plugin-guidelines
description: 使用 my-custom-plugin 的任何 Skill 或 Agent 產生程式碼時，必須遵循的團隊原則
user-invocable: false
---

1. 所有生成的程式碼必須通過 lint 檢查
2. 遵循專案現有的命名慣例
3. 變更前先確認不會破壞現有功能

2.4.5 Plugin 安全與信任

安全模型

⚠️ v3.5 更正：Plugin 沒有「權限宣告」機制，v3.4 流程圖中「依要求的工具評估風險」並不存在。Plugin 的 hooks、MCP server、monitors 與 bin/ 執行檔都會以與你相同的權限、在沙箱之外執行；Anthropic 也不控制 plugin 內含的 MCP server、檔案或其他軟體。因此 plugin 的安全性取決於來源治理與安裝前審查。

flowchart TD
    I[安裝 Plugin] --> S{來源}
    S -->|claude-plugins-official| O[Anthropic 策展]
    S -->|claude-community| C[自動化驗證與安全篩檢<br/>釘選 commit SHA]
    S -->|組織 / 第三方 marketplace| T[⚠️ 需自行審查]
    S -->|--plugin-dir / skills-dir| L[⚠️ 本機開發用途]

    O --> G{managed settings 允許此來源?<br/>strictKnownMarketplaces / blockedMarketplaces}
    C --> G
    T --> G
    L --> G
    G -->|否| X[❌ 拒絕安裝]
    G -->|是| R[人工審查 hooks / .mcp.json / monitors / bin/]
    R --> E[啟用：元件以使用者權限執行]

    style X fill:#fee2e2,stroke:#ef4444
    style T fill:#fef3c7,stroke:#f59e0b
    style L fill:#fef3c7,stroke:#f59e0b

最佳實踐

⚠️ 注意事項

1. 執行權限：Plugin 的 hooks 與 monitors 在沙箱外執行，等同於你親手執行的程式
2. 來源信任：優先使用官方與組織審核過的 marketplace，謹慎使用來路不明的 Plugin
3. 定期更新：關注 Plugin 的安全更新；移除 marketplace 會一併解除安裝來自它的 plugin
4. 企業合規：在企業環境中，透過 managed settings 的 strictKnownMarketplaces、blockedMarketplaces、enabledPlugins 統一管理

🆕 Plugin settings.json 預設設定

Plugin 根目錄的 settings.json 會在 plugin 啟用時套用預設設定，但只支援 agent 與 subagentStatusLine 兩個鍵（v3.5 更正：model 不受支援）：

{
  "agent": "spring-architect",
  "subagentStatusLine": true
}

📌 需要讓使用者填寫的值（API 端點、token 等）請使用 manifest 的 userConfig，不要要求使用者手動編輯 settings.json。

🆕 Plugin Hints（插件推薦安裝提示）

Plugin Hints 是給 CLI／SDK 維護者的協定（v3.5 更正：不是在 plugin.json 設定 hints 欄位）。Claude Code 會對它透過 Bash／PowerShell 工具與 hooks 執行的每個命令設定環境變數 CLAUDECODE=1（v2.1.172 起另設 CLAUDE_CODE_CHILD_SESSION=1）。你的 CLI 偵測到後，在 stderr 輸出一行標記：

if (process.env.CLAUDECODE) {
  process.stderr.write(
    '<claude-code-hint v="1" type="plugin" value="example-cli@claude-plugins-official" />
',
  )
}

Claude Code 會在輸出送進模型前移除這行，確認該 plugin 列在官方 Anthropic marketplace、尚未安裝且未提示過，才顯示安裝提示；永遠不會自動安裝。

Anthropic 維護兩個公開 Marketplace：claude-plugins-official（官方策展，首次互動式啟動 Claude Code 時會自動註冊；若曾在自動註冊前以非互動模式執行、或曾被 marketplace 政策擋下，需自行執行 claude plugin marketplace add anthropics/claude-plugins-official）與 claude-community（社群審核後上架，使用者以 /plugin marketplace add anthropics/claude-plugins-community 加入，安裝時以 @claude-community 為前綴）。

發佈 Plugin 前，建議先在本機執行 claude plugin validate ./your-plugin 驗證結構與 plugin.json 格式（審核流程會執行相同檢查，加上自動化安全掃描）。提交至社群 Marketplace 審核的入口：

審核通過的 Plugin 會被釘選到 anthropics/claude-plugins-community 倉庫中的特定 commit SHA，並隨後續推送自動更新釘選版本；公開目錄每晚才會同步一次，通過審核到能實際安裝之間可能有延遲。claude-plugins-official 則由 Anthropic 自行決策收錄名單，沒有對應的申請流程。

🆕 Background Monitors（背景監控器）

Plugin 可在 monitors/monitors.json（或 plugin.json 的 experimental.monitors）宣告背景監控器。Plugin 啟用時，Claude Code 自動啟動這些命令，並把每一行 stdout 作為通知送給 Claude，讓它對日誌、部署狀態等即時反應：

[
  {
    "name": "deploy-status",
    "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/poll-deploy.sh",
    "description": "部署狀態變化"
  },
  {
    "name": "error-log",
    "command": "tail -F ./logs/error.log",
    "description": "應用程式錯誤日誌",
    "when": "on-skill-invoke:debug"
  }
]

⚠️ Monitors 屬於實驗性元件，只在互動式 CLI session 執行，且與 hooks 相同、在沙箱之外執行；session 中停用 plugin 並不會停止已在執行的 monitor。v3.4 範例中的 watch／trigger／action 欄位不是官方格式。

2.4.6 Plugin 實戰範例

⚠️ v3.5 全面改寫：v3.4 範例使用了官方不存在的 manifest tools[]（含 command／args 模板）欄位，以及 read_file、grep_search、semantic_search 等其他 AI 工具的工具名稱。Claude Code plugin 要提供「自訂工具」有三種正規做法：bin/ 執行檔（加入 Bash 的 PATH，由 Skill 指示 Claude 呼叫）、MCP Server（.mcp.json，提供結構化工具）、Skill 內的 ! 動態命令。以下範例皆依官方 Standard plugin layout 撰寫。

範例一：Spring Boot 開發 Plugin

spring-boot-dev/
├── .claude-plugin/
│   └── plugin.json
├── bin/
│   ├── spring-init            # 產生 Controller／Service／Repository／DTO 骨架
│   └── spring-actuator-check  # 檢查 Actuator 端點並輸出報告
├── skills/
│   ├── entity-design/SKILL.md
│   ├── api-design/SKILL.md
│   └── security-config/SKILL.md
├── agents/
│   └── spring-architect.md
└── hooks/
    └── hooks.json             # 編輯 .java 後自動執行格式化

{
  "name": "spring-boot-dev",
  "version": "1.0.0",
  "description": "Spring Boot 開發輔助工具集",
  "author": { "name": "Platform Team" },
  "keywords": ["spring-boot", "java"],
  "userConfig": {
    "base_package": {
      "type": "string",
      "title": "Base package",
      "description": "產生程式碼時使用的根套件，例如 com.acme.order"
    }
  }
}

對應的 Agent 定義（agents/spring-architect.md，在 UI 中顯示為 spring-boot-dev:spring-architect）：

---
name: spring-architect
description: Spring Boot 架構顧問。設計 API、規劃模組結構或審查架構決策時主動使用。
model: sonnet
tools: Read, Grep, Glob, Bash
skills:
  - spring-boot-dev:entity-design
  - spring-boot-dev:api-design
  - spring-boot-dev:security-config
---

你是 Spring Boot 架構顧問。需要產生模組骨架時，執行 `spring-init --type <type> --name <name>`；
需要確認執行中服務的健康狀態時，執行 `spring-actuator-check --url <base-url>`。
所有建議都要附上對應的檔案路徑與理由。

對應的 Skill（skills/api-design/SKILL.md）：

---
description: 設計或修改 Spring Boot REST API 時使用。涵蓋 URL 命名、DTO 分層、錯誤回應格式與 OpenAPI 註解。
paths: "src/main/java/**/controller/**/*.java"
---

1. URL 使用複數名詞與 kebab-case，版本放在路徑（/api/v1/...）
2. Controller 只做請求解析與回應組裝，業務邏輯放 Service
3. 錯誤回應統一使用 RFC 9457 Problem Details
4. 新增端點後執行 `spring-init --type test --name <Controller>` 產生測試骨架

📌 Plugin 中 Agent 的 permissionMode、hooks、mcpServers 欄位會被忽略（安全考量），需要的 hooks 請放在 plugin 的 hooks/hooks.json。

範例二：前端元件庫 Plugin

react-component-kit/
├── .claude-plugin/plugin.json
├── bin/
│   ├── create-component       # 建立 TSX、樣式、測試與 Story
│   └── a11y-audit             # 以 axe-core 檢查元件無障礙可及性
├── skills/
│   └── component-conventions/SKILL.md
├── agents/
│   └── ui-reviewer.md
└── .mcp.json                  # 連接 Storybook MCP server

{
  "name": "react-component-kit",
  "version": "1.2.0",
  "description": "React 元件開發工具集，含 Storybook 整合",
  "mcpServers": "./.mcp.json"
}

---
name: ui-reviewer
description: 審查 React 元件的可及性、一致性與效能。元件新增或修改後主動使用。
tools: Read, Grep, Glob, Bash
disallowedTools: Edit, Write
---

先執行 `a11y-audit --component <path>`，再依團隊設計規範逐項審查，只提出建議、不直接修改。

範例三：資安合規 Plugin

security-compliance/
├── .claude-plugin/plugin.json
├── bin/
│   ├── secret-scan            # 包裝 gitleaks
│   ├── license-check          # 檢查依賴授權
│   └── owasp-scan             # 包裝 SAST 工具
├── skills/
│   ├── threat-modeling/SKILL.md
│   └── compliance-report/SKILL.md
├── hooks/hooks.json           # PreToolUse：阻擋寫入含密鑰的內容
└── evals/                     # plugin eval 測試案例（上架前品質閘門）

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "\"${CLAUDE_PLUGIN_ROOT}\"/bin/secret-scan --stdin-hook"
          }
        ]
      }
    ]
  }
}

💡 企業建議：資安類 plugin 應放在組織 marketplace，以 managed settings 的 enabledPlugins 強制啟用，並在上架前以 claude plugin eval 確認偵測率（見 2.4.4）。

2.4.7 Plugin 與其他機制的關係

graph TB
    subgraph "Plugin 生態系統"
        PL[Plugin] --> AG[Agents]
        PL --> SK[Skills]
        PL --> TL[bin/ 執行檔]
        PL --> MC[MCP Servers]
        PL --> PR[Hooks / Monitors]
        
        AG --> SK
        AG -->|使用| TL
        AG -->|使用| MC
        SK -->|參考| PR
    end
    
    subgraph "Claude Code 核心"
        CC[Claude Code] --> PL
        CC --> HK[Hooks]
        CC --> CF[CLAUDE.md]
        CC --> ST[Settings]
        
        HK -.- PL
        CF -.- PL
    end
    
    style PL fill:#6366f1,stroke:#4f46e5,color:#fff
    style CC fill:#10b981,stroke:#059669,color:#fff

2.5 Hooks（鉤子機制）

2.5.1 Hooks 系統概述

什麼是 Hooks？

Hooks 是 Claude Code 的事件驅動擴展機制。透過 Hooks，你可以在 Claude Code 執行流程的各個階段插入自訂邏輯（Shell 命令、HTTP Webhook、Prompt 注入或 Agent 處理），實現自動化的安全檢查、日誌記錄、通知、程式碼品質控制等工作流程。

Hooks 在 settings.json 中以宣告式 JSON 配置，不需要撰寫任何 TypeScript/JavaScript SDK 程式碼。

graph LR
    subgraph "Hook 執行流程"
        A[使用者輸入] --> B[UserPromptSubmit Hook]
        B --> C[Claude 處理]
        C --> D[PreToolUse Hook]
        D --> E{通過?}
        E -->|是| F[執行工具]
        E -->|否| G[攔截/修改]
        F --> H[PostToolUse Hook]
        H --> I[Stop Hook]
        I --> J[回傳結果]
    end
    
    style B fill:#f59e0b,stroke:#d97706
    style D fill:#f59e0b,stroke:#d97706
    style H fill:#10b981,stroke:#059669
    style I fill:#6366f1,stroke:#4f46e5,color:#fff

2.5.2 Hook 事件類型（33 種）

🆕 v3.5 更新：依官方 hooks 頁重新覆核，新增 DirectoryAdded、PreModelSwitch（v2.1.251+）、PostModelSwitch 三個事件，總計 33 種；並補上各事件 exit code 2 的實際行為（見本節末的速查表）。

Claude Code 支援 33 種 Hook 事件，涵蓋整個會話生命週期：

會話生命週期事件

使用者互動事件

工具執行事件

檔案與環境事件

Subagent 事件

Agent Teams 事件

📌 WorktreeCreate／WorktreeRemove 常被誤認為 Agent Teams 專屬事件，實際上它們是通用的 git worktree 生命週期事件，見下方「檔案與環境事件」——只要透過 --worktree、Subagent 的 isolation: worktree，或背景 session 建立/移除 worktree 就會觸發，與是否使用 Agent Teams 無關；Agent Teams 預設共用同一份工作目錄，並不會觸發它們。

Context 管理事件

🆕 模型切換事件

MCP 互動事件

🆕 Exit code 2 行為速查（v3.5 依官方覆核）

「能否阻擋」是設計 hook 時最容易誤判的地方。以下為官方定義：

2.5.3 Hook 類型（5 種）

🆕 v3.2 更新：新增 MCP Tool Hook（mcp_tool）類型，總計 5 種 Hook 類型

每個 Hook 可以配置為以下五種類型之一：

1. Command Hook（Shell 命令）

最常用的 Hook 類型，執行 Shell 命令。Hook 的 stdin 接收事件 JSON 資料，透過 exit code 和 stdout/stderr 回傳結果：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  }
}

📌 注意：Hook 命令透過 stdin 接收 JSON 格式的事件資料，使用 jq 解析欄位。exit code 0 表示無決定（正常流程繼續），exit code 2 表示阻止工具執行。

環境變數：Hook 命令可使用 Claude Code 注入的環境變數：

2. HTTP Hook（Webhook）

將事件資料以 POST 方式發送到 HTTP 端點，回應使用與 Command Hook 相同的 JSON 格式：

{
  "hooks": {
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "http",
            "url": "http://localhost:8080/hooks/tool-use",
            "headers": {
              "Authorization": "Bearer $MY_TOKEN"
            },
            "allowedEnvVars": ["MY_TOKEN"]
          }
        ]
      }
    ]
  }
}

🆕 allowedEnvVars 欄位可以指定哪些環境變數會在 header 值中展開。未列入的環境變數 $VAR 引用會保持為空值，確保敏感資訊不外洩。

3. MCP Tool Hook（MCP 工具呼叫）

🆕 v3.2 新增

呼叫已連接的 MCP Server 上的工具，適用於需要外部服務處理的 Hook 邏輯。欄位為 server（plugin 內建的 server 須寫成 plugin:<plugin>:<server>）、tool 與 input（字串值支援 ${tool_input.file_path} 這類替換；v3.5 更正：不是 arguments 與 {{ }}）。Server 未連線或工具回傳 isError: true 時，會產生非阻擋性錯誤：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "mcp_tool",
            "server": "code-quality",
            "tool": "analyze_file",
            "input": {
              "path": "${tool_input.file_path}"
            }
          }
        ]
      }
    ]
  }
}

4. Prompt Hook（LLM 單輪評估）

使用 Claude 模型（預設 Haiku）進行單輪 LLM 評估，做出 ok: true/false 判斷決策：

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Check if all tasks are complete. If not, respond with {\"ok\": false, \"reason\": \"what remains to be done\"}.",
            "model": "haiku"
          }
        ]
      }
    ]
  }
}

📌 行為說明：ok: false 時行為因事件而異 — Stop/SubagentStop 會將 reason 回饋給 Claude 使其繼續工作；PreToolUse 會拒絕工具呼叫。

5. Agent Hook（多輪代理驗證）⚠️ 實驗性

⚠️ 實驗性功能：Agent Hook 的行為和配置可能在未來版本中變更。正式環境建議優先使用 Command Hook。

委派給一個具備工具存取能力的子代理處理 Hook 邏輯，可讀取檔案、搜尋程式碼、執行命令後回傳判斷：

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "agent",
            "prompt": "Verify that all unit tests pass. Run the test suite and check the results. $ARGUMENTS",
            "timeout": 120
          }
        ]
      }
    ]
  }
}

📌 Agent Hook vs Prompt Hook：當 Hook 輸入資料本身就足以做出判斷時，使用 Prompt Hook；當需要對程式碼庫實際狀態進行驗證時，使用 Agent Hook。Agent Hook 預設 timeout 60 秒，最多 50 次工具呼叫。

Hook 類型 timeout 預設值摘要：

2.5.4 Hook 配置詳解

配置位置

Hooks 配置在 settings.json 中，支援多個層級：

Hook 來源（v3.5 更正：hooks 不是「覆寫」關係，而是所有來源的 hooks 都會註冊並平行執行）：
- ~/.claude/settings.json          所有專案（本機）
- .claude/settings.json            單一專案（可提交版控）
- .claude/settings.local.json      單一專案（不進版控）
- Managed policy settings          全組織（管理員控制；可用 allowManagedHooksOnly 只執行這一層）
- Plugin 的 hooks/hooks.json       plugin 啟用期間
- Skill frontmatter                Skill 被呼叫後的 session 剩餘時間
- Subagent frontmatter             該子代理執行期間

📌 停用所有 Hooks：在 settings.json 中設定 "disableAllHooks": true 可停用所有 Hooks。Managed settings 中的 Hooks 不受此設定影響，除非 disableAllHooks 也設定在 managed settings 中。

完整配置範例

🆕 v3.2 格式修正：Hooks 配置結構中，每個事件名稱下包含 Hook 群組陣列，每個群組含 matcher 和 hooks 子陣列。

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Reminder: use Bun, not npm. Run bun test before committing.'"
          }
        ]
      }
    ],
    
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/check-bash-safety.sh"
          }
        ]
      },
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-files.sh"
          }
        ]
      }
    ],
    
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ],
    
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "powershell -Command \"[System.Reflection.Assembly]::LoadWithPartialName('System.Windows.Forms'); [System.Windows.Forms.MessageBox]::Show('Claude Code needs your attention','Claude Code')\""
          }
        ]
      }
    ],
    
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "echo '[STOP] $(date)' >> .claude/session.log"
          }
        ]
      }
    ],
    
    "SessionEnd": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/hooks/cleanup.sh"
          }
        ]
      }
    ]
  }
}

⚠️ 結構注意：每個事件鍵值下是 群組陣列，每個群組可包含 matcher（選填）和 hooks（必填，Hook 定義陣列）。一個群組內的所有 hooks 共享同一個 matcher。

if 欄位 — 精細過濾工具名稱與參數

需要 Claude Code v2.1.85 或更新版本

if 欄位使用權限規則語法同時過濾工具名稱和參數，僅在匹配時才啟動 hook 進程：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "if": "Bash(git *)",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/check-git-policy.sh"
          }
        ]
      }
    ]
  }
}

📌 if 僅適用於工具事件：PreToolUse、PostToolUse、PostToolUseFailure、PermissionRequest、PermissionDenied。加在其他事件上會導致 hook 無法執行。

Matcher 語法

matcher 欄位用於過濾特定工具或條件，支援正規表達式：

📌 matcher 對非工具事件有不同的匹配欄位，詳見 2.5.2 各事件的「Matcher 匹配欄位」欄。

🆕 結構化 JSON 輸出（hookSpecificOutput）

Hook 命令可以輸出結構化 JSON 到 stdout（而非純文字），讓 Claude Code 進行程式化處理：

// Hook 輸出的 JSON 格式
{
  "hookSpecificOutput": {
    "permissionDecision": "allow"
  }
}

範例：自動化權限決策 Hook

#!/bin/bash
# auto-permission.sh — 根據規則自動決定權限
# Hook 資料透過 stdin 的 JSON 傳入（沒有 $CLAUDE_TOOL_NAME／$CLAUDE_FILE_PATH 環境變數）
INPUT=$(cat)
TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name')
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

# 對測試檔案自動允許
if echo "$FILE_PATH" | grep -qE '\.(test|spec)\.(ts|js)$'; then
  echo '{"hookSpecificOutput": {"hookEventName": "PreToolUse", "permissionDecision": "allow", "permissionDecisionReason": "測試檔案自動允許"}}'
  exit 0
fi

# 對 production 目錄檔案要求確認
if echo "$FILE_PATH" | grep -q '/prod/'; then
  echo '{"hookSpecificOutput": {"hookEventName": "PreToolUse", "permissionDecision": "ask", "permissionDecisionReason": "production 目錄需人工確認"}}'
  exit 0
fi

exit 0

🆕 updatedInput 輸入重寫

PreToolUse Hook 可以透過 updatedInput 欄位修改工具的輸入參數：

#!/bin/bash
# rewrite-path.sh — 自動修正檔案路徑
# updatedInput 必須放在 hookSpecificOutput 中，且會「整個取代」原輸入，未修改的欄位也要一併帶上
jq '{hookSpecificOutput: {hookEventName: "PreToolUse", permissionDecision: "allow",
     updatedInput: (.tool_input | .file_path |= sub("src/old/"; "src/new/"))}}'

🆕 CLAUDE_ENV_FILE 環境持久化

Hook 可以透過 CLAUDE_ENV_FILE 環境變數指向的檔案來設定持久環境變數，後續的 Hook 和工具呼叫都能讀取：

#!/bin/bash
# setup-env.sh — 在 SessionStart Hook 中設定持久環境
echo "PROJECT_VERSION=$(cat VERSION)" >> "$CLAUDE_ENV_FILE"
echo "BUILD_NUMBER=$(git rev-list --count HEAD)" >> "$CLAUDE_ENV_FILE"

🆕 stop_hook_active 防止無限迴圈

當 Hook 觸發的操作本身又可能觸發 Hook 時（如 PostToolUse Hook 呼叫了額外的工具），Claude Code 會自動設定 stop_hook_active 標記來防止無限遞迴。

🆕 FileChanged watchPaths 過濾

FileChanged 事件可以使用 watchPaths 限制只監聽特定路徑的檔案變更：

{
  "hooks": {
    "FileChanged": [
      {
        "watchPaths": ["src/**/*.ts", "src/**/*.tsx"],
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx eslint --fix 2>/dev/null || true"
          }
        ]
      },
      {
        "watchPaths": [".env", ".env.*"],
        "hooks": [
          {
            "type": "command",
            "command": "echo 'WARNING: 環境變數檔案已變更！' >&2"
          }
        ]
      }
    ]
  }
}

📌 watchPaths 使用 glob 語法，僅在匹配路徑的檔案變更時觸發 Hook。

2.5.5 實用 Hook 範例

範例一：自動程式碼格式化

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write 2>/dev/null || true"
          }
        ]
      }
    ]
  }
}

範例二：安全性 Bash 命令攔截

#!/bin/bash
# .claude/hooks/check-bash-safety.sh
# 從 stdin 讀取 JSON，檢查即將執行的 Bash 命令是否安全

COMMAND=$(jq -r '.tool_input.command' < /dev/stdin)

# 危險命令模式清單
DANGEROUS_PATTERNS=(
    "rm -rf /"
    "rm -rf ~"
    "mkfs"
    "dd if="
    "> /dev/sd"
    "chmod 777"
    "curl.*|.*sh"
    "wget.*|.*sh"
)

for pattern in "${DANGEROUS_PATTERNS[@]}"; do
    if echo "$COMMAND" | grep -qE "$pattern"; then
        echo "❌ BLOCKED: 偵測到潛在危險命令模式: $pattern" >&2
        exit 2  # exit 2 = 阻止工具執行
    fi
done

exit 0  # exit 0 = 無決定，正常流程繼續

範例三：變更時自動執行測試

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs -I{} sh -c 'echo \"$1\" | grep -qE \"\\.(ts|js)$\" && npm test -- --findRelatedTests \"$1\" 2>/dev/null || true' _ {}"
          }
        ]
      }
    ]
  }
}

範例四：Slack 通知整合

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "http",
            "url": "https://hooks.slack.com/services/T.../B.../xxx",
            "headers": {
              "Content-Type": "application/json"
            }
          }
        ]
      }
    ]
  }
}

範例五：使用 Prompt Hook 在 Stop 時驗證完成度

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Review the work done so far. Are all tasks complete? If not, respond with {\"ok\": false, \"reason\": \"what remains\"} to continue working."
          }
        ]
      }
    ]
  }
}

2.5.6 Hook 執行規則與最佳實踐

執行規則

flowchart TD
    E[事件觸發] --> M{有 matcher?}
    M -->|有| MC{matcher 匹配?}
    M -->|無| EX[執行 Hook]
    MC -->|匹配| IF{有 if 條件?}
    MC -->|不匹配| SK[跳過]
    IF -->|有且匹配| EX
    IF -->|有且不匹配| SK
    IF -->|無| EX
    
    EX --> T{Hook 類型}
    T -->|command| CMD[執行 Shell 命令]
    T -->|http| HTTP[發送 HTTP POST]
    T -->|mcp_tool| MCP[呼叫 MCP 工具]
    T -->|prompt| PRM[單輪 LLM 評估]
    T -->|agent| AGT[多輪代理驗證]
    
    CMD --> RC{退出碼}
    RC -->|0| NOOP[無決定 — 繼續]
    RC -->|2| BLK[❌ 阻止工具執行]
    RC -->|其他非 0| ERR[⚠️ Hook 錯誤]
    
    HTTP --> RESP[解析 JSON 回應]
    MCP --> RESP
    PRM --> DECISION{ok: true?}
    AGT --> DECISION
    DECISION -->|true| OK[✅ 允許]
    DECISION -->|false| BLK
    
    style E fill:#6366f1,stroke:#4f46e5,color:#fff
    style OK fill:#dcfce7,stroke:#22c55e
    style NOOP fill:#dcfce7,stroke:#22c55e
    style BLK fill:#fee2e2,stroke:#ef4444
    style ERR fill:#fef3c7,stroke:#f59e0b

關鍵規則：

⚠️ 注意事項

1. 效能影響：Hook 會增加每次操作的執行時間，避免在 Hook 中執行耗時操作
2. 非零退出碼：Command Hook 的退出碼在 PreToolUse 事件中有特殊意義——非零會阻止工具執行
3. 安全性：Hook 命令以使用者權限執行，需注意命令注入風險
4. 偵錯方式：使用日誌檔案記錄 Hook 執行情況，方便排查問題
5. 企業管控：組織管理員可透過 managed-settings.json 強制套用安全 Hooks

2.5.7 進階 Hook 架構模式

模式一：多層防禦（Defense in Depth）

建立多層 Hook 防禦機制，每層負責不同的安全檢查：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/hooks/layer1-blocklist.sh"
          },
          {
            "type": "command",
            "command": "bash .claude/hooks/layer2-path-check.sh"
          },
          {
            "type": "prompt",
            "prompt": "Layer 3: 執行此命令前，請確認不會影響生產環境資料或系統穩定性"
          }
        ]
      },
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/hooks/file-protection.sh"
          }
        ]
      }
    ]
  }
}

#!/bin/bash
# .claude/hooks/layer1-blocklist.sh — 第一層：命令黑名單

BLOCKLIST=(
  "rm -rf /"
  "rm -rf ~"
  "rm -rf \$HOME"
  "mkfs"
  "dd if=/dev"
  "> /dev/sd"
  "chmod -R 777 /"
  ":(){ :|:& };:"
)

INPUT=$(jq -r '.tool_input.command // empty')   # 從 stdin JSON 取出 Bash 命令
for pattern in "${BLOCKLIST[@]}"; do
  if echo "$INPUT" | grep -qF "$pattern"; then
    echo "BLOCK: 命令包含黑名單模式: $pattern" >&2
    exit 2
  fi
done
exit 0

#!/bin/bash
# .claude/hooks/layer2-path-check.sh — 第二層：路徑保護

PROTECTED_PATHS=(
  "/etc"
  "/usr"
  "/var/lib"
  "$HOME/.ssh"
  "$HOME/.aws"
  "$HOME/.kube"
)

INPUT=$(jq -r '.tool_input.command // empty')   # 從 stdin JSON 取出 Bash 命令
for path in "${PROTECTED_PATHS[@]}"; do
  if echo "$INPUT" | grep -q "$path"; then
    echo "BLOCK: 命令涉及受保護路徑: $path" >&2
    exit 2
  fi
done
exit 0

模式二：品質管道（Quality Pipeline）

在檔案修改後自動執行一系列品質檢查：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/hooks/quality-pipeline.sh"
          }
        ]
      }
    ]
  }
}

#!/bin/bash
# .claude/hooks/quality-pipeline.sh — 完整品質管道

FILE=$(jq -r '.tool_input.file_path // empty')   # 從 stdin JSON 取出檔案路徑
EXT="${FILE##*.}"
REPORT=""
PASS=true

# Stage 1: 格式化
case "$EXT" in
  ts|tsx|js|jsx)
    npx prettier --write "$FILE" 2>/dev/null
    RESULT=$(npx eslint "$FILE" 2>&1)
    if [ $? -ne 0 ]; then
      REPORT="$REPORT\n⚠️ ESLint: $(echo "$RESULT" | grep -c 'error') errors"
      npx eslint --fix "$FILE" 2>/dev/null
    fi
    ;;
  py)
    python -m black "$FILE" 2>/dev/null
    RESULT=$(python -m ruff check "$FILE" 2>&1)
    if [ $? -ne 0 ]; then
      REPORT="$REPORT\n⚠️ Ruff: $(echo "$RESULT" | wc -l) issues"
      python -m ruff check --fix "$FILE" 2>/dev/null
    fi
    ;;
  java)
    google-java-format --replace "$FILE" 2>/dev/null
    ;;
  go)
    gofmt -w "$FILE" 2>/dev/null
    RESULT=$(go vet "./$(dirname "$FILE")/..." 2>&1)
    if [ $? -ne 0 ]; then
      REPORT="$REPORT\n⚠️ Go vet: $(echo "$RESULT" | wc -l) issues"
    fi
    ;;
esac

# Stage 2: Type Checking (TypeScript/Java)
case "$EXT" in
  ts|tsx)
    RESULT=$(npx tsc --noEmit "$FILE" 2>&1)
    if [ $? -ne 0 ]; then
      REPORT="$REPORT\n❌ TypeScript: 型別錯誤"
      PASS=false
    fi
    ;;
esac

# Stage 3: 安全性快速掃描
if grep -qE "(eval\(|exec\(|__import__|subprocess\.call)" "$FILE" 2>/dev/null; then
  REPORT="$REPORT\n🔒 Security: 偵測到潛在危險函數呼叫"
fi

# 輸出報告
if [ -n "$REPORT" ]; then
  echo -e "📋 品質檢查報告 ($FILE):$REPORT"
fi

# 記錄到日誌
echo "[$(date -Iseconds)] Quality check: $FILE${REPORT:+ |$REPORT}" >> .claude/quality-log.txt

exit 0  # PostToolUse hook 不阻止操作

模式三：環境感知 Hook

根據執行環境（開發/測試/生產）自動調整 Hook 行為：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'ENV=${CLAUDE_ENV:-development}; if [ \"$ENV\" = \"production\" ]; then echo \"BLOCK: 生產環境禁止執行 Shell 命令\" >&2; exit 2; fi'"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'ENV=${CLAUDE_ENV:-development}; if [ \"$ENV\" = \"development\" ]; then jq -r .tool_input.file_path | xargs npx prettier --write 2>/dev/null; fi; if [ \"$ENV\" = \"staging\" ] || [ \"$ENV\" = \"production\" ]; then jq -r .tool_input.file_path | xargs npx eslint 2>&1 || true; fi'"
          }
        ]
      }
    ]
  }
}

Hook 架構比較

2.5.8 Hook 進階控制機制

🆕 v3.3 新增

PermissionRequest 的 updatedPermissions 與 setMode

PermissionRequest Hook 除了回傳 permissionDecision（allow/deny/ask）外，還可透過 updatedPermissions 和 setMode 精細控制權限行為：

⚠️ v3.5 更正：PermissionRequest 的決策放在 hookSpecificOutput.decision 物件中（behavior: "allow"|"deny"），不是 permissionDecision；updatedPermissions 是型別化的更新項目陣列，setMode 是其中一種項目，不是獨立欄位。PermissionRequest 以 exit 2 結束而沒有 decision 物件時，權限流程不變。

{
  "hookSpecificOutput": {
    "hookEventName": "PermissionRequest",
    "decision": {
      "behavior": "allow",
      "updatedPermissions": [
        {
          "type": "addRules",
          "rules": [{ "toolName": "Bash", "ruleContent": "npm test" }],
          "behavior": "allow",
          "destination": "session"
        },
        {
          "type": "setMode",
          "mode": "acceptEdits",
          "destination": "session"
        }
      ]
    }
  }
}

⚠️ 安全性考量：updatedPermissions 和 setMode 具有很高的權限控制能力。在企業環境中，建議僅在 managed-settings.json 的 Hooks 中使用，避免專案級 Hooks 擅自擴大權限範圍。

Stop Hook 阻擋上限機制

Stop／SubagentStop Hook 可以透過 exit 2、JSON decision: "block"，或 prompt hook 回傳 {"ok": false} 來阻止 Claude 停止工作。但為防止無限迴圈，系統設有連續阻擋上限（CLAUDE_CODE_STOP_HOOK_BLOCK_CAP），hook 也可從輸入的 stop_hook_active 判斷自己是否已處於阻擋迴圈中：

# 設定 Stop Hook 阻擋上限為 12 次
export CLAUDE_CODE_STOP_HOOK_BLOCK_CAP=12

# 或在 .env 中設定
echo "CLAUDE_CODE_STOP_HOOK_BLOCK_CAP=12" >> .env

📌 使用情境：結合 Stop Hook 的 Prompt 類型，可實現「完成度自動驗證」機制——Claude 每次嘗試停止時，Hook 會評估工作是否完整，若不完整則阻擋並附上原因。阻擋上限確保此機制不會陷入無限循環。

Exec Form（陣列形式命令）

Hook 的 command 支援 exec form，以 JSON 陣列形式指定命令和參數，避免 shell 解析帶來的安全風險：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "node",
            "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/format.js"]
          }
        ]
      }
    ]
  }
}

📌 Exec form 優點：直接執行二進位檔而不經過 shell，避免命令注入風險。適合在安全敏感的企業環境中使用。

2.5.9 非同步 Hook、一次性 Hook 與企業治理

🆕 v3.5 新增：補齊官方 hooks 頁中與企業部署直接相關、但 v3.4 未涵蓋的欄位與安全規則。

共通欄位補充

📌 所有符合的 hooks 平行執行；同一個 handler 定義在多個設定檔中只會執行一次（plugin 或 Skill 的副本則各自獨立）。

非同步 Hook（async: true）

長時間工作（部署、完整測試、呼叫外部 API）可以在背景執行，Claude 不必等待：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          { "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/scripts/run-tests.sh", "async": true }
        ]
      }
    ]
  }
}

• 非同步 hook 不能阻擋或控制 Claude；背景行程結束後，JSON 回應中的 additionalContext 與 systemMessage 會在下一輪送給 Claude（不顯示給你）
• 背景執行後不再強制 timeout（asyncRewake 例外；asyncRewake 以 exit 2 結束時會立即喚醒閒置中的 Claude）
• -p 模式結束時，仍在執行的非同步 hook 會被終止並標記為 cancelled；需要比 session 活得更久的工作請自行啟動完全分離的行程
• 每次觸發都是獨立行程，不會去重

Workspace trust：Hook 什麼時候會被執行

🔐 CI／自動化的關鍵風險：對不是你撰寫的 repo 執行 claude -p 前，請先審查它的 .claude/ 設定，或以 --bare 啟動，或以 --settings '{"disableAllHooks": true}' 關閉該次執行的 hooks。

企業治理設定

{
  "allowManagedHooksOnly": true,
  "allowedHttpHookUrls": ["https://audit.internal.example.com/*"],
  "httpHookAllowedEnvVars": ["AUDIT_TOKEN"],
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "http", "url": "https://audit.internal.example.com/claude/pre-tool", "headers": { "Authorization": "Bearer $AUDIT_TOKEN" }, "allowedEnvVars": ["AUDIT_TOKEN"] }
        ]
      }
    ]
  }
}

撰寫 Hook 的安全守則

• Command hook 以你的完整使用者權限執行，可存取、修改、刪除你能存取的任何檔案
• 驗證並清理 stdin 輸入，永遠不要盲目信任
• Shell 變數一律加引號（"$VAR"），並檢查路徑中的 .. 以防路徑穿越
• 腳本使用絕對路徑（"$CLAUDE_PROJECT_DIR"/scripts/...）
• 避免讀取 .env、.git/、金鑰等敏感檔案

2.6 MCP（Model Context Protocol）

🆕 v3.2 更新：streamable-http 取代 http 作為推薦 Transport 名稱、SSE 已標記為 deprecated、alwaysLoad 欄位、per-server timeout、workspace 保留名稱、OAuth authServerMetadataUrl/oauth.scopes、CLAUDE_PROJECT_DIR 環境變數注入

2.6.1 MCP 概述

什麼是 MCP？

Model Context Protocol (MCP) 是一個開放標準協議，定義了 AI 應用程式（如 Claude Code）與外部工具伺服器之間的通訊介面。透過 MCP，Claude Code 可以連接到各種外部服務（資料庫、API、雲端平台、DevOps 工具等），讓 AI 直接操作這些外部資源。

📌 重要澄清：MCP 不是 Claude Code 內部的上下文管理機制。它是一個外部工具整合協議，讓第三方開發者可以建立 MCP Server 來擴展 Claude Code 的能力。

graph TB
    subgraph "MCP 架構"
        CC[Claude Code<br>MCP Client] 
        
        CC <-->|MCP Protocol| S1[MCP Server<br>GitHub]
        CC <-->|MCP Protocol| S2[MCP Server<br>PostgreSQL]
        CC <-->|MCP Protocol| S3[MCP Server<br>Jira]
        CC <-->|MCP Protocol| S4[MCP Server<br>AWS]
        CC <-->|MCP Protocol| S5[MCP Server<br>自訂服務]
        
        S1 --> T1[建立 PR / 搜尋 Issues]
        S2 --> T2[查詢資料 / 執行 SQL]
        S3 --> T3[建立工單 / 更新狀態]
        S4 --> T4[部署 / 監控]
        S5 --> T5[任意自訂功能]
    end
    
    style CC fill:#6366f1,stroke:#4f46e5,color:#fff
    style S1 fill:#dbeafe,stroke:#3b82f6
    style S2 fill:#dcfce7,stroke:#22c55e
    style S3 fill:#fef3c7,stroke:#f59e0b
    style S4 fill:#fce7f3,stroke:#ec4899
    style S5 fill:#f3e8ff,stroke:#a855f7

MCP 核心概念

2.6.2 配置 MCP Server

.mcp.json 配置檔

MCP Server 透過專案根目錄的 .mcp.json 檔案配置：

🆕 v3.0 更新：支援環境變數預設值語法 ${VAR:-default}、三層配置範圍

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "Authorization": "Bearer ${GITHUB_TOKEN}"
      }
    },
    
    "postgres": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@bytebase/dbhub", "--dsn", "${DATABASE_URL:-postgresql://localhost:5432/devdb}"]
    },
    
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/dir"]
    },
    
    "custom-api": {
      "type": "sse",
      "url": "https://mcp.company.internal/api/sse",
      "headers": {
        "Authorization": "Bearer ${API_TOKEN}"
      }
    }
  }
}

📌 環境變數語法：🆕 支援 ${VAR} 和 ${VAR:-default} 兩種格式。後者在環境變數未設定時使用預設值。

🆕 MCP 配置範圍（Scope）

🆕 v3.5 依官方 mcp 頁更正：可由使用者設定的範圍只有 Local／Project／User 三種；Plugin 與 claude.ai connectors 是另外的來源；組織以 managedMcpServers 提供的 server 優先順序高於以上全部。

優先順序：（組織 managedMcpServers）> Local > Project > User > Plugin-provided > claude.ai connectors。同一 server 只連線一次，採用最高優先來源的完整定義（欄位不跨範圍合併）；三種範圍依名稱判定重複，plugin 與 connectors 則依端點（URL 或命令）判定。

📌 workspace 保留名稱（🆕 v3.2）：MCP Server 名稱 workspace 是保留名稱，Claude Code 內部使用。請勿將自訂 MCP Server 命名為 workspace。

Transport 類型比較

⚠️ SSE 已標記為 deprecated：新專案請使用 http。對只提供 SSE 端點的服務，claude mcp add --transport http 會先嘗試 HTTP、失敗再自動改用 SSE。

⚠️ JSON 中有 url 卻沒有 type 的項目是設定錯誤（會被當成 stdio 而略過），請明確寫 "type": "http"。

使用 claude mcp 命令管理 MCP Server

⚠️ v3.5 更正：在 CLI 中，新增、列出、移除 server 是在 shell 執行的 claude mcp 子命令（VS Code 擴充功能則可在 /mcp 對話框中新增）；CLI session 內的 /mcp 是檢視狀態、驗證、啟用／停用的互動面板，只接受 reconnect <server>、enable／disable [<server>|all] 等參數，不接受 /mcp add、/mcp list。

# 遠端 HTTP server（推薦）；--scope 可為 local（預設）、project、user
claude mcp add --transport http notion https://mcp.notion.com/mcp
claude mcp add --transport http github https://api.githubcopilot.com/mcp/   --header "Authorization: Bearer YOUR_GITHUB_PAT" --scope project

# 本機 stdio server（-- 之後是啟動命令）
claude mcp add --transport stdio db -- npx -y @bytebase/dbhub --dsn "postgresql://..."

# 以 JSON 新增（適合 ws 或複雜設定）
claude mcp add-json events-server '{"type":"ws","url":"wss://mcp.example.com/socket"}'

# 管理
claude mcp list                 # 列出並顯示健康狀態（✔ Connected／! Needs authentication／✘ Failed）
claude mcp get notion
claude mcp remove notion        # 同時刪除該 server 的 OAuth token
claude mcp login sentry         # 🆕 在 shell 直接跑 OAuth（v2.1.186+）；無瀏覽器時加 --no-browser
claude mcp logout sentry

# session 內：查看狀態、驗證、停用或重新連線
> /mcp
> /mcp reconnect github
> /mcp disable all

# 重設專案 .mcp.json server 的核准選擇（shell）
claude mcp reset-project-choices

🆕 進階 MCP Server 配置欄位

{
  "mcpServers": {
    "critical-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@company/mcp-server-core"],
      "alwaysLoad": true,
      "timeout": 30000,
      "env": {
        "PROJECT_DIR": "${CLAUDE_PROJECT_DIR}"
      }
    }
  }
}

📌 MCP server 也可以在個別工具的 _meta 中加入 "anthropic/alwaysLoad": true，只讓該工具始終載入。設定 alwaysLoad 會讓啟動等待該 server 的工具（上限為標準的 5 秒連線逾時），請只用於真正每次都需要的 server。

2.6.3 工具搜尋（Tool Search）

當配置了多個 MCP Server 且工具數量很多時，Claude Code 使用 Tool Search 機制來有效率地找到正確的工具：

sequenceDiagram
    participant U as 使用者
    participant CC as Claude Code
    participant TS as Tool Search
    participant S1 as MCP Server 1
    participant S2 as MCP Server 2

    U->>CC: "查詢上個月的銷售數據"
    CC->>TS: 搜尋相關工具
    TS->>TS: 語義匹配工具描述
    TS-->>CC: 匹配結果: postgres.query_database
    CC->>S1: 呼叫 query_database
    S1-->>CC: 查詢結果
    CC->>U: 回傳分析結果

Tool Search 的工作方式：

• Session 開始時只載入各 MCP server 的工具名稱與 server instructions，完整的工具定義（schema）延遲載入
• Claude 需要某個工具時，呼叫內建的 ToolSearch 工具搜尋並載入其定義
• 支援跨多個 MCP Server 的工具搜尋；Claude Code 不對每個 server 設工具數量上限
• 以 /mcp 查看各 server 與工具，以 /context 查看 MCP 實際佔用的 context（v3.5 更正：沒有 /tools 命令）

🆕 Tool Search 模式

Tool Search 預設開啟：session 開始時只載入工具名稱與 server instructions，完整定義在 Claude 需要時才經 ToolSearch 載入，因此多加 MCP server 對 context 的影響很小。以 ENABLE_TOOL_SEARCH 調整：

# 經由 LLM gateway 但確認 gateway 會轉送 tool_reference 時，明確開啟
export ENABLE_TOOL_SEARCH=true

# 自訂 5% 門檻
ENABLE_TOOL_SEARCH=auto:5 claude

⚠️ v3.5 更正：v3.4 所述「auto 為推薦值、工具少於 50 個時全部載入」不正確，預設（未設定）就是全部延遲載入，auto 是以 context 佔比判斷。設定 CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS 會強制關閉 Tool Search；企業可透過 managed settings 保持開啟（v2.1.227+）。Server 作者須注意：每個工具描述與 server instructions 預設在 2,048 字元截斷（CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH 可調，v2.1.280+），重要資訊請放在前面。

🆕 MCP Resources（資源引用）

MCP Server 可以暴露 Resources（靜態資源），使用者可以透過 @ 提及將資源加入 context：

# 在 VS Code 中使用 @ 引用 MCP 資源
@mcp:postgres/schema/users      → 引用 users 表的 schema 定義
@mcp:confluence/page/12345      → 引用 Confluence 頁面內容
@mcp:github/file/src/README.md  → 引用 GitHub 上的檔案

# 在 CLI 中使用
> 幫我分析 @mcp:postgres/schema/orders 這個表的效能問題

🆕 MAX_MCP_OUTPUT_TOKENS

控制單次 MCP 工具呼叫的最大輸出量，避免過大的回應佔滿 context：

# 預設 25,000 tokens，超過 10,000 tokens 會顯示警告
export MAX_MCP_OUTPUT_TOKENS=25000

🆕 Claude Code 作為 MCP Server

Claude Code 本身可以作為 MCP Server 被其他工具呼叫：

# 啟動 Claude Code 作為 MCP Server
claude mcp serve

# 其他 MCP Client 可以連接到 Claude Code 的 stdio
# 使用 Claude Code 的所有工具（Read, Edit, Bash 等）

2.6.4 MCP 認證

OAuth 2.0 認證

⚠️ v3.5 更正：MCP 的 OAuth 設定只有 oauth 物件，v3.4 範例中的 auth 物件（type: oauth2、authorizationUrl、tokenUrl 等）不是官方格式；Claude Code 會依 MCP 規範自動探索授權伺服器，通常不需要任何 OAuth 設定，只要在 /mcp 或 claude mcp login <name> 完成瀏覽器登入即可。

需要自訂時，可用的欄位如下：

{
  "mcpServers": {
    "company-mcp": {
      "type": "http",
      "url": "https://mcp.company.com/mcp",
      "oauth": {
        "clientId": "claude-code-client",
        "callbackPort": 8080,
        "authServerMetadataUrl": "https://auth.company.com/.well-known/openid-configuration",
        "scopes": "mcp:read mcp:write"
      }
    }
  }
}

# 以命令列加入並設定 OAuth client（secret 以遮罩方式輸入）
claude mcp add --transport http company-mcp https://mcp.company.com/mcp   --client-id claude-code-client --client-secret --callback-port 8080

環境變數安全

最佳做法是使用環境變數管理敏感資訊：

{
  "mcpServers": {
    "database": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "${DB_CONNECTION_STRING}"
      }
    }
  }
}

📌 安全提示：永遠不要在 .mcp.json 中硬編碼 API keys 或密碼。使用 ${ENV_VAR} 語法引用環境變數。

headersHelper 動態認證

🆕 v3.0 新增：headersHelper 允許在每次請求時動態產生認證 header（例如短期 token）：

{
  "mcpServers": {
    "internal-api": {
      "type": "http",
      "url": "https://mcp.company.internal/api",
      "headersHelper": "node ./scripts/get-auth-header.js"
    }
  }
}

headersHelper 指定的命令會在連線時執行（非每次呼叫），stdout 輸出 JSON 格式的 headers 並與 headers 合併；適用於 Kerberos、短期 token、內部 SSO 等非 OAuth 認證。它也適用於 ws 類型的 server。

Elicitation（互動式確認）

🆕 MCP Server 可以透過 Elicitation 向使用者發起互動式確認請求：

MCP Server 回傳 elicitation 請求
  → Claude Code 顯示問題給使用者
  → 使用者回答
  → 回傳給 MCP Server 繼續處理

例如：資料庫 MCP Server 在執行 DELETE 語句前，可以透過 elicitation 要求使用者確認。

MCP Prompts（命令式提示）

🆕 MCP Server 可以暴露 Prompts 作為可呼叫的命令。在 Claude Code 中，MCP Prompts 會自動轉換為斜線命令：

# 輸入 / 即可看到 MCP prompts，列為 /<server>:<prompt> (MCP)
> /github:create-pr-description

# 也可輸入完整形式
> /mcp__github__list_prs

# 參數以空白分隔傳入（每個參數是一個 token）
> /mcp__github__pr_review 456

📌 MCP Prompts 和自訂 Skills 的差異：MCP Prompts 由 MCP Server 端定義並動態載入，Skills 是本地的 SKILL.md 檔案。兩者都以斜線命令形式呈現給使用者。

2.6.5 企業級 MCP 管理

⚠️ v3.5 依官方 managed-mcp 頁全面改寫：v3.4 範例中 managed-mcp.json 內的 policy 物件（allowUserMcpServers、allowlist、denylist、requiredServers）以及 serverName:pattern 字串語法皆不存在。官方機制分為三個：managed-mcp.json（獨佔式固定清單）、managedMcpServers（提供 server 但不獨佔）、allowedMcpServers／deniedMcpServers（允許／封鎖清單，寫在 managed settings）。

選擇管控模式

📌 Claude Code 沒有內建可瀏覽的 MCP registry。採用「核准目錄」模式時，請把核准清單與對應的 claude mcp add 命令放在內部 wiki，或包成內部 plugin 發佈。

managed-mcp.json：獨佔式固定清單

部署在系統目錄（macOS /Library/Application Support/ClaudeCode/、Linux／WSL /etc/claude-code/、Windows C:\Program Files\ClaudeCode\），格式與專案 .mcp.json 相同。它是獨立檔案，無法透過 server-managed settings 發送，需以 Jamf、Intune、Group Policy 等 MDM 工具部署：

{
  "mcpServers": {
    "github": { "type": "http", "url": "https://api.githubcopilot.com/mcp/" },
    "sentry": { "type": "http", "url": "https://mcp.sentry.dev/mcp" },
    "company-internal": {
      "type": "stdio",
      "command": "/usr/local/bin/company-mcp-server",
      "args": ["--config", "/etc/company/mcp-config.json"],
      "env": { "COMPANY_API_URL": "https://internal.example.com" }
    }
  }
}

部署後，使用者不能新增、修改或使用任何其他 MCP server，包含 plugin 提供的 server 與 --mcp-config 傳入的 server；也會停用 Claude Code 自行抓取的 claude.ai connectors（除非設定 allowAllClaudeAiMcps）。

managedMcpServers：提供 server 但不獨佔

{
  "managedMcpServers": {
    "search": { "type": "http", "url": "https://search.example.com/mcp" },
    "records": {
      "type": "http",
      "url": "https://records.example.com/mcp",
      "headers": { "X-Records-Key": "key-issued-for-all-claude-code-users" }
    }
  }
}

⚠️ 能讀取該機器 managed settings 的人（包含使用者本人）都看得到這裡的 header 值，只能放發給整個使用者群體的憑證；個人憑證請讓使用者以 OAuth 自行登入。

allowedMcpServers／deniedMcpServers：允許與封鎖清單

每個項目是只含一個 key 的物件：

{
  "allowManagedMcpServersOnly": true,
  "allowedMcpServers": [
    { "serverUrl": "https://api.githubcopilot.com/*" },
    { "serverUrl": "https://*.internal.example.com/*" },
    { "serverCommand": ["npx", "-y", "@modelcontextprotocol/server-filesystem", "."] }
  ],
  "deniedMcpServers": [
    { "serverUrl": "https://*.untrusted.example.com/*" },
    { "serverCommand": ["npx", "-y", "unapproved-package"] },
    { "serverName": "claude.ai Slack" }
  ]
}

評估順序：（1）合併所有層級的清單（allowManagedMcpServersOnly: true 時只採用 managed 的允許清單；封鎖清單永遠跨層合併）→（2）封鎖清單命中即封鎖，沒有任何例外 →（3）有設定允許清單時，server 必須符合。一旦允許清單中出現任何 serverUrl，所有遠端 server 都必須符合 URL；出現任何 serverCommand，所有 stdio server 都必須符合命令。組織自己的 managedMcpServers 與未使用 ${VAR} 展開的 managed-mcp.json 項目可略過允許清單檢查。

🔐 三個常見陷阱：（1）serverName 是使用者自己取的名字，任何 server 都能被命名為 github，不能拿來當允許條件；（2）沒有 allowManagedMcpServersOnly 時，使用者可在自己的 ~/.claude/settings.json 擴充允許清單；（3）allowManagedPermissionRulesOnly 只鎖權限規則，不會強制 MCP 允許清單。要關閉 Claude Code 自行抓取的所有 claude.ai connectors，使用 disableClaudeAiConnectors。

2.6.6 常見 MCP Server 推薦

⚠️ v3.5 更正：v3.4 表格中的 @anthropic/mcp-server-* 系列套件並不存在，直接照抄會安裝失敗，甚至可能安裝到搶註的惡意套件。以下改列官方文件範例與各服務商自行維護的端點；實際網址請以服務商文件為準，並在納入允許清單前完成安全評估。

📌 從其他工具的設定搬過來：官方支援把寫給其他 MCP client 的設定轉入（見 mcp 頁「Add a server from setup instructions written for another client」），也可用 claude mcp add-from-claude-desktop 匯入 Claude Desktop 的 server。

📖 官方的 server 探索入口：Anthropic Directory（claude.ai/directory）與 MCP 官方 registry；完整說明請參考 code.claude.com/docs/en/mcp。

2.6.7 自行開發 MCP Server

MCP Server 開發核心步驟：

graph LR
    subgraph "MCP Server 開發流程"
        S1[選擇 SDK] --> S2[定義 Tools]
        S2 --> S3[實作邏輯]
        S3 --> S4[選擇 Transport]
        S4 --> S5[測試]
        S5 --> S6[部署]
    end
    
    S1 -.- N1["TypeScript SDK<br>Python SDK"]
    S4 -.- N4["stdio / SSE /<br>Streamable HTTP"]
    S6 -.- N6["npm publish /<br>Docker / 雲端"]
    
    style S1 fill:#dbeafe,stroke:#3b82f6
    style S5 fill:#fef3c7,stroke:#f59e0b
    style S6 fill:#dcfce7,stroke:#22c55e

TypeScript MCP Server 範例

// my-mcp-server/src/index.ts
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const server = new McpServer({
  name: "company-internal-tools",
  version: "1.0.0",
});

// 定義工具：查詢公司內部 Wiki
server.tool(
  "search_wiki",
  "搜尋公司內部 Wiki 文件",
  {
    query: z.string().describe("搜尋關鍵字"),
    limit: z.number().optional().default(5).describe("最多返回幾筆"),
  },
  async ({ query, limit }) => {
    const results = await searchInternalWiki(query, limit);
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(results, null, 2),
        },
      ],
    };
  }
);

// 定義工具：查詢部署狀態
server.tool(
  "deployment_status",
  "查詢應用程式的部署狀態",
  {
    app_name: z.string().describe("應用程式名稱"),
    environment: z.enum(["dev", "staging", "production"]).describe("環境"),
  },
  async ({ app_name, environment }) => {
    const status = await getDeploymentStatus(app_name, environment);
    return {
      content: [
        {
          type: "text",
          text: `${app_name} (${environment}): ${status.state}\n` +
                `版本: ${status.version}\n` +
                `上次部署: ${status.lastDeployed}`,
        },
      ],
    };
  }
);

// 啟動 Server
const transport = new StdioServerTransport();
await server.connect(transport);

在 Claude Code 中使用自訂 MCP Server

// .mcp.json
{
  "mcpServers": {
    "company-tools": {
      "command": "node",
      "args": ["./my-mcp-server/dist/index.js"],
      "env": {
        "WIKI_API_KEY": "${WIKI_API_KEY}",
        "DEPLOY_API_URL": "https://deploy.company.internal"
      }
    }
  }
}

2.6.8 MCP 進階機制

🆕 list_changed 動態工具更新

MCP Server 可以透過 list_changed 通知，在 runtime 動態新增或移除工具。Claude Code 收到此通知後，會自動重新讀取該 Server 的工具清單，無需重新連線：

MCP Server → 發送 notifications/tools/list_changed
Claude Code → 重新呼叫 tools/list
Claude Code → 更新可用工具列表

這在「依據使用者角色動態載入工具」或「根據專案類型調整工具集」的場景中非常有用。

🆕 anthropic/maxResultSizeChars 工具標註

MCP Server 的工具可以使用 annotations 欄位宣告 anthropic/maxResultSizeChars，告知 Claude Code 此工具預期的最大回傳字元數：

{
  "name": "query_database",
  "description": "執行 SQL 查詢",
  "annotations": {
    "anthropic/maxResultSizeChars": 50000
  }
}

📌 如果工具實際回傳超過此限制，Claude Code 會自動截斷。另可透過環境變數 MAX_MCP_OUTPUT_TOKENS（預設 25000）全域控制。

🆕 OAuth 固定回呼端口

遠端 MCP Server 使用 OAuth 認證時，Claude Code 支援固定回呼端口，避免每次認證使用隨機端口（適用於企業防火牆環境需要白名單的場景）。

🆕 Plugin 提供的 MCP Server

Plugins（.claude-plugin/）可以包含內建的 MCP Server 配置。安裝 Plugin 後，其定義的 MCP Server 會自動註冊到 Claude Code 中，無需手動在 .mcp.json 中配置。

🆕 MCP 工具自動背景化（v2.1.213）

長時間執行的 MCP 工具呼叫（例如觸發一個耗時的資料匯出、長時間查詢）預設在執行超過 2 分鐘後會自動轉為背景執行，讓 Claude 可以繼續處理其他工作，等結果就緒時再回來讀取，不會整個工作階段被單一 MCP 工具呼叫卡住：

# 調整自動轉背景的時間門檻（毫秒）
export CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS=300000   # 改為 5 分鐘

2.6.9 MCP 除錯與疑難排解

常見問題

除錯命令

# 啟動 debug 模式並過濾 MCP 相關訊息
claude --debug=mcp

# 互動模式中查看 MCP 狀態
/mcp

# 手動測試 MCP Server 啟動
npx -y @modelcontextprotocol/server-github 2>&1

# 檢查 MCP Server 日誌
cat ~/.claude/logs/mcp-*.log

⚠️ MCP 安全注意事項

1. 安全性：MCP Server 有權限執行外部操作（查詢資料庫、呼叫 API 等），安裝前需審查其權限範圍
2. Token 消耗：每個 MCP Server 的工具描述會佔用 context token，過多的 MCP Server 會影響可用 context
3. 網路依賴：SSE/HTTP Transport 的 MCP Server 需要網路連線，確保在使用環境中可達
4. 版本相容：確認 MCP Server 版本與 Claude Code 版本相容
5. 企業合規：在企業環境中透過 managed-mcp.json 統一管理，避免員工任意連接不受控的外部服務
6. 避免 Prompt Injection：MCP Server 返回的資料可能包含惡意注入內容，注意工具的輸入驗證

2.6.10 MCP 2026-07-28 協定、claude.ai Connectors 與新增控制

🆕 v3.5 新增：依官方 mcp 頁（基準 v2.1.281）整理 2026 下半年的 MCP 變動。

兩種 MCP client runtime

v2 runtime 的行為差異：

• 詢問 HTTP server 是否支援新協定，支援者就使用新版；以持續開啟的串流接收 list_changed 通知
• OAuth 授權回應的 issuer 不符預期時，登入直接失敗（防止授權伺服器混淆攻擊）
• 以新協定連線的 channel server 不會被註冊（新協定無法承載 channel 訊息）
• 手動選擇：MCP_SDK_GENERATION=v1|v2；是否協商新協定：MCP_PROTOCOL_NEGOTIATION=auto|legacy

⚠️ 企業影響：自建 channel 或舊版內部 MCP server 若在升級後失效，先檢查是否因 v2 runtime 協商到新協定；可暫時以 MCP_PROTOCOL_NEGOTIATION=legacy 排除，但應安排 server 升級。

claude.ai Connectors

以 claude.ai 訂閱登入時，你在 claude.ai 加入的 connectors 會自動出現在 /mcp（Team／Enterprise 只有管理員能新增）。以下情況不會載入 connectors：ANTHROPIC_API_KEY／ANTHROPIC_AUTH_TOKEN／apiKeyHelper 認證、第三方供應商、Anthropic profile／federation 憑證、CLAUDE_CODE_OAUTH_TOKEN。看不到 connector 時先用 /status 確認認證方式。組織可用 disableClaudeAiConnectors 全面關閉，或以 deniedMcpServers 的 serverName（顯示名稱，如 "claude.ai Slack"）個別封鎖。

強制每次都要人工核准的工具

MCP server 作者可在 tools/list 的工具項目設定 _meta["anthropic/requiresUserInteraction"]: true（v2.1.199+）。該工具每次呼叫都會詢問，即使在 acceptEdits、auto、bypassPermissions 模式也一樣，且不提供「不再詢問」；Remote Control 與 Agent SDK 的一鍵核准也會被停用。適用於授權、同意這類「核准本身就是重點」的工具。

Elicitation 的兩種模式

輸出上限與大型結果

• 單一工具輸出超過 10,000 tokens 時顯示警告；預設上限 25,000 tokens（MAX_MCP_OUTPUT_TOKENS 可調）
• 工具可用 anthropic/maxResultSizeChars 宣告自己的上限，此時不受環境變數影響
• 超過上限且不含圖片的結果會存成檔案，對話中改以檔案路徑取代，Claude 需要時再讀取

企業導入檢核要點

• 選定 MCP 管控模式（固定部署／提供 server／核准目錄），並以 allowManagedMcpServersOnly 鎖定允許清單
• 允許清單只使用 serverUrl／serverCommand，不使用 serverName
• 決定是否允許 claude.ai connectors（disableClaudeAiConnectors）
• 經由 LLM gateway 部署時，確認 Tool Search 是否可用（gateway 是否轉送 tool_reference）
• 內部 MCP server 升級至支援 2026-07-28 協定，並驗證 OAuth issuer 設定
• 以 OpenTelemetry 監控實際使用的 MCP server（見官方 managed-mcp 頁「Monitor MCP usage」）

2.7 Output Styles（輸出風格）

2.7.1 Output Styles 概述

🆕 v3.0 更新：全新的 Output Styles 系統，支援內建風格、自訂 .md 風格檔案

Output Styles 讓你可以自訂 Claude Code 的回應格式和風格。透過內建風格、自訂風格檔案或 CLAUDE.md 設定，控制回應的詳細程度、語氣、格式偏好等特性。

內建輸出風格

🆕 v3.5 更新：除了 Default（不套用任何風格指示）之外，官方目前有 4 種內建風格；v2.1.234 新增 Concise：

📌 v3.5 更正：自 v2.1.251 起，會話中切換風格會從下一則訊息開始生效，不再需要 /clear 或開新會話（切換後的第一則訊息會重建 prompt cache）。但在終端機中，風格檔案是啟動時讀取的，執行中新增或修改自訂風格檔需重新啟動。

🆕 快速切換：/output-style <風格>（如 /output-style concise，v2.1.269+）、/config 選單，或 VS Code 命令選單的 Output styles。選擇後的偏好自動儲存至 .claude/settings.local.json（不進 Git）。

自訂輸出風格檔案

🆕 自訂風格使用 .md 檔案定義，可放在三個層級：使用者 ~/.claude/output-styles/、專案 .claude/output-styles/（從工作目錄往上到 repo 根目錄，同名時取最近者），以及 managed settings 目錄下的 .claude/output-styles/（組織強制）；Plugin 也可在 output-styles/ 提供。檔名即風格名稱（除非 frontmatter 設定 name）：

<!-- ~/.claude/output-styles/enterprise-report.md -->
---
name: enterprise-report
description: 企業報告風格，正式語氣、結構化輸出
keep-coding-instructions: true
---

## 輸出規範
- 使用正式中文語氣
- 每次回應以「摘要」開始
- 使用表格呈現結構化資訊
- 程式碼區塊附帶語言標記
- 變更清單使用勾選框格式

自訂風格 frontmatter 欄位：

⚠️ 常見誤區修正：keep-coding-instructions 預設是 關閉，不是原文誤植的「預設 true」——若你的自訂風格沒有明確設 true，Claude 會完全跳脫工程師身分（適合寫作助理、資料分析等非開發情境），這通常不是多數團隊想要的行為，請依需求明確指定。

2.7.2 配置 Output Styles

透過 settings.json 設定

outputStyle 是唯一對應的設定欄位，值為內建風格名稱（"Proactive"／"Concise"／"Explanatory"／"Learning"）或自訂風格的 name。⚠️ 值區分大小寫：寫成 explanatory 會退回 Default（/output-style 指令則不分大小寫）。要跨專案預設某風格，寫在 ~/.claude/settings.json：

{
  "outputStyle": "Explanatory"
}

⚠️ 修正：Output Style 只負責語氣／角色／輸出格式，不是用來設定「使用繁體中文」「程式碼註解用英文」這類專案慣例的地方——這類偏好請寫進 CLAUDE.md（見下方），不存在文件中曾提及的 outputPreferences（codeComments／explanationLevel／language）設定物件。

透過 CLAUDE.md 設定專案慣例

# CLAUDE.md 中的輸出偏好（非 Output Style，屬於一般指引）

## 輸出偏好
- 回應請使用繁體中文
- 程式碼註解使用英文
- 優先展示程式碼，解釋放在後面
- 變更摘要使用表格格式
- 每次修改後列出受影響的檔案清單

即時切換

# 直接切換（不分大小寫；不帶參數會列出可選風格並標示目前使用中）
> /output-style concise

# 或從選單選擇
> /config

🆕 v3.5 更正：/output-style 指令已恢復。此指令曾在 v2.1.73 棄用、之後移除，但 v2.1.269 重新加入為 /output-style [style]，可列出與切換風格，且可在非互動模式、Agent SDK、雲端 session 與 Remote Control（僅內建風格）中使用。Desktop App 沒有終端機選單，請直接在設定檔寫 outputStyle。

2.7.3 自訂輸出範本

你可以在 CLAUDE.md 中定義自訂的輸出範本，讓 Claude Code 在特定場景下使用固定格式：

## 程式碼生成輸出格式

生成程式碼時，請遵循以下格式：

1. **摘要**：一行說明這次變更做了什麼
2. **檔案清單**：列出所有修改的檔案
3. **程式碼**：展示變更的程式碼
4. **驗證**：說明如何驗證變更是否正確

## Code Review 輸出格式

進行程式碼審查時，請使用以下格式：

| 嚴重度 | 位置 | 問題描述 | 建議修復 |
|--------|------|---------|---------|
| 🔴 高 | 檔案:行號 | 描述 | 修復方式 |
| 🟡 中 | 檔案:行號 | 描述 | 修復方式 |
| 🟢 低 | 檔案:行號 | 描述 | 修復方式 |

2.7.4 場景化輸出風格

不同開發情境適合不同的輸出風格組合，以下是常見場景的建議配置：

PR Review 專用風格

# CLAUDE.md — PR Review 輸出風格

## 輸出偏好（PR Review 模式）
- 先列出整體評估摘要（一段話）
- 使用表格列出所有問題，按嚴重度排序
- 對每個問題提供「修正前 vs 修正後」的對比程式碼
- 最後給出「Approve / Request Changes / Comment」建議
- 統計數據：新增行數、刪除行數、影響的模組

## 嚴重度分類
| 等級 | 定義 | 是否阻擋合併 |
|------|------|-------------|
| 🔴 Critical | 安全漏洞、資料遺失風險 | 是 |
| 🟠 High | 效能問題、邏輯錯誤 | 是 |
| 🟡 Medium | 程式風格、可讀性 | 否 |
| 🟢 Low | 建議改善、最佳實踐 | 否 |

除錯專用風格

# CLAUDE.md — 除錯模式輸出風格

## 輸出偏好（除錯模式）
- 先重現問題：列出錯誤訊息和 stack trace
- 分析根本原因（Root Cause Analysis）
- 列出可能的原因（機率從高到低）
- 每個可能原因提供：
  1. 驗證方法（如何確認是否為此原因）
  2. 修復方案
  3. 預防措施
- 使用流程圖展示除錯步驟

文件撰寫專用風格

# CLAUDE.md — 文件撰寫輸出風格

## 輸出偏好（文件撰寫模式）
- 使用正式語氣
- 包含目的、適用對象、前置條件
- 步驟使用有序列表，每步搭配截圖說明佔位符
- 重要注意事項使用 admonition 格式（> **⚠️ 注意**）
- 所有專有名詞第一次出現時附英文原名
- 末尾包含 FAQ 和相關文件連結

2.7.5 Output Styles 覆寫機制

⚠️ 修正核心觀念：Output Style 只有 一個 設定來源——settings.json 的 outputStyle 欄位，依一般 settings 優先順序（Managed > CLI 參數 > Local > Project > User，v3.5 更正原文順序）解析；例外是 Plugin 風格設定 force-for-plugin: true 時會覆蓋使用者的 outputStyle，沒有獨立的「即時指令 > CLAUDE.md > settings.json > 系統預設」四層覆寫鏈，也沒有 CLAUDE.md 中的 outputPreferences 設定——CLAUDE.md 與 Output Style 是兩個平行機制，不是誰覆寫誰：

graph TB
    subgraph "outputStyle 設定解析順序（由高到低，與一般 settings 相同）"
        L4["Managed Policy（企業強制）"]
        L0["CLI 參數 / --settings"]
        L1["Local: .claude/settings.local.json"]
        L2["Project: .claude/settings.json"]
        L3["User: ~/.claude/settings.json"]
    end

    L4 --> L0 --> L1 --> L2 --> L3

    style L4 fill:#fee2e2,stroke:#ef4444
    style L1 fill:#fef3c7,stroke:#f59e0b
    style L2 fill:#dbeafe,stroke:#3b82f6
    style L3 fill:#f3f4f6,stroke:#9ca3af

2.7.6 與 Agent/Skill 結合

⚠️ v3.5 更正：Subagent 與 Skill 的 frontmatter 都沒有 output-style 欄位（寫了會被靜默忽略）。Subagent 只接收自己定義檔的本文作為 system prompt（加上工作目錄等基本環境資訊），不會套用主 session 的 Output Style；要控制子代理的輸出格式，請直接寫在它的本文中。

<!-- .claude/agents/senior-reviewer.md -->
---
name: senior-reviewer
description: 資深程式碼審查者。PR 審查或重大變更後主動使用。
tools: Read, Grep, Glob
---

你是一位具有 15 年經驗的資深軟體工程師。

## 輸出格式（寫在本文即生效）
- 使用專業語氣，引用具體 RFC 或規範
- 問題描述包含「為什麼這是問題」
- 每個建議標注「必須修改」或「建議修改」
- 以表格列出：嚴重度｜檔案:行號｜問題｜建議修正

Skill 則在呼叫時把內容注入主對話，可在 Skill 本文中規定該任務的輸出格式（例如 release notes 範本）；它與目前 session 的 Output Style 同時生效，因此兩者的格式要求不宜互相衝突。

Plugin 可在 output-styles/ 提供風格；設定 force-for-plugin: true 時，啟用該 plugin 就會自動套用並覆蓋使用者的 outputStyle，企業可藉此在特定團隊統一輸出格式。

2.8 Scheduled Tasks（排程任務）

2.8.1 Scheduled Tasks 概述

🆕 v3.5 依官方 scheduled-tasks、routines、desktop-scheduled-tasks 頁全面更正：v3.4 中的「Routines 需要 Max 訂閱」、「7 天未觸發自動刪除」、「jitter 為間隔的 10%、上限 15 分鐘」、「每位使用者 50 個」、專案根目錄的 loop.md，以及 settings.json 中的 scheduledTasks 陣列設定，皆與官方不符，已全部更正。

Claude Code 提供三種排程方式：

📌 選用原則（官方）：需要「電腦關機也可靠執行」→ Routines；需要存取本機檔案與工具 → Desktop 排程任務；只是在目前 session 中臨時輪詢 → /loop。要對事件「即時反應」而不是輪詢，請改用 Channels。

/loop：在 session 中反覆執行

/loop 是 bundled skill，間隔與 prompt 都可省略：

# 間隔可放在前面（30m）或後面（every 2 hours）；單位 s／m／h／d，秒數會進位到分鐘
> /loop 10m npm test，若失敗就修復
> /loop check the release/next PR every 2 hours

# 把 Skill 當 prompt（只有 Claude 可自行呼叫的 Skill 才會被執行）
> /loop 20m /review-pr 1234

內建維護 prompt（裸 /loop）依序：接續對話中未完成的工作 → 處理目前分支 PR 的 review 意見、失敗的 CI、合併衝突 → 沒有待辦時做 bug hunt 或簡化；不會開啟範圍外的新工作，push、刪除等不可逆動作只在延續逐字稿中已授權的工作時才執行。

loop.md 自訂預設 prompt：放在 .claude/loop.md（專案，優先）或 ~/.claude/loop.md（使用者）。它定義的是裸 /loop 的單一預設 prompt，不是排程清單；修改後下一輪即生效，超過 25,000 bytes 會被截斷。

<!-- .claude/loop.md -->
Check the `release/next` PR. If CI is red, pull the failing job log,
diagnose, and push a minimal fix. If new review comments have arrived,
address each one and resolve the thread. If everything is green and
quiet, say so in one line.

💡 搭配 Monitor 工具：動態間隔的 /loop 中，Claude 可能直接改用 Monitor 工具，在背景執行腳本並即時串流每行輸出，完全不需輪詢，通常更省 token、反應更快。

停止：自我調整節奏的 /loop 在等待下一輪時按 Esc 即可取消；Claude 判斷任務完成時也會以 ScheduleWakeup（stop: true）自行結束。固定間隔的 loop 需以自然語言要求取消，或等 7 天到期。

一次性提醒與排程管理

一次性提醒不用 /loop，直接用自然語言：

> remind me at 3pm to push the release branch
> in 45 minutes, check whether the integration tests passed
> what scheduled tasks do I have?
> cancel the deploy check job

底層工具：CronCreate（5 欄位 cron 表達式、prompt、是否重複）、CronList、CronDelete（以 8 字元 ID 取消）。

⚠️ Session 排程的限制（官方）：

• 每個 session 最多同時 50 個排程任務
• 重複任務在建立後 7 天自動到期：最後觸發一次後刪除自己（避免被遺忘的 loop 無限執行）
• Jitter：重複任務最多延後 30 分鐘觸發（間隔小於一小時者最多延後半個間隔）；排在整點或半點的一次性任務最多提早 90 秒。需要精準時間時，避開 :00／:30（例如 3 9 * * *）
• 只在 Claude Code 執行中且閒置時觸發（在兩輪之間，不會打斷正在進行的回應）；時間以本機時區解讀
• 沒有補跑：忙碌時錯過的觸發，只會在閒置後補觸發一次
• 開新對話會清除所有 session 排程；把 session 送到背景（agent view）則會帶著 /loop 任務繼續執行
• 停用排程：CLAUDE_CODE_DISABLE_CRON=1

2.8.2 配置排程任務

Cloud Routines

Routine 是一組「prompt＋一或多個 repository＋connectors」的已儲存設定，可同時掛上多種觸發：

# 在任一 CLI session 以對話方式建立排程型 routine
> /schedule daily PR review at 9am
> /schedule tomorrow at 9am, summarize yesterday's merged PRs     # 一次性
> /schedule in 2 weeks, open a cleanup PR that removes the feature flag

# 管理既有 routine
> /schedule list
> /schedule update          # 例如改成自訂 cron 表達式
> /schedule run             # 立即執行
> /schedule why did my nightly review do nothing this morning?