Claude Code CLI 教學手冊

版本:v3.0(2026-11-18)

適用對象:系統分析師、軟體架構師、後端工程師、前端工程師、DevOps工程師、SRE工程師、AI工程師、企業資訊部門、Framework維護團隊、Legacy System維護團隊

內容定位:本手冊聚焦於 Claude Code CLI 層級的安裝、設定、指令、Agent 架構、MCP 整合與企業導入實務,以「企業標準技術白皮書」等級撰寫:每一條規範都附範例,並說明人工如何審查與驗證 AI 依規範產出的結果。可與專案內其他 Claude Code 相關手冊(生態圈版、資深同仁版等)並行參考

對齊基準:官方文件 code.claude.com/docs(2026-11-18 下載 llms.txt 所列全部 205 頁原始 Markdown,逐章對照)與 Changelog 至 Claude Code v2.1.327(2026-11-17);指令旗標以本機 Claude Code v2.1.327 的 --help(含 21 個子指令)逐一比對;設定/Hook/MCP/Subagent/Skill 範例皆經第30章的檢查工具實際執行,另以 claude -p --model haiku 實測 8 項關鍵行為(第29.8章),細節見附錄H(v3.0)與附錄G(v2.0)

授權:內部教育訓練使用


如何使用本手冊

Claude Code CLI 是一套以終端機(Terminal)為主要操作介面的 AI 編碼代理人(Coding Agent)。它不像傳統 IDE 外掛只做行內自動完成,而是能夠自主規劃、呼叫工具、跨檔案修改、執行測試、操作 Git,甚至協調多個子 Agent 完成大型任務。本手冊依角色整理出建議閱讀路徑:

角色建議優先閱讀章節
新進工程師第1、3、4、6、7、11、32章
後端/前端工程師第8、9、14、17、18章
架構師/系統分析師第2、13、15、16、26、31章
DevOps/SRE第5、12、19、20、28、29、32、33章
企業資訊部門主管第21、25、28、33章、附錄H
Legacy System維護團隊第15、16章
平台/AI賦能團隊第9、10、26、27、29、30、31、33章
資安/稽核人員第6.6、12、19、28、30、31章

本手冊每一章的結構固定為:本章目標 → 概念與規範 → 範例 → 實務建議/注意 → 本章審查與驗證清單。「本章審查與驗證清單」是 v2.0 新增的固定段落,列出 AI 依本章規範產出內容時最常見的錯誤、正確寫法,以及人工可執行的驗證方式;第30章則把這些驗證方式整理成可直接放進 CI 的檢查工具。

v3.0 重點變更速覽(v2.1.299 → v2.1.327)

若你讀過 v2.0,以下是本次改版中會改變既有設定或流程行為的項目(完整清單見附錄H.2,升級程序見第33章):

主題v2.0(v2.1.299)說法v3.0(v2.1.327)現況章節
Sandbox 自動放行開啟 Sandbox 後,沙箱內的 Bash 指令免詢問直接執行v2.1.324 起 sandbox.autoAllowBashIfSandboxed 預設改為 false:沙箱內指令改走一般權限流程;要沿用舊行為必須在最高層級的 Managed 來源明確設為 true19.5、33.1
模型別名fable=Fable 5.1;best 在有 Fable 權限時等於 fablefable=Fable 5.2(v2.1.321+,Claude apps gateway 仍為 Fable 5);best 改為等同 opus5.6
限制可選模型availableModels/deniedModels 即可鎖定只設 availableModels 時,/model 的 Default 仍解析為帳號預設;要讓 Default 也受白名單約束,需加 enforceAvailableModels: true5.6、5.8
代理伺服器未特別區分 ALL_PROXY組織設定與政策請求(v2.1.323+)、TLS 憑證自動修復(v2.1.319+)不再使用只有 ALL_PROXY 的代理,需設 HTTPS_PROXY28.6、33.1
無效的 --settings-p 模式會靜默略過無效檔案仍會靜默略過;但檔案含 sandbox 鍵時拒絕啟動(結束碼 1,v2.1.323+,本次實測)29.8
OpenTelemetry新增 claude_code.safety_eventv2.1.312 起已停止送出;被拒的工具呼叫改查 tool_decision(含 classifier_verdict、permission_mode)20.5
新設定鍵—permissions.denyInsteadOfPrompting、permissions.blockWritesOutsideWorkingDirectories、sandbox.network.strictAllowlist、sandbox.allowNestedUserNamespaces、subagentPromptCacheTtl 等;subagentStatusLine 已移除、pluginDigests 已忽略5.8
新功能—Code Mode(實驗性)、Advisor 工具、Projects(雲端長期協作)、Claude Models on Google Cloud(Anthropic 代管)、MCP Tasks、Plugin engines 版本宣告31、9.11、4.7、13.7、27.7
新增章節—第31章 Code Mode 與 Advisor、第32章 設定除錯與健康檢查、第33章 v2.1.300~v2.1.327 升級指引、附錄H v3.0 查證紀錄31~33、附錄H

v2.0 重點變更速覽

若你讀過 v1.3,以下是最可能影響日常使用與企業治理的變更(完整清單見附錄C、附錄G.2):

主題v1.3 說法v2.0(v2.1.299)現況章節
預設模型Sonnet 5/Opus 5default 在 Anthropic API 與各訂閱方案皆為 Opus 5.5;sonnet=Sonnet 5.5、haiku=Haiku 5.5、fable=Fable 5.1(v3.0 起為 Fable 5.2,見上表)4.3、5.6
預設權限模式Pro/Max/Team 自 2026-08-14 起為 autov2.1.283 起,終端機與 VS Code 互動 Session 的內建起始模式一律為 auto(不分方案);claude -p 仍為 default;default 在介面上改稱 Manual,可用別名 manual6.6
Hooks 設定格式handlers 陣列、matcher 寫權限規則正確格式為 matcher + hooks 陣列;權限規則語法放在 handler 的 if;新增 onFailure: "block"(v2.1.295)12.4
.mcp.json 格式"transport": "http"必須寫 "type": "http",否則被當成 stdio 而略過13.2
effortLevel/modelOverrides/autoMode.classifyAllShellv1.3 以「查無依據」移除三者皆為官方有效設定鍵,v2.0 恢復並補充 maxEffortLevel、modelPicker5.4
AGENTS.md只能用 @AGENTS.md 匯入v2.1.277 起原生讀取(專案沒有 CLAUDE.md 時)11.7
跨 Session 訊息傳遞原生 Windows 與第三方雲端不支援原生 Windows v2.1.234+ 支援;同機傳訊在 Bedrock/Vertex/Foundry 亦可用(v2.1.248+)9.10
新增章節—第29章 Headless 與 CI/CD 自動化、第30章 AI 產出驗證方法論、附錄G 查證紀錄29、30、附錄G

目錄

下列目錄為三層結構:章 → 節 → 小節,每一項皆可直接跳轉到 Hugo 實際產生的錨點。


第 1 章 Claude Code CLI 介紹

本章目標:說清楚 Claude Code 是什麼、和其他 AI 編碼工具的定位差異、適合與不適合的情境,以及 CLI 與 Desktop/Web/IDE 等周邊介面的關係。讀完後,你應該能判斷一個任務是否適合交給 Claude Code,並知道如何追蹤它快速演進的版本。

1.1 Claude Code 是什麼

Claude Code 是 Anthropic 推出的終端機原生 AI 編碼代理人(Agentic Coding Tool)。與一般「聊天視窗貼程式碼」的使用方式不同,Claude Code 直接在你的專案目錄裡執行,能夠讀取檔案、搜尋程式碼、編輯多個檔案、執行 Bash/PowerShell 指令、操作 Git、呼叫外部系統(透過 MCP),並以「自主代理人迴圈」(Agent Loop)的方式持續規劃與執行,直到任務完成或需要你確認為止。

它的核心價值不是「幫你打字快一點」,而是「幫你把一個模糊的需求,拆解成一連串可驗證的動作」。因此本手冊反覆強調的一件事是:Claude Code 的每一個產出都必須能被人以客觀方式驗證——跑測試、看 diff、查設定來源、用檢查工具掃描,而不是「看起來合理」就接受。

1.2 Claude Code 與 Claude Web 差異

Claude.ai 網頁版是以「對話」為中心的助理:你貼上程式碼、它回覆建議,所有檔案操作都需要你手動複製貼上。Claude Code CLI 則是以「執行環境」為中心:它本身就站在你的檔案系統與終端機之上,可以直接讀寫檔案、跑測試、看 build 結果,再依據真實結果調整下一步動作。網頁版適合討論設計、寫文件草稿;CLI 版適合實際落地到程式碼庫。

1.3 與其他工具的定位比較

工具介面形態Agent 自主性Context 處理典型用途
Claude Code CLI終端機為主,另有 Desktop/VS Code/JetBrains/Web 介面共用同一引擎高(多步驟自主規劃、背景 Session、Subagent、Dynamic Workflows)依需求動態探索整個專案,不需預建索引;目前主力模型皆有 1M Token 上下文大型重構、逆向工程、跨檔案任務、CI 自動化
GitHub CopilotIDE 行內補全 + Chat/Agent 模式,另有 Copilot CLI中高(Agent 模式可多步驟)開啟分頁、工作區索引即時補全、IDE 內小到中範圍修改
CursorIDE Fork(VS Code-based)中高專案索引 + 開啟分頁IDE 內整合式 AI 開發
Gemini CLI/Codex CLI終端機中高動態讀取終端機任務自動化

⚠️ 注意:AI 編碼工具的功能每月都在變動,上表只描述「定位」而非功能清單;導入選型時請以各產品當下的官方文件實測為準,不要直接引用本表做採購決策。

1.4 適用情境

  • 大型 Monorepo 的探索與理解(不需先建索引,邊探索邊理解)
  • 跨檔案、跨服務的重構與升級
  • Legacy 系統的逆向工程與文件補完
  • CI/CD 中的無人值守任務(-p 非互動模式,詳見第29章)
  • 多 Agent 協作的大規模程式碼審查或遷移(第26章)

1.5 限制

  • 不是即時打字補全工具,單輪互動的延遲高於行內補全
  • 輸出仍可能有錯誤或幻覺,特別是冷僻語言(COBOL、Delphi)或極新框架版本
  • 高度依賴良好的 Context(CLAUDE.md、專案結構)才能發揮最大效益,雜亂無章的專案效果會打折
  • 大量平行 Agent/長對話會直接反映在 Token 成本與延遲上
  • 部分功能有平台限制:例如 OS 層級 Sandbox 只支援 macOS、Linux 與 WSL2,原生 Windows 不支援(第19.4章)
# 快速確認安裝與版本
claude --version

# 以非互動模式快速問答(適合腳本化)
claude -p "用三句話說明這個 repo 的主要技術棧"

📌 實務建議:第一次在新專案使用 Claude Code 時,先讓它讀過 README 與目錄結構再下任務指令,效果會明顯優於一開始就丟出複雜需求;若專案還沒有 CLAUDE.md,可執行 /init 讓 Claude 產生初稿再人工修訂(第11章)。

⚠️ 注意:Claude Code 不是確定性編譯器,產出的程式碼仍需要人工 Review,尤其是安全相關(認證、加解密、SQL)的程式碼。

實務案例:一名後端工程師接手一個沒有文件的微服務,先執行 claude -p "列出這個服務對外的所有 REST endpoint 與對應的 Controller",10 分鐘內就拿到一份可核對的清單,再以 grep -rn "@GetMapping\|@PostMapping" src/ 抽查清單是否完整——這正是「AI 產出、人工驗證」的最小循環。

1.6 與 Claude Code 周邊介面/產品的關係

本手冊聚焦於「CLI 層級」的使用方式,但 Claude Code 實際上是一整套共用同一引擎的產品線。設定檔、專案記憶(CLAUDE.md)與 MCP Server 在本機各介面之間是共用的。下表簡要定位各周邊介面與本手冊的關係:

周邊介面/產品定位與本手冊關係
VS Code/JetBrains 擴充套件IDE 內建面板(行內 Diff、@提及、Plan 審閱、Focus view、Agent map)操作概念與 CLI 一致;VS Code 擴充套件讀取起始權限模式的規則與終端機略有不同(第6.6章)
Desktop App(桌面應用)圖形化 Diff 審閱、多 Session 並行、App 預覽、內建瀏覽器、iOS 模擬器(Public Beta)、面板可拆成獨立視窗;可用 /resume 接續 CLI 啟動的 Session,或在 CLI 執行 claude --desktop、/desktop 把目前目錄/Session 交給 Desktop(v2.1.285+)核心 Agent 行為與 CLI 相同;需 Claude 訂閱;企業部署 Desktop 的 WSL2 Session 預設關閉(第28.1章)
Claude Code on the Web(claude.ai/code)在 Anthropic 託管(或企業自架)雲端環境執行的 Session,離線後持續執行以 claude --cloud "任務描述" 建立雲端 Session,claude --teleport 拉回本機;--remote 為棄用別名
自架執行環境(Self-hosted Environments,Team/Enterprise)讓雲端 Session 實際執行在企業自有基礎設施,以 claude self-hosted-runner setup/doctor/orchestrator 建置與維運,claude -p ... --environment ccpool_xxx 指定環境適合資料落地/網路隔離要求高的企業
Remote Control從 claude.ai/code 或 Claude 手機 App 接手本機正在執行的 Session;執行 claude remote-control 的機器會在手機上顯示為「裝置卡」,可直接從手機在該機器開新 Session以 claude --remote-control(別名 --rc)或 /remote-control 啟用;需 claude.ai 登入
Dispatch從手機傳送任務給 Desktop,由 Desktop 在你的電腦上開 Session 執行(Pro/Max)與 Remote Control 的差異在於「發起新任務」而非「接手既有 Session」
Routines/排程任務Routines 在雲端依排程、GitHub 事件或 API 觸發;Desktop 排程與 CLI /loop 則在本機執行與第29章本機排程 claude -p 腳本目的相近,差異在執行位置
Channels(研究預覽)將 Telegram、Discord 或自建 Webhook 事件推送進本機 Session透過 --channels 旗標接收,概念與 MCP Server 相通
Claude in Chrome(GA)讓 Claude 以你已登入的瀏覽器操作網頁,用於前端驗證與除錯--chrome/--no-chrome;可與第14、18章測試流程搭配
Artifacts(Team/Enterprise)將 Session 產出發布為 claude.ai 上可分享、隨 Session 更新的頁面,可呼叫檢視者自己的 MCP 連接器可用 disableArtifact 關閉;/artifacts 管理
/design(研究預覽)把 Claude Design 的 artboard 工作流程帶進 CLI 與 Desktop,先畫可編輯的 UI 稿再實作選定的版本前端與 UI 規劃情境可搭配第14章
Slack 與 Claude TagSlack 整合讓個人在頻道 @Claude 觸發雲端 Session(Pro/Max);Claude Tag 則以組織共用身分運作,由管理者設定存取範圍(Team/Enterprise)屬團隊協作通道,任務在雲端完成
GitHub Actions/GitLab CI/CD/Code Review在 CI 平台呼叫 Claude Code,或為每個 PR 自動審查第17、29章
Agent SDK以 TypeScript/Python 程式化建構自訂 Agent,完全掌控工具、權限與 Orchestration與 claude -p 同源,是更底層的客製化路徑(第29章)

⚠️ 注意:雲端 Session、Routines、Code Review、Remote Control、Chrome 擴充套件需要 claude.ai 帳號,單靠 Console API Key 或雲端供應商憑證(Bedrock/Google Cloud Agent Platform/Foundry)無法使用;企業若僅部署第三方雲端供應商,導入前應規劃工程師是否也需要 Claude for Teams/Enterprise 席位(第4.5章)。

📌 實務建議:周邊介面的詳細設定請查閱官方文件對應頁面,或本系列「生態圈版」「資深同仁版」手冊;本手冊維持 CLI 範疇可避免內容重複與版本不同步。

1.7 版本節奏與更新追蹤

Claude Code 幾乎每個工作日都有新版本(2026 年 8~10 月就從 v2.1.224 演進到 v2.1.299),行為差異會直接影響團隊教材與自動化腳本。企業應把「追蹤版本」當成固定流程,而不是等到出問題才查:

資訊來源內容建議用途
/release-notes(Session 內)互動式版本選單,可看任一版本的變更個人升級後快速確認差異
官方 Changelog(code.claude.com/docs/en/changelog)每一版的新增、修正、行為變更平台團隊每週掃描,判斷是否影響 Managed 設定或腳本
What’s New 週報(code.claude.com/docs/en/whats-new)每週重點功能、範例與示範團隊週會分享、決定是否試行
claude --version、claude doctor本機版本與安裝/設定健檢排查「為什麼我的行為和文件不同」
# 確認版本與安裝健康狀態
claude --version
claude doctor            # 唯讀診斷,不會啟動 Session

# 依發布通道更新:latest(預設,最快)或 stable(約落後一週,略過重大缺陷版本)
claude update

📌 實務建議:在 Managed 設定以 autoUpdatesChannel: "stable" 搭配 minimumVersion 設定版本地板,並以 requiredMinimumVersion/requiredMaximumVersion 限定公司驗證過的版本區間(第3.8、5.4章);平台團隊每週對照 Changelog 決定是否調整區間。本手冊附錄G記錄了每一項內容是以哪一版文件為依據。

1.8 v2.1.300~v2.1.327 新功能與行為變更地圖(v3.0 新增)

v2.0 定稿後的五週內(2026-10-14~11-17),Claude Code 發布了 v2.1.300~v2.1.327 共 20 餘個版本。下表只列出會影響 CLI 使用者或企業治理的項目,依「是否需要動手處理」分級,方便主管與平台團隊決定優先順序。分級的定義:

  • 必須處理:預設值或既有行為已改變,不處理就會出現不同結果(第33章提供逐項遷移範例)
  • 建議評估:新增的治理能力,導入後可提高安全性或可觀測性
  • 知悉即可:介面或便利性改善,不影響既有設定
分級項目版本一句話說明章節
必須處理Sandbox 自動放行預設翻轉v2.1.324sandbox.autoAllowBashIfSandboxed 預設由 true 改為 false19.5、33.1
必須處理ALL_PROXY 不再用於組織設定請求v2.1.319/v2.1.323只設 ALL_PROXY 的網路需加設 HTTPS_PROXY28.6
必須處理best 別名改指 opus、fable 改指 Fable 5.2v2.1.321依賴 best=Fable 的腳本與成本估算需重算5.6
必須處理claude_code.safety_event 停止送出v2.1.312以此事件做的告警會靜默失效,改查 tool_decision20.5
必須處理subagentStatusLine 移除、pluginDigests 忽略v2.1.323/v2.1.325設定仍可載入但不再生效5.8、27.7
必須處理claude remote-control 移除 --sandbox/--no-sandboxv2.1.300腳本傳入會直接結束6.8
必須處理Opus 4.8 Fast Mode 退場公告 v2.1.3162026-11-30 移除,之後請求會失敗且不自動退回20.5
建議評估permissions.denyInsteadOfPromptingv2.1.319無人回應的權限詢問直接拒絕,Session 繼續5.8、29.8
建議評估permissions.blockWritesOutsideWorkingDirectoriesv2.1.314所有模式(含 bypass)禁止 Write/Edit 寫到工作目錄外5.8
建議評估enforceAvailableModels 的必要性文件釐清只設白名單時 Default 不受約束5.6
建議評估Code Mode(實驗性)v2.1.323Claude 以 JavaScript 一次呼叫多個工具31
建議評估Plugin engines["claude-code"]v2.1.323Plugin 宣告支援的 Claude Code 版本範圍27.7
建議評估MCP Tasks 背景化v2.1.319長時間 MCP 呼叫自動轉背景13.7
建議評估Claude Models on Google Cloud(Anthropic 代管)v2.1.307+新的供應商 anthropicGoogleCloud4.7
建議評估tool_decision 新欄位v2.1.301classifier_verdict、permission_mode 可區分分類器與規則20.5
知悉即可/status 列出損壞的 Agent/Skill/Hook matcherv2.1.327診斷更直接32.1
知悉即可claude mcp add-json <name> -v2.1.327從 stdin 讀取 JSON,Token 不留在指令列13.7
知悉即可claude auth status 的 loginExpiresAtv2.1.318可在 CI 前檢查登入是否即將到期4.7
知悉即可Projects(雲端長期協作,Public Beta)官方文件Pro/Max/Ultra 方案,Team/Enterprise 尚未開放9.11

📌 實務建議:把這張表當成「升級審查會議」的議程:「必須處理」逐項指派負責人與完成期限;「建議評估」放進下一季治理計畫;「知悉即可」在團隊週報帶過即可。

1.9 本章審查與驗證清單

AI 產出項目❌ 常見錯誤✅ 正確做法人工如何驗證
「這個任務適不適合交給 Claude Code」的評估把需要即時補全或單行修改的工作交給 Agent,徒增延遲與成本多檔案、需執行驗證、可拆步驟的任務才交給 Agent檢查任務是否有可執行的完成條件(測試、建置、清單比對)
對周邊介面能力的說明宣稱 Console API Key 也能用 Remote Control、雲端 Session依第1.6章註記,這些功能需要 claude.ai 帳號以實際帳號執行 claude auth status,看 authMethod 欄位
引用版本行為用舊版教材描述目前行為(例如仍稱 /fork 是繼承上下文的 Subagent)註明行為對應的最低版本,並以 Changelog 查證claude --version 比對文件標註的版本;必要時看 /release-notes
AI 產出的程式碼或清單「看起來合理」就接受每個產出都附驗證方式(測試、grep、建置)依本章案例,用 grep/測試抽查 AI 給的清單是否完整
版本變更摘要直接貼上 Changelog 原文或只列新功能,不說明對既有設定的影響依「必須處理/建議評估/知悉即可」分級,並標出受影響的設定鍵與章節對照第33章 check_upgrade.py 的 BREAK 清單,確認每一項「必須處理」都有對應
版本號與功能對應把官方文件新增的頁面當成某個版本的新功能,自行編造版本號只寫 Changelog 或官方頁面明確寫出的版本;文件未標示時寫「官方文件」在官方 Changelog 頁搜尋該功能名稱,確認版本號

第 2 章 Claude Code 架構原理

本章目標:理解 Agent Loop、Context、工具呼叫、子 Agent 與 Session 儲存這幾個底層機制。之後各章的權限、Hook、成本與治理設計,都是建立在這些機制上;懂原理,才能判斷 AI 的行為是「設計如此」還是「設定錯誤」。

2.1 Agent Loop(代理人迴圈)

Claude Code 的核心運作模式是一個「感知 → 規劃 → 工具呼叫 → 觀察結果 → 再規劃」的迴圈:模型先理解目前任務與已知資訊,決定下一步要呼叫哪個工具(讀檔、搜尋、編輯、執行指令…),取得結果後重新評估,直到任務完成或需要使用者介入。

sequenceDiagram
    participant U as 使用者
    participant A as Agent (Claude Code)
    participant P as 權限層 (規則/模式/Hook)
    participant T as 工具層 (Read/Edit/Bash/MCP)
    U->>A: 下達任務(例如:修這個 Bug)
    A->>P: 請求呼叫 Bash 搜尋關鍵字
    P-->>A: 依規則放行
    A->>T: 執行搜尋
    T-->>A: 回傳符合的檔案與行號
    A->>P: 請求 Edit 修改程式碼
    P-->>A: 需詢問使用者或依模式自動核准
    A->>T: 執行 Edit
    A->>T: 呼叫 Bash 執行測試
    T-->>A: 回傳測試結果
    A->>U: 回報修正結果與測試通過狀況

每一次工具呼叫在真正執行前,都會先經過「權限層」:permissions.deny/ask/allow 規則、目前的權限模式(第6.6章)以及 PreToolUse Hook(第12章)。這是企業治理的切入點——治理不是限制模型怎麼想,而是限制它能執行什麼。

2.2 Context 管理與 Token 管理

每次呼叫模型,系統提示、工具定義、CLAUDE.md、對話歷史、檔案內容都會佔用 Context Window。Claude Code 會視情況進行「壓縮」(Compaction,將較舊的對話歷史摘要化),並透過 Prompt Caching 降低重複內容(如系統提示、工具定義)的成本。Token 管理的關鍵是:不要把整個專案一次性塞進 Context,而是讓 Agent 依需求動態讀取。

目前主力模型(Opus 5.5、Sonnet 5.5、Haiku 5.5、Fable 系列)都有原生 1M Token 上下文;未自訂時,自動壓縮會在約 967K Token 時觸發,可用 /autocompact 500k 或 --autocompact 提早壓縮。v2.1.290 起還有「閒置壓縮」(Idle Compaction):超過 200K Token 的對話閒置約 54 分鐘、Prompt Cache 即將過期前會自動壓縮,避免你回來時整段重新計費(設定 idleCompaction: false 可關閉)。細節見第8章。

2.3 Tool Calling 與 MCP 整合

模型本身不會直接操作檔案系統,而是透過「工具呼叫」協定,向執行環境請求特定動作(例如 Read(file_path)),執行環境跑完之後把結果以結構化格式回傳給模型。內建工具之外,MCP(Model Context Protocol)讓 Claude Code 能以同樣的工具呼叫機制,串接外部系統(GitHub、Jira、資料庫…),詳見第13章。MCP 工具預設採「延遲載入」:Session 開始時只載入工具名稱,需要時才透過 ToolSearch 載入完整定義,降低基礎 Context 佔用。

2.4 子 Agent 與 Agent 協作

主 Agent 可以「派生」出子 Agent(Subagent),讓它在獨立的 Context 與工具權限範圍內完成特定子任務,再把結果回報給主 Agent。這讓大型任務可以拆解、平行化,也能限制每個子任務能存取的工具範圍(最小權限原則)。預設可往下巢狀派生 3 層,互動式 Session 中派生的 Subagent 預設在背景執行。詳見第9、10章。

2.5 Codebase 理解機制

Claude Code 不要求預先建立索引,而是以「探索式理解」運作:先搜尋檔名與關鍵字找出相關檔案,再用 Read 深入閱讀,邊探索邊建立對專案的理解;大範圍搜尋通常委派給唯讀的內建 Subagent「Explore」,避免搜尋結果淹沒主對話。這與需要預建知識圖譜的工具(如某些靜態分析平台)路線不同——優點是零前置成本、缺點是超大型專案首次探索可能要花較多輪次。

graph TB
    CLI["CLI Shell"] --> Orchestrator["Agent Orchestrator<br/>(Context Manager / Token Accountant / Tool Router)"]
    Orchestrator --> Perm["權限層<br/>規則 / 權限模式 / Hooks"]
    Perm --> Builtin["內建工具<br/>Read/Edit/Write/Bash/PowerShell..."]
    Perm --> MCP["MCP Servers<br/>GitHub/Jira/DB..."]
    Perm --> Sub["Sub Agents<br/>獨立 Context/權限"]
    Builtin --> FS["檔案系統 / Shell / 網路"]
    MCP --> FS
    Sub --> FS
# 加入額外的工作目錄(只授予檔案存取權,不會載入該目錄大部分的 .claude/ 設定)
claude --add-dir ../shared-lib

📌 實務建議:對超大型 Monorepo,從要處理的子專案目錄啟動 Session,再用 --add-dir 補上必要的共用目錄,比從 repo 根目錄讓 Agent 全庫亂逛更省 Token、更準確(第8.4章)。

⚠️ 注意:長時間對話會因為壓縮而遺失部分早期決策細節,重要的約束(如「不要用 Lombok」)建議寫進 CLAUDE.md 而不是只在對話中提一次。

實務案例:一個「修這個 Bug」的請求,實際在背景觸發了搜尋(找關鍵字)→ Read(看程式碼)→ Edit(修改)→ Bash(跑測試)→ Read(確認結果)五次工具呼叫,每一次都先經過權限層,這正是 Agent Loop 的具體呈現。用 Ctrl+O 開啟 Transcript 檢視器,就能逐一看到這些工具呼叫與結果。

2.6 內建工具一覽與平台差異

理解「Claude 實際呼叫了哪個工具」對撰寫權限規則與 Hook 非常重要,因為規則與 Hook 的 matcher 都是以工具名稱比對。以下列出最常用的內建工具(完整清單見官方 Tools reference):

工具用途是否需要權限
Read讀取檔案內容否(工作目錄內)
Edit/Write/NotebookEdit修改、建立檔案、編輯 Notebook是
Bash/PowerShell執行 Shell 指令(Windows 未安裝 Git Bash 時改用 PowerShell)是
Glob/Grep依檔名樣式找檔、搜尋檔案內容否
WebFetch/WebSearch抓取網頁、網路搜尋是
Agent派生 Subagent否
Skill執行 Skill是
Monitor背景執行指令並把每行輸出即時回饋給 Claude(追 log、等建置)是
LSP透過語言伺服器跳到定義、找參考、回報型別錯誤否
AskUserQuestion以選擇題向你確認需求否
TaskCreate/TaskList/TaskUpdate管理 Session 任務清單否
SendMessage/ListAgents對 Subagent、Agent Teams 隊友或其他 Session 傳訊(第9.10章)否
ToolSearch搜尋並載入延遲載入的工具(如大量 MCP 工具)否

⚠️ 注意(平台差異):在 macOS、Linux 與 WSL 上,Glob 與 Grep 預設不在工具集內——Claude 會透過 Bash 工具執行內嵌的 find(bfs)與 grep(ugrep)。這代表:(1) 這些搜尋會以 Bash 呼叫的形式經過你的權限規則與 Hook;(2) 若你寫了 matcher 為 Bash 的 PreToolUse Hook,它也會收到大量搜尋指令,腳本必須夠快並正確放行。在 Windows 上 Glob/Grep 則是預設工具。

2.7 Session 的儲存與生命週期

每個 Session 的對話紀錄(Transcript)以 JSONL 格式儲存在本機 ~/.claude/projects/<專案路徑轉換後名稱>/<session-id>.jsonl,預設保留 30 天(cleanupPeriodDays)。這是 --continue/--resume//rewind 能運作的基礎,也是稽核與除錯時的第一手資料:

動作指令
繼續目前目錄最近一次對話claude -c
依 ID 或名稱回復claude -r auth-refactor(名稱由 -n//rename 設定)
回復時另開新 Session ID(保留原對話不變)claude -r <id> --fork-session
匯出成純文字/export transcript.txt
清除某專案在本機的全部狀態claude purge <path> --dry-run 先預覽,再去掉 --dry-run
非互動模式不留紀錄claude -p --no-session-persistence "..."

⚠️ 注意:Transcript 的 JSONL 格式是 Claude Code 內部格式,每個版本都可能改變。需要以程式分析對話時,請使用 /export、--output-format json/stream-json(第29章)或 Agent SDK,不要直接解析 JSONL 檔。Transcript 可能含有程式碼與敏感資料,屬於需要納入資料保護規範的本機資料(第28.4章)。

2.8 工具呼叫的背景化與 Context 假設(v3.0 新增)

v2.1.319~v2.1.323 有三項變更會改變「一次工具呼叫要等多久、佔多少 Context」的直覺,寫 Prompt 或估算成本時要知道:

變更行為調整方式
MCP 工具呼叫自動背景化(v2.1.319)主對話中的 MCP 呼叫超過 2 分鐘未完成,會轉為背景任務,Claude 先拿到任務 ID 繼續工作,結果以通知回傳;MCP Server 以「task」方式執行的呼叫則立刻轉背景CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS 調整門檻(0 關閉);CLAUDE_CODE_DISABLE_MCP_TASK_BACKGROUND=1 讓 Claude 在工具呼叫內等待 MCP task
未知模型 ID 的 Context 假設(v2.1.323)Claude Code 不認得的模型 ID(例如 Gateway 後的自訂模型)預設視為 1M 視窗(原為 200K)後端模型視窗較小時設 CLAUDE_CODE_DISABLE_1M_CONTEXT=1,否則對話填滿後每一輪都可能失敗直到 /clear
Code Mode(v2.1.323,實驗性)Claude 寫一段 JavaScript,由 REPL 工具一次執行多個工具呼叫;對話中看到的是各工具呼叫,Ctrl+O 才看得到程式碼預設關閉,以 CLAUDE_CODE_EXPERIMENTAL_CODE_MODE=1 開啟(第31章)
Read 工具不再回傳「檔案未變更」短訊(v2.1.317)重複讀取未變更的檔案會回傳完整內容提醒 Claude 不要重複讀大檔,或以 /context 觀察 Token 佔用

以 Gateway 接入自訂模型的團隊,建議在使用者或 Managed 設定中明確宣告 Context 假設,避免「前幾天正常、對話一長就每輪失敗」的難以排查現象:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://llm-gateway.corp.example",
    "CLAUDE_CODE_DISABLE_1M_CONTEXT": "1"
  }
}

⚠️ 注意:MCP 呼叫轉背景後,Claude 會在結果回來前繼續做其他事。若後續步驟依賴該結果(例如先查工單再改程式),請在 Prompt 中明確要求「等工單查詢結果回來再修改」,或以 /tasks 確認背景任務已完成。

2.9 本章審查與驗證清單

AI 產出項目❌ 常見錯誤✅ 正確做法人工如何驗證
解釋「Claude 為什麼能/不能做某件事」歸因於模型能力,忽略權限層先檢查權限規則、權限模式與 Hook/permissions 看規則、/status 看模式與設定來源、/hooks 看 Hook
撰寫 matcher 為 Bash 的 Hook假設搜尋走 Grep 工具,Hook 被大量 find/grep 呼叫拖慢依第2.6章平台差異設計,搜尋類指令快速放行以第12章 harness 餵入 grep -rn foo src 測試,確認 exit 0 且耗時極短
以程式讀取 Session 內容直接解析 ~/.claude/projects/*.jsonl使用 /export、--output-format json 或 Agent SDK升級 Claude Code 後重跑腳本,確認未依賴內部格式
大型 Monorepo 的任務範圍從 repo 根目錄啟動並要求「讀完整個 repo」從子專案目錄啟動,必要時 --add-dir/context 檢查 Context 佔用是否合理
自訂模型的 Context 設定Gateway 後接小視窗模型,卻沒有設定 CLAUDE_CODE_DISABLE_1M_CONTEXT未知模型 ID 自 v2.1.323 起預設 1M;小視窗模型必須明確設為 1長對話測試到超過後端視窗,確認會自動壓縮而不是每輪失敗;check_upgrade.py 會對自訂 ANTHROPIC_BASE_URL 提出 CHECK
依賴 MCP 結果的流程假設 MCP 呼叫一定同步回傳超過 2 分鐘會轉背景,Prompt 中寫明等待條件,或調整 CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS以 /tasks 檢查背景任務狀態;在 Transcript(Ctrl+O)確認 Claude 是在結果回來後才進行下一步

第 3 章 安裝教學

本章目標:在 Windows、macOS、Linux、WSL 上正確安裝 Claude Code,理解各安裝方式的「自動更新」差異,並學會企業環境下的版本鎖定、套件庫簽章驗證與疑難排解。讀完後,你應該能為團隊寫出一份可重現、可驗證的安裝 SOP。

3.1 系統需求

Claude Code 提供原生安裝程式(建議)、套件管理器(Homebrew/WinGet/apt/dnf/apk)與 npm 三種安裝路徑。原生安裝程式與 npm 安裝的都是同一個原生執行檔,執行時不依賴 Node.js。

項目需求
作業系統macOS 13.0+;Windows 10 1809+ 或 Windows Server 2019+;Ubuntu 20.04+;Debian 10+;Alpine Linux 3.19+
硬體4 GB 以上記憶體,x64 或 ARM64 處理器
網路需要連網(企業代理與防火牆白名單見第28.3章)
ShellBash、Zsh、PowerShell 或 CMD
其他ripgrep(通常已隨附);npm 安裝路徑需要 Node.js 22 以上(舊版 Node 只會出現 EBADENGINE 警告,安裝仍會完成)
地區需位於 Anthropic 支援的國家/地區

⚠️ 勘誤:v1.3 寫「npm 安裝需要 Node.js 18 以上」,官方目前要求為 Node.js 22 以上。

flowchart TD
    Start["你的作業系統?"] -->|Windows| Win["PowerShell 安裝程式 / WinGet"]
    Start -->|macOS| Mac["curl 安裝程式 / Homebrew"]
    Start -->|Linux| Lin["curl 安裝程式 / apt-dnf-apk"]
    Start -->|WSL2| Wsl["於 WSL2 內以 Linux 安裝方式安裝"]
    Win --> Verify["claude --version 與 claude doctor 驗證"]
    Mac --> Verify
    Lin --> Verify
    Wsl --> Verify

3.2 Windows 安裝

# PowerShell 一鍵安裝(不需要系統管理員權限)
irm https://claude.ai/install.ps1 | iex

# 或使用 WinGet(不會自動更新,需定期 winget upgrade Anthropic.ClaudeCode)
winget install Anthropic.ClaudeCode

原生 Windows 與 WSL 的選擇:

選項需求OS 層級 Sandbox適用時機
原生 Windows無;Git for Windows 為選配不支援Windows 原生專案與工具鏈
WSL 2啟用 WSL 2支援Linux 工具鏈,或需要 Sandbox 隔離指令執行
WSL 1啟用 WSL 1不支援WSL 2 無法使用時

📌 實務建議:原生 Windows 建議另外安裝 Git for Windows,讓 Claude Code 使用 Git Bash 執行 Bash 工具(Monitor 工具也需要 Git Bash);若未安裝,Claude Code 會自動改用 PowerShell 工具。找不到 Git Bash 時,可在設定的 env 指定 CLAUDE_CODE_GIT_BASH_PATH(例如 C:\Program Files\Git\bin\bash.exe)。

3.3 macOS 安裝

curl -fsSL https://claude.ai/install.sh | bash
# 或
brew install --cask claude-code

Homebrew 提供兩個 cask:claude-code 追蹤穩定發布通道(通常落後約一週,並會跳過有重大缺陷的版本),claude-code@latest 則追蹤最新通道。兩者都預設不自動更新,需定期手動執行 brew upgrade claude-code(或 claude-code@latest);若希望 Claude Code 代為執行升級,可設定環境變數 CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1。原生安裝程式才會在背景自動更新。

3.4 Linux 安裝

curl -fsSL https://claude.ai/install.sh | bash
# Debian/Ubuntu、Fedora/RHEL、Alpine 亦可改用官方簽章的 apt / dnf / apk 套件庫(見第3.9章)

Alpine 等 musl 系發行版需先安裝相依套件,並改用系統的 ripgrep:

apk add bash curl libgcc libstdc++ ripgrep
# 之後在 settings.json 的 env 設定 "USE_BUILTIN_RIPGREP": "0"

3.5 Windows CMD 安裝(備選)

若團隊環境慣用 CMD 而非 PowerShell,可改用以下指令:

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

若在 PowerShell 視窗誤用 CMD 語法會出現 The token '&&' is not a valid statement separator;反之在 CMD 視窗誤用 PowerShell 語法會出現 'irm' is not recognized as an internal or external command。可依錯誤訊息判斷目前所在的命令列環境(PowerShell 提示字元為 PS C:\,CMD 則沒有 PS 前綴)。

3.6 WSL2 安裝注意事項

WSL2 內請依 Linux 流程安裝。常見的坑是「專案放在 Windows 路徑(/mnt/c/...)但在 WSL2 內開發」會有檔案系統效能與權限落差,建議將實際開發中的專案放在 WSL2 原生檔案系統(如 ~/projects/)下操作。另外要注意:WSL2 內的 Claude Code 預設只讀取 Linux 端的 Managed 設定(/etc/claude-code/),要讓 Windows 端政策延伸到 WSL,必須由管理者部署 wslInheritsWindowsSettings: true(第5.5章)。

3.7 npm 安裝路徑(備選)

npm install -g @anthropic-ai/claude-code

# 升級時請指定 @latest,不要用 npm update -g(會受原安裝的 semver 範圍限制)
npm install -g @anthropic-ai/claude-code@latest

⚠️ 注意:不要使用 sudo npm install -g,容易造成權限問題與安全風險;npm 透過平台專屬的 optional dependency(如 @anthropic-ai/claude-code-linux-x64)下載原生執行檔,若套件管理器設定為不安裝 optional dependency,安裝後會找不到執行檔。

3.8 更新與驗證

claude --version       # 驗證安裝版本
claude doctor          # 唯讀健檢:安裝路徑、PATH、設定檔驗證錯誤、最近一次自動更新結果
claude update          # 立即更新到所選通道的最新版本
claude install stable  # 重新安裝原生執行檔,可指定 stable、latest 或特定版本(例如 2.1.296)

發布通道由 autoUpdatesChannel 設定控制:"latest"(預設,最快取得新功能)或 "stable"(約落後一週,略過有重大缺陷的版本)。原生安裝會在啟動時與執行期間定期檢查更新、背景下載,下次啟動時生效。

📌 實務建議:企業內建議在入職文件與 Managed 設定中明確記錄「目前團隊統一使用的版本區間」,因為跨版本行為可能有差異(第3.9章)。

⚠️ 注意:企業內網/代理伺服器環境,npm 安裝路徑可能需要額外設定 registry mirror 或 proxy 環境變數;原生安裝程式則需放行 claude.ai 與 downloads.claude.ai。

實務案例:某團隊筆電有公司代理伺服器限制,原生安裝程式因為直連被防火牆擋下;平台團隊改為申請放行官方下載網域並改用簽章的 apt 套件庫,再以 claude doctor 確認安裝來源與自動更新狀態,全公司安裝方式從此一致。

3.9 企業大量部署與版本鎖定

企業部署需要回答三個問題:從哪裡安裝、誰負責更新、允許哪些版本。

1. 從簽章的套件庫安裝(Linux):官方提供 apt、dnf、apk 套件庫,皆以 Claude Code 發布簽章金鑰簽署,並各有 stable 與 latest 兩個通道(以套件庫 URL 區分,而非 autoUpdatesChannel)。以 Debian/Ubuntu 為例:

sudo install -d -m 0755 /etc/apt/keyrings
sudo curl -fsSL https://downloads.claude.ai/keys/claude-code.asc \
  -o /etc/apt/keyrings/claude-code.asc
# 驗證金鑰指紋,必須是 31DDDE24DDFAB679F42D7BD2BAA929FF1A7ECACE
gpg --show-keys /etc/apt/keyrings/claude-code.asc

echo "deb [signed-by=/etc/apt/keyrings/claude-code.asc] https://downloads.claude.ai/claude-code/apt/stable stable main" \
  | sudo tee /etc/apt/sources.list.d/claude-code.list
sudo apt update && sudo apt install claude-code

2. 決定更新責任:

安裝方式是否自動更新企業建議
原生安裝程式是(背景)搭配 autoUpdatesChannel: "stable" 與 minimumVersion
Homebrew/WinGet否(可設 CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1)由 MDM 或軟體派送工具統一升級
apt/dnf/apk否(需要提權)納入既有作業系統修補排程
npm是(若全域目錄可寫)不建議作為企業標準路徑

3. 鎖定版本區間(Managed 設定):

設定作用
minimumVersion版本地板:自動更新與 claude update 不會安裝低於此版本
requiredMinimumVersion/requiredMaximumVersion強制區間:版本不符直接拒絕啟動,比 minimumVersion 更嚴格;設定值格式錯誤時會被忽略(Fail Open)
env.DISABLE_AUTOUPDATER: "1"只停用背景自動更新,claude update/claude install 仍可用
env.DISABLE_UPDATES: "1"封鎖所有更新途徑(含手動),適合由企業自行派送版本
{
  "autoUpdatesChannel": "stable",
  "minimumVersion": "2.1.283",
  "requiredMinimumVersion": "2.1.280"
}

📌 實務建議:新模型推出時,常需要較新的 Claude Code 版本(例如 Sonnet 5.5 需 v2.1.284+、Haiku 5.5 需 v2.1.293+),而 stable 通道可能還沒提供。平台團隊應在模型開放前先評估是否暫時調高 requiredMinimumVersion 或切換通道。

3.10 解除安裝與疑難排解

症狀排查步驟
claude: command not found開新終端機;確認安裝目錄(macOS/Linux 為 ~/.local/bin)在 PATH 中;執行 claude doctor
安裝指令出現 syntax error near unexpected token '<' 或 403下載被代理或防火牆攔截,回傳的是 HTML 錯誤頁;確認網域放行
npm 安裝後找不到執行檔套件管理器未安裝 optional dependency;改用原生安裝程式
自動更新沒有生效claude doctor 看「Auto-updates」行與最近一次更新結果;若自建 launcher 取代了 ~/.local/bin/claude,自動更新不會覆蓋它
Windows 找不到 Git Bash設定 CLAUDE_CODE_GIT_BASH_PATH,或接受改用 PowerShell 工具

解除安裝依安裝方式而定:原生安裝刪除 ~/.local/bin/claude 與 ~/.local/share/claude;Homebrew 用 brew uninstall --cask claude-code;WinGet 用 winget uninstall Anthropic.ClaudeCode;npm 用 npm uninstall -g @anthropic-ai/claude-code。設定檔(~/.claude/、~/.claude.json)需另外手動移除;若只想清除某個專案的本機狀態,用 claude purge <path>。

3.11 版本下限檢查與 v2.1.300 以後的安裝變更(v3.0 新增)

v2.1.300~v2.1.327 與安裝、更新有關的變更:

變更版本影響
安裝腳本不再重複下載最新版v2.1.323安裝時間縮短,流程不變
Windows 尋找 git 等程式時略過相對路徑、UNC 路徑與網路磁碟上的連結,並套用設定中的 PATH 變更v2.1.321PATH 中含網路磁碟的企業電腦,若 git 只放在網路磁碟,需改裝到本機
在 IDE 內建終端機啟動時不再自動安裝/更新 IDE 擴充套件v2.1.318改由外部終端機執行 /ide,或從編輯器的擴充套件畫面安裝
Linux /home 為 autofs 時不再自行查詢 /homev2.1.323掛載點比 / 下一層更深時設 CLAUDE_CODE_AUTOMOUNT_ROOTS
claude update 結束瞬間按 Ctrl+C 會移除 claude 指令的問題已修正v2.1.323舊版本請避免在更新完成時中斷

企業最常需要的是「確認每台機器都達到團隊版本下限」。v3.0 的多項安全修正(例如 Bash 權限檢查的複合指令漏洞、--settings 無效時 Sandbox 不生效)都在 v2.1.323~v2.1.325,建議把下限訂在 v2.1.325。以下腳本可放進開發機登入腳本或 CI 第一步:

#!/usr/bin/env bash
# 確認 Claude Code 版本不低於團隊下限;低於下限時結束碼 1
set -euo pipefail
MIN="${CLAUDE_MIN_VERSION:-2.1.325}"
ver=$(claude --version | awk '{print $1}')
lowest=$(printf '%s\n%s\n' "$MIN" "$ver" | sort -V | head -n1)
if [ "$lowest" != "$MIN" ]; then
  echo "Claude Code $ver 低於團隊下限 $MIN,請執行 claude update" >&2
  exit 1
fi
echo "Claude Code $ver OK(下限 $MIN)"

Managed 設定中的 minimumVersion 會讓低於下限的版本在啟動時提示更新(第3.9章);上面的腳本則讓 CI 在呼叫 claude -p 之前就失敗,兩者互補。第32.6章的健康檢查腳本也包含相同的版本檢查。

3.12 本章審查與驗證清單

AI 產出項目❌ 常見錯誤✅ 正確做法人工如何驗證
團隊安裝 SOP寫「需要 Node.js 18」、或以 sudo npm install -g 安裝優先原生安裝或簽章套件庫;npm 需 Node.js 22+ 且不可用 sudo在乾淨 VM 依 SOP 實跑,claude --version 與 claude doctor 皆無錯誤
套件庫設定未驗證簽章金鑰指紋就信任套件庫以 gpg --show-keys 比對指紋 31DD DE24 DDFA B679 F42D 7BD2 BAA9 29FF 1A7E CACE實際執行 gpg --show-keys,指紋逐字比對
版本治理設定只設 minimumVersion 就以為能阻止舊版啟動需要強制區間時用 requiredMinimumVersion/requiredMaximumVersion在測試機安裝區間外版本,確認被拒絕啟動
停用更新用 DISABLE_AUTOUPDATER 期待阻擋所有更新要封鎖手動更新必須用 DISABLE_UPDATES設定後執行 claude update,確認行為符合預期;claude doctor 顯示 disabled
Windows 環境說明宣稱原生 Windows 也有 OS 層級 Sandbox原生 Windows 不支援 Sandbox,需要隔離時改用 WSL2在原生 Windows 執行 /sandbox,確認顯示不支援
版本下限只寫在 Wiki,沒有任何機制檢查Managed minimumVersion + CI 第一步的版本檢查腳本,下限至少 v2.1.325在低於下限的機器執行腳本,確認結束碼為 1 且訊息指出應執行的指令
Windows PATH把 git 放在網路磁碟並靠 PATH 找到v2.1.321 起略過網路磁碟上的 PATH 項目,git 需安裝在本機在受影響的電腦執行 claude doctor,並在 Session 中請 Claude 執行 git --version

第 4 章 Authentication

本章目標:掌握 Claude Code 支援的帳號類型、登入方式、CI 用的憑證,以及多種憑證同時存在時「到底用了哪一個」的優先順序。讀完後,你應該能在登入異常時用 /status 與 claude auth status 自行定位問題,並為 CI 選擇正確的憑證類型。

4.1 帳號類型

Claude Code 透過以下其中一種「API 供應商」連到 Claude,選擇會影響計費、認證方式、繼承的合規邊界與可用功能:

供應商適用情境
Claude for Teams/EnterpriseClaude Code 與 claude.ai 一起以席位訂閱,不需自建基礎設施——官方預設建議
Claude ConsoleAPI 優先、依用量付費
Amazon Bedrock沿用既有 AWS 合規控管與計費
Google Cloud’s Agent Platform(原 Vertex AI)沿用既有 GCP 合規控管與計費
Microsoft Foundry沿用既有 Azure 合規控管與計費
Claude Platform on AWS透過 AWS 取得 Anthropic 平台

個人使用者則以 Claude Pro/Max 訂閱登入。團隊導入時建議優先評估 Team/Enterprise 方案,避免每人各自申請 API Key 造成費用與權限分散難管理。

4.2 登入方式

claude auth login                  # 標準 OAuth 登入(跳轉瀏覽器)
claude auth login --email you@co   # 登入時預先帶入信箱
claude auth login --sso            # 強制以 SSO 方式登入
claude auth login --console        # 改用 Claude Console 依 API 用量計費登入(非訂閱制)
claude auth status                 # 輸出 JSON;exit code 0=已登入、1=未登入
claude auth status --text          # 人類可讀格式
claude auth logout                 # 登出
claude setup-token                 # 產生一年效期的 OAuth Token(僅印在終端機、不落地儲存;需 Claude 訂閱)

Session 內則用 /login、/logout;/status 會顯示目前生效的登入方式、組織與信箱,若同時設定了登入與 API Key,未使用的那一個會被標註出來。

claude auth status 的 JSON 中,authMethod 欄位會是 none、claude.ai、oauth_token、api_key、api_key_helper 或 third_party 其中之一;v2.1.268 起還有 configDirectory 欄位標示 CLI 實際使用的設定目錄。

# 健康檢查腳本:確認已登入且使用的是公司要求的訂閱登入
status="$(claude auth status)" || { echo "尚未登入"; exit 1; }
method="$(printf '%s' "$status" | jq -r '.authMethod')"
[ "$method" = "claude.ai" ] || { echo "目前登入方式為 $method,請改用公司 Claude for Enterprise 帳號"; exit 1; }

同時使用多個帳號(例如公司與個人):為每個帳號指定獨立的設定目錄即可,各自保存登入、設定與 Session 紀錄:

alias claude-work='CLAUDE_CONFIG_DIR=~/.claude-work claude'
sequenceDiagram
    participant CLI as Claude Code CLI
    participant Browser as 瀏覽器
    participant Auth as Anthropic 認證伺服器
    CLI->>Browser: 開啟登入頁面
    Browser->>Auth: 使用者輸入帳密 / SSO
    Auth-->>Browser: 核發授權碼
    Browser-->>CLI: 回傳授權碼
    CLI->>Auth: 交換 Access Token
    Auth-->>CLI: 回傳 Token,存入本機憑證儲存

憑證儲存位置:macOS 為加密的 Keychain(Keychain 拒絕寫入時改存 ~/.claude/.credentials.json,權限 0600);Linux 為 ~/.claude/.credentials.json(0600);Windows 為 %USERPROFILE%\.claude\.credentials.json。登入到期前三天,啟動時會提示 Your login expires in 3 days · run /login to renew。

4.3 API Key 與環境變數(適合 CI / Headless)

export ANTHROPIC_API_KEY="sk-ant-xxxxx"       # Claude Console API Key,以 X-Api-Key 標頭送出
export CLAUDE_CODE_OAUTH_TOKEN="xxxxx"        # claude setup-token 產生的長效 OAuth Token(訂閱制 CI 用)
export ANTHROPIC_AUTH_TOKEN="xxxxx"           # 以 Bearer 標頭送出,給需要 Bearer Token 的 LLM Gateway/Proxy 使用
export ANTHROPIC_MODEL="opus"                 # 覆寫目前 Session 模型(別名 sonnet/opus/haiku/fable 或完整 ID 如 claude-opus-5-5)

⚠️ 勘誤:v1.3 將 ANTHROPIC_AUTH_TOKEN 註解為「OAuth Token」並不正確。ANTHROPIC_AUTH_TOKEN 是以 Authorization: Bearer 送出、用於 LLM Gateway 的權杖;claude setup-token 產生的 OAuth Token 應放在 CLAUDE_CODE_OAUTH_TOKEN。

apiKeyHelper 設定可指定一支 Shell 腳本動態回傳 API Key(例如從 Vault 取得短效權杖),適合需要輪替的企業環境;腳本超過 10 秒才回傳會在提示列顯示警告,失敗、逾時或沒有輸出時,請求會在三次嘗試內失敗。

4.4 安全建議

  • 絕對不要把 API Key 寫進程式碼或提交到 Git(搭配第19章的 Secret Scan 與第12章的 Hook)
  • CI/CD 用的 Token 與工程師個人登入帳號分離,個別輪替、個別撤銷
  • 企業環境優先用 Team/Enterprise 的集中管理,而非每人各自申請 Key 報帳
  • 需要限制登入方式時,在 Managed 設定以 forceLoginMethod 指定 "claudeai"、"console" 或 "gateway",並以 forceLoginOrgUUID 限制只能登入特定 Anthropic 組織;限制涵蓋 VS Code 擴充套件、Agent SDK、claude setup-token、/install-github-app 等第一方登入途徑
  • v2.1.285 起可用 allowedProviders 限制機器只能使用哪些供應商(anthropic、bedrock、vertex、foundry、anthropicAws、anthropicGoogleCloud、mantle、customEndpoint、gateway),未列出的供應商會在啟動、登入與下次呼叫 API 時被拒絕;anthropicGoogleCloud 是 v3.0 新增的「Claude Models on Google Cloud(Anthropic 代管)」,與 Google 代管的 vertex 是不同供應商(第4.7章)
{
  "forceLoginMethod": "claudeai",
  "forceLoginOrgUUID": "00000000-0000-4000-8000-000000000000",
  "allowedProviders": ["anthropic"]
}

📌 實務建議:互動式開發用個人帳號登入;CI Pipeline 用獨立的 Service Token(Console API Key 或 CLAUDE_CODE_OAUTH_TOKEN),兩者權限與額度都應該分開管理。

⚠️ 注意:ANTHROPIC_API_KEY 一旦外洩等同於直接授予帳務存取權,務必搭配 Secret Manager 而非寫入 .env 後提交版本控制。若你同時有訂閱登入又在環境中設了 ANTHROPIC_API_KEY,Claude Code 會在你核准一次後改用 API Key——金鑰所屬組織若已停用就會出現認證失敗,此時 unset ANTHROPIC_API_KEY 並以 /status 確認即可。

實務案例:某團隊原本每位工程師各自申請 API Key 報公帳,導入 Enterprise 方案後改為集中開立席位,並在 Managed 設定加上 forceLoginMethod: "claudeai" 與 forceLoginOrgUUID,財務與權限稽核時間從每月數小時縮短到幾分鐘。

4.5 企業雲端供應商登入

除了 Claude 訂閱帳號與 Claude Console 之外,Claude Code 也支援透過企業既有的雲端帳號登入,模型呼叫經由各雲端供應商代理,便於併入企業現有的雲端治理(IAM、計費、資料駐留)框架:

供應商啟用方式設定精靈
Amazon BedrockCLAUDE_CODE_USE_BEDROCK=1登入畫面選 3rd-party platform,或執行 /setup-bedrock
Google Cloud’s Agent PlatformCLAUDE_CODE_USE_VERTEX=1/setup-vertex
Microsoft FoundryCLAUDE_CODE_USE_FOUNDRY=1無精靈,只能用環境變數設定
# 以環境變數指定走第三方雲端供應商(region、專案等其餘變數依各供應商文件設定)
export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=us-east-1

第三方供應商上的模型別名可能指向較舊的版本:例如在 Bedrock/Google Cloud 上 sonnet 目前解析為 Sonnet 4.5、Foundry 的 opus 解析為 Opus 4.6(Anthropic API 上則是 Opus 5.5/Sonnet 5.5)。需要較新模型時,請以完整模型 ID 或 ANTHROPIC_DEFAULT_OPUS_MODEL/ANTHROPIC_DEFAULT_SONNET_MODEL 明確指定,或用 modelOverrides 把模型 ID 對應到供應商的 inference profile(第5.6章)。

📌 實務建議:已有雲端供應商合規框架(如金融業要求資料不可離開特定雲端區域)的企業,優先評估透過 Bedrock/Google Cloud/Foundry 登入,可降低法遵與資安審查的額外溝通成本。

⚠️ 注意:透過第三方雲端供應商登入時,部分功能的開放節奏與原生帳號不同(例如雲端 Session、Routines、Remote Control 需要 claude.ai 帳號;Enterprise 的伺服器端模型治理不涵蓋這些供應商)。Auto Mode 目前在這些供應商上不再需要 CLAUDE_CODE_ENABLE_AUTO_MODE=1(v2.1.207 起,該變數保留相容但無作用)。導入前請以官方「Feature availability」頁面確認所需功能。

4.5.1 Claude apps gateway:讓第三方雲端也能拿到集中治理

企業若透過 Bedrock/Google Cloud/Foundry 登入,原生就無法使用 claude.ai 管理後台的 Server-managed 設定推送(第5.5章),也缺乏依使用者拆分的用量歸屬與花費上限。Claude apps gateway 是官方提供、可自架的閘道服務(claude gateway --config gateway.yaml),讓部署在第三方雲端的 Claude Code 也能:

  • 以企業 IdP 登入(SSO),並依 IdP 群組交付不同的 Managed 設定(claude.ai 後台目前無法分群)
  • 記錄具備 IdP 身分資訊的逐請求稽核紀錄(Request-level Audit Log)
  • 設定依使用者的花費上限(Per-user Spend Limits),v2.1.284 起 /usage 與狀態列會顯示金額
  • 把不同模型路由到不同上游(每個上游可設定 models 清單,v2.1.295+),並支援 Bedrock 的 assume_role 與 Guardrail

開發者端以 forceLoginMethod: "gateway" 搭配 forceLoginGatewayUrl 引導登入到閘道。

📌 實務建議:同時混用多種雲端供應商登入方式的企業,應優先評估部署 Claude apps gateway,讓治理與稽核機制在所有供應商間保持一致,避免「原生帳號有完整治理、第三方雲端卻是治理死角」的落差。

4.6 認證優先順序與排查

同一台機器上可能同時存在多種憑證。Claude Code 依下列順序選用第一個存在的憑證:

順位憑證來源典型用途
—已登入的 Claude apps gateway Session(屬於供應商選擇,優先於下列所有項目)企業閘道
1雲端供應商憑證(設定了 CLAUDE_CODE_USE_BEDROCK/_VERTEX/_FOUNDRY)Bedrock/Google Cloud/Foundry
2ANTHROPIC_AUTH_TOKEN(Bearer)LLM Gateway/Proxy
3ANTHROPIC_API_KEY(X-Api-Key;互動模式需核准一次)Console API 直連
4apiKeyHelper 腳本輸出動態/輪替憑證
5CLAUDE_CODE_OAUTH_TOKEN訂閱制 CI
6Anthropic profile/Workload Identity Federation 憑證ant CLI、聯合身分
7/login 取得的訂閱 OAuth 憑證Pro/Max/Team/Enterprise 日常使用
# 排查「為什麼用的不是我預期的帳號」
claude auth status --text      # 看目前登入方式
env | grep -E '^(ANTHROPIC_|CLAUDE_CODE_USE_|CLAUDE_CODE_OAUTH)'   # 找出可能搶先的環境變數
# Session 內執行 /status,看 Login method/Organization/Email 與被標註為未使用的憑證

⚠️ 注意:apiKeyHelper、ANTHROPIC_API_KEY、ANTHROPIC_AUTH_TOKEN 只作用於 CLI 及包裝它的介面(VS Code 擴充套件、Agent SDK、GitHub Actions);Claude Desktop 與雲端 Session 不會讀取它們,而是使用 OAuth。雲端 Session 中設定 ANTHROPIC_API_KEY 也不會覆蓋訂閱憑證。

4.7 Claude Models on Google Cloud(Anthropic 代管)與登入到期管理(v3.0 新增)

官方文件在 v2.0 之後新增一個供應商:Claude Models on Google Cloud(Anthropic managed)。它與第4.5章的 Google Cloud’s Agent Platform(舊稱 Vertex AI)不是同一個服務:

比較項目Google Cloud’s Agent PlatformClaude Models on Google Cloud(Anthropic 代管)
由誰營運 APIGoogleAnthropic,透過你的 Google Cloud 專案
啟用變數CLAUDE_CODE_USE_VERTEX=1CLAUDE_CODE_USE_ANTHROPIC_GOOGLE_CLOUD=1
必要資訊專案、區域專案 ID、Workspace ID(wrkspc_ 開頭);區域預設 global
權限Vertex AI 相關 IAMroles/claude.user
allowedProviders 值vertexanthropicGoogleCloud
最低版本—v2.1.307

設定方式:先以 gcloud auth application-default login(或 CI 中的 GOOGLE_APPLICATION_CREDENTIALS 服務帳號金鑰)取得憑證,再在使用者設定的 env 加入三個變數。不需要登入 Anthropic 帳號:

{
  "env": {
    "CLAUDE_CODE_USE_ANTHROPIC_GOOGLE_CLOUD": "1",
    "ANTHROPIC_GOOGLE_CLOUD_PROJECT": "acme-ai-prod",
    "ANTHROPIC_GOOGLE_CLOUD_WORKSPACE_ID": "wrkspc_01ABCDEFGHIJKLMN"
  }
}

需要知道的限制:這個供應商不支援 Fast Mode、Remote Control 與雲端 Session、claude.ai 的 MCP 連接器、Channels、/design-sync 與 /import、Server-managed settings(必須改用每台機器上的 Managed 設定檔),也不能使用 Code Mode(第31章)。同時設定了 CLAUDE_CODE_USE_BEDROCK、CLAUDE_CODE_USE_FOUNDRY 或 CLAUDE_CODE_USE_ANTHROPIC_AWS 會造成供應商判斷錯誤,切換前要先移除。

登入到期管理(v2.1.318+):以 claude.ai 帳號登入的機器,憑證有到期日。v3.0 實測 v2.1.327:

  • claude auth status 的 JSON 輸出含 loginExpiresAt 欄位
  • claude -p --output-format json 的結果含 credential_expires_at 欄位
  • 到期前 10 天起,claude -p 的文字輸出會在 stderr 印出一行警告

CI 不應等到失敗才發現登入過期。第29.8章的 gate_result.py 會在剩不到 7 天時輸出警告,第32.6章的健康檢查會印出剩餘天數。另外,v2.1.319 起當 claude.ai 登入結束、改用 ant auth login 的登入繼續時,Claude Code 會警告並在啟動時指出改由哪個 Claude Console 組織計費——在共用機器上看到這行訊息要立即確認。

📌 實務建議:企業若同時有 Google 代管與 Anthropic 代管兩種合約,請在 Managed 設定以 allowedProviders 只列出真正簽約的那一個,並在供應商清單文件中寫清楚兩者的變數差異,避免工程師照著網路文章設成另一個。

4.8 本章審查與驗證清單

AI 產出項目❌ 常見錯誤✅ 正確做法人工如何驗證
CI 的憑證設定把 claude setup-token 的結果放進 ANTHROPIC_AUTH_TOKEN訂閱 Token 放 CLAUDE_CODE_OAUTH_TOKEN;Console Key 放 ANTHROPIC_API_KEY在 CI 執行 claude auth status,確認 authMethod 為 oauth_token 或 api_key
「登入正常但用錯帳號」的排查建議只叫使用者重新 /login依第4.6章優先順序找出搶先的環境變數env | grep ANTHROPIC_ 與 /status 交叉比對
限制登入的 Managed 設定forceLoginMethod 寫成 "sso"、"enterprise" 等不存在的值只能是 claudeai、console、gateway以第30章 check_settings.py 檢查,並在測試機嘗試以 Console 帳號登入應被拒絕
第三方雲端的模型設定假設 sonnet 在 Bedrock 也是最新的 Sonnet 5.5以完整模型 ID 或 ANTHROPIC_DEFAULT_*_MODEL 明確指定Session 內 /model 或 /status 確認實際模型
憑證保存方式把 API Key 寫進 settings.json 的 env 並提交版控使用 Secret Manager、CI Secret 或 apiKeyHelpergit log -p | grep -E "sk-ant-" 與 Secret Scan 工具掃描
Google Cloud 供應商設定把 CLAUDE_CODE_USE_VERTEX 與 Anthropic 代管的變數混用,或 allowedProviders 寫 vertex 卻使用 Anthropic 代管依合約選一種:Agent Platform 用 vertex、Anthropic 代管用 anthropicGoogleCloud 與 CLAUDE_CODE_USE_ANTHROPIC_GOOGLE_CLOUDSession 內 /status 看 API provider;以 check_settings.py 檢查 allowedProviders 值
登入到期CI 用個人 claude.ai 登入,到期後才發現所有 Job 失敗CI 改用 API Key 或供應商憑證;若必須用登入,以 loginExpiresAt/credential_expires_at 提前告警claude auth status 看 loginExpiresAt;gate_result.py 對 7 天內到期輸出 WARN

第 5 章 Claude Code 設定管理

本章目標:理解 settings.json 的四個層級與優先順序、常用設定鍵、Managed 設定的交付機制,以及模型與推理強度(Effort)的設定方式。讀完後,你應該能寫出正確、可通過檢查工具的設定檔,並在「設定沒生效」時用 /status 找到原因。

5.1 settings.json 三層架構

Claude Code 從四個檔案讀取設定(使用者、共用專案、本機專案三層,加上企業 Managed 設定):

層級檔案路徑影響範圍是否版控
使用者~/.claude/settings.json(Windows 為 %USERPROFILE%\.claude\settings.json)你在這台機器上的所有專案否(個人機器)
共用專案.claude/settings.json所有在這個專案工作的人是(提交到 Git,全隊共用)
本機專案.claude/settings.local.json只有你、只在這個專案否(Claude Code 首次寫入時會自動加入全域 git excludes;手動建立需自行加入 .gitignore)
企業管理managed-settings.json 或其他 Managed 來源(第5.5章)組織部署到的所有機器由 IT 集中管理

另外還有兩個常被忽略的位置:~/.claude.json 是 Claude Code 自己維護的檔案(登入 Session、MCP Server 設定、各專案的信任決定、/config 寫入的全域設定),一般不需要手動編輯;CLAUDE_CONFIG_DIR 環境變數則可把 ~/.claude 整個搬到別處(第4.2章多帳號用法)。

安裝 Claude Code 不會建立任何設定檔。~/.claude/settings.json 會在你第一次透過 /config 改設定時建立,.claude/settings.local.json 則在你第一次對權限詢問選「Yes, and don’t ask again」時建立。

5.2 優先順序

flowchart TD
    Managed["1. 企業 Managed 設定<br/>(IT 強制,最高優先)"] --> Final["最終生效設定"]
    CliArgs["2. 命令列 --settings<br/>(僅限當次 Session)"] --> Final
    Local["3. 本機專案<br/>.claude/settings.local.json"] --> Final
    Project["4. 共用專案<br/>.claude/settings.json"] --> Final
    User["5. 使用者<br/>~/.claude/settings.json"] --> Final

優先順序由高到低:Managed > 命令列 --settings > Local > Project > User。Managed 設定一旦設定,個別開發者無法覆寫,這是企業治理的關鍵保護機制。三個容易誤解的細節:

  1. 「命令列」層級只指 --settings:其他旗標(如 --model、--effort)是針對單一功能的覆寫,不屬於這個堆疊;每個設定鍵在官方 Settings reference 中會註明哪些旗標可以覆寫它。
  2. 環境變數不是一個層級:同一功能同時有 Shell 變數與設定鍵時,依「每一對」各自規定。例如 Shell 中 export ANTHROPIC_MODEL 會勝過任何檔案的 model,但 ANTHROPIC_DEFAULT_MODEL 只在沒有任何檔案設定 model 時才生效。寫在設定檔 env 區塊的值則是一般設定鍵,照上面的層級走。
  3. 陣列會合併:permissions.allow 等清單型設定在各層之間是合併而非取代;例外是 fallbackModel(取最高層的整條鏈)、modelPicker(只讀 managed/--settings/user,忽略 project 與 local)、availableModels(Managed 有設定時以 Managed 為準)與 modelSettings(逐模型解析)。

少數「限制性」的鍵有例外:較低層級設定了更嚴格的值時仍會被採用,例如任何層級的 disableClaudeAiConnectors: true、isolatePeerMachines: true、permissions.blockReadsOutsideWorkingDirectories: true,以及任何層級設定了更低的 maxEffortLevel。

5.3 設定範例

設定檔是嚴格 JSON:不能有 // 註解,也不能有尾逗號,否則互動模式會跳出 Settings Error 對話框,而 claude -p 會靜默略過整個檔案。加上 $schema 可以讓 VS Code 等編輯器提供自動完成與即時驗證(SchemaStore 的 schema 可能落後最新版本,例如目前還不認得 v2.1.295 新增的 onFailure,看到警告時請以官方文件為準)。

以下是一份可提交版控的專案設定(.claude/settings.json),已通過第30章 check_settings.py 與 SchemaStore schema 驗證:

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test *)",
      "Bash(git diff *)",
      "Bash(git log *)"
    ],
    "ask": [
      "Bash(git push *)"
    ],
    "deny": [
      "Bash(git push --force *)",
      "Bash(rm -rf *)",
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ]
  },
  "env": {
    "NODE_ENV": "development"
  },
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "bash",
            "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/block-dangerous.sh"],
            "timeout": 10
          }
        ]
      }
    ]
  },
  "attribution": {
    "commit": "Co-Authored-By: Claude <noreply@anthropic.com>",
    "pr": "Generated with Claude Code"
  },
  "cleanupPeriodDays": 30
}

個人在本機的覆寫(.claude/settings.local.json),不提交版控:

{
  "effortLevel": "high",
  "permissions": {
    "allow": [
      "Bash(docker compose up *)"
    ]
  },
  "spinnerTipsEnabled": false
}

⚠️ 勘誤(推翻 v1.3 的勘誤):v1.3 曾以「查無官方依據」為由移除 effortLevel 與 modelOverrides,並宣稱 autoMode.classifyAllShell 不存在。經比對 2026-10 官方 Settings reference,這三個鍵都是有效設定:effortLevel 設定沒有個別儲存等級之模型的預設推理強度(low/medium/high/xhigh,不接受 max);modelOverrides 把 Anthropic 模型 ID 對應到供應商專屬 ID(例如 Bedrock inference profile ARN);autoMode.classifyAllShell 讓 Auto Mode 下所有 Shell 指令都送分類器審核。v1.3 的範例另有一個錯誤:在 JSON 第一行放了 // 註解,該檔案在非互動模式會被整個忽略。

5.4 常見設定鍵分類

以下依官方 Settings reference 的分類整理常用鍵(官方共列出約 245 個鍵與子鍵,完整清單見第30章附帶的 settings-keys.txt):

  • 模型與回應:model、availableModels、availableModelsMatch("exact" 讓清單只允許指定版本,v2.1.283+)、deniedModels(v2.1.283+)、enforceAvailableModels、fallbackModel(最多三個、依序嘗試)、effortLevel、maxEffortLevel(v2.1.267+)、modelSettings(逐模型的 effort/autocompact 等)、modelOverrides、modelPicker(v2.1.242+)、modelPricing、alwaysThinkingEnabled、advisorModel、fastMode/fastModePerSessionOptIn、ultracode、outputStyle、language、promptCacheTtl
  • 權限:permissions.allow/ask/deny(清單型,跨層合併)、permissions.defaultMode(第6.6章)、permissions.additionalDirectories、permissions.blockReadsOutsideWorkingDirectories、permissions.disableBypassPermissionsMode、allowManagedPermissionRulesOnly、disableAutoMode(也可寫成 permissions.disableAutoMode)、autoMode(environment/allow/soft_deny/hard_deny 四組文字規則,加上 classifyAllShell 布林值)、useAutoModeDuringPlan
  • Sandbox:sandbox.enabled、sandbox.failIfUnavailable、sandbox.autoAllowBashIfSandboxed、sandbox.excludedCommands、sandbox.filesystem.allowWrite/denyWrite/denyRead/allowRead、sandbox.network.allowedDomains/deniedDomains/allowManagedDomainsOnly/allowUnixSockets、sandbox.credentials(詳見第19.4、28.2章)
  • 記憶與 Context:autoMemoryEnabled、autoMemoryDirectory、claudeMd(Managed 層級直接內嵌 CLAUDE.md)、claudeMdExcludes、autoCompactEnabled、autoCompactWindow、idleCompaction(v2.1.290+)、fileCheckpointingEnabled、plansDirectory、env
  • 介面與終端機:theme、tui、viewMode、editorMode、axScreenReader、maxProseWidth、statusLine、spinnerTipsEnabled、autoContinueAtUsageLimit、respectGitignore、defaultShell、companyAnnouncements、footerLinksRegexes
  • Git 與歸屬:attribution(commit/pr/sessionUrl;v2.1.281+ 可直接設 false 隱藏全部歸屬,但較舊版本會略過含此值的檔案)、includeGitInstructions、prUrlTemplate
  • Hooks 與自動化:hooks、disableAllHooks、allowManagedHooksOnly、allowedHttpHookUrls、httpHookAllowedEnvVars、disableWorkflows、workflowSizeGuideline
  • Plugin 與 Skill:enabledPlugins、extraKnownMarketplaces、strictKnownMarketplaces、blockedMarketplaces、pluginSuggestionMarketplaces、disableCommandPluginSources、strictPluginOnlyCustomization、disableBundledSkills、disableSkillShellExecution、skillOverrides、syncClaudeAiSkills/syncClaudeAiPlugins(v2.1.275+)
  • MCP:allowedMcpServers、deniedMcpServers、allowManagedMcpServersOnly、managedMcpServers、enableAllProjectMcpServers、enabledMcpjsonServers/disabledMcpjsonServers、allowAllClaudeAiMcps、disableClaudeAiConnectors
  • Agent、Session 與 Worktree:agent、disableAgentView、processWrapper(Corporate Launcher)、crossSessionInbound、isolatePeerMachines、teammateMode、worktree.baseRef/symlinkDirectories/sparsePaths/location
  • 遠端與通知:disableRemoteControl、remoteControlAtStartup、disableArtifact/enableArtifact、agentPushNotifEnabled、inputNeededNotifEnabled、disableDesktopLocalSessions
  • 認證與供應商:apiKeyHelper、awsAuthRefresh、awsCredentialExport、gcpAuthRefresh、otelHeadersHelper、forceLoginMethod、forceLoginOrgUUID、forceLoginGatewayUrl、allowedProviders(v2.1.285+)
  • 更新與版本:autoUpdatesChannel、minimumVersion、requiredMinimumVersion、requiredMaximumVersion
  • 企業與 Managed 專用:policyHelper、managedSourcesBehavior(v2.1.242+)、parentSettingsBehavior、wslInheritsWindowsSettings、disableSideloadFlags、forceRemoteSettingsRefresh
  • 隱私:cleanupPeriodDays(預設 30 天)、feedbackSurveyRate、feedbackDrafts

Corporate Launcher(processWrapper):與其整體關閉 Agent View(disableAgentView),企業可改用 processWrapper 為背景 Agent 監督程序(Supervisor)、其 Worker,以及其他受涵蓋的背景程序,強制加上一層企業要求的啟動包裝程式(例如企業自有的權限審查或稽核代理),在保留背景 Agent 能力的前提下納入既有的程序治理機制。

📌 實務建議:把團隊共同的安全防護(如禁止 rm -rf、禁止強制推送、禁止讀取 .env)寫進專案層級 .claude/settings.json 並提交版控,讓全隊自動套用,而不是靠口頭約定;但要記得專案設定可被任何有 commit 權限的人修改,真正的安全底線應放在 Managed 層級。

⚠️ 注意:Claude Code 對拼錯的鍵名不會報錯(例如 disallowAllHooks、sandbox.enable),只是靜默無效。這類錯誤肉眼很難看出,應以第30章的 check_settings.py 在 PR 中自動檢查。

實務案例:某團隊在專案層級設定中加入 permissions.deny 阻擋危險指令,個別開發者即使想在本機覆寫也無法移除(陣列合併只能增加不能刪除),避免了一次誤執行 git push --force 到共用分支的事故。

5.5 Managed Settings 交付機制

企業 Managed 設定並非單一檔案,而是依平台有不同交付管道,且彼此有明確優先序:

flowchart TD
    Remote["1. Server-managed<br/>(claude.ai 管理後台或 Claude apps gateway)"] --> Effective["最終生效設定"]
    Policy["2. 平台原生政策<br/>macOS plist / Windows HKLM Registry"] --> Effective
    FileBased["3. 檔案型<br/>managed-settings.json + managed-settings.d/*.json"] --> Effective
    HKCU["4. Windows HKCU Registry<br/>(免提權,優先序最低,不算 admin 來源)"] --> Effective
平台交付方式路徑/位置讀取時機
任何平台Server-managedclaude.ai 管理後台(Team/Enterprise),或自架 Claude apps gateway(可依 IdP 群組分派)啟動時取得,執行中每小時輪詢
macOS平台政策(plist)com.anthropic.claudecode 設定描述檔(Jamf 等 MDM 推送)啟動時讀取,每 30 分鐘檢查變更
Windows平台政策(Registry)HKLM\SOFTWARE\Policies\ClaudeCode 下名為 Settings 的 REG_SZ/REG_EXPAND_SZ 值(Intune、GPO 推送)同上
macOS檔案型/Library/Application Support/ClaudeCode/managed-settings.json啟動時讀取,檔案變更時重新載入
Linux/WSL檔案型/etc/claude-code/managed-settings.json同上
Windows檔案型C:\Program Files\ClaudeCode\managed-settings.json同上
Windows/WSLRegistry(使用者層級)HKCU\SOFTWARE\Policies\ClaudeCode只有在上方沒有任何 admin 文件時才使用

檔案型交付可額外放一個 managed-settings.d/ 目錄(與 managed-settings.json 同層),讓多個團隊各自維護一個片段檔,Claude Code 會合併讀取。C:\ProgramData\ClaudeCode\managed-settings.json 為已不再讀取的舊路徑,若團隊文件仍引用此路徑請更新。

Windows 上若在 HKLM 或 C:\Program Files\ClaudeCode 設定 wslInheritsWindowsSettings: true,可讓 Windows 端政策延伸套用到 WSL2;否則 WSL 只讀取 /etc/claude-code(而且該目錄在 WSL 內是使用者可寫的)。Desktop 在 Windows 上的 WSL2 Session 也走同一套解析路徑,且在偵測到組織管理的裝置上預設關閉(第28.1章)。若團隊使用 CrowdStrike Falcon 等端點偵測工具,WSL2 虛擬機內的程序對 Windows 端偵測感應器不可見,須依廠商指引另外在發行版內部署 Linux 感應器。

多個來源同時存在時怎麼合併? 預設行為(managedSourcesBehavior: "first-wins")是:依上表順序,取第一個帶有政策鍵的 admin 來源作為政策,其餘來源忽略——但有三個例外機制:

  • policyHelper:由 MDM 或檔案來源設定的本機輔助程式,動態運算出 Managed 設定內容;設定後其輸出取代原本選中的來源。
  • 跨來源讀取的鍵:少數安全關鍵鍵會從每一個 admin 來源讀取,例如 sandbox.network.allowManagedDomainsOnly、allowManagedMcpServersOnly、deniedMcpServers、maxEffortLevel(取最低值)、env(逐變數合併),避免某一層交付管道被繞過就整組防護失效。
  • managedSourcesBehavior: "merge"(v2.1.242+):讓所有 admin 來源依鍵的類型合併——清單合併、鎖定取最嚴格、允許清單(如 availableModels、allowedMcpServers)取最高來源的整份清單。只有在所有較低來源都在管理者控制之下時才應開啟。

Server-managed 設定會在登入時送達裝置,並在 Session 執行期間每小時刷新,不需要額外的端點基礎建設;但只有 claude.ai 組織的使用者會收到。若企業混用多種供應商,應同時部署 Server-managed 與檔案型/平台政策作為備援,或以第4.5.1章的 Claude apps gateway 讓第三方雲端也能取得 Server-managed 交付。

如何確認政策已生效:工程師在 Session 中執行 /status,看 Setting sources 這一行——出現 Enterprise managed settings 並在括號中標示來源:(remote)、(plist)、(HKLM)、(file)、(drop-ins)、(file + drop-ins)、(HKCU)、(helper),合併模式下則是以 , merged 結尾的清單;v2.1.242 起另有 Skipped sources 行列出「找到但被較高來源蓋過」的來源。

/status 顯示代表下一步
沒有 Setting sources 那一行沒有任何 Managed 來源帶有政策鍵檢查檔案路徑、內容是否只有控制鍵;Server-managed 則執行 claude doctor 看取得結果
括號中是別的來源有更高優先的來源蓋過你部署的來源看 Skipped sources,決定移除高優先來源或改用 merge
啟動直接失敗Managed 文件不是合法 JSON依錯誤訊息修正;Managed 檔案解析失敗會阻止啟動,而非靜默忽略

一份企業 Managed 設定範例(危險指令 deny 規則、強制 Hook、版本區間、模型與推理上限、Marketplace 允許清單、Sandbox 與遙測,已通過 check_settings.py --scope managed 與 SchemaStore schema 驗證;schema 唯一的差異是尚未收錄 onFailure):

{
  "permissions": {
    "defaultMode": "default",
    "disableBypassPermissionsMode": "disable",
    "deny": [
      "Bash(git push --force *)",
      "Bash(git push -f *)",
      "Bash(curl * | bash)",
      "Read(**/.env)",
      "Read(**/id_rsa*)"
    ]
  },
  "allowManagedHooksOnly": true,
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "/etc/claude-code/hooks/block-dangerous.sh",
            "timeout": 10,
            "onFailure": "block"
          }
        ]
      }
    ]
  },
  "maxEffortLevel": "xhigh",
  "availableModels": ["opus", "sonnet", "haiku"],
  "enforceAvailableModels": true,
  "minimumVersion": "2.1.325",
  "requiredMinimumVersion": "2.1.280",
  "autoUpdatesChannel": "stable",
  "strictKnownMarketplaces": [
    { "source": "github", "repo": "acme-corp/claude-plugins" }
  ],
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": false,
    "network": {
      "allowedDomains": ["registry.npmjs.org", "repo.maven.apache.org", "github.com"]
    }
  },
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_EXPORTER": "otlp",
    "OTEL_LOGS_EXPORTER": "otlp",
    "OTEL_EXPORTER_OTLP_PROTOCOL": "grpc",
    "OTEL_EXPORTER_OTLP_ENDPOINT": "http://otel-collector.corp.example:4317"
  },
  "companyAnnouncements": [
    "Claude Code 使用規範:https://wiki.corp.example/ai/claude-code"
  ]
}

📌 實務建議:跨平台團隊若選用檔案型交付,務必在三個平台路徑都放置內容一致的 managed-settings.json,並以第30章 check_settings.py --scope managed 在派送前驗證;官方另提供 Jamf、Intune、Group Policy 的範本(GitHub anthropics/claude-code 的 examples/mdm)。

⚠️ 注意:Server-managed 設定優先序最高且無法在本機以任何方式覆寫,IT 部門變更前應充分測試,否則一次錯誤推送會立即影響全公司所有工程師的 Session 行為。v2.1.316 起 Team/Enterprise 登入的 Server-managed 設定不再需要使用者核准即套用,測試的重要性更高(第28.6章)。

v3.0 對本範例的調整:加上 enforceAvailableModels: true(否則 /model 的 Default 不受白名單約束)、minimumVersion 提高到 2.1.325(包含 Bash 權限檢查與 Sandbox 的安全修正),並明確寫出 sandbox.autoAllowBashIfSandboxed(v2.1.324 起預設 false,要免詢問請改為 true,第19.5章)。

5.6 模型、Effort 與 Fallback 設定

模型別名:建議在設定與腳本中使用別名,讓模型隨官方建議版本自動演進;需要固定版本時才寫完整模型 ID。

別名行為(Anthropic API,2026-10)
default清除覆寫,回到帳號類型的預設模型:Pro/Max/Team/Enterprise/Anthropic API 皆為 Opus 5.5;Bedrock、Google Cloud、Claude Platform on AWS 亦為 Opus 5.5;Foundry 為 Sonnet 4.5
opus最新 Opus:Opus 5.5(claude-opus-5-5,需 v2.1.280+)
sonnet最新 Sonnet:Sonnet 5.5(claude-sonnet-5-5,需 v2.1.284+)
haikuHaiku 5.5(claude-haiku-5-5,需 v2.1.293+)
fableFable 5.2(claude-fable-5-2,需 v2.1.321+;Claude apps gateway Session 中仍解析為 Fable 5,需改用 /model claude-fable-5-2);最強、適合長時間自主任務,不是任何方案的預設,需明確選擇。要用 Fable 5.1 請寫完整 ID claude-fable-5-1
bestv2.1.321 起等同 opus(之前的版本在有 Fable 權限時等於 fable)
opusplanPlan 模式用 Opus、執行時切換 Sonnet
sonnet[1m]/opus[1m]強制 1M 上下文;目前的 Sonnet 5.5、Opus 4.7 以後已原生支援 1M,加上 [1m] 沒有額外效果

模型選擇的優先順序:Session 內 /model > --model > ANTHROPIC_MODEL > 設定檔 model > ANTHROPIC_DEFAULT_MODEL(v2.1.236+,設定「新 Session 起始模型」)> 帳號預設。注意 Managed 的 model 只是起始預設值而非鎖定,要限制可選模型必須用 availableModels/deniedModels;而且只設 availableModels 時,使用者在 /model 選 Default 仍會解析為帳號的執行期預設模型,要讓 Default 也受白名單約束,必須在 Managed 設定同時加上 enforceAvailableModels: true(白名單需非空,且至少一項確定可用)。

推理強度(Effort):

模型可用等級未設定時的預設
Fable 5.2、Opus 5.5、Sonnet 5.5、Haiku 5.5low/medium/high/xhigh/maxmedium
Fable 5.1/5、Opus 5、Sonnet 5、Opus 4.8low~maxhigh
Opus 4.7low~maxxhigh
Opus 4.6、Sonnet 4.6low/medium/high/max(無 xhigh)high

解析順序:CLAUDE_CODE_EFFORT_LEVEL/--effort//effort > 設定檔(modelSettings 中該模型的等級,或 effortLevel)> 模型預設。--effort 另接受 ultracode(等於 xhigh 並開啟自動 Workflow 編排,第26.3章)。/effort max 只對當次 Session 有效。

注意一個版本差異:使用者層級的 effortLevel 是 /effort 在 v2.1.251 以前寫入的舊格式,對 Opus 5.5 及之後的模型不生效(它們有自己的預設,直到你用 /effort 為該模型儲存等級);但專案、本機、Managed 設定或 --settings 中的 effortLevel 對所有模型都生效。

企業常用的模型治理設定:

{
  "availableModels": ["opus", "sonnet", "haiku"],
  "enforceAvailableModels": true,
  "deniedModels": ["claude-opus-4-6"],
  "maxEffortLevel": "xhigh",
  "fallbackModel": ["sonnet", "haiku"],
  "modelSettings": {
    "claude-haiku-5-5": { "maxEffortLevel": "high" }
  }
}
  • maxEffortLevel 由 Claude Code 在送出請求前自行套用,因此在 Bedrock/Google Cloud/Foundry 上也有效(Enterprise 後台的伺服器端 Effort 上限則不涵蓋這些供應商,第28.3.1章);多個層級都有設定時取最低值。
  • fallbackModel 在主要模型過載或下架時依序嘗試,最多三個;它不跨層合併,取最高層的整條鏈。
  • 第三方供應商需要把模型 ID 對應到 inference profile 時,用 modelOverrides:
{
  "modelOverrides": {
    "claude-opus-5-5": "arn:aws:bedrock:us-east-1:123456789012:inference-profile/opus-prod"
  }
}
  • modelPicker 自訂 /model 選單顯示的模型與標籤(只從 managed、--settings、user 讀取,避免 clone 下來的 repo 竄改選單)。

5.7 互動調整與單次 Session 覆寫

目的做法寫入位置
從選單改常用個人選項Session 內 /config多數寫入 ~/.claude/settings.json;少數(如 Show tips)寫入 .claude/settings.local.json;全域選項寫入 ~/.claude.json
不開選單直接設定/config verbose=true(也可在 -p 與 Remote Control 中使用)同上
只在這次 Session 試用某值claude --settings '{"effortLevel":"low"}' 或 --settings ./try.json(檔案 ≤ 2 MiB)不寫檔,優先於 user/project/local、低於 managed
以旗標覆寫單一功能--model、--effort、--permission-mode 等不寫檔
讓 Claude 代為修改設定/update-config 允許 npm run testClaude 編輯對應的設定檔,你審核 diff

改完之後,用 /status 確認 Setting sources 列出了你預期的檔案;若檔案有錯,互動模式會顯示 Settings Error(整檔無效)或 Settings Warning(個別項目被略過),再用 claude doctor 看每個錯誤的細節。

# 先以 --settings 試用,確認行為後再寫入專案設定
claude --settings '{"permissions":{"deny":["Bash(npm publish *)"]}}'

5.8 設定鍵補遺:v2.1.300~v2.1.327 新增、移除與範圍限制(v3.0 新增)

官方 Settings reference 目前列出 249 個鍵與子鍵(v2.0 為約 245 個)。本節只整理企業治理需要知道的部分;完整清單以第30章附帶、本次重新擷取的 settings-keys.txt 為準。

新增或本次補充說明的治理鍵:

鍵版本作用可設定的層級
permissions.denyInsteadOfPromptingv2.1.319會等待權限詢問的工具呼叫改為直接拒絕,回合繼續(終端機 Session、Subagent、Teammate)使用者、Managed、--settings;repo 不可設定
permissions.blockWritesOutsideWorkingDirectoriesv2.1.314Write/Edit/NotebookEdit 在**所有權限模式(含 bypass)**拒絕寫到工作目錄外;同時移除 EnterWorktree/ExitWorktree 工具。不限制 Shell、MCP 與 Hook任何檔案;任一檔案設 true 即生效,repo 只能開不能關
enforceAvailableModels文件釐清讓 /model 的 Default 也受 availableModels 約束Managed
sandbox.network.strictAllowlist—白名單外的主機直接拒絕,不再詢問使用者、Managed、--settings
sandbox.allowNestedUserNamespacesv2.1.305Linux 沙箱內允許建立 user namespace(Chromium、rootless podman);會讓程式碼有機會跑到沙箱外使用者(repo 不可開)
subagentPromptCacheTtl—Subagent、Workflow 與背景請求的 Prompt Cache 存活時間 "5m"/"1h"任何檔案
switchModelsOnFlag—安全分類器標記請求時自動換模型(true)或暫停詢問(false;-p 中會直接以錯誤結束)任何檔案
enableWorkflows/workflowKeywordTriggerEnabled—個人開關 Dynamic Workflows;關閉 ultracode 關鍵字觸發。全組織關閉用 disableWorkflows任何檔案
pluginTrustMessage—在 Plugin 信任警告中加入組織說明Managed
worktree.bgIsolation—背景 Session 是否必須先進 Worktree 才能編輯("worktree" 預設/"none")任何檔案
advisorModel—Advisor 工具的預設模型(第31.5章)任何檔案

已移除或棄用、寫了也不會生效的鍵:

鍵狀態替代做法
subagentStatusLinev2.1.323 移除(設定檔仍可載入)Subagent 列一律使用預設外觀
pluginDigestsv2.1.325 棄用並忽略Managed 設定宣告、啟用並列在 prependPlugins/appendPlugins 的遠端 Marketplace Plugin 視為組織所有
teammateDefaultModelv2.1.234 移除見 Agent Teams 的模型指定方式
taskOutputMaxCharsv2.1.277 移除—
permissionExplainerEnabledv2.1.257 移除—
includeCoAuthoredBy棄用attribution
keybindingFlavor棄用、無作用—

專案層級(repo 內的 .claude/settings*.json)不會生效的設定,是審查 PR 時最容易漏掉的一類:除了本節第一張表中標示「repo 不可設定」的鍵,env 區塊中凡是決定 Claude Code 寫檔位置(CLAUDE_CONFIG_DIR、CLAUDE_CODE_TMPDIR)、開啟或導向遙測(CLAUDE_CODE_ENABLE_TELEMETRY、OTEL_EXPORTER_OTLP_*、OTEL_LOG_*)、登入憑證(CLAUDE_CODE_OAUTH_TOKEN)、啟動包裝(CLAUDE_CODE_PROCESS_WRAPPER)與 Code Mode(CLAUDE_CODE_EXPERIMENTAL_CODE_MODE)的變數都會被丟棄。這是刻意的安全設計:clone 下來的 repo 不能把你的遙測導向外部端點,也不能替你打開實驗功能。

以下是一份已通過 check_settings.py --scope managed 與 check_upgrade.py 的 v3.0 Managed 設定範例:

{
  "permissions": {
    "denyInsteadOfPrompting": true,
    "blockWritesOutsideWorkingDirectories": true,
    "deny": ["Bash(git push --force *)", "Read(./.env)"]
  },
  "sandbox": {
    "enabled": true,
    "failIfUnavailable": true,
    "autoAllowBashIfSandboxed": true,
    "network": {
      "strictAllowlist": true,
      "allowedDomains": ["registry.npmjs.org", "github.com"]
    }
  },
  "availableModels": ["opus", "sonnet", "haiku"],
  "enforceAvailableModels": true,
  "allowedProviders": ["anthropic", "anthropicGoogleCloud"],
  "pluginTrustMessage": "內部 Marketplace 的 Plugin 皆已通過資安審查",
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_CODE_MODE": "0",
    "HTTPS_PROXY": "http://proxy.corp.example:8080"
  }
}

逐項說明審查重點:denyInsteadOfPrompting 與 blockWritesOutsideWorkingDirectories 放在 Managed 才能保證不被個人設定關閉;autoAllowBashIfSandboxed 明確寫出;enforceAvailableModels 搭配非空白名單;CLAUDE_CODE_EXPERIMENTAL_CODE_MODE: "0" 封鎖 Code Mode;代理使用 HTTPS_PROXY 而非只用 ALL_PROXY。

5.9 本章審查與驗證清單

AI 產出項目❌ 常見錯誤✅ 正確做法人工如何驗證
settings.json 內容在 JSON 中寫 // 註解或尾逗號嚴格 JSON;說明放在 PR 描述或旁邊的 READMEpython -m json.tool settings.json;或第30章 check_settings.py
設定鍵名稱拼錯(disallowAllHooks、sandbox.enable)或發明不存在的鍵對照官方 Settings reference 的鍵名check_settings.py 會列出未知鍵;/status 看 Settings Warning
權限規則寫成 Bash(rm -rf:*) 以為能擋所有刪除了解 Bash 規則是字串比對,關鍵防線應搭配 Hook 與 Sandbox(第12、19章)以第12章 harness 實測變形指令(如 rm -fr /)
專案層級 defaultMode在 .claude/settings.json 設 "auto" 或 "bypassPermissions"這兩個值在專案/本機設定不生效,需放 user 或 managedcheck_settings.py --scope project 會警告;/status 看實際模式
模型治理以 Managed 的 model 當成「鎖定模型」;或只設 availableModels 就以為 Default 也被鎖住鎖定要用 availableModels/deniedModels,並加 enforceAvailableModels: true 讓 Default 也受約束;model 只是起始預設以一般帳號執行 /model 嘗試切到不允許的模型,並選 Default 看實際模型;-p --output-format json 的 modelUsage 鍵名就是實際使用的模型
Managed 交付同時部署 Server-managed 與檔案型,以為兩者會合併預設 first-wins;需要合併時明確設定 managedSourcesBehavior: "merge"/status 看 Setting sources 與 Skipped sources
effortLevel 設定在使用者設定寫 effortLevel 期待 Opus 5.5 生效用 /effort 為該模型儲存等級,或寫在專案/Managed 設定/effort status 確認目前等級
新治理鍵的層級把 denyInsteadOfPrompting、strictAllowlist 寫進 repo 的 .claude/settings.json 期待全員生效這些鍵只認使用者、Managed 或 --settings;全員生效要放 Managedcheck_settings.py --scope project 會對這些鍵發出警告
已移除的鍵沿用舊範本中的 subagentStatusLine、pluginDigests依第5.8節對照表改用替代做法,或直接刪除check_settings.py 對已移除鍵報錯、棄用鍵警告;check_upgrade.py 標示 BREAK
repo 內的 env在專案設定的 env 開遙測、改 OTLP 端點或打開 Code Mode這些變數在專案層級會被丟棄;需要時放使用者或 Managed 設定check_settings.py --scope project 會警告;/status 或 claude doctor 會列出被忽略的變數名稱

第 6 章 CLI 指令大全

本章目標:熟悉 claude 的子指令、常用旗標、Slash Commands,以及六種權限模式與 Auto Mode 的運作與治理方式。本章所有旗標都已與 Claude Code v2.1.296 的 claude --help(v3.0 再以 v2.1.327 重新比對,新增與移除項目見第6.8章) 及官方 CLI reference 逐一比對;讀完後,你應該能寫出正確的指令組合,並能判斷 AI 給你的指令是否存在、是否用錯情境。

6.1 指令依生命週期分類

graph LR
    A["安裝與認證<br/>install / update / auth / doctor"] --> B["Session 操作<br/>claude / -p / -c / -r"]
    B --> C["背景與多 Session<br/>agents / --bg / attach / logs"]
    C --> D["擴充與整合<br/>mcp / plugin / gateway"]
    D --> E["維運與清理<br/>daemon / respawn / rm / purge"]

claude --help 只列出常用旗標,沒出現在 --help 不代表不存在(例如 --teammate-mode、--system-prompt-file 就沒有列出);反過來,AI 產生的旗標若在 --help 與官方 CLI reference 都找不到,就應視為幻覺。第30章的 check_flags.py 會自動做這項比對。

6.2 Session 操作

指令說明範例
claude啟動互動式 Sessionclaude
claude "query"啟動並帶入初始提示claude "幫我看一下這個錯誤訊息"
claude -p "query"非互動模式,印出結果後結束,適合腳本/CI(第29章)claude -p "總結最近的變更" --output-format json
cat file | claude -p "query"處理管線輸入內容cat error.log | claude -p "解釋這個錯誤"
claude -c繼續目前目錄最近一次對話(含已結束的背景 Session)claude -c
claude -c -p "query"以非互動模式繼續對話claude -c -p "檢查是否有型別錯誤"
claude -r "<session>" "query"依 ID、名稱或 .jsonl 檔絕對路徑回復對話;回復仍在執行的背景 Session 會直接附著claude -r "auth-refactor" "繼續完成這個 PR"
claude --bg "query"以背景 Session 啟動並立即返回,印出 Session ID(不可與 -p 併用)claude --bg "調查不穩定的測試"
claude --desktop在 Claude Desktop 開啟目前目錄(搭配 -c 或 -r <id> 開啟該 Session),v2.1.285+claude --desktop -c
claude update更新 CLI 本身至所選通道最新版claude update
claude install [version]安裝/重新安裝原生執行檔,可指定版本號、stable 或 latestclaude install stable

若指令打錯字,Claude Code 會直接提示最接近的正確指令並結束(例如 claude udpate 會印出 Did you mean claude update?),不會誤啟動一個以錯字為提示詞的 Session。

6.3 Agent 管理

背景 Session 由一個常駐的監督程序(Supervisor)託管,以下指令都作用在背景 Session(第9.5章):

指令說明
claude agents開啟 Agent View,監看與派發背景 Session;--cwd <path> 只顯示該目錄啟動的 Session、--json 以 JSON 輸出(加 --all 含已結束的,不需 TTY)、--permission-mode/--model/--effort/--agent 設定派發 Session 的預設值
claude attach <id|name>在目前終端機附著到背景 Session;v2.1.290 起可用名稱的一部分
claude logs <id|name>印出背景 Session 的最新輸出
claude stop <id>停止背景 Session(別名 claude kill),對話保留,可再 attach 或 --resume
claude respawn <id>重新啟動背景 Session(執行中或已停止皆可);--all 重啟所有執行中 Session,用於套用更新後的版本
claude rm <id>從清單移除 Session,安全時一併刪除其 Worktree;Worktree 有未推送 commit 被拒時,依提示加 --discard-unpushed(v2.1.260+)或 --force-remove-worktree(v2.1.268+)。對話紀錄仍保留在本機
claude daemon status印出 Supervisor 狀態、版本、Socket 目錄與 worker 數量;未執行時 exit 1
claude daemon logs持續輸出 Supervisor 日誌(~/.claude/daemon.log)
claude daemon run在前景執行 Supervisor 並印出日誌(除錯用)
claude daemon stop --any [--keep-workers]停止 Supervisor;加 --keep-workers 保留背景 Session 讓下一個 Supervisor 重新接手

6.4 MCP / Plugin / 專案維護

指令說明
claude mcp add --transport http <name> <url>新增遠端 MCP Server;stdio 用 claude mcp add <name> -e KEY=v -- <command>;--scope local|project|user 決定寫入位置(第13章)
claude mcp add-json <name> '<json>'以 JSON 新增 Server(stdio/SSE/HTTP/WebSocket);v2.1.327 起 <json> 可寫成 - 從 stdin 讀取,讓 Token 不出現在指令列(在 Claude Code Session 內執行會被拒絕,第13.7章)
claude mcp list/get <name>/remove <name>列出、查看(含健康檢查)、移除;未核准的 .mcp.json Server 顯示為 ⏸ Pending approval
claude mcp login <name>/logout <name>不開 /mcp 面板直接完成或清除 OAuth;SSH 遠端加 --no-browser
claude mcp reset-project-choices重設本專案對 .mcp.json Server 的核准/拒絕選擇
claude mcp serve把 Claude Code 本身當成 MCP Server 提供給其他客戶端
claude plugin install <plugin>[@marketplace]安裝 Plugin;--marketplace <source>(v2.1.292+)可先加入 Marketplace 再安裝;--json 以單一 JSON 物件輸出結果
claude plugin list/details <name>/enable/disable/update/uninstall管理 Plugin;details 會顯示元件清單與預估 Token 成本
claude plugin marketplace ...管理 Marketplace 來源
claude plugin validate <path>驗證 Plugin 或 Marketplace manifest,以及目錄中的 skills/agents/commands
claude plugin eval [target]/eval init以測試案例評分 Plugin,並與「不載入 Plugin」的基準比較(v2.1.269+,第27.6章)
claude plugin init <name>在 ~/.claude/skills/<name>/ 建立 Plugin 骨架
claude purge [path]刪除某專案在本機的所有 Claude Code 狀態(Transcript、任務清單、除錯日誌、檔案編輯歷史、~/.claude.json 中的專案項目);--dry-run 預覽、-y 略過確認、-i 逐項確認、--all 所有專案
claude ultrareview [target]非互動式雲端多 Agent 程式碼審查,成功 exit 0/失敗 exit 1;--json 取原始資料、--timeout <分鐘> 覆寫預設 45 分鐘;對 github.com PR 加 --post 把結果貼成 PR 留言(v2.1.227+)
claude auto-mode defaults [--label <prefix>]印出 Auto Mode 分類器內建規則(JSON),--label 依規則名稱前綴篩選
claude auto-mode config印出套用目前設定後的實際生效規則
claude auto-mode reset [-y]從使用者設定檔移除 autoMode 區段、恢復預設(Managed 與 --settings 的規則仍然有效)
claude remote-control以伺服器模式啟動 Remote Control,供 claude.ai 或手機 App 操控
claude gateway --config gateway.yaml啟動自架 Claude apps gateway(第4.5.1章)
claude doctor(Session 內 /doctor,別名 /checkup)終端機版為唯讀診斷(安裝、設定檔驗證錯誤、Remote Control 資格);Session 內的 /doctor 可診斷並在你同意後修正,/doctor prompt-audit 會檢查 CLAUDE.md、Skill、Agent 是否還在用針對舊模型的寫法(v2.1.283+)
claude import [codex|gemini]啟動執行 /import 的互動 Session,從 Codex CLI 或 Gemini CLI 匯入設定;--dry-run 預覽
claude self-hosted-runner setup/doctor/orchestrator建置、健檢自架執行環境,orchestrator 依需求啟動 runner(第1.6章)
claude setup-token產生一年效期的 OAuth Token 給 CI 使用(第4.3章)

⚠️ 勘誤:v1.3 寫的 claude project purge 已改為 claude purge;claude auto-mode reset 的作用是「移除使用者設定中的 autoMode 區段」,並非 v1.3 所說的「清除本機已快取的分類器判斷結果」;claude ultrareview 預設逾時為 45 分鐘(v1.3 寫 30 分鐘)。

6.5 常用旗標(Flags)

以下依用途分類整理;版本註記為該旗標或行為的最低版本。

Session 與輸出控制

旗標說明
--continue / -c繼續目前目錄最近一次對話
--resume / -r依 ID、名稱或 Transcript 路徑回復對話,或開啟互動式選單(背景 Session 標示 bg)
--fork-session搭配 --resume/--continue,建立新 Session ID 而非沿用原 ID
--name / -n設定 Session 顯示名稱,之後可用 claude -r <name> 回復
--session-id <uuid>指定 UUID 作為 Session ID
--from-pr <PR>開啟篩選出與某 PR 相關的 Session 選單(接受 PR 編號、GitHub/GitHub Enterprise/Bitbucket PR 網址或 GitLab MR 網址)
--print / -p非互動模式;工作區信任對話框會被略過,且設定檔驗證失敗時靜默忽略,只應在信任的目錄使用
--output-format text|json|stream-json輸出格式(僅 -p)
--input-format text|stream-json輸入格式(僅 -p)
--json-schema <schema>完成後輸出符合 JSON Schema 的結構化結果,放在 structured_output 欄位(僅 -p)
--include-partial-messages/--include-hook-events/--forward-subagent-text在 stream-json 中額外輸出部分訊息、Hook 事件、Subagent 文字(第29章)
--no-session-persistence不把 Session 寫入磁碟(僅 -p)
--verbose顯示完整逐輪過程
--bare最小模式:略過 Hooks、Skills、Plugins、MCP、Auto Memory、CLAUDE.md 的自動探索,只保留 Bash/讀檔/編輯工具,啟動更快;認證只接受 ANTHROPIC_API_KEY 或 --settings 指定的 apiKeyHelper
--safe-mode停用所有客製化(CLAUDE.md、Skills、Plugins、Hooks、MCP、自訂指令與 Agent、Output Styles、Workflows、主題、鍵盤綁定、狀態列、LSP、Auto Memory)以排查設定問題;認證、模型、內建工具與權限照常,Managed 政策仍套用
--restricted受限模式(v2.1.248+):移除會執行指令或程式碼的內建工具與 WebFetch(除非在 --tools 逐一指名)、檔案工具限縮在工作目錄、只載入 Managed 與 --settings、拒絕 bypassPermissions,適合在共用機器上跑評估腳本
--autocompact <auto|tokens>只對本次 Session 設定自動壓縮門檻,例如 500k(v2.1.221+)
--debug [filter]/--debug-file <path>除錯模式,可篩選類別(例如 --debug='mcp,startup')

Agent 與 Subagent

旗標說明
--agent <name>指定某個 Subagent 定義接管整個主 Session(覆寫 agent 設定)
--agents '<json>'以 JSON 動態定義當次 Session 的 Subagent;-p 模式可改傳 JSON 檔路徑(v2.1.281+);啟動時會驗證,無效即結束(v2.1.242+)
--bg / --background以背景 Agent 啟動並立即返回;可搭配 --exec '<cmd>' 改跑 Shell 背景工作,或 --agent 指定 Subagent;不可與 -p 併用
--worktree [name] / -w在 <repo>/.claude/worktrees/<name> 建立隔離的 Git Worktree 啟動 Session;也可傳 #<PR編號>、GitHub PR 網址或 GitLab MR 網址(v2.1.233+)從該 PR 分支
--tmux搭配 --worktree 建立 tmux Session;有 iTerm2 時改用原生分頁,--tmux=classic 強制傳統 tmux
--teammate-mode in-process|auto|tmux|iterm2Agent Teams 隊友的顯示方式(實驗性,不在 --help 中,第9.6章)
--append-subagent-system-prompt <text>/-file <path>附加文字到每一個 Subagent(含巢狀,但不含 Fork)的系統提示,僅限 -p
--channels <list>(研究預覽)指定要監聽通知的 Channel,格式為 plugin:<name>@<marketplace>

權限與安全

旗標說明
--permission-mode <mode>以指定權限模式啟動:default(介面名稱 Manual,也可寫 manual)、acceptEdits、plan、auto、dontAsk、bypassPermissions(第6.6章)
--dangerously-skip-permissions等同 --permission-mode bypassPermissions
--allow-dangerously-skip-permissions只把 bypassPermissions 加入 Shift+Tab 循環,不會一啟動就進入,比上一個保守
--allowedTools / --allowed-tools免詢問即可執行的規則,例如 "Bash(git log *)" Read
--disallowedTools / --disallowed-tools拒絕規則;裸工具名稱會整個移除該工具("Edit"、"mcp__*"),Bash(rm *) 這類範圍化規則則只擋符合的呼叫
--tools <list>限制本次可用的內建工具集合("" 全部停用、"default" 預設集合、或清單如 "Bash,Edit,Read");不影響 MCP 工具
--permission-prompt-tool <mcp tool>指定一個 MCP 工具接手 -p 模式下的權限詢問
--permission-prompts host|none-p 模式由誰回答權限詢問;none 代表沒人回答、會詢問的動作一律拒絕(v2.1.259+)

MCP/Plugin

旗標說明
--mcp-config <file|json...>載入指定 JSON 中的 MCP 設定;搭配 -p 時會等待尚未連上的 Server,最多 MCP_TIMEOUT(預設 30 秒)
--strict-mcp-config只使用 --mcp-config 指定的 MCP Server,忽略其他來源
--plugin-dir <path>從本機目錄或 .zip 載入 Plugin,僅限本次 Session;可重複指定;v2.1.265 起可指向「多個 Plugin 的資料夾」
--plugin-url <url>從 URL 抓取 .zip Plugin,僅限本次 Session

系統提示(System Prompt)

旗標行為適用時機
--system-prompt <text>完全取代預設系統提示非「編碼助理」定位、無人值守的自訂 Agent
--system-prompt-file <path>以檔案內容取代預設系統提示同上,內容較長時使用
--append-system-prompt <text>附加在預設系統提示之後保留內建工具指引與安全規則,只補充規則
--append-system-prompt-file <path>附加檔案內容同上,內容較長時使用
--system-prompt-snapshot on|offon(預設):對話第一次請求時記錄系統提示,之後(含 --resume)沿用直到壓縮;off:每次重建,方便反覆調整提示文字(v2.1.257+)迭代調整提示文字時

取代類與附加類可以並用;v2.1.283 起同一旗標的文字版與檔案版也可並用。在自訂提示中放一行 __SYSTEM_PROMPT_DYNAMIC_BOUNDARY__,可讓上方固定內容留在 Prompt Cache、下方每次變動(v2.1.275+)。需要跨 Session 沿用的角色設定改用 Output Styles,每次都要套用的專案規則則寫進 CLAUDE.md(第11章)。

其他常用旗標

旗標說明
--add-dir <path...>加入額外工作目錄,只授予檔案存取權,.claude/ 下大部分設定不會從該目錄載入;例外是 .claude/agents/ 與 Skills(第10.2章)。要跨 Session 保留請設定 permissions.additionalDirectories
--max-turns <n>限制自動化輪數(僅 -p),達上限即以錯誤結束
--max-budget-usd <amount>依客戶端估算成本限制花費(僅 -p);Subagent 花費也計入,實際可能略為超過,需保留餘裕
--effort low|medium|high|xhigh|max|ultracode本次 Session 推理強度;ultracode 等於 xhigh 並開啟自動 Workflow 編排(v2.1.203+)
--model <name>指定模型:別名 sonnet/opus/haiku/fable/best 或完整模型 ID(如 claude-opus-5-5)
--fallback-model <list>主要模型過載或下架時依序嘗試的備援模型(逗號分隔)
--advisor <model>為本次 Session 啟用伺服器端 Advisor 工具
--chrome / --no-chrome啟用/停用 Claude in Chrome 整合
--ide若剛好只有一個可用 IDE,啟動時自動連接
--init / --init-only / --maintenance執行 Setup Hooks:--init(init matcher,僅 -p)、--init-only(執行完 Setup 與 SessionStart Hooks 即結束)、--maintenance(maintenance matcher)
--cloud "<task>"在 claude.ai 建立雲端 Session;改傳 Session ID(session_.../cse_...)或網址並加 -p,則把訊息排入該 Session
--remote "<task>"已棄用,--cloud 的相容別名
--environment <ccpool_...> / --ref <branch>在指定的自架執行環境建立雲端 Session,可指定 checkout 的分支(v2.1.224+)
--teleport把雲端 Session 拉回本機終端機繼續
--remote-control [name] / --rc啟動互動式 Session 並同時開啟 Remote Control
--settings <file|json>以檔案或內嵌 JSON 覆寫當次 Session 的設定鍵值(第5.7章)
--setting-sources user,project,local指定要載入的設定來源
--ax-screen-reader螢幕報讀器友善輸出(平面文字、無裝飾邊框與動畫)
--disable-slash-commands停用本次 Session 的所有 Skill 與指令
# 在獨立 worktree + tmux 中啟動一個不影響目前工作目錄的平行任務
claude -w billing-fix --tmux

# 問題排查:暫時停用所有客製化,確認是否為 CLAUDE.md/Hook/Plugin 造成異常
claude --safe-mode

# 大量腳本化呼叫追求啟動速度,略過自動探索
claude --bare -p "回傳這段輸入的 JSON schema"

# 在共用機器跑評估:不能執行指令、不讀使用者與專案設定
claude --restricted -p "讀取 README.md 並摘要"
# CI 腳本中安全地呼叫 Claude Code:限制成本與輪數、無人回答的權限詢問一律拒絕、輸出 JSON 方便解析
claude -p "檢查這次變更是否有明顯的安全風險" \
  --output-format json \
  --permission-mode plan \
  --permission-prompts none \
  --max-turns 10 \
  --max-budget-usd 1.0

📌 實務建議:任何自動化/CI 情境都應同時設定 --max-turns 與 --max-budget-usd,避免一個邊界條件讓 Agent 進入長時間迴圈而失控燒費用;完整的 CI 範本與結果解析腳本見第29章。

⚠️ 注意:--permission-mode bypassPermissions 在自動化環境中很方便,但等同於關閉安全閥,只應在與主機隔離的容器或 VM 中使用;企業可用 permissions.disableBypassPermissionsMode: "disable" 強制關閉此模式。

實務案例:團隊建立一個夜間排程腳本,用 claude -p ... --output-format json --json-schema ... 產出當日程式碼健康報告,再用 jq 檢查 is_error 與結構化欄位後才送到 Slack;某次 Claude 因達到 --max-turns 而以 error_max_turns 結束,腳本正確地把它當成失敗而非空報告。

6.6 權限模式與 Auto Mode(自動權限分類器)

⚠️ 重大變更:自 v2.1.283(2026-09-25) 起,終端機與 VS Code 擴充套件的互動 Session,其「內建起始權限模式」在所有方案與供應商上一律為 auto(較早版本只有 Pro/Max/Team 自 2026-08-14 起預設為 auto)。claude -p 與 Agent SDK 在會抓取 feature flag 的 Session 仍以 default 起始。組織可用 permissions.defaultMode 改指定起始模式,或用 disableAutoMode: "disable" 完全移除 Auto Mode(第6.6.2章)。企業導入團隊應主動檢視這個預設值是否符合風險胃納,而不是被動接受。

Claude Code 共有 6 種權限模式,終端機以 Shift+Tab 循環切換(Windows 部分環境為 Alt+M),IDE/Desktop 用介面上的模式選單:

模式(設定值)介面名稱免詢問即可執行的動作適用情境
default(別名 manual)Manual僅讀取逐一審核每個動作、處理敏感程式碼
acceptEditsAccept edits讀取+檔案編輯+常見檔案系統指令(mkdir、touch、mv、cp 等)一邊看 diff 一邊迭代
planPlan讀取;可用 Auto Mode 時,另含分類器核准的指令修改前先研究、規劃
autoAuto幾乎所有動作,改由背景分類器審核長任務、減少權限詢問疲勞
dontAskDon’t ask工作目錄內讀檔與預先允許的工具;其餘會詢問的動作一律拒絕鎖定的 CI/腳本
bypassPermissionsBypass所有動作僅限與主機隔離的容器、VM

⚠️ 勘誤:v1.3 把 default 模式稱為「預設模式」;自 v2.1.200 起介面一律稱為 Manual,claude --help 也只列出 manual。設定檔、Hook 輸入(permission_mode)與 SDK 仍使用 default,兩個值都可用。

任何模式都不會自動核准的動作(包括 bypassPermissions):明確的 ask 規則、需要使用者互動的工具(如 AskUserQuestion)、以 rm/rmdir 刪除關鍵路徑(Critical Paths:檔案系統根目錄、頂層目錄如 /usr、家目錄、工作目錄及其上層、Windows 磁碟根目錄等,任何 allow 規則或 Hook 的 allow 都無法核准)。permissions.deny 規則在所有模式都生效。

另有一組受保護路徑(Protected Paths)——.git、.claude(.claude/worktrees 除外)、.vscode、.idea、.husky、.devcontainer 等目錄,以及 Shell 設定檔、套件管理器設定檔等——除了 bypassPermissions 之外,任何模式都不會自動核准寫入(auto 模式下改交給分類器審核、dontAsk 下直接拒絕)。

claude --permission-mode plan          # 以 Plan 模式啟動
claude --permission-mode manual        # 以 Manual(default)模式啟動
claude auto-mode defaults              # 印出分類器內建規則
claude auto-mode config                # 印出套用目前設定後的實際生效規則

6.6.1 Auto Mode 分類器運作方式

Auto Mode 不是「全部允許」,而是由一個獨立於 /model 選擇的分類器模型,在每次動作執行前先行審核。審核順序固定,第一個符合的步驟決定結果:

  1. 符合 allow/ask/deny 規則者立即依規則處理——例外:寫入受保護路徑仍送分類器;刪除關鍵路徑不會被 allow 規則核准;依指令內容比對的 ask 規則(如 Bash(git push *))改為詢問你。
  2. 唯讀動作與工作目錄內的檔案編輯自動放行(受保護路徑與「第一次讀取工作目錄外的檔案」除外)。
  3. 其餘動作送進分類器判斷。
  4. 分類器封鎖時,Claude 會收到理由;多數情況下理由會直接寫出命中的規則名稱,例如 [Data Exfiltration]。

分類器看得到使用者訊息、工具呼叫與 CLAUDE.md,看不到工具執行結果,用意是避免被檔案或網頁中夾帶的惡意內容(Prompt Injection)反過來操控判斷;Claude 透過 SendMessage 傳給其他 Agent 的訊息也會先經分類器審核。

  • 預設封鎖(節錄):下載並執行程式碼(curl | bash)、把敏感資料送往外部、正式環境部署與遷移、雲端儲存大量刪除、授予 IAM 或 repo 權限、強制推送、git reset --hard/git checkout -- ./git clean -fd 等會丟棄未提交變更的指令、對非本次 Session 建立或已推送的 commit 執行 --amend、terraform destroy 等、合併沒有人工核准的 PR、切換正式環境 Feature Flag、把即時憑證印到 Transcript、改寫 Session Transcript、以未賦值的變數執行遞迴強制刪除;v2.1.257 起還會封鎖向雲端 metadata 端點(169.254.169.254)索取憑證、掃描非自己啟動的容器或節點等。
  • 預設允許:工作目錄內的本機檔案操作、依 lock 檔安裝相依套件、讀取 .env 並送給對應的 API、唯讀 HTTP 請求、推送到目前 repo 的任一分支(包含預設分支)——但名稱看起來是部署目標的分支(如 production、gh-pages)會另外判斷。
  • 對話中聲明的邊界會被當作封鎖訊號:例如你說「先別 push」,分類器會據此擋下對應動作;但這類邊界只存在於對話紀錄中,壓縮後可能遺失,真正需要保證擋下的規則仍應寫成 deny 規則或 Hook。
  • 失敗退回機制:分類器連續 3 次或累計 20 次封鎖後(不可調整),Auto Mode 暫停並改回逐次詢問,核准一次後恢復。被封鎖的動作會列在 /permissions 的 Recently denied 分頁,可按 r 以人工核准重試。-p 非互動模式沒有可退回的詢問:達到門檻時該動作不執行,但 Claude 會繼續工作,Session 不會中止。

⚠️ 勘誤:v1.3 寫「Auto Mode 預設封鎖直接推送到 main」,目前官方預設允許推送到工作中 repo 的任何分支(含預設分支),需要禁止時請自行寫 deny/ask 規則或 Hook;v1.3 另寫「-p 模式達門檻會直接中止 Session」,目前行為是不執行該動作並繼續。

6.6.2 啟用條件與企業治理

條件說明
方案所有方案皆可使用;Team/Enterprise 預設開放,管理者可用 Managed 設定 permissions.disableAutoMode: "disable" 關閉
模型Anthropic API 與 Claude Platform on AWS:Opus 4.6+、Sonnet 4.6+、Haiku 5.5 或 Fable;Bedrock/Google Cloud/Foundry/Claude apps gateway:僅特定機型,以官方文件為準
供應商Anthropic API、Claude Platform on AWS、Bedrock、Google Cloud’s Agent Platform、Microsoft Foundry、已登入的 Claude apps gateway 皆預設可用(第三方供應商自 v2.1.207 起不再需要 CLAUDE_CODE_ENABLE_AUTO_MODE=1)
起始模式依序:--permission-mode/--dangerously-skip-permissions → 設定檔 permissions.defaultMode → 內建預設(見下表)
指定其他起始模式在 user 或 Managed 設定 permissions.defaultMode;注意 "auto" 與 "bypassPermissions" 寫在專案的 .claude/settings.json/.claude/settings.local.json 不會生效
企業鎖定disableAutoMode(或 permissions.disableAutoMode)設為 "disable":自 Shift+Tab 循環移除 auto,任何會以 auto 起始的 Session 改以 default 起始

內建起始模式(沒有旗標與 defaultMode 時,取第一個符合的列):

執行方式內建起始模式
任何設定檔設了 disableAutoMode: "disable"default
claude -p 或 Agent SDK會抓取 feature flag 的 Session 為 default;不抓取者(第三方供應商、關閉遙測)在 v2.1.285+ 為 auto
組織套用 HIPAA 設定default(v2.1.285+),仍可切換到 auto
終端機或 VS Code 擴充套件v2.1.283+ 為 auto;更早版本只有 Pro/Max/Team 為 auto
{
  "permissions": { "defaultMode": "acceptEdits" }
}

📌 實務建議:對於互動式開發,Auto Mode 通常是比 Manual 更實用的折衷;但企業層級仍應以 deny 規則、Hook 與 Sandbox 明確定義「即使分類器判斷為低風險也一律禁止」的動作(例如對受保護分支的推送),因為分類器仍有機率誤判。Auto Mode 若在你的環境中常誤擋內部服務,請以第6.6.4章的 autoMode.environment 告訴分類器哪些是可信基礎設施。

⚠️ 注意:bypassPermissions 對 Prompt Injection 或非預期動作沒有任何防護;需要「大幅減少詢問次數」又想保有背景安全檢查時,應優先選 Auto Mode。

6.6.3 權限規則語法速查

權限規則格式為 Tool 或 Tool(specifier),評估順序是 deny → ask → allow,第一個符合者決定,與規則多具體無關:

規則符合
Bash所有 Bash 指令
Bash(npm run *)以 npm run 開頭的指令(Bash(npm run:*) 為等效的舊寫法,:* 只在結尾有效)
Read(./.env)讀取專案根目錄的 .env(Read 的 deny 規則也會阻擋 Edit/Write 寫入同路徑)
Edit(src/**)編輯 src/ 下的檔案(Edit 規則適用於所有會編輯檔案的內建工具)
WebFetch(domain:example.com)抓取 example.com(子網域需另加 domain:*.example.com)
mcp__github__*GitHub MCP Server 的所有工具
Agent(Explore)/Agent(fork)指定的 Subagent 類型
Agent(model:opus)以參數比對:要求用 opus 模型的 Agent 呼叫

⚠️ 注意:Bash 規則本質上是字串樣式比對,無法窮舉所有寫法(rm -fr、find -delete、透過腳本間接執行等)。deny 規則適合擋「明確、常見」的危險指令,真正的安全底線應搭配 PreToolUse Hook(第12章)與 OS 層級 Sandbox(第19.4章)。

6.6.4 Auto Mode 規則客製(autoMode)

autoMode 只從使用者設定與 Managed 設定讀取(不讀專案設定,避免 clone 下來的 repo 放寬分類器)。規則是給分類器看的自然語言,不是正規表示式;在陣列中放入 "$defaults" 代表保留內建規則並在其前後加上自己的規則,省略則會取代內建規則。以下是一份已通過檢查工具驗證的企業範例:

{
  "permissions": {
    "defaultMode": "auto",
    "disableBypassPermissionsMode": "disable"
  },
  "autoMode": {
    "environment": [
      "$defaults",
      "Organization: Acme Bank. Primary use: software development for internal banking systems",
      "Source control: github.acme.example/acme-bank and all repos under it",
      "Trusted internal domains: *.corp.acme.example, artifacts.acme.example",
      "Internal package registry: npm and Maven installs must go through artifacts.acme.example",
      "Sensitive remote targets: any Kubernetes namespace named prod-* and hosts under *.prod.acme.example",
      "Sensitive data locations: s3://acme-customer-pii may only be shared with the data-governance team"
    ],
    "soft_deny": [
      "$defaults",
      "Never run terraform apply or helm upgrade against any environment"
    ],
    "classifyAllShell": true
  }
}
  • environment:描述可信的原始碼平台、內部網域、套件登錄站、敏感資料位置與正式環境範圍,讓分類器不再誤擋例行內部操作。Pro/Max/Team 使用者可執行 /auto-mode-setup,讓 Claude 依專案與近期 Session 草擬 environment 條目後由你審核儲存(v2.1.228+)。
  • soft_deny/hard_deny/allow:增減封鎖或允許規則;hard_deny 無論 allow 例外都一律封鎖。
  • classifyAllShell: true:Auto Mode 下所有 Bash/PowerShell 指令都送分類器(預設只暫停可能執行任意程式碼的寬鬆 allow 規則,如 Bash(*)、Bash(python *))。
# 儲存後確認實際生效的規則包含你的條目
claude auto-mode config | jq '.environment'

6.6.5 Auto Mode 在 v2.1.300~v2.1.327 的行為變更(v3.0 新增)

Auto Mode 是預設起始模式,因此它的細微變更影響面最大。以下依「會不會改變既有 Session 的結果」排序:

變更版本實際影響
--permission-mode auto 或設定 defaultMode: "auto",但 Auto Mode 對此 Session 不可用時v2.1.323改以 Manual 啟動(之前可能落入允許更多動作的模式)。CI 中需核准的動作會被拒絕,必須檢查 permission_denials(第29.8章)
claude -p 與 Agent SDK 未指定模式時v2.1.302在第三方供應商、遙測關閉或全新安裝的環境中以 default(Manual)啟動;明確傳 --permission-mode auto 才維持 Auto
分類器的計費備援(billed fallback)即將移除v2.1.327 公告之後原本由備援檢查的動作會改為詢問或拒絕;無人值守流程要預先以 allow 規則涵蓋
HIPAA 設定的組織v2.1.326終端機與 VS Code Session 預設以 Auto 啟動,disableAutoMode 可關閉
專案設定或 Plugin 不能再把你在專案外關閉的伺服器端檢查重新打開v2.1.319個人的關閉決定不會被 clone 下來的 repo 推翻
autoMode.allow 沒寫 "$defaults" 時,不再移除排程任務提示的內建規則v2.1.316自訂 allow 清單不會意外放寬排程任務
/auto-mode-setup 導引設定v2.1.304讀取專案與近期 Session,協助撰寫 autoMode.environment;也可用於 Bedrock/Vertex/Foundry/Gateway
CLAUDE_CODE_AUTO_MODE_MODELv2.1.302指定用戶端分類器使用的模型;不影響伺服器端 Auto Mode
Code Mode 下分類器審查的是整段程式碼而非每個工具呼叫v2.1.323執行期才算出的值(例如從搜尋結果取得的路徑)分類器看不到,關鍵管制仍要靠規則與 Hook(第31.3章)

在互動 Session 內讓 Auto Mode 學習你的環境(產生的 autoMode 規則需人工審核 diff):

/auto-mode-setup

在終端機檢查目前生效的規則,並請 AI 評論自訂規則的漏洞:

claude auto-mode defaults   # 內建的 environment/allow/soft_deny/hard_deny 規則
claude auto-mode config     # 套用你的設定後實際生效的規則(JSON)
claude auto-mode critique   # 由 AI 審查自訂規則,結果仍需人工判斷

⚠️ 注意:「Auto Mode 不可用時退回 Manual」是安全方向的變更,但會讓過去「看起來正常」的無人值守腳本開始默默做不完事——結束碼仍是 0、is_error 仍是 false,只有 permission_denials 會揭露真相(第29.8章 T2、T4 實測)。

6.7 Slash Commands 速查

Session 內以 / 開頭的指令分兩種:內建指令(執行固定邏輯)與隨附 Skill(以提示驅動 Claude 完成工作,第27.3章)。常用的如下:

類別指令
Session/clear、/compact [指示]、/resume、/rename、/branch(分支對話)、/fork(複製成背景 Session)、/subtask(繼承上下文的 Subagent)、/rewind(別名 /checkpoint、/undo)、/export、/cd <path>、/add-dir
模型與推理/model、/effort [level|auto|status|ultracode]、/fast、/advisor、/autocompact
設定與狀態/config [key=value]、/status、/permissions、/hooks、/memory、/doctor、/context、/usage(別名 /cost、/stats)、/keybindings、/statusline、/theme、/tui、/output-style
擴充/mcp、/plugin、/skills、/agents、/reload-plugins、/reload-skills、/skill-doctor、/update-config
程式碼品質/code-review [level|ultra](別名 /review)、/ultrareview、/security-review、/simplify、/verify、/run
多 Agent 與自動化/tasks、/workflows、/batch、/loop、/goal、/schedule、/background、/list-agents(別名 /peers)
其他/init、/diff、/design、/desktop、/remote-control、/teleport、/insights、/team-onboarding、/feedback、/release-notes、/help

/pr-comments(v2.1.91 移除)、/vim(v2.1.92 移除,改在 /config → Editor mode)、/ultraplan(已移除)若仍出現在團隊教材中請更新。

6.8 v2.1.300~v2.1.327 旗標、子指令與 Slash Command 補遺(v3.0 新增)

v3.0 以本機 v2.1.327 的 claude --help(含 21 個子指令的 --help)與官方 CLI reference 全量比對,v2.0 未收錄或本次有變更的項目如下。

旗標:

旗標說明注意事項
--betas <betas...>在 API 請求加入 beta header只適用 API Key 使用者
--brief開啟 SendUserMessage 工具,讓 Claude 主動傳訊息給你—
--file <file_id:相對路徑...>啟動時下載指定檔案到工作目錄例:--file file_abc:doc.txt
--prompt-suggestions每回合後輸出 prompt_suggestion 訊息(預測下一個提示)需同時使用 -p、--output-format stream-json 與 --verbose
--replay-user-messages把 stdin 的使用者訊息回送到 stdout 作為確認需 --input-format stream-json 與 --output-format stream-json
--append-subagent-system-prompt-file <檔案>從檔案附加 Subagent 系統提示只在 -p 生效;不可與 --append-subagent-system-prompt 併用
--remote-control-session-name-prefix <前綴>Remote Control 自動產生名稱的前綴(預設為主機名稱)也可用 CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX
--dangerously-load-development-channels <項目...>載入不在核准清單上的 Channel,供本機開發會要求確認,-p 中被忽略
--advisor <模型>單次 Session 指定 Advisor 模型(第31.5章)不列在 --help 中;主模型不支援或模型被白名單排除時直接結束

子指令:

指令v3.0 變更
claude mcp add-json <name> -v2.1.327 起從 stdin 讀取 JSON;在 Claude Code Session 內執行會被拒絕(v3.0 實測訊息:「Reading the JSON from stdin is refused inside a Claude Code session」)
claude mcp logout <name>清除 MCP Server 儲存的 OAuth 憑證;v2.1.314 起憑證未真的移除時不再回報成功
claude remote-control --settings <檔案>v2.1.321 起可替它啟動的每個 Session 套用設定檔;檔案變更後需重啟
claude remote-control --sandbox/--no-sandboxv2.1.300 移除,傳入即以錯誤結束;改在設定中寫 sandbox.enabled
claude ultrareview --no-post預設即不貼回 PR;--post 只能用於 github.com PR
claude auto-mode reset -y略過確認,直接從使用者設定移除 autoMode 區段
claude purge -i/--dry-run/--all逐項確認、預覽或清除所有專案的本機資料
claude rmv2.1.323 起明確說明「從清單移除、對話保留,claude --resume 仍可找到」

Slash Command 與介面:

指令/按鍵說明
/statusv2.1.327 起列出損壞的 Agent/Skill/Command/Output Style 檔案、快捷鍵錯誤、不可用的 Sandbox、被忽略的權限設定與永遠不會命中的 Hook matcher;v2.1.326 起另有一列說明哪些功能被供應商或 DISABLE_TELEMETRY 等變數關閉
/configv2.1.327 起標示被其他設定覆寫的列;新增 Idle compaction 列(v2.1.302)
/auto-mode-setupAuto Mode 導引設定(第6.6.5章)
/advisor [模型|off]設定或關閉 Advisor(第31.5章)
/tui classic非全螢幕渲染器的新名稱(/tui default 仍可用,v2.1.327)
/tasksv2.1.319 起有「Earlier in this session」列,可重新開啟已完成的 Subagent 並傳訊
Ctrl+Ov2.1.326 起可顯示被隱藏的啟動通知;也是 Transcript 檢視(Code Mode 的程式碼在此展開)

權限行為的細部變更(會讓過去不詢問的動作開始詢問):

  • 在非專案、也未信任的 repo 中執行唯讀 git 指令會先詢問;要免詢問請以 --add-dir 加入該路徑,而不是 additionalDirectories 設定(v2.1.325)
  • 「Don’t ask again」產生的 allow 規則若看起來含秘密,或會寫入被 git 追蹤的 settings.local.json,只在本次 Session 有效、不寫檔(v2.1.323)
  • ExitWorktree 移除可能含未儲存工作的 Worktree 前會詢問(v2.1.327),背景 Subagent 仍在其中執行時拒絕移除(v2.1.326)
  • --allowedTools/--disallowedTools/--tools 的值看起來不是完整規則時,互動啟動會警告(v2.1.326);v3.0 實測 -p 模式 stderr 沒有任何警告(第29.8章 T8),CI 必須靠 check_flags.py 與人工審查
# 以 stdin 加入 MCP Server:Token 只出現在環境變數,不出現在指令列與 shell history
# (須在一般終端機執行,不能在 Claude Code Session 內)
printf '%s' '{"type":"http","url":"https://mcp.tracker.corp.example/mcp","headers":{"Authorization":"Bearer ${TRACKER_TOKEN}"}}' \
  | claude mcp add-json --scope project issue-tracker -

# 預覽要清除哪些本機資料,確認後再逐項清除
claude purge ~/work/legacy-repo --dry-run
claude purge ~/work/legacy-repo -i

6.9 本章審查與驗證清單

AI 產出項目❌ 常見錯誤✅ 正確做法人工如何驗證
指令與旗標使用不存在或已移除的旗標(--enable-auto-mode、claude project purge、claude auto-mode enable)以 claude --help、子指令 --help 與官方 CLI reference 為準第30章 check_flags.py 比對;或直接執行 claude <子指令> --help
旗標組合claude --bg -p "..."、claude --worktree ../path--bg 不可與 -p 併用;--worktree 接名稱或 PR,不是路徑在測試目錄實際執行,確認沒有參數錯誤
CI 指令只設 --output-format json,沒有輪數、成本與權限詢問的上限同時設 --max-turns、--max-budget-usd、--permission-prompts none 與最小 --allowedTools以第29章 gate 腳本與 fixture 測試三種結果(通過、失敗、錯誤)
權限模式說明仍說 Pro/Max/Team 才預設 auto、或稱 default 為「預設模式」v2.1.283+ 終端機互動 Session 一律以 auto 起始;default 介面名稱為 Manual新開 Session 看狀態列的模式標示;/status 確認
起始模式設定在專案 .claude/settings.json 寫 defaultMode: "auto"放在 user 或 Managed 設定check_settings.py --scope project 會警告;開新 Session 驗證
Auto Mode 規則把 autoMode.environment 寫成正規表示式或寫在專案設定用自然語言描述、放 user 或 Managed,並保留 "$defaults"claude auto-mode config 確認條目已生效
危險指令防護只靠 permissions.deny 的字串規則deny 規則+PreToolUse Hook+Sandbox 多層防護以第12章 harness 測試變形指令
remote-control 指令沿用 claude remote-control --no-sandboxv2.1.300 起已移除,改在設定寫 sandbox.enabledcheck_upgrade.py 會把腳本中的此用法標為 BREAK;實際執行會以錯誤結束
隱藏旗標因為 --help 沒列出就判定 --advisor 不存在,或反過來發明不存在的旗標以 --help 與官方 CLI reference 兩者聯集為準check_flags.py --known help/ cli-reference.md -- 文件
--allowedTools 規則寫出不完整的規則(如少了右括號)並以為 CI 會警告-p 模式不會警告(v3.0 實測),規則要先經過 lint以 check_flags.py 與人工 Review 檢查括號與萬用字元;以 permission_denials 驗證實際效果

第 7 章 Hotkey 大全

本章目標:掌握中斷、回溯、切換模式、背景執行等最常用的快捷鍵,並學會用 keybindings.json 依團隊環境自訂。本章依官方 Interactive mode 與 Keybindings 文件重新整理;v1.3 的部分按鍵(如以 y/n/a 回答權限詢問)已不是目前的預設行為。

7.1 終端機層級快捷鍵

快捷鍵說明
Ctrl + C中斷執行中的操作;沒有執行中的操作時,第一次清空輸入、第二次結束 Claude Code(v2.1.288 起,清空後在空白提示按 ↑ 可救回草稿)
Ctrl + D結束 Session(第一次顯示提示,800ms 內再按一次才結束;輸入框有文字時改為刪除游標後一個字)
Ctrl + Z暫停 Claude Code 回到 Shell(僅 Unix),以 fg 恢復
Ctrl + L重繪畫面(畫面亂掉時使用,不會清除對話)
↑ / ↓ 或 Ctrl + P / Ctrl + N在多行輸入中移動游標,或瀏覽歷史輸入
Ctrl + R反向搜尋歷史指令

7.2 Claude Code Session 內快捷鍵

快捷鍵說明
Enter送出目前輸入
\ + Enter 或 Ctrl + J多行輸入(任何終端機皆可)
Shift + Enter多行輸入(iTerm2、WezTerm、Ghostty、Kitty、Warp、Apple Terminal、Windows Terminal 原生支援;其他終端機執行 /terminal-setup)
/開啟指令與 Skill 選單(v2.1.269 起輸入到一半打 / 也會列出符合的指令)
!Shell 模式:直接執行指令,輸出加入 Session 並由 Claude 回應
@檔案路徑提及;在支援跨 Session 訊息的 Session 中,@ 加上字母還會建議本機其他 Session(第9.10章)
Esc中斷 Claude 目前的回應或工具呼叫(保留已完成的工作)、或關閉對話框
Esc Esc輸入框有文字時清空並存入歷史;輸入框為空時開啟 Rewind 選單(第8.5章)
Ctrl + G 或 Ctrl + X Ctrl + E在預設文字編輯器中編輯目前的提示或回覆(Plan 模式下可直接編修計畫)
Ctrl + S暫存目前輸入並清空,再按一次恢復
Ctrl + V(Windows/WSL 也可用 Alt + V)從剪貼簿貼上圖片
Ctrl + O開啟 Transcript 檢視器,看每個工具呼叫的細節與使用的模型
Ctrl + T切換 Claude 的任務清單顯示
?(輸入框為空時)顯示快捷鍵說明面板

7.3 Agent 操作快捷鍵

快捷鍵說明
Esc讓 Agent 停下來改方向(比 Ctrl + C 更推薦,已完成的工作會保留)
Shift + Tab(Windows 部分環境為 Alt + M)循環切換權限模式:default(Manual)→ acceptEdits → plan,可用時再接 auto、bypassPermissions(第6.6章)
Option + P(macOS)/Alt + P切換模型,不會清除目前輸入
Option + T(macOS)/Alt + T切換延伸思考(Opus 5.5、Sonnet 5.5、Haiku 5.5 與 Fable 系列永遠開啟,按了沒有作用)
Option + O(macOS)/Alt + O切換 Fast mode
Ctrl + B把執行中的 Bash 指令或 Agent 轉到背景,可繼續輸入(tmux 使用者按兩次)
Ctrl + X Ctrl + K停止本 Session 所有執行中的背景 Subagent
Ctrl + Enter 或 Ctrl + X Ctrl + S立即送出排隊中的訊息(中斷目前回合)
Option + W(macOS)/Alt + W取消這次提示中 ultracode 關鍵字的 Workflow 觸發(第26.3章)
權限對話框中的 Tab對權限回答附加說明
權限對話框中的 ← / →切換對話框分頁

⚠️ 勘誤:v1.3 寫「權限詢問時按 y/n/a」。權限對話框目前以方向鍵選擇選項後按 Enter;y/n 對應確認動作的預設綁定已在 v2.1.280 移除(若你以前用 /keybindings 產生過設定檔,舊綁定會保留到你刪除為止)。中斷 Agent 建議改用 Esc。

graph LR
    Normal["一般輸入"] <--> Multi["多行輸入<br/>(Shift+Enter / Ctrl+J)"]
    Normal <--> Cmd["指令選單<br/>(/)"]
    Normal <--> Shell["Shell 模式<br/>(!)"]
    Normal --> Rewind["Rewind 選單<br/>(空白輸入時 Esc Esc)"]

📌 實務建議:盡早熟悉 Esc(中斷並改方向)與 Esc Esc(回溯),這是糾正 Agent 走錯方向最有效的工具,比等它跑完再重來省時間也省 Token。

⚠️ 注意:若你同時使用 tmux/vim,部分快捷鍵可能衝突(例如 tmux 預設吃掉 Ctrl + B),建議在團隊 Onboarding 文件中列出實際環境下驗證過的快捷鍵組合,必要時以第7.4章的設定重新綁定。

實務案例:資深工程師在 Agent 開始往錯誤方向修改時立即按 Esc 中斷,再按 Esc Esc 回到下指令之前的時間點,重新給出更精確的指示,整個任務只花了原本預估時間的一半。

7.4 自訂鍵盤綁定(keybindings.json)

執行 /keybindings 會開啟 ~/.claude/keybindings.json。綁定以「情境(context)」分組,值為動作名稱,設為 null 代表解除綁定:

{
  "$schema": "https://www.schemastore.org/claude-code-keybindings.json",
  "bindings": [
    {
      "context": "Chat",
      "bindings": {
        "ctrl+e": "chat:externalEditor",
        "ctrl+s": null
      }
    },
    {
      "context": "Confirmation",
      "bindings": {
        "y": "confirm:yes",
        "n": "confirm:no"
      }
    }
  ]
}

常用情境包括 Global、Chat、Confirmation、Transcript、Autocomplete 等;完整動作清單見官方 Keybindings 文件(例如 modelPicker:thisSessionOnly、effortSlider:toggleUltracode)。

7.5 終端機與編輯模式設定

需求做法
Shift + Enter 無法換行執行 /terminal-setup(VS Code、Cursor、Alacritty、Zed 等),或改用 Ctrl + J
macOS 的 Option 組合鍵無效在終端機啟用「Option as Meta」(iTerm2:Profiles → Keys;Terminal.app:Use Option as Meta key)
想用 Vim 操作輸入框/config → Editor mode 選 Vim(/vim 指令已於 v2.1.92 移除)
畫面閃爍或想要全螢幕介面/tui fullscreen 切換到全螢幕渲染(支援滑鼠、{/} 跳到上下一個提示)
使用螢幕報讀器claude --ax-screen-reader 或設定 axScreenReader

7.6 介面設定與快捷鍵補遺(v3.0 新增)

項目版本用途
Ctrl+O 顯示隱藏的啟動通知v2.1.326啟動時一閃而過的警告(例如設定被忽略)可以回頭查看
Vim 模式 % 動作v2.1.301跳到配對括號,可與 d/c/y 組合
點擊送出排隊訊息v2.1.312全螢幕模式下點「to send now」提示即可立即送出
子 Agent 畫面的 esc to stop 提示v2.1.326提示在該畫面按 Esc 會停止子 Agent
timeFormat/timeZone—介面時間格式("12-hour"、"24-hour"、"24-hour-utc" 或 strftime 樣式)與時區
vimInsertModeRemaps—把兩鍵序列(如 jj)對應到 Esc
prefersReducedMotion—減少或關閉 Spinner、閃爍等動畫(無障礙需求)
askUserQuestionTimeout—Claude 提問無人回應時自動繼續:"60s"/"5m"/"10m"/"never"(預設)

跨國團隊或有無障礙需求的成員,可在個人設定加入:

{
  "timeFormat": "24-hour",
  "prefersReducedMotion": true,
  "vimInsertModeRemaps": { "jj": "<Esc>" }
}

⚠️ 注意:askUserQuestionTimeout 讓 Claude 在你離開時「自己決定」原本要問你的問題。在需要人工決策的流程(例如是否刪除資料、選擇遷移策略)不要設定,維持預設 "never"。

7.7 本章審查與驗證清單

AI 產出項目❌ 常見錯誤✅ 正確做法人工如何驗證
新人快捷鍵教材沿用舊教材的 y/n/a 權限鍵、/vim 指令依本章表格;權限對話框以方向鍵+Enter在目前版本實際操作一次並截圖
中斷 Agent 的建議只教 Ctrl + C(沒有執行中操作時會清空輸入甚至結束)教 Esc 中斷、Esc Esc 回溯實際在長任務中按 Esc,確認已完成的工作保留
自訂 keybindings.json把綁定寫在 settings.json,或動作名稱拼錯寫在 ~/.claude/keybindings.json,加 $schema 讓編輯器驗證用 VS Code 開啟檔案看 schema 驗證;重開 Session 實測按鍵
多行輸入說明只寫 Shift + Enter,未說明終端機相依同時提供 \ + Enter 與 Ctrl + J 兩個通用方法在團隊實際使用的終端機逐一測試
無人值守時的提問為了讓長任務不中斷,把 askUserQuestionTimeout 設為 "60s"需要人工決策的專案維持 "never";無人值守流程改以 denyInsteadOfPrompting 與明確的 Prompt 範圍控制檢查使用者與專案設定中是否出現此鍵;在 Transcript 中搜尋自動繼續的提問

第 8 章 Context Engineering

本章目標:理解 Context Window 由哪些內容組成、壓縮(Compaction)時哪些東西會保留、Prompt Cache 何時失效,以及 Checkpoint/Rewind 能還原與不能還原的範圍。讀完後,你應該能用 /context 診斷 Context 膨脹,並設計出「壓縮後規則不會消失」的專案記憶結構。

8.1 Context Window 組成

graph TB
    Sys["系統提示 + Output Style + 工具定義"] --> Window["Context Window"]
    Claude["CLAUDE.md / AGENTS.md + 無 paths 的 Rules + Auto Memory"] --> Window
    Skills["Skill 清單(名稱與描述)+ MCP 工具名稱"] --> Window
    Hist["對話歷史"] --> Window
    Files["讀取過的檔案與工具結果"] --> Window
    Window --> Compact["壓縮 / 摘要化<br/>(歷史層優先被壓縮)"]

Auto Memory(Claude 自己在對話中累積、寫入 MEMORY.md 的學習筆記)是 CLAUDE.md 之外另一個會載入 Context 的機制,兩者互補但性質不同:CLAUDE.md 是「你寫給 Claude 的規則」,Auto Memory 是「Claude 自己記下的經驗」。完整機制與設定方式詳見第11章。

在 Session 中執行 /context,會以彩色格子視覺化目前的 Context 使用量,並針對佔用過多的工具、過大的記憶檔提出最佳化建議;/skill-doctor(v2.1.252+)則列出每個 Skill 佔用多少 Context、多常被使用,方便找出應該停用的 Skill。

8.2 壓縮(Compaction)與重用

當對話累積到一定程度,Claude Code 會將較舊的歷史摘要化以釋放空間。原生 1M 上下文的模型(Fable、Sonnet 5 以後、Haiku 5.5、Opus 4.7 以後)預設在約 967K Token 時自動壓縮;你可以用 /autocompact 500k(儲存到使用者設定)或 --autocompact 500k(只對本次)提早壓縮,或用 /compact <重點指示> 手動壓縮並告訴 Claude 摘要時要保留什麼。

壓縮後會保留/重新載入與會被摘要掉的內容:

機制壓縮後
系統提示、Output Style仍然生效
專案根目錄 CLAUDE.md 與沒有 paths 的 Rules從磁碟重新注入
Auto Memory從磁碟重新注入
Plan 模式寫下的計畫從磁碟重新注入
有 paths 的 Rules、子目錄的 CLAUDE.md被摘要掉,下次讀到符合的檔案時才重新載入
讀過或編輯過的檔案重新讀取最近修改的最多 5 個(超過 5,000 Token 的只留路徑)
已呼叫的 Skill 本文重新注入,每個上限 5,000 Token、總計 25,000 Token,最舊的先被捨棄
早期由 Hook 加入的 Context與對話一起被摘要
背景指令與背景 Subagent繼續執行

閒置壓縮(Idle Compaction,v2.1.290+):在互動式終端機中,使用一小時 Prompt Cache 的對話若超過 200K Token、閒置約 54 分鐘,Claude Code 會在快取過期前先壓縮,你回來時看到 Compacted while idle, before the prompt cache expired。門檻可用 CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS 調整,設定 idleCompaction: false 可關閉。

這張表直接決定了規則該放哪裡:跨壓縮都必須存在的規則,要放在根目錄 CLAUDE.md 或沒有 paths 的 Rules;只和特定檔案有關的規則才放 paths 範圍化的 Rules(第11.6章)。

8.3 快取(Caching)

重複出現的內容(系統提示、工具定義、CLAUDE.md 開頭)會被 Prompt Cache 快取,降低延遲與成本。Claude 訂閱在方案額度內時,主對話預設使用一小時 TTL;使用 API Key 或雲端供應商時預設為五分鐘,可設定 promptCacheTtl: "1h"(v2.1.242+)。

會讓快取失效的常見操作:切換模型、調整 Effort(/effort 會先顯示快取警告)、開啟 Fast mode、新增或移除 MCP Server、啟用或停用含 MCP Server 的 Plugin、整個 deny 掉某個工具、壓縮對話、累積大量圖片、升級 Claude Code。不會讓快取失效的:編輯 repo 中的檔案。

📌 實務建議:同一個長任務中盡量不要頻繁切換模型或 Effort;腳本化的多使用者任務可加 --exclude-dynamic-system-prompt-sections,把每台機器不同的資訊移出系統提示,提高跨使用者的快取命中率(第29章)。

8.4 Token 優化技巧

  • 從需要處理的子目錄啟動 Session,必要時用 --add-dir 補上共用目錄,而不是讓 Agent 在整個 Monorepo 漫遊
  • 讓 Claude 先搜尋定位再讀檔,而不是一次性讀取整個大檔案;大範圍搜尋交給 Explore Subagent,結果不會淹沒主對話
  • 把重複需要解釋的規則寫進 CLAUDE.md,一次投資、多次重用;但 CLAUDE.md 每個檔案建議控制在 200 行以內
  • 善用 MCP 的延遲載入(工具定義依需求載入,而非一開始全部塞入 Context)
  • 用 /btw <問題> 問與主任務無關的旁支問題,不會加進對話歷史
  • 想讓 Claude 只拿到 @ 提及的檔案路徑、自己決定讀哪些內容時,設定 CLAUDE_CODE_DISABLE_FILE_MENTIONS=1(v2.1.299+)
# 反面教材:一次性丟整個倉庫
claude -p "讀完整個 repo 並解釋所有模組"

# 建議做法:先定位,再深入
claude -p "先列出 services/ 下有哪些模組,再針對 billing 模組說明其職責"

📌 實務建議:把 CLAUDE.md 當作「Context 重用投資」——任何你在對話中解釋了第二次的事情,都該寫進 CLAUDE.md。

⚠️ 注意:長對話中段如果做了重要決策(例如「這個欄位禁止改型別」),建議在後續訊息中主動重申,或直接寫進 CLAUDE.md,避免壓縮後遺失約束。

實務案例:一個 5 萬行的 Monorepo Session,因為一次性塞入 6 個大檔案而明顯變慢、回應品質下降;工程師執行 /context 發現檔案內容佔了超過一半,改為先搜尋定位再針對性讀取後,同樣任務的輪數減少超過一半。

8.5 Checkpoints 與 Rewind(對話回溯)

壓縮(8.2)會摘要化舊歷史以釋放空間,但摘要化是「不可逆」的——一旦壓縮,細節就回不來了。Checkpoints/Rewind 提供另一種更可控的狀態管理手段:

  • File Checkpointing(設定鍵 fileCheckpointingEnabled,預設開啟):Claude 以內建檔案編輯工具修改檔案前自動建立快照,可還原到任一步驟之前的檔案狀態。
  • Rewind 選單(/rewind,別名 /checkpoint、/undo;或在空白輸入時按 Esc Esc):選定一則過去的提示後,可選擇下列動作:
    • Restore code and conversation:程式碼與對話都回到該點
    • Restore conversation:只回溯對話、保留目前程式碼
    • Restore code:只還原檔案、保留對話(僅在該點之後有被追蹤的檔案變更時出現)
    • Summarize from here:把該點之後的對話摘要化,釋放 Context
    • Summarize up to here:把該點之前的對話摘要化,保留之後的訊息 兩種摘要都等同「有選擇性的 /compact」,可在選項上直接輸入摘要重點;原始訊息仍保留在 Transcript。若同一個程序中曾執行 /clear,選單頂端還會出現回到 /clear 之前對話的項目。
flowchart LR
    T1["時間點 A"] --> T2["時間點 B<br/>(走錯方向)"]
    T2 --> T3["時間點 C"]
    T3 -.Rewind 回到 B.-> T2
    T2 -."Summarize up to here"<br/>摘要 B 之前的內容.-> T4["精簡後的對話"]

Checkpoint 的限制(務必在團隊教材中講清楚):

不會被還原的變更原因與替代做法
Bash 指令造成的檔案變更(rm、mv、cp、建置產物)只有內建檔案編輯工具的修改會被追蹤;請依賴 Git
背景 Subagent 的編輯(含背景執行的 context: fork Skill、背景 /code-review --fix)不在主 Session 的 Checkpoint 中;請用 Git 還原
在 Claude Code 之外(IDE、其他程序)做的修改不在追蹤範圍
符號連結與硬連結指向的路徑不還原

📌 實務建議:當發現 Agent 在某個時間點開始走錯方向時,優先用 Rewind 回到該點重新引導,而不是讓對話繼續累積後再靠人工 Prompt 糾正——這比事後修正更省 Token,也更乾淨。

⚠️ 注意:Checkpoint 不能取代版本控制。重要的里程碑請 commit;只還原對話而不還原程式碼(或反之),容易造成檔案狀態與對話描述不一致。

8.6 Context 與快取的行為變更(v3.0 新增)

變更版本對成本與行為的影響建議
未知模型 ID 預設 1M 視窗v2.1.323Gateway 後的小視窗模型可能在對話變長後每輪失敗設 CLAUDE_CODE_DISABLE_1M_CONTEXT=1,或以 /autocompact 提早壓縮
CLAUDE_CODE_AUTO_COMPACT_WINDOW 接受 k/M 後綴v2.1.304之前 200k 會被靜默當成 100K;現在超出範圍或被忽略時會警告寫成 200k 或 1M,並以 /context 確認
subagentPromptCacheTtl—Subagent、Workflow、壓縮等主對話外請求的快取存活時間;"1h" 讓長休息後仍命中快取,但快取寫入單價較高大量 Subagent、長時間 Workflow 設 "1h";短任務維持預設
Read 工具移除「未變更」短訊v2.1.317重複讀取未變更的大檔會再次消耗 Token在 CLAUDE.md 提醒「已讀過的檔案不要重讀」
bashOutputMaxChars—Bash 成功輸出內嵌給 Claude 的字元數(預設 30,000,可調 4,000~128,000)輸出很長的建置工具可調高,但要評估 Token 成本
閒置壓縮的 /config 開關v2.1.302可關閉一小時快取對話閒置後的自動壓縮需要保留完整對話細節的除錯 Session 可暫時關閉
{
  "subagentPromptCacheTtl": "1h",
  "bashOutputMaxChars": 60000,
  "env": {
    "CLAUDE_CODE_AUTO_COMPACT_WINDOW": "400k"
  }
}

📌 實務建議:調整這些值之前,先用 /context 與 /usage 記錄一週的基準(第20章),調整後比較同類任務的 Token 與成本;沒有基準的調整無法驗證是否有效。

8.7 本章審查與驗證清單

AI 產出項目❌ 常見錯誤✅ 正確做法人工如何驗證
「規則要放哪裡」的建議把必須全程生效的安全規則放在有 paths 的 Rules跨壓縮必須存在的規則放根目錄 CLAUDE.md 或無 paths 的 Rules長對話中執行 /compact 後,再問 Claude 該規則內容是否仍知道
還原變更的建議宣稱 /rewind 能還原所有變更Bash 指令與背景 Subagent 的修改要用 Git 還原在測試 repo 讓 Claude 以 rm 刪檔後 Rewind,確認檔案未恢復
Context 膨脹診斷只叫使用者「開新對話」先用 /context 與 /skill-doctor 找出佔用來源比較最佳化前後 /context 的格子分佈
成本最佳化為了「最佳化」頻繁切換模型與 Effort長任務維持固定模型與 Effort,避免快取失效/usage 比較調整前後的快取讀取比例
壓縮門檻設定寫 CLAUDE_CODE_AUTO_COMPACT_WINDOW=200000 或 v2.1.304 以前寫 200k 而被當成 100Kv2.1.304 起以 200k/1M 書寫,並注意啟動警告/context 看自動壓縮門檻;在 Transcript 確認壓縮發生的 Token 數
Prompt Cache 存活時間全面設 ENABLE_PROMPT_CACHING_1H,以為一定更省一小時快取寫入單價較高;只對長休息、長 Workflow 有利以 /usage 或 OTel 的 cache_creation_5m_tokens/cache_creation_1h_tokens 比較調整前後成本(第20.5章)

第 9 章 Agent 系統

本章目標:分清楚 Subagent、Agent View、Agent Teams、Dynamic Workflows 四種平行化機制(v3.0:官方另列第五種 Projects,見第9.11章),以及 Worktree、Fork、跨 Session 訊息傳遞三個輔助工具。讀完後,你應該能依「誰負責協調、工作者要不要互相溝通、會不會改到同一批檔案」三個問題,替任務選對機制。

9.1 概念釐清:Agent / Sub Agent / Multi Agent

  • Agent:指你目前互動的 Claude Code Session 本身,具備完整工具存取與規劃能力。
  • Sub Agent:由主 Agent 派生出來、擁有獨立 Context 與限定工具權限的工作者,專門處理特定子任務,完成後把結果回報主 Agent。
  • Multi Agent:多個 Sub Agent(或多個獨立 Session)協同運作,由主 Agent、你本人或腳本進行調度與整合。

官方文件目前將「平行化」拆成五種機制(v3.0:官方新增第五種 Projects,見第9.11章),彼此的協調模型不同,不能混為一談:

機制這能帶給你什麼何時選用詳見
Subagent單一 Session 內派生的委派工作者,在自己的 Context 中完成側支任務,回傳摘要給主 Agent側支任務會用大量搜尋結果、日誌或檔案內容淹沒主對話,且事後不需要再參考細節本章 9.2-9.4、第10章
Agent View(研究預覽)一個畫面集中派發/監看多個在背景執行的獨立 Session,以 claude agents 開啟手上有多個彼此獨立的任務,想直接交辦、之後再回來檢視狀態,只在需要時介入9.5
Agent Teams(實驗性、預設關閉)多個協調中的 Session,共享任務清單並可互相傳訊息,由一個 Lead 統籌想讓 Claude 把一個專案拆成多份工作、指派下去,並讓工作者之間保持同步9.6
Dynamic WorkflowsClaude 寫出一支 JavaScript 編排腳本,由執行環境在背景跑數十到數百個 Subagent 並交叉檢核彼此的結果全庫規模的稽核、數百檔案的遷移、需要交叉驗證的研究9.7、26.3
Projects(Public Beta,Pro/Max/Ultra)claude.ai/code 或 Desktop 中一個長期對話,由 Claude 擔任協調者,把工作拆成雲端 Thread 平行執行,共用 repo、指示與記憶目標跨越多天、會持續產生新任務,且希望電腦關機後仍繼續執行9.11

除了以上五種「協調機制」,官方另外點名三個輔助工具——它們支援平行工作,但本身不是派發/協調 Agent 的方式:Worktrees(9.8,讓平行 Session 各自持有獨立的 Git 工作目錄)、跨 Session 訊息傳遞(9.10,讓你自己各別啟動的 Session 之間互傳訊息)、/batch(第26.4章,Subagent+Worktree 的一種封裝用法)。

⚠️ 概念澄清(避免與「平行化機制」混淆):以下幾者雖然也讓 Claude 在背景運作,但不是用來拆分工作給多個 Agent 協調的機制——背景 Bash 指令(Ctrl+B)只是讓單一 Shell 指令不阻塞對話;Fork 機制(/subtask)是「繼承完整上下文的一種 Subagent」;/branch 是在同一 Session 分出另一條對話;Routine 是在雲端排程執行單一 Session。

這四種機制都可能搭配 Worktrees 做檔案層級的隔離:Agent View 派發的 Session 在編輯檔案前會自動移入獨立 Worktree,Subagent 可透過 isolation: worktree 取得同樣的隔離(第10.1章);Agent Teams 目前不會自動做 Worktree 隔離,需要靠人工切分工作範圍(第9.6、26.2章)。

9.2 何時該建立 Sub Agent

情境建議
任務可拆解成獨立子模組每個模組派一個 Sub Agent,平行處理
需要限制某段工作的工具權限用 Sub Agent 隔離(例如只給 Read,不給 Edit)
側支任務會產生大量輸出(搜尋、日誌、測試結果)用 Sub Agent,只把摘要帶回主對話
單一任務但邏輯單純直接在主 Agent 內處理,不必額外派生

9.3 生命週期管理

Subagent 活在單一 Session 內,用 /tasks 查看與停止;背景 Session(Agent View)則用以下指令管理:

claude agents              # 開啟 Agent View
claude attach 7c5dcf5d     # 附著查看(可用 Session 名稱的一部分取代 ID)
claude logs flaky-test     # 查看背景輸出(此例以名稱片段指定)
claude stop 7c5dcf5d       # 停止(別名 claude kill;對話保留,之後可再 attach)
claude respawn 7c5dcf5d    # 重新啟動(執行中或已停止皆可)
claude rm 7c5dcf5d         # 從清單移除,安全時一併刪除 Worktree

⚠️ 勘誤:v1.3 把 claude kill 描述為「強制終止」、與 claude stop 並列;實際上 kill 只是 stop 的別名,兩者行為相同。

graph TB
    Main["主 Agent"] --> Sub1["子 Agent:前端開發"]
    Main --> Sub2["子 Agent:測試撰寫"]
    Main --> Sub3["子 Agent:文件產生"]
    Sub1 --> Main
    Sub2 --> Main
    Sub3 --> Main

9.4 設計考量

  • 模型選擇可依子任務複雜度分配(簡單任務用 haiku,複雜任務用 opus);v2.1.292 起 Agent 工具多了 effort 參數,可要求 Subagent 以指定推理強度執行
  • 每個 Sub Agent 的工具權限應採最小權限原則
  • 平行 Sub Agent 若會修改重疊檔案,務必先界定模組/檔案的所有權邊界,或以 isolation: worktree 隔離
  • Subagent 預設在背景執行:只要「Fork Mode」開啟(互動式 Session 自 v2.1.232 起預設開啟),Claude 派生的 Subagent 一律在背景執行,Claude 無法要求前景執行;Fork Mode 關閉時(-p 與 Agent SDK 預設)則預設背景,但 Claude 需要立即拿到結果時會改用前景。背景 Subagent 遇到需要授權的動作時,提示會出現在主 Session,核准後才繼續
  • 背景 Subagent 的工具會被縮減:只保留 Read、Grep、Glob、LSP、Bash、PowerShell、Edit、Write、WebFetch、WebSearch、Skill、Monitor、SendMessage 等一組內建工具與全部 MCP 工具,即使定義檔的 tools 有列其他內建工具也會被移除
  • Subagent 可再派生子 Subagent:預設深度上限為主對話往下 3 層,達到上限的 Subagent 會被收回 Agent 工具,需自行完成工作並回傳摘要(Fork 例外:仍保留 Agent 工具,但呼叫會回傳錯誤)。深度可用環境變數 CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH 調整(例如 "2"),與另一個「同時執行中 Subagent 數量上限」互不影響;一個 Session 派生的 Subagent 總數沒有上限

📌 實務建議:派生 Sub Agent 前,先明確切分「誰負責哪個目錄/模組」,再分配工具權限,避免兩個 Agent 同時改同一個檔案。

⚠️ 注意:沒有協調的平行 Sub Agent 同時編輯重疊檔案,會造成衝突甚至互相覆寫對方的修改,這類問題在 Code Review 階段才發現會非常昂貴。另外,背景 Subagent 的編輯不會被主 Session 的 Checkpoint 追蹤,需要還原時請用 Git(第8.5章)。

實務案例:一個大型重構任務被拆成 4 個模組,分別派生 4 個設定了 isolation: worktree 的 Sub Agent 平行處理,比單一 Session 序列處理節省了大半時間,最後再依模組逐一 Review 各自的分支。

9.5 Agent View(背景多 Session 監看)

Agent View 透過 claude agents 開啟(研究預覽,介面與快捷鍵可能變動),將多個獨立、彼此不互相溝通的背景 Session 集中在一個畫面中監看與派發。這與 Subagent 的差異在於:Subagent 活在「單一 Session 內」、結束後即消失;Agent View 管理的是「多個完整獨立的 Session」,可隨時附著查看細節。

claude agents                  # 開啟 Agent View
claude agents --json --all     # 以 JSON 輸出所有 Session(含已結束的),適合寫腳本整合
claude --bg "修正 #1234 的分頁錯誤"   # 以背景 Session 啟動,自動納入 Agent View(不可加 -p)
claude --bg --exec 'pytest -x' # 以背景工作執行 Shell 指令

每一列 Session 會顯示狀態:Working(動畫)、Needs input(黃色,等你回答問題或核准權限)、Idle(暗色)、Completed(綠色)、Failed(紅色)、Stopped(灰色),並附上由分類器撰寫的一行摘要與 PR 狀態。常用操作:選取列後可「Peek」快速查看並直接回覆、或附著進入完整對話;Ctrl+F 依名稱搜尋、n:<文字> 篩選(v2.1.287+);在 Agent View 中執行 /model、/effort、/fast 可設定新派發 Session 的預設值(v2.1.299+)。

檔案隔離:從 Agent View 派發或以 --bg 啟動的 Session,會在第一次編輯檔案前自動移入 .claude/worktrees/ 下的獨立 Worktree;若 Session 已在 Worktree 中、目錄不是 Git repo(且沒有 WorktreeCreate Hook),或是你用 ←//background 把原本開著的 Session 送到背景,則不會建立 Worktree。

Agent View 依賴背景常駐的 Supervisor 運作,可用 claude daemon status 檢查;企業可用 disableAgentView 整體關閉(同時停用 claude agents、--bg、/background),或改用 processWrapper(Corporate Launcher)為 Supervisor 加上企業包裝程式(第5.4章)。

/tasks 與 claude agents 是不同層級的指令:/tasks 列出「目前這個 Session 內」的背景項目(背景 Subagent、背景 Bash 指令),claude agents 則是跨越多個獨立 Session 的 Agent View。

📌 實務建議:適合「同時推進多個彼此獨立任務」的情境(例如同時修三個不相關的 Bug),而非需要互相協調的任務。背景 Session 會一直跑到登入到期為止,長時間無人值守前先確認登入沒有快到期(/status 的 Login 列)。

9.6 Agent Teams(多 Session 協作,實驗性)

Agent Teams 讓多個 Session 共享同一份任務清單並互相傳遞訊息,目前為實驗性功能、預設關閉,需在環境變數或 settings.json 的 env 設定 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 才會啟用。一個 Session 擔任 Lead 負責協調與指派,隊友各自在獨立 Context 中工作並可直接互傳訊息,你也可以直接和任一隊友對話。

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

⚠️ 注意:Agent Teams 有已知限制(Session 回復、任務協調與關閉行為),而且 Token 消耗明顯高於單一 Session。企業導入前應先在非生產專案試行,並評估「多 Session 互相傳訊」是否會放大錯誤傳播的範圍。若只是想讓你自己開的兩個 Session 互通訊息,較輕量的做法是第9.10章的跨 Session 訊息傳遞。詳細治理建議見第26.2章。

9.7 Dynamic Workflows(腳本化大規模編排)

當任務規模超出「派生幾個 Subagent」的量級,Dynamic Workflows 讓編排邏輯變成程式碼:Claude 依你描述的任務寫出一支 JavaScript 腳本,由執行環境在背景執行,腳本掌握迴圈、分支與中間結果,Claude 的 Context 只會收到最終答案。啟動方式:

  • 在提示中加入關鍵字 ultracode,或直接說「use a workflow」(只對你親自輸入的提示有效,-p 傳入的提示不會觸發)
  • /effort ultracode 讓 Claude 對本 Session 每個實質任務都規劃 Workflow
  • 執行隨附的 /deep-research <問題>,或執行你儲存過的 Workflow 指令

/workflows 可觀看執行中與已完成的 Workflow,按 s 可把某次執行的腳本存到 .claude/workflows/(團隊共用)或 ~/.claude/workflows/(個人),之後以 /<名稱> 重複執行。這是一種「確定性編排 + AI 執行」的混合模式,適合需要可重複、可審查流程的場景;實務設計與治理建議見第26.3章。

9.8 Worktrees(Git Worktree 隔離機制)

9.4 提到的「平行 Sub Agent 若修改重疊檔案會互相覆寫」問題,最直接的解法是 Git Worktree:讓每個平行任務在獨立的工作目錄中執行,彼此操作不同的檔案系統路徑,從根本上避免檔案層級的衝突,最後再各自以分支/PR 的方式合併回來。

claude -w feature-a --tmux     # 在 .claude/worktrees/feature-a 建立 Worktree 並開 tmux
claude -w feature-b --tmux
claude -w "#1234"              # 從 PR #1234 建立 Worktree(GitLab MR 網址需 v2.1.233+)
# 兩個 Session 在不同的 worktree 中平行進行,互不影響對方的工作目錄

新的 Worktree 預設從 repo 的預設分支分出(不是目前的 HEAD);要改從本機 HEAD 分出,設定 worktree.baseRef: "head"。Worktree 是全新的 checkout,.env 這類被 gitignore 的檔案不會存在——在專案根目錄放一個 .worktreeinclude(.gitignore 語法)即可在建立 Worktree 時自動複製:

.env
.env.local
config/secrets.json
graph TB
    Repo["主 Repo"] --> WT1["Worktree A<br/>(分支 feature-a)"]
    Repo --> WT2["Worktree B<br/>(分支 feature-b)"]
    WT1 --> Agent1["Subagent / 背景 Session 1"]
    WT2 --> Agent2["Subagent / 背景 Session 2"]
    Agent1 --> PR1["PR / 合併回主分支"]
    Agent2 --> PR2["PR / 合併回主分支"]

📌 實務建議:只要平行任務「可能寫入檔案」,就優先用 Worktree 隔離,而不是僅靠「口頭約定模組邊界」——口頭約定容易因任務範圍判斷失準而失效,Worktree 是檔案系統層級的硬性隔離。

⚠️ 注意:Worktree 隔離解決的是「檔案衝突」,不解決「邏輯衝突」(例如兩個分支各自修改了同一個共用介面但簽名不同),合併前仍需要正常的 Code Review 與整合測試。

實務案例:團隊將原本因為「兩個 Subagent 同時改到同一個共用元件」而導致互相覆寫的重構任務,改為各自在獨立 Worktree 中進行、完成後各自開 PR,衝突問題完全消失,僅在合併階段才需要人工確認介面相容性。

9.9 Fork 機制:/subtask(分支 Subagent)與 /fork(複製整個 Session)

一般 Subagent(第10章)啟動時是全新、空白的 Context,只拿到 Claude 為它寫的委派任務描述。「Fork」則會完整繼承目前對話為止的所有上下文(系統提示、工具、模型、對話歷史),讓你不必重新解釋情境就能交辦一個側支任務。目前有三個容易混淆的指令:

指令作用結果去哪裡
/subtask <任務>啟動一個繼承完整上下文的 Subagent(背景執行),需 v2.1.212+回報到目前對話
/fork [任務]把整個 Session 複製成一個新的獨立背景 Session,在 Agent View 中繼續新的背景 Session
/branch [名稱]在此時間點分出另一條對話並切換過去,原對話保留(可用 /resume 回去)目前終端機

當 Agent View 被關閉時,/subtask 不可用,/fork 會退回舊行為(啟動繼承上下文的 Subagent,即 v2.1.161–v2.1.211 的 /fork)。撰寫團隊教材或腳本時務必先確認 Agent View 是否開啟。

/subtask 針對目前為止的解析器變更草擬單元測試
比較項目Fork Subagent(/subtask)具名 Subagent
Context完整對話歷史全新 Context,只有 Claude 寫的委派提示
系統提示與工具與主 Session 相同來自該 Subagent 的定義檔
模型與主 Session 相同依該 Subagent 定義檔的 model 欄位
Prompt Cache與主 Session 共用,成本較低各自獨立的快取
巢狀派生不可再派生另一個 Fork,但可派生具名 Subagent(計入深度上限)依 tools 欄位是否含 Agent 決定
--append-subagent-system-prompt不套用(沿用對話本身的提示)套用

Fork Mode(控制 Claude 能否自主決定派生 Fork 的開關;手動打 /subtask 不受此限制)互動式 Session 自 v2.1.232 起預設開啟,-p 與 Agent SDK 預設關閉。可用環境變數 CLAUDE_CODE_FORK_SUBAGENT 覆寫:1 在任何情境強制開啟、0 強制關閉。若想保留 Fork Mode 但禁止 Claude 自主派生 Fork,加入 Agent(fork) 的 deny 規則。

📌 實務建議:側支任務「需要太多背景說明」才講得清楚時用 /subtask;任務定義清楚、不需要主對話細節時,具名 Subagent(附帶明確的工具限制)通常更適合,因為它的權限邊界更容易稽核;想「同時嘗試另一條路線」時用 /branch(在前景切換)或 /fork(丟到背景跑)。

9.10 跨 Session 訊息傳遞(Cross-session Messaging)

需 Claude Code **v2.1.224 以上(macOS、Linux、WSL2)**或 v2.1.234 以上(原生 Windows),符合條件即自動開啟。同一台機器上的 Session 互傳在所有供應商(含 Bedrock、Google Cloud、Foundry、Claude Platform on AWS)都可用,這些供應商需 v2.1.248+;跨機器與雲端 Session 則需要以 claude.ai 登入並連上 Remote Control。

⚠️ 勘誤:v1.3 寫「原生 Windows 不支援、Bedrock 等供應商不支援」,目前兩者都已支援(原生 Windows 使用具名管道,每個連線須先以只有你的作業系統帳號能讀取的金鑰驗證)。

跨 Session 訊息傳遞讓 Claude 把一段文字從你啟動的某個 Session 傳給另一個獨立啟動的 Session——例如 A Session 的變更會影響 B Session 正在做的工作時主動示警。這解決的是「你自己各別開啟的 Session 之間如何互通有無」,與 Subagent、Agent Teams、Agent View 都是不同定位(第9.1章)。

Claude 透過兩個工具運作:ListAgents(找出可傳訊的對象)與 SendMessage(依名稱送出訊息)。訊息只會是一段純文字,不包含對話紀錄或檔案。

/list-agents          # 列出目前可觸及的 Session(別名 /peers)
@api-worker 請通知它:共用的 OrderDto 新增了 currency 欄位
  • 指定對象:在提示中輸入 @ 加上 Session 名稱的前幾個字,從建議清單選取(v2.1.232+);也可以請 Claude 在另一個 Session 下次閒置或結束時回報一次(v2.1.236+)。
  • 傳遞路徑:同機器 Session 之間透過各自的 Socket(macOS/Linux)或具名管道(Windows)直接傳遞,不經過 Anthropic 伺服器;跨機器則透過 Remote Control 轉送。容器內與主機上的 Session、WSL2 與原生 Windows 的 Session 彼此無法互傳。
  • 收件治理:crossSessionInbound 控制收到訊息時的行為——accept(直接送達)、hold(先擱置並跳出核准對話框)、refuse(直接捨棄);也可在 /config 的「Messages from your other sessions」設定。專案設定中更嚴格的值會勝過 Managed 與使用者設定。
  • 限制對外傳訊:isolatePeerMachines: true 時,任何要送到本機以外的訊息都須先經你核准,即使在 bypassPermissions 模式下也一樣。
  • 收到訊息不等於你本人核准:接收端 Claude 被明確告知訊息來自另一個 Session,不能代替你核准權限詢問、不能因此變更權限設定或 CLAUDE.md,訊息中的 /compact 等指令也只當成純文字;Auto Mode 的分類器也會審核送出的每則訊息。
{
  "permissions": { "deny": ["SendMessage", "ListAgents"] },
  "crossSessionInbound": "refuse"
}

📌 實務建議:多個 Worktree/多個 Session 平行開發同一個 Repo 時,跨 Session 訊息傳遞很適合讓 Session 之間互相通報「這裡動了共用介面」;但仍應搭配 Worktree 隔離,訊息傳遞無法取代檔案層級的隔離。

⚠️ 注意:治理上應與 Agent Teams(第9.6、26.2章)合併考量——兩者都涉及「一個 Session 的判斷透過訊息影響另一個 Session」;企業若尚未評估風險,可先用上方範例整體關閉,待治理流程到位後再局部開放。

9.11 Projects:雲端長期協作與五種平行方式的選擇(v3.0 新增)

Projects 是官方在 v2.0 之後新增的第五種平行方式(Public Beta,Pro/Max/Ultra 方案,逐步開放;Team/Enterprise 尚未提供)。它不是 CLI 指令,而是 claude.ai/code 與 Desktop Code 分頁中的一個長期對話:

  • Project 對話:Claude 擔任協調者,接收你送進來的工作、決定哪些要變成 Thread,並追蹤每個 Thread 的回報(只看回報,不看每一步)
  • Thread:實際做事的獨立 Session,各有自己的 Context;雲端 Thread 在自己的分支工作,需要時開 PR
  • 每個雲端 Thread 會拿到:Project 的 repo 與上傳檔案、Project 指示與記憶、各 repo 的 CLAUDE.md(不含 repo 的 Skills、.claude/settings.json、.mcp.json)、claude.ai 帳號的連接器,以及一個雲端環境
  • Overview 面板:列出所有 Thread 與狀態(待審、等你回覆、執行中)
情境建議方式原因
一個 Session 就做得完的任務一般 Session 或雲端 SessionProjects 的協調成本不值得
每個任務都需要本機資源(本機 DB、VPN 內 API、模擬器)本機 Session,多個時用 Agent View(9.5)雲端 Thread 碰不到你的機器;少數任務可請 Claude「在你的電腦上執行該 Thread」
一個目標跨多個 repo(例如所有服務升級 lint 設定)Projects每個 repo 一個 Thread、各自開 PR,Overview 追蹤
持續餵入同一服務的錯誤與審查需求Projects一次修好的陷阱可寫進 Project 記憶,後續 Thread 會用到
固定排程、不需要對話的工作雲端排程任務(Routines)不需要協調者
單一 Session 內的側支任務Subagent(第10章)結果直接回到目前對話
需要交叉驗證的大規模工作Dynamic Workflows(9.7、26.3)由腳本保證每個工作者都被檢核

治理要點:

  1. Projects 使用的是個人 claude.ai 帳號與雲端環境,企業 Managed 設定與 repo 的 .claude/settings.json 不會套用到雲端 Thread;企業尚未開放的方案也不能用它取代受控的本機流程。
  2. Projects 與其他 Claude Code Session 共用方案額度,且消耗更快;長期 Project 應定期在 Usage 頁檢視用量。
  3. 雲端 Thread 開出的 PR 與一般 PR 一樣,必須經過人工 Review 與 CI(第17、29章)。

同時補充三項與平行 Agent 有關的 v3.0 行為變更:

變更版本治理意義
同機 Session 之間不需你介入即可互傳的訊息數,由約 20 則提高到 100,000 則v2.1.323跨 Session 傳訊實質上不再有「數量煞車」;不需要此功能的環境請以 crossSessionInbound: "refuse" 與 SendMessage/ListAgents 的 deny 規則關閉(第9.10章)
/tasks 新增「Earlier in this session」列v2.1.319已完成的 Subagent 可重新開啟並傳訊,方便事後追問
同時執行的 Subagent 上限預設 20文件說明超過時 Agent 工具回傳 Concurrent subagent limit reached 且要求不要重試;以 CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS 調整

9.12 本章審查與驗證清單

AI 產出項目❌ 常見錯誤✅ 正確做法人工如何驗證
平行化機制選擇需要互相協調的任務用 Agent View;或簡單側支任務也開 Agent Teams依第9.1章三個問題選擇,從最輕量的機制開始檢查設計文件是否回答了「誰協調、要不要溝通、是否同檔」
背景 Session 指令claude --bg -p "..."、把 claude kill 當強制終止claude --bg "...";kill 是 stop 的別名實際執行並以 claude agents --json 確認狀態
Worktree 指令claude --worktree ../feature-a(傳路徑)claude -w feature-a(傳名稱、PR 編號或網址)執行後確認 .claude/worktrees/feature-a 已建立
Worktree 環境忘了 .env 不會被帶進 Worktree,導致測試失敗以 .worktreeinclude 列出要複製的 gitignore 檔案建立 Worktree 後 ls -a 確認檔案存在
Agent Teams 啟用說明說「在 /config 打開即可」或不提實驗性設定 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1,並註明限制未設定時確認 Claude 不會提議組隊
/fork 的說明沿用 v2.1.211 以前「繼承上下文的 Subagent」說法依 Agent View 是否開啟區分 /subtask、/fork、/branch在目前版本各執行一次,觀察結果出現在哪裡
跨 Session 訊息的平台說明宣稱原生 Windows 不支援v2.1.234+ 支援原生 Windows在 Windows 執行 /list-agents 確認指令可用
平行方式選擇把 Projects 當成企業版功能規劃導入,或用它處理需要 VPN 內資源的任務Projects 目前只在 Pro/Max/Ultra;雲端 Thread 不套用企業 Managed 設定與 repo 的 settings/MCP對照第9.11章表格逐項確認;在 Thread 中執行 /status 確認設定來源
跨 Session 傳訊治理以為傳訊次數有上限可當作安全機制v2.1.323 起上限為 100,000,不能當成煞車;不需要時以 crossSessionInbound 與 deny 規則關閉Session 內 /status 看 Peer address 列;/list-agents 確認是否仍可列出其他 Session

第 10 章 Agents 目錄

本章目標:學會撰寫 Subagent 定義檔、理解載入優先順序與呼叫方式、認識內建 Subagent,並為團隊建立可共用、可稽核的 Subagent 庫。讀完後,你應該能審查一份 AI 產生的 Subagent 定義檔,判斷欄位是否正確、權限是否最小。

⚠️ 注意(用語澄清):本章標題沿用常見口語「Agents 目錄」,但 Claude Code 實際載入子 Agent 定義的路徑是 .claude/agents/(專案層級) 與 ~/.claude/agents/(使用者層級),並不是 .github/agents/。.github/ 是 GitHub 平台慣例使用的目錄,與 Claude Code 的子 Agent 載入機制無關。

10.1 子 Agent 定義檔格式

子 Agent 是一個 Markdown 檔案,搭配 YAML Frontmatter 描述其名稱、說明、可用工具、模型等,本體則是系統提示。以下兩份範例皆已通過第30章 check_agents.py 驗證。

唯讀的程式碼審查者(.claude/agents/code-reviewer.md):

---
name: code-reviewer
description: 審查剛完成的程式碼變更是否符合公司安全與可維護性規範。完成一段實作或修正後主動使用。
tools: Read, Grep, Glob, Bash
model: sonnet
permissionMode: plan
effort: high
maxTurns: 30
memory: project
color: blue
---

你是本專案的資深程式碼審查者,只負責「找問題」,不直接修改程式碼。

審查流程:
1. 執行 `git diff --stat` 與 `git diff`,確認本次變更範圍。
2. 依下列順序逐項檢查,每一項都要引用檔案路徑與行號:
   - 正確性:邊界條件、null 處理、錯誤處理是否吞掉例外
   - 安全:輸入驗證、SQL/命令注入、敏感資料寫入 log
   - 測試:新邏輯是否有對應測試,斷言是否驗證「正確行為」而非「現有行為」
3. 輸出格式固定為三段:「必須修正」「建議修正」「確認無誤的項目」。

限制:
- 不得執行任何會修改檔案或推送的指令。
- 沒有證據(檔案路徑+行號)的意見不要寫。

會改檔案的測試撰寫者(.claude/agents/test-writer.md),以 isolation: worktree 隔離修改:

---
name: test-writer
description: 針對指定類別或函式撰寫單元測試並執行。使用者要求「補測試」或修改商業邏輯後使用。
tools:
  - Read
  - Grep
  - Glob
  - Edit
  - Write
  - Bash
model: inherit
isolation: worktree
effort: medium
---

你是專注於單元測試的子 Agent。

1. 先閱讀待測程式與既有測試,沿用專案現有的測試框架、命名與目錄慣例。
2. 每個公開方法至少涵蓋:正常路徑、邊界值、例外路徑。
3. 測試完成後執行專案的測試指令(見 CLAUDE.md),把失敗訊息原文附在回報中。
4. 不可為了讓測試通過而修改被測程式碼;若判斷被測程式碼有錯,回報給主對話決定。

只有 name 與 description 為必填。多字欄位使用 camelCase 且必須完全吻合——Claude Code 遇到不認得的欄位會靜默忽略、不報錯,這是 AI 產生定義檔最常見的隱性錯誤。完整支援欄位如下:

欄位說明
name唯一識別碼,最多 256 字元,不可包含 :(保留給 Plugin 命名空間,如 my-plugin:reviewer);Hooks 以此值作為 agent_type;檔名不必與 name 相同
descriptionClaude 何時該委派給這個子 Agent;寫得越具體,自動匹配的命中率越高
tools允許的工具清單(逗號分隔字串或 YAML 清單),省略則繼承全部;清單中沒有任何可解析的工具時會無法啟動
disallowedTools從繼承或指定清單中移除的工具;即使寫成 Bash(git push *) 也會移除整個 Bash 工具
modelsonnet/opus/haiku/fable、完整模型 ID(如 claude-opus-5-5),或 inherit
permissionModedefault(或 manual)/acceptEdits/auto/dontAsk/bypassPermissions/plan;Plugin 提供的子 Agent 會忽略此欄位
maxTurns最大輪數;達上限時輸出會標示為部分結果,Claude 可接續(v2.1.246+)
skills啟動時預先載入完整內容的 Skill 清單
mcpServers只給這個子 Agent 使用的 MCP Server(引用既有名稱或內嵌完整設定);Plugin 子 Agent 忽略
hooks只在這個子 Agent 存活期間生效的 Hook;Plugin 子 Agent 忽略
memory持久記憶範圍:user/project/local(第10.5章)
backgroundtrue 強制背景執行;Fork Mode 開啟時本來就是背景執行
omitClaudeMdtrue 時不載入使用者、專案、本機 CLAUDE.md(Managed 政策檔仍載入),適合只需要委派提示的子 Agent(v2.1.271+)
effort覆寫推理強度:low/medium/high/xhigh/max
autoCompactWindow讓此子 Agent 比主對話更早自動壓縮(v2.1.296+)
isolationworktree:在暫時的 Git Worktree 中執行(預設從預設分支分出),沒有變更時自動清除
color任務清單中的顯示色(red/blue/green/yellow/purple/orange/pink/cyan)
initialPrompt以 --agent 或 agent 設定把此定義當成主 Session 時,自動送出的第一則訊息
experimental實驗選項,目前支援 cacheTtl: 5m|1h(必須寫在 experimental 底下,v2.1.248+)

⚠️ 勘誤:v1.3 寫 name「僅限小寫字母與連字號」,官方實際限制是「最多 256 字元、不可含 :」;團隊仍可自訂「小寫加連字號」作為命名慣例,但那是團隊規範而非系統限制。

10.2 載入順序

flowchart LR
    Managed["1. Managed 設定部署<br/>(組織層級,最高優先)"] --> Merge["合併註冊表"]
    CliFlag["2. --agents 旗標<br/>(當次 Session)"] --> Merge
    ProjectDir["3. .claude/agents/<br/>(專案層級)"] --> Merge
    UserDir["4. ~/.claude/agents/<br/>(使用者層級)"] --> Merge
    PluginDir["5. Plugin 的 agents/<br/>(最低優先)"] --> Merge
    Merge --> Registry["可用子 Agent 清單<br/>(同名以較高優先層級為準)"]
    Registry --> Invoke["依名稱呼叫 / 依描述自動匹配"]

專案層級的 .claude/agents/ 採「由工作目錄往上逐層掃描」的方式載入:從目前目錄一路掃到 repo 根目錄,途中每一個 .claude/agents/ 都會被讀取;同名時離工作目錄較近的定義優先。專案與使用者層級都會遞迴掃描子資料夾(如 agents/review/),子資料夾不影響識別,識別完全依 name;同一層級兩個檔案宣告相同 name 時,只會載入其中一個(依檔案系統讀取順序,沒有保證),務必保持唯一。以 --add-dir 加入的目錄也會載入其中的 .claude/agents/。Plugin 的子資料夾則會成為識別名稱的一部分(例如 my-plugin:review:security)。

name 請避免使用 fork——這是官方保留給 Fork 機制(第9.9章)的內建類型名稱。

10.3 呼叫方式

自 v2.1.198 起,/agents 不再開啟互動式管理面板——執行 /agents 只會提示你請 Claude 建立,或直接編輯 .claude/agents//~/.claude/agents/ 底下的檔案。目前建立與呼叫子 Agent 的方式:

# 1. 請 Claude 依自然語言描述建立子 Agent 檔案(推薦,產出後務必以 check_agents.py 檢查)
claude "在 .claude/agents/ 建立一個 code-improver 子 Agent,
負責掃描程式碼並提出可讀性/效能建議,唯讀、使用 sonnet"

# 2. 讓整個主 Session 以某個子 Agent 的設定運作(其系統提示會完全取代預設提示)
claude --agent code-reviewer

# 3. 以 JSON 動態定義當次 Session 專屬、不落地存檔的子 Agent
claude --agents '{"debugger":{"description":"除錯專家","prompt":"你是除錯專家","tools":["Read","Grep","Bash"]}}'

在對話中指定子 Agent:

使用 test-writer 子 Agent 幫 PaymentService 補測試          ← 自然語言:Claude 自行判斷是否委派
@"code-reviewer (agent)" 看一下 auth 相關的變更              ← 從 @ 選單挑選:保證由該子 Agent 執行
@agent-code-reviewer 看一下 auth 相關的變更                  ← 手動輸入的等效寫法

新增或編輯 .claude/agents/ 下的檔案,Claude Code 通常幾秒內就會套用,不需要重啟;但若是該層級第一次建立 agents/ 資料夾,仍需重啟 Session 才會開始監看。要委派一個繼承目前對話完整上下文的側支任務(不需要定義檔),改用 /subtask <任務描述>(第9.9章)。

10.4 內建子 Agent

內建子 Agent模型工具範圍用途
Explore主對話模型;主對話為 Fable 時,訂閱/Console/LLM Gateway 改用 opus 別名對應的模型唯讀(拒絕 Write/Edit)程式碼搜尋與探索,依 quick/medium/very thorough 調整範圍
Plan繼承主對話模型唯讀Plan 模式下的研究輔助,讓主對話保持唯讀
general-purpose繼承主對話模型全部工具需要探索又需要修改的複合任務
statusline-setupSonnet—執行 /statusline 時設定狀態列
claude-code-guideHaiku—回答關於 Claude Code 本身功能的問題

Explore 與 Plan 為了保持快速、低成本,不會載入 CLAUDE.md 與 Git 狀態;其餘內建與自訂子 Agent 都會載入(除非設定 omitClaudeMd)。若想讓 Explore 固定跑在低成本模型,可自建一個名為 Explore 的專案/使用者層級子 Agent 並指定 model: haiku。要停用某個內建子 Agent,在 permissions.deny 加入 Agent(Explore);要完全禁止委派,deny Agent 工具本身;只想移除 Explore/Plan,設定環境變數 CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1。

10.5 Persistent Memory(子 Agent 持久記憶)

建立子 Agent 時可用 memory 欄位啟用持久記憶,讓子 Agent 在跨對話之間累積程式碼慣例、除錯經驗、架構決策等知識:

Scope路徑適用情境
user~/.claude/agent-memory/<agent名稱>/這個子 Agent 的學習內容適用於你所有專案
project.claude/agent-memory/<agent名稱>/知識屬於特定專案,且希望團隊透過版控共用(建議預設選擇)
local.claude/agent-memory-local/<agent名稱>/知識屬於特定專案,但不適合提交版控

啟用後,Read/Write/Edit 工具會自動加入該子 Agent,系統提示也會附上目前 MEMORY.md(前 200 行或 25KB,取先達到者)。實務上可在系統提示中直接寫「開始工作前先檢查你的記憶」「完成後把學到的東西存進記憶」,讓子 Agent 主動維護自己的知識庫。

⚠️ 注意:project 範圍的記憶會進版控,等同於「由 AI 撰寫、團隊共用的文件」,應納入 PR 審查,避免錯誤的經驗被當成團隊共識擴散。

10.6 實務範例:團隊共用子 Agent

平台團隊可以把常用的子 Agent(程式碼審查、文件撰寫、遷移輔助、安全掃描)統一提交到 .claude/agents/,每個人 clone 專案後就自動擁有同一套子 Agent。建議的維護流程:

  1. 新增或修改子 Agent 一律走 PR,CI 執行 python check_agents.py agent .claude/agents/*.md(第30章)。
  2. 審查重點:tools 是否最小、permissionMode 是否合理(審查類用 plan)、description 是否具體、系統提示是否要求「附證據」。
  3. 每季檢視一次:哪些子 Agent 從未被使用(可從 OpenTelemetry 的 agent.name 維度查看),哪些權限可以再收斂。

📌 實務建議:description 欄位寫得越精確,自動匹配的命中率越高;建議用「動作 + 對象 + 時機」的句型,例如「審查剛完成的 Java 變更是否符合公司安全規範。完成一段實作後主動使用」。

⚠️ 注意:子 Agent 的 tools 授權範圍應該定期稽核,過寬的工具授權(例如賦予不必要的 Bash 權限)會讓「隔離」失去意義。

實務案例:平台團隊將 code-reviewer、doc-writer、migration-helper、security-scanner 四個子 Agent 提交到 .claude/agents/,並在 CI 加上 frontmatter 檢查;某次有人把 permissionMode 打成 permission-mode,CI 立刻擋下——若沒有檢查,這個欄位會被靜默忽略,審查者子 Agent 就會以預設模式執行。

10.7 Subagent 的 Effort、模型與權限行為變更(v3.0 新增)

變更版本影響與做法
與主對話不同模型的 Subagent/Teammate,改用該模型自己儲存的 Effort 或其預設,不再沿用 Session 的 Effortv2.1.317主對話 /effort max 不會讓 Haiku Subagent 也跑 max;要指定請寫 frontmatter 的 effort
CLAUDE_CODE_SUBAGENT_EFFORTv2.1.316沒有其他來源指定時,Subagent 使用此 Effort
被輸出 Token 上限截斷的 Subagent 會被要求以更精簡的方式重新給出完整答案v2.1.325不再只拿到答案的後半段
被同層 Subagent 訊息喚醒的 Subagent 遵循 Session 的權限設定v2.1.327可能開始詢問,或在無人回應時被拒
核准 Subagent 計畫的卡片只剩「Yes, and switch to default (ask each time)」與「No」v2.1.326核准計畫的同時會把該 Session 切回逐次詢問
Plugin 提供的 agent 設定(讓主對話以 Plugin 的子 Agent 執行)棄用,仍生效但啟動、claude plugin list 與 claude plugin validate 會警告v2.1.323子 Agent 本身放在 Plugin 的 agents/ 目錄;要讓主對話以某個子 Agent 執行,由使用者以 agent 設定或 --agent 指定。注意 plugin.json 裡的 "agent" 不是這個設定:v3.0 實測 claude plugin validate 判為未知欄位(「did you mean ‘agents’?」)且不生效
CLAUDE_CODE_DISABLE_AGENT_PROGRESS_SUMMARIES=1v2.1.323(v2.1.318 起可用)關閉 Subagent 進度摘要與產生摘要的請求,可省 Token

一份明確指定模型與 Effort、可被稽核的子 Agent 定義(已通過第30章 check_agents.py):

---
name: dependency-auditor
description: 檢查 pom.xml/package.json 的相依套件版本與已知弱點,只讀不改。需要相依套件稽核時使用。
tools: Read, Grep, Glob, Bash
model: haiku
effort: medium
disallowedTools: Write, Edit, NotebookEdit
---
你是相依套件稽核員。只讀取檔案與執行列出的稽核指令,不修改任何檔案。
輸出一張表:套件、目前版本、建議版本、弱點編號、證據(指令輸出的行)。
沒有證據的項目標示為「未驗證」,不要猜測版本號。

審查這份定義時要注意:tools 只決定子 Agent 有哪些工具,不決定 Bash 能執行哪些指令;disallowedTools 中寫 Bash(git push *) 也會移除整個 Bash 工具。要「保留 Bash 但禁止特定指令」,請在設定檔加 Bash 的 deny 規則(第6.6.3章)。本例以 disallowedTools 移除檔案寫入工具,讓「只讀不改」由工具清單保證,而不只寫在提示中。

📌 實務建議:在 frontmatter 明確寫 model 與 effort,比依賴 Session 的設定更容易審查與重現;成本敏感的稽核類子 Agent 用 haiku+medium,需要深度推理的設計審查才用 opus。

10.8 本章審查與驗證清單

AI 產出項目❌ 常見錯誤✅ 正確做法人工如何驗證
Frontmatter 欄位permission-mode、allowed_tools、maxturns 等拼法(會被靜默忽略)camelCase 且與官方欄位表完全一致python check_agents.py agent <file>
name含 :、使用保留字 fork、與其他檔案重名唯一、不含 :檢查工具+grep -rh "^name:" .claude/agents | sort | uniq -d 找重名
tools 權限審查類子 Agent 給了 Edit/Write審查類只給 Read/Grep/Glob/Bash,並設 permissionMode: planCode Review 比對任務需求與工具清單
cacheTtl寫在 frontmatter 頂層寫在 experimental: 底下檢查工具會報錯
disallowedTools 用法以為 Bash(git push *) 只擋 push帶限定詞也會移除整個工具;細部限制改用權限規則或 Hook啟動子 Agent 後請它執行 git status,確認 Bash 是否還在
子 Agent 系統提示只寫角色,不寫流程、輸出格式與限制寫清楚步驟、輸出格式、禁止事項與「需附證據」用固定測試案例呼叫子 Agent,檢查輸出是否符合格式
子 Agent 的 Effort以為主對話 /effort 的值會套用到所有子 Agentv2.1.317 起不同模型的子 Agent 用自己的 Effort;需要時在 frontmatter 寫 effort/tasks 開啟子 Agent 查看其模型與 Effort;以 check_agents.py 驗證 effort 值
Plugin 與子 Agent在 plugin.json 寫 "agent" 欄位,或依賴 Plugin 的 agent 設定切換主對話子 Agent 放 Plugin 的 agents/ 目錄;主對話要用哪個子 Agent 由使用者以 agent 設定或 --agent 決定claude plugin validate 對 plugin.json 的 agent 報「Unknown field」(v3.0 實測)

第 11 章 CLAUDE.md

本章目標:寫出精簡、有效、可維護的 CLAUDE.md,理解各層級檔案的載入順序、@ 匯入、.claude/rules/ 路徑範圍化規則、Auto Memory 與 AGENTS.md 的關係。讀完後,你應該能審查一份 AI 產生的 CLAUDE.md,判斷它是否會被正確載入、是否太長、規則是否放對位置。

11.1 用途

CLAUDE.md 是 Claude Code 每次啟動 Session 都會自動載入的專案上下文檔案,用來記錄架構慣例、技術棧、建置/測試指令、安全注意事項,以及「不要做什麼」的限制。它的本質是把工程師重複口頭/書面交代的事情「一次寫好、長期重用」。

要特別理解的一點:CLAUDE.md 是Context,不是強制設定。Claude 會盡量遵循,但沒有強制力;「無論如何都必須擋下」的規則應寫成權限規則或 Hook(第5、12章)。

11.2 四層檔案

層級路徑用途共享對象
企業 Managed 政策macOS /Library/Application Support/ClaudeCode/CLAUDE.md、Linux/WSL /etc/claude-code/CLAUDE.md、Windows C:\Program Files\ClaudeCode\CLAUDE.md(或 Managed 設定的 claudeMd 鍵)組織全體強制套用,個別使用者無法排除機器上所有使用者
使用者個人~/.claude/CLAUDE.md個人偏好,跨專案生效只有你
專案共用./CLAUDE.md 或 ./.claude/CLAUDE.md(沒有 CLAUDE.md 時可改讀 AGENTS.md,第11.7章)團隊共識,提交版控團隊
本機限定./CLAUDE.local.md個人專案備註,加入 .gitignore只有你
graph TD
    Managed["Managed 政策 CLAUDE.md<br/>(企業強制,最先載入)"] --> Effective["最終生效的<br/>Project Context"]
    User["~/.claude/CLAUDE.md<br/>(個人偏好)"] --> Effective
    Project["./CLAUDE.md 或 ./.claude/CLAUDE.md<br/>(專案共用,版控)"] --> Effective
    Local["./CLAUDE.local.md<br/>(本機限定,不版控)"] --> Effective

載入規則:

  • Claude Code 從工作目錄往上逐層讀取 CLAUDE.md/CLAUDE.local.md:在 foo/bar/ 啟動,會讀到 foo/bar/CLAUDE.md、foo/CLAUDE.md 及對應的 CLAUDE.local.md。這些檔案全部串接注入 Context,而不是互相覆寫,順序由檔案系統根目錄往工作目錄排列,同一目錄內 CLAUDE.local.md 接在 CLAUDE.md 之後。
  • 子目錄的 CLAUDE.md 不在啟動時載入,而是 Claude 讀、寫或編輯該子目錄檔案時才隨附載入。
  • --add-dir 加入的目錄預設不載入 CLAUDE.md,需設定 CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1。
  • 區塊層級的 HTML 註解(<!-- 給維護者的說明 -->)會在注入前被移除,可用來留給人看的備註而不耗 Token。
  • 超過 4 MiB 的檔案會被略過;官方建議每個 CLAUDE.md 控制在 200 行以內,過長會降低遵循度。

@ 匯入:CLAUDE.md 可用 @path/to/file 匯入其他檔案(相對路徑以「含此匯入的檔案」為基準,最多遞迴 4 層);寫在反引號中的 `@README` 不會被匯入。專案層級檔案匯入工作目錄以外的檔案時,第一次會跳出核准對話框,避免他人提交的檔案偷偷引入外部內容。注意:匯入只是幫助整理,被匯入的檔案在啟動時一樣全部載入,不會降低 Context 成本。

11.3 企業標準範本

以下範本示範「只放每次都需要知道的事」:建置與測試指令、架構慣例、必須遵守的限制,其餘細節以 @ 匯入或移到 .claude/rules/:

# 訂單服務(order-service)

訂單建立、付款回呼與出貨通知的後端服務。Java 21、Spring Boot 3.5、PostgreSQL 16。

## 建置與測試

- 建置:`./mvnw -q -DskipTests package`
- 單元測試:`./mvnw test`
- 單一測試類別:`./mvnw test -Dtest=OrderServiceTest`
- 靜態檢查:`./mvnw -q spotless:check`

## 架構慣例

- 分層:`controller` → `service` → `repository`,Controller 不得直接呼叫 Repository。
- DTO 一律用 Java `record`;本專案不使用 Lombok。
- 金額使用 `BigDecimal`,四捨五入一律 `RoundingMode.HALF_UP`。

## 必須遵守

- 不可在 Service 層以字串拼接 SQL;使用 Spring Data 或具名參數。
- 付款相關欄位(卡號、CVV)不得寫入任何 log。
- 修改 `src/main/resources/db/migration/` 時只能新增檔案,不可修改已存在的 migration。

## 參考文件

- API 規格:@docs/openapi.yaml
- 路徑範圍化規則:`.claude/rules/`

11.4 維護方式

CLAUDE.md 應該被當成「活文件」,在 PR 流程中與程式碼一起檢視更新,而不是寫一次就再也不碰:

動作工具
新專案產生初稿/init(設定 CLAUDE_CODE_NEW_INIT=1 會進入互動流程,連同 Skills、Hooks 與個人設定一起引導)
查看目前載入了哪些檔案、編輯檔案、開關 Auto Memory/memory
檢查 CLAUDE.md、Skill、Agent 是否還在用為舊模型寫的提示模式/doctor prompt-audit(v2.1.283+)
確認哪些規則檔在何時被載入InstructionsLoaded Hook(第12章)
大型 Monorepo 排除其他團隊的 CLAUDE.mdclaudeMdExcludes 設定(第11.8章)

📌 實務建議:CLAUDE.md 內容會載入每次 Session 的 Context,不要把整份 API 規格或巨大表格塞進去,只放「真正每次都需要知道」的精華內容;只和部分程式碼有關的規則移到有 paths 的 Rules,多步驟程序移到 Skill(第27章)。

⚠️ 注意:沒有 CLAUDE.md 的專案,每次新 Session 都要重新解釋一次建置指令與規範,新人 Onboarding 體驗會明顯比有 CLAUDE.md 的專案差。

實務案例:某團隊導入 CLAUDE.md 前,每個新 Session 都要重新告知「我們不用 Lombok」,導入後新人第一次使用 Claude Code 就自動遵守此規範;後來 CLAUDE.md 長到 450 行、遵循度下降,團隊把前後端各自的規則拆到 .claude/rules/frontend/、.claude/rules/backend/,主檔回到 120 行,問題隨之消失。

11.5 Auto Memory(自動記憶):Claude 自己寫的筆記

CLAUDE.md 之外,Claude Code 還有第二套跨 Session 記憶機制——Auto Memory(本機 Session 預設開啟)。CLAUDE.md 是「你寫給 Claude 的規則」,Auto Memory 是「Claude 自己記下、對未來對話有用的資訊」:

比較項目CLAUDE.mdAuto Memory
誰來寫工程師Claude 自己
內容性質規則、慣例、建置與測試指令、架構決策四類筆記:user(你的角色與偏好)、feedback(你的糾正與確認過的做法)、project(程式碼與 git 歷史看不出來的進行中工作、期限與決策)、reference(外部資訊的位置,如追蹤系統、儀表板)
不會寫的內容—能從程式碼推導出的內容(架構、檔案路徑、除錯修正),以及 CLAUDE.md 已經寫過的內容
範圍專案/使用者/組織每個 Git repo 一份,所有 Worktree 與子目錄共用;僅限本機
載入方式每次 Session 全文載入每次 Session 載入 MEMORY.md 前 200 行或 25KB(取先達到者)

⚠️ 勘誤:v1.3 寫 Auto Memory 會記「學到的建置指令、除錯線索」,目前官方行為是刻意不記能從程式碼推導的內容(含除錯修正),只記上述四類。建置與測試指令請寫進 CLAUDE.md。

Auto Memory 的儲存位置是 ~/.claude/projects/<project>/memory/:

~/.claude/projects/<project>/memory/
├── MEMORY.md          # 索引,每次 Session 開頭載入(前 200 行或 25KB)
├── feedback-testing.md  # 個別主題筆記,需要時才讀取
└── ...
{ "autoMemoryEnabled": false }
{ "autoMemoryDirectory": "~/my-custom-memory-dir" }

在 /memory 中可切換 Auto Memory(寫入 ~/.claude/settings.json);只想對某個專案關閉,在該專案設定 autoMemoryEnabled: false;也可用環境變數 CLAUDE_CODE_DISABLE_AUTO_MEMORY=1。背景 Session 與由另一個 Claude Code 啟動的 Session 只能關閉、不能在其中重新開啟。當你說「以後都用 pnpm」這類偏好時,Claude 通常會寫進 Auto Memory;若要確保寫進團隊共用的 CLAUDE.md,請明確要求「把這個寫進 CLAUDE.md」。

📌 實務建議:定期打開 /memory 檢視 Claude 記了什麼;Auto Memory 是 Claude 的判斷,可能記錯或過時,發現錯誤就直接刪改。

⚠️ 注意:Auto Memory 是 Context(模型會盡量遵循但無強制力);需要「不管 Claude 怎麼判斷都必須擋下」的規則,仍應使用權限規則或 PreToolUse Hook(第12章)。

11.6 .claude/rules/:路徑範圍化的模組化規則

大型專案的 CLAUDE.md 若塞入過多規則,會拖累每次 Session 的基礎 Token 成本、也會降低遵循度。.claude/rules/ 讓你把規則拆成多個主題檔案,並可選擇只在 Claude 處理符合特定路徑的檔案時才載入:

your-project/
├── .claude/
│   ├── CLAUDE.md           # 主要專案指令
│   └── rules/
│       ├── code-style.md   # 沒有 paths frontmatter:每次 Session 都載入
│       ├── testing.md
│       └── backend/
│           └── api.md      # 支援巢狀子目錄

一份只在處理 Controller/API 程式時才載入的規則(.claude/rules/backend/api.md):

---
paths:
  - "src/main/java/**/controller/**/*.java"
  - "src/main/java/**/api/**/*.java"
---

# REST API 規則

- 所有對外端點的輸入 DTO 必須加上 Bean Validation 註解(`@NotNull`、`@Size` 等),Controller 方法參數加 `@Valid`。
- 錯誤一律回傳 RFC 9457 `ProblemDetail`,不可回傳堆疊追蹤。
- 新增端點時,同步更新 `docs/openapi.yaml`,並在對應的 `*ControllerTest` 補上 400/404 案例。

沒有 paths 欄位的規則檔會在啟動時無條件載入(優先序與 .claude/CLAUDE.md 相同);有 paths 的規則檔則在 Claude 讀取或編輯符合 glob 的檔案時才載入,壓縮時會被摘要掉,直到下次碰到符合的檔案才重新載入(第8.2章)。.claude/rules/ 支援 symlink,可讓多個專案共用同一份規則庫;~/.claude/rules/ 則是套用到你本機所有專案的個人規則,載入順序在專案規則之前(優先序較低)。

📌 實務建議:若 CLAUDE.md 裡有一段內容只跟前端或後端其中一邊有關,優先移到對應的路徑範圍規則;但安全相關、必須全程生效的規則不要加 paths,以免壓縮後消失。

11.7 AGENTS.md:與其他 AI 編碼工具共用指令檔

自 v2.1.277 起,Claude Code 能直接讀取 AGENTS.md(其他編碼代理人常用的指令檔),已經為其他工具準備好的 repo 不需要再加 CLAUDE.md 或匯入:

repo 中有Claude 讀取
AGENTS.md,且工作目錄及上層都沒有 CLAUDE.md/CLAUDE.local.mdAGENTS.md(含 .claude/AGENTS.md),啟動時會顯示 no CLAUDE.md found; AGENTS.md loaded: ...
AGENTS.md 與 CLAUDE.md(或 CLAUDE.local.md)只讀 CLAUDE.md
CLAUDE.md 內寫了 @AGENTS.mdCLAUDE.md,AGENTS.md 透過匯入載入(不會重複讀取)

可在 /config 的 Project instructions 改變預設:claude-md-or-agents-md(預設)、claude-md-and-agents-md(兩者都讀)、claude-md(只讀 CLAUDE.md)、managed-only(只讀組織 Managed CLAUDE.md 與 Auto Memory)。也可以寫在使用者或 Managed 設定(專案設定中會被忽略):

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

⚠️ 注意:加一個 CLAUDE.local.md 也算「有 CLAUDE.md」,會讓 Claude 停止讀取 AGENTS.md——若團隊以 AGENTS.md 為主、個人又想放 CLAUDE.local.md,請改設 claude-md-and-agents-md。AGENTS.local.md、AGENTS.override.md 與 .agents/ 目錄不會被讀取。v2.1.285 以前此 Plugin ID 為 agents-md@builtin。在 Windows 上要讓兩個檔案共用,建議用 @AGENTS.md 匯入而非 symlink(Windows 建立 symlink 需要系統管理員或開發者模式)。

11.8 大型團隊與 Monorepo 的記憶治理

  • 組織層級 CLAUDE.md:以 MDM、GPO、Ansible 等工具把公司編碼規範與安全政策部署到 Managed 政策路徑,個別使用者無法排除;或在 Managed 設定以 claudeMd 鍵直接內嵌。
  • 排除不相關的 CLAUDE.md:Monorepo 中其他團隊的 CLAUDE.md 也會因為「往上逐層讀取」而被載入,可用 claudeMdExcludes(glob,比對絕對路徑,各層級合併)略過:
{
  "claudeMdExcludes": [
    "**/legacy-billing/CLAUDE.md",
    "**/teams/mobile/**/CLAUDE.md"
  ]
}
  • 跨 Worktree 共用個人說明:被 gitignore 的 CLAUDE.local.md 只存在於建立它的 Worktree;要在所有 Worktree 共用,改在 CLAUDE.md 中匯入家目錄的檔案(@~/.claude/my-project-instructions.md)。

11.9 CLAUDE.md 沒生效時的排查(v3.0 新增)

「Claude 沒照 CLAUDE.md 做」有兩類完全不同的原因:檔案沒有載入,或載入了但寫法讓模型難以遵守。先分清楚是哪一類再動手:

步驟指令判斷
1/context(全螢幕模式用 /context all)記憶檔分類中沒有該檔案 → 載入問題;有 → 寫法問題
2/memory列出使用者與專案層級實際載入的記憶檔路徑,可直接開啟編輯
3檢查位置子目錄的 CLAUDE.md 是按需載入,在 Claude 讀取該子目錄的檔案之前本來就不會出現在 /context
4檢查 Subagent內建 Explore 與 Plan 子 Agent 啟動時不讀 CLAUDE.md;自訂子 Agent 會讀,除非定義檔設了 omitClaudeMd
5寫法問題指示含糊、兩個檔案互相矛盾、檔案太長導致個別規則被稀釋,都會降低遵守度;把「必須」的規則改成 deny 規則或 Hook
/context all
/memory

v2.1.312 修正了一個與大型 CLAUDE.md 有關的風險:Claude 只看到檔案開頭就覆寫子目錄中很大的 CLAUDE.md、Rules 或被 @ 匯入的檔案。新版本的 Write 工具會要求先讀完整個檔案或改用就地編輯。若你的團隊有超過數百行的 CLAUDE.md,除了升級,也建議拆成 .claude/rules/ 的路徑範圍化規則(第11.6章)。

⚠️ 注意:CLAUDE.md 是「告訴 Claude 這個專案怎麼運作」,不是安全邊界。「絕對不能發生」的事(刪除正式資料、推送到 main)必須用權限規則、Hook 或 Sandbox 強制,即使 CLAUDE.md 已經寫了。

11.10 本章審查與驗證清單

AI 產出項目❌ 常見錯誤✅ 正確做法人工如何驗證
CLAUDE.md 長度與內容超過 200 行、塞入整份 API 規格或 README 內容只放每次都需要的指令與限制,其餘用 @ 匯入、Rules 或 Skillwc -l CLAUDE.md;/context 看 Memory 佔用
指令的可執行性寫了不存在的建置指令或錯誤的測試指令每條指令都在乾淨環境實跑過逐條複製到終端機執行
規則的放置位置安全規則放在有 paths 的 Rules,壓縮後消失必須全程生效的規則放根目錄 CLAUDE.md 或無 paths 的 Rules長對話 /compact 後詢問 Claude 是否仍知道該規則
檔名與位置.claude.local.md、claude.md 放錯目錄CLAUDE.local.md 放專案根目錄並加入 .gitignore/memory 確認檔案出現在載入清單
強制性規則以為寫在 CLAUDE.md 就「保證」不會發生強制規則改用 permissions.deny 或 Hook以第12章 harness 驗證 Hook 真的阻擋
AGENTS.md 共用同時放 CLAUDE.md 與 AGENTS.md,以為兩者都會讀依第11.7章規則,或設定 claude-md-and-agents-md啟動訊息與 /memory 確認實際讀取的檔案
外部匯入專案 CLAUDE.md 匯入 ~/ 或絕對路徑的檔案而不自知外部匯入需核准,團隊檔案只匯入 repo 內路徑grep -nE "@(~|/)" CLAUDE.md
CLAUDE.md 排查Claude 沒遵守就一直加長 CLAUDE.md、加更多「務必」先用 /context 判斷是否載入;載入了才修寫法,必要規則改用權限或 Hook/context all 截圖附在 PR;改寫後以同一個 Prompt 重跑比較
子 Agent 與 CLAUDE.md以為 Explore/Plan 子 Agent 也會遵守 CLAUDE.md內建 Explore/Plan 不讀 CLAUDE.md;關鍵約束要寫進委派 Prompt 或自訂子 Agent在 /tasks 開啟子 Agent,檢查其 Context 是否包含記憶檔

第 12 章 Hooks

本章目標:寫出結構正確、行為可預期、可被自動化測試的 Hook。讀完後,你應該能分辨 exit 0/2/其他碼的差異,知道 matcher 與 if 各比對什麼,並能用本章的 harness 在合併前證明一支 Hook 真的會擋下該擋的指令。

12.1 生命週期事件

Hook 是在 Claude Code 生命週期特定時點自動執行的腳本、HTTP 端點、MCP 工具或提示。官方目前共有 33 個事件,依作用範圍分類:

分類事件
Session 層級SessionStart、SessionEnd、Setup(以 --init/--init-only/--maintenance 觸發)
對話輪層級UserPromptSubmit、UserPromptExpansion、Stop、StopFailure、MessageDisplay
工具層級PreToolUse、PostToolUse、PostToolUseFailure、PostToolBatch、PermissionRequest、PermissionDenied
Subagent 與任務SubagentStart、SubagentStop、TaskCreated、TaskCompleted、TeammateIdle
記憶與設定InstructionsLoaded(記錄實際載入了哪些 CLAUDE.md/Rules,第11.6章)、ConfigChange
檔案系統與目錄CwdChanged、DirectoryAdded、FileChanged、WorktreeCreate、WorktreeRemove
Context 與模型PreCompact、PostCompact、PreModelSwitch、PostModelSwitch
通知與 MCPNotification、Elicitation、ElicitationResult

Hook 可以定義在:使用者設定、專案設定、本機設定、Managed 設定、Plugin 的 hooks/hooks.json、Skill 的 frontmatter(Skill 被呼叫後持續到 Session 結束)、Subagent 的 frontmatter(只在該 Subagent 執行期間)。

12.2 Handler 類型

type必要欄位選用欄位用途
commandcommandargs(有 args 時以 exec 形式執行、不經 Shell)、async、asyncRewake、shell、onFailure執行腳本,最常用
httpurlheaders、allowedEnvVars、onFailure把事件 JSON POST 到外部端點(企業稽核服務)
mcp_toolserver、toolinput呼叫已設定的 MCP 工具
promptpromptmodel交給模型判斷($ARGUMENTS 會替換成輸入 JSON)
agentpromptmodel派生子 Agent 判斷(實驗性)

所有類型都可加 if(只在工具事件生效的權限規則篩選)、timeout(秒;預設 command/http/mcp_tool 為 600、prompt 為 30、agent 為 60)、statusMessage(執行時的提示文字)。Windows 上要以 PowerShell 撰寫 command Hook,加上 "shell": "powershell"(預設為 bash;沒有 Git Bash 的 Windows 預設為 powershell)。

12.3 PreToolUse/PostToolUse 機制

sequenceDiagram
    participant A as Agent
    participant H as PreToolUse Hook
    participant P as 權限規則與模式
    participant T as 工具
    participant Q as PostToolUse Hook
    A->>H: 即將呼叫工具(stdin 傳入 JSON)
    H-->>A: exit 0 放行 / exit 2 阻擋 / JSON 決策
    A->>P: 依規則與權限模式決定是否詢問
    A->>T: 執行工具(若允許)
    T-->>Q: 工具完成(stdin 含工具結果)
    Q-->>A: 後處理(格式化、記錄)或回饋給 Claude

輸入:Hook 從 stdin 收到 JSON,共通欄位包括 session_id、transcript_path、cwd、permission_mode、hook_event_name;PreToolUse 另有 tool_name、tool_input、tool_use_id。以 Bash 為例:

{
  "session_id": "abc123",
  "cwd": "/home/user/my-project",
  "permission_mode": "default",
  "hook_event_name": "PreToolUse",
  "tool_name": "Bash",
  "tool_input": { "command": "npm test", "description": "Run test suite" },
  "tool_use_id": "toolu_01ABC123"
}

輸出(command Hook 的結束碼)——這是最常寫錯的地方:

結束碼意義行為
0成功放行;stdout 若整段是一個 JSON 物件則解析為決策,否則當純文字(UserPromptSubmit、SessionStart 等事件會把純文字加入 Context)
2阻擋在可阻擋的事件上擋下動作,stderr 內容作為理由回饋給 Claude;此時 JSON 無法覆蓋阻擋
其他(含 1)非阻擋錯誤動作照常進行,只顯示 <hook name> hook error 提示

⚠️ 注意:exit 1 不會阻擋任何動作。政策型 Hook 一定要用 exit 2,或回傳 JSON 決策,並建議加上 "onFailure": "block"(v2.1.295+),讓「Hook 無法啟動、逾時、以非預期結束碼結束」時也視同阻擋。第12.6章的反向測試會實際證明 exit 1 版本擋不住任何東西。

JSON 決策(exit 0 並輸出單一 JSON 物件):PreToolUse 用 hookSpecificOutput.permissionDecision,值為 allow/deny/ask/defer,搭配 permissionDecisionReason;也可用 updatedInput 改寫工具參數、additionalContext 補充 Context。UserPromptSubmit、PostToolUse、Stop 等事件則用頂層的 "decision": "block" 加 reason(例如 Stop Hook 回傳 block 可要求 Claude 繼續工作)。

12.4 設定範例

Hook 設定的正確結構是「事件 → matcher 群組陣列 → 每組的 hooks 陣列」。matcher 比對的是工具名稱("Bash"、"Write|Edit"、"mcp__github__.*";只含英數、_、-、空白、,、| 時為精確比對或清單,含其他字元時視為不錨定的 JavaScript 正規表示式,"*"/空字串/省略代表全部);要依指令內容篩選,用 handler 的 if 欄位,裡面放一條權限規則語法(例如 "Bash(rm *)"、"Edit(**/*.ts)"),且一次只能一條。

以下設定已通過第30章 check_settings.py 驗證:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "bash",
            "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/block-dangerous.sh"],
            "timeout": 10,
            "onFailure": "block"
          }
        ]
      },
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash",
            "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/block-secrets.sh"],
            "timeout": 10
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "if": "Edit(**/*.ts)",
            "command": "npx prettier --write \"$(jq -r '.tool_input.file_path')\"",
            "timeout": 60
          }
        ]
      }
    ],
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "echo \"目前分支:$(git branch --show-current)\""
          }
        ]
      }
    ]
  }
}

阻擋危險指令的 PreToolUse Hook(.claude/hooks/block-dangerous.sh),以 exit 2 阻擋:

#!/usr/bin/env bash
# PreToolUse hook:阻擋危險的 Bash 指令(matcher: "Bash")
# 輸入:stdin 為 Claude Code 傳入的 JSON(含 tool_name、tool_input.command)
# 輸出:exit 0 = 放行;exit 2 = 阻擋(stderr 內容會回饋給 Claude 作為理由)
set -u

if ! command -v jq >/dev/null 2>&1; then
  # 依賴缺失時採 fail-closed:寧可擋下也不要無聲放行
  echo "block-dangerous.sh: 找不到 jq,基於安全預設阻擋此指令" >&2
  exit 2
fi

input="$(cat)"
tool_name="$(printf '%s' "$input" | jq -r '.tool_name // empty')"
cmd="$(printf '%s' "$input" | jq -r '.tool_input.command // empty')"

# 只處理 Bash;其他工具一律放行
[ "$tool_name" = "Bash" ] || exit 0

block() {
  echo "已被企業政策阻擋:$1。指令:$cmd" >&2
  exit 2
}

# 1. 強制推送(允許較安全的 --force-with-lease)
if printf '%s' "$cmd" | grep -Eq 'git[[:space:]]+push([[:space:]].*)?[[:space:]](--force([[:space:]]|$)|-f([[:space:]]|$))'; then
  block "禁止 git push --force / -f,請改用 --force-with-lease 並經過審查"
fi

# 2. 對根目錄或家目錄的遞迴刪除
if printf '%s' "$cmd" | grep -Eq 'rm[[:space:]]+-[a-zA-Z]*r[a-zA-Z]*f?[a-zA-Z]*[[:space:]]+(/|~|\$HOME)([[:space:]]|/?$)'; then
  block "禁止遞迴刪除根目錄或家目錄"
fi

# 3. 下載後直接執行(curl | bash、wget | sh)
if printf '%s' "$cmd" | grep -Eq '(curl|wget)[^|]*\|[[:space:]]*(sudo[[:space:]]+)?(ba|z)?sh'; then
  block "禁止下載後直接以 shell 執行"
fi

exit 0

阻擋寫入金鑰的 PreToolUse Hook(.claude/hooks/block-secrets.sh),以 JSON 決策回覆:

#!/usr/bin/env bash
# PreToolUse hook:阻擋把疑似金鑰寫進檔案(matcher: "Write|Edit")
# 以 JSON 的 permissionDecision 回覆,而不是 exit 2,示範結構化決策的寫法
set -u

if ! command -v jq >/dev/null 2>&1; then
  echo "block-secrets.sh: 找不到 jq,基於安全預設阻擋" >&2
  exit 2
fi

input="$(cat)"
# Write 的內容在 tool_input.content;Edit 的新內容在 tool_input.new_string
text="$(printf '%s' "$input" | jq -r '[.tool_input.content, .tool_input.new_string] | map(select(. != null)) | join("\n")')"
file="$(printf '%s' "$input" | jq -r '.tool_input.file_path // "(unknown)"')"

pattern='AKIA[0-9A-Z]{16}|-----BEGIN ([A-Z]+ )?PRIVATE KEY-----|ghp_[A-Za-z0-9]{36}|sk-ant-[A-Za-z0-9_-]{20,}'

if printf '%s' "$text" | grep -Eq "$pattern"; then
  jq -n --arg f "$file" '{
    hookSpecificOutput: {
      hookEventName: "PreToolUse",
      permissionDecision: "deny",
      permissionDecisionReason: ("偵測到疑似金鑰,拒絕寫入 " + $f + ";請改用 Secret Manager 或環境變數")
    }
  }'
  exit 0
fi

exit 0

⚠️ 勘誤:v1.3 的範例使用 "handlers": [...] 並把 matcher 寫成 "Bash(rm -rf:*)"。這兩點都不正確:鍵名必須是 "hooks",matcher 只比對工具名稱,權限規則語法要放在 handler 的 "if"。v1.3 的寫法會被 Claude Code 判定為無效項目而略過——也就是那支「安全 Hook」從來沒有執行過。

Windows/PowerShell 版本:matcher 同時涵蓋 Bash|PowerShell,因為一條 if 只能比對一種工具,所以每種工具各用一個 handler;建議用 exec 形式(command 加 args)並以 ${CLAUDE_PROJECT_DIR} 引用腳本,不需處理引號:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash|PowerShell",
        "hooks": [
          {
            "type": "command",
            "if": "Bash(rm *)",
            "command": "powershell.exe",
            "args": ["-NoProfile", "-ExecutionPolicy", "Bypass", "-File", "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.ps1"]
          },
          {
            "type": "command",
            "if": "PowerShell(Remove-Item *)",
            "command": "powershell.exe",
            "args": ["-NoProfile", "-ExecutionPolicy", "Bypass", "-File", "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.ps1"]
          }
        ]
      }
    ]
  }
}

路徑佔位符 ${CLAUDE_PROJECT_DIR} 永遠指向 Session 啟動時的專案根目錄;Claude 進入 Worktree 或 cd 之後,請改讀輸入 JSON 的 cwd 欄位取得目前目錄。Plugin 內的 Hook 則用 ${CLAUDE_PLUGIN_ROOT}。

12.5 安全考量

Hook 腳本以使用者的完整權限執行,而且在 OS Sandbox 之外執行(第19.4章),應該視同 CI 腳本一樣審查與管控:

  • 不應讓任何貢獻者未經審查就修改專案層級的 Hook:把 .claude/ 納入 CODEOWNERS,變更需平台/資安團隊核准。
  • 安全關鍵的 Hook 放在 Managed 層級,並設定 allowManagedHooksOnly: true,讓使用者、專案、Plugin 的 Hook 不再執行(disableAllHooks 則是全部停用,用於排查)。
  • 工作區信任:互動 Session 在你接受工作區信任對話框前不會執行任何 Hook;但 -p 與 SDK Session 不顯示對話框、直接視為信任,repo 中 .claude/settings.json 的 Hook 會照常執行。對來路不明的 repo 執行 claude -p 前,先審查其 .claude/,或加 --bare/--settings '{"disableAllHooks": true}'。
  • HTTP Hook:以 allowedHttpHookUrls 限制可呼叫的端點,httpHookAllowedEnvVars 限制可帶入標頭的環境變數。
  • 撰寫守則:驗證輸入、變數一律加引號("$VAR")、檢查路徑中的 ..、腳本使用絕對路徑或 ${CLAUDE_PROJECT_DIR}、依賴缺失時 fail-closed。
  • if 是盡力而為的篩選:無法解析的指令仍會執行 Hook;硬性的允許/拒絕應交給權限系統與 Hook 腳本內的判斷,而不是只靠 if。

📌 實務建議:把「絕對不可發生」的規則(強制推送、刪除遠端分支、寫入金鑰)寫成 PreToolUse Hook,而不是只靠 Prompt 提醒,Hook 是真正的強制阻擋;並搭配 permissions.deny 與 Sandbox 形成多層防護。

⚠️ 注意:在 macOS/Linux/WSL 上,搜尋也會以 Bash 呼叫的形式送進 matcher 為 Bash 的 Hook(第2.6章),PreToolUse Hook 若包含緩慢的網路呼叫,會拖慢每一次工具呼叫;Hook 腳本務必保持快速,必要時把耗時工作改成 "async": true 的背景 Hook。

實務案例:某企業在 Managed 層級部署 block-dangerous.sh 並設定 allowManagedHooksOnly 與 onFailure: "block",即使有人在 Prompt 中要求 Agent 強制推送也會被直接擋下;某次發佈的映像檔漏裝 jq,因為腳本採 fail-closed、設定又加了 onFailure: "block",所有 Bash 呼叫都被擋下並顯示明確理由,問題在第一個工程師回報時就被找到,而不是安全防線無聲失效。

12.6 Hook 測試與除錯

Hook 是程式碼,就應該有測試。以下 harness 以模擬的 stdin JSON 呼叫 Hook,驗證每個案例的結束碼與 JSON 決策;它同時包含「應阻擋」與「應放行」兩類案例,以及「缺少 jq 時應 fail-closed」的案例:

#!/usr/bin/env bash
# Hook 測試 harness:模擬 Claude Code 傳給 PreToolUse hook 的 stdin JSON,
# 驗證每個案例的 exit code 與(必要時)JSON 決策是否符合預期。
# 用法:bash test_hooks.sh <hooks 目錄>
set -u
HOOKS="${1:-.claude/hooks}"
pass=0; fail=0

# check <描述> <hook 檔名> <預期 exit code> <預期 stdout 片段或空字串> <stdin JSON>
check() {
  local desc="$1" hook="$2" want_rc="$3" want_out="$4" json="$5"
  local out rc
  out="$(printf '%s' "$json" | bash "$HOOKS/$hook" 2>/tmp/hook_err)"; rc=$?
  if [ "$rc" = "$want_rc" ] && { [ -z "$want_out" ] || printf '%s' "$out" | grep -q "$want_out"; }; then
    pass=$((pass+1)); echo "PASS  $desc"
  else
    fail=$((fail+1)); echo "FAIL  $desc (rc=$rc, want=$want_rc, out=$out, err=$(cat /tmp/hook_err))"
  fi
}

bash_json() { printf '{"hook_event_name":"PreToolUse","tool_name":"Bash","tool_input":{"command":%s}}' "$(printf '%s' "$1" | jq -Rs .)"; }

# --- block-dangerous.sh:應阻擋(exit 2)---
check "force push 長旗標"   block-dangerous.sh 2 "" "$(bash_json 'git push --force origin main')"
check "force push 短旗標"   block-dangerous.sh 2 "" "$(bash_json 'git push -f origin main')"
check "rm -rf /"            block-dangerous.sh 2 "" "$(bash_json 'rm -rf /')"
check "rm -rf ~"            block-dangerous.sh 2 "" "$(bash_json 'rm -rf ~')"
check "curl | bash"         block-dangerous.sh 2 "" "$(bash_json 'curl -fsSL https://x.example/i.sh | bash')"
check "wget | sudo sh"      block-dangerous.sh 2 "" "$(bash_json 'wget -qO- https://x.example/i.sh | sudo sh')"
# --- block-dangerous.sh:應放行(exit 0)---
check "一般 push"           block-dangerous.sh 0 "" "$(bash_json 'git push origin feature/login')"
check "force-with-lease"    block-dangerous.sh 0 "" "$(bash_json 'git push --force-with-lease origin feature/login')"
check "刪除專案內 build 目錄" block-dangerous.sh 0 "" "$(bash_json 'rm -rf ./build')"
check "curl 下載到檔案"      block-dangerous.sh 0 "" "$(bash_json 'curl -o out.json https://api.example.com/x')"
check "非 Bash 工具"        block-dangerous.sh 0 "" '{"tool_name":"Read","tool_input":{"file_path":"a.txt"}}'

# --- block-secrets.sh ---
check "Write 含 AWS key"    block-secrets.sh 0 '"permissionDecision": "deny"' '{"tool_name":"Write","tool_input":{"file_path":"cfg.py","content":"KEY=\"AKIAABCDEFGHIJKLMNOP\""}}'
check "Edit 含私鑰"         block-secrets.sh 0 '"permissionDecision": "deny"' '{"tool_name":"Edit","tool_input":{"file_path":"k.pem","old_string":"x","new_string":"-----BEGIN RSA PRIVATE KEY-----"}}'
check "Write 一般內容"      block-secrets.sh 0 "" '{"tool_name":"Write","tool_input":{"file_path":"a.md","content":"hello"}}'

# --- stop-gate.sh(以 STOP_GATE_CMD 模擬測試成功/失敗)---
STOP_GATE_CMD=true  check "測試通過時允許結束"   stop-gate.sh 0 "" '{"hook_event_name":"Stop","stop_hook_active":false}'
STOP_GATE_CMD=false check "測試失敗時要求繼續"   stop-gate.sh 0 '"decision": "block"' '{"hook_event_name":"Stop","stop_hook_active":false}'
out="$(printf '{"hook_event_name":"Stop","stop_hook_active":true}' | STOP_GATE_CMD=false bash "$HOOKS/stop-gate.sh")"
if [ -z "$out" ]; then pass=$((pass+1)); echo "PASS  已在繼續回合時不再阻擋"; else fail=$((fail+1)); echo "FAIL  已在繼續回合時不再阻擋 (out=$out)"; fi

# --- fail-closed:jq 不在 PATH 時應阻擋 ---
out="$(printf '{}' | PATH=/nonexistent /usr/bin/bash "$HOOKS/block-dangerous.sh" 2>/dev/null)"; rc=$?
if [ "$rc" = 2 ]; then pass=$((pass+1)); echo "PASS  缺少 jq 時 fail-closed"; else fail=$((fail+1)); echo "FAIL  缺少 jq 時 fail-closed (rc=$rc)"; fi

echo "----"; echo "PASS=$pass FAIL=$fail"
[ "$fail" -eq 0 ]

本手冊的三支範例 Hook(含第14.5章的 stop-gate.sh)在 Git Bash(jq 1.8.1)下執行結果為 PASS=18 FAIL=0。反向測試:把 block-dangerous.sh 中的 exit 2 改成 exit 1 後再跑一次,harness 會回報 PASS=11 FAIL=7——所有「應阻擋」的案例都失敗,證明 exit 1 版本完全擋不住,也證明這個 harness 不是空跑。

# 在 CI 中執行(Linux runner 需先安裝 jq)
bash .claude/hooks/test_hooks.sh .claude/hooks

# 互動除錯
claude --debug-file /tmp/claude-hooks.log   # 日誌會記錄每個 Hook 的輸入輸出與耗時
# Session 內 /hooks 檢視目前生效的 Hook 與來源

其他除錯手段:CLAUDE_CODE_DEBUG_LOG_LEVEL=verbose 顯示 matcher 比對細節;claude -p --output-format stream-json --verbose --include-hook-events 在串流中輸出 Hook 生命週期事件;claude --init-only 只執行 Setup 與 SessionStart Hook 後結束,方便測試初始化 Hook。

12.7 Hooks 的 v2.1.300~v2.1.327 行為變更與 Code Mode(v3.0 新增)

變更版本影響
PreToolUse Hook 回傳 allow 之後,工具的權限檢查本身出錯時,改為「當作沒有 Hook 回答」來決定v2.1.323Hook 的 allow 不再能蓋過權限檢查的錯誤
PermissionRequest Hook 改寫了輸入、而權限檢查在改寫後的輸入上失敗時,改為再次詢問(無人可問時拒絕)v2.1.323改寫輸入的 Hook 不能用來繞過檢查
Managed 設定中的 PreToolUse Hook 拒絕直接工具呼叫時,會留下 OTel tool_decision 事件與 permission_denials 紀錄v2.1.326稽核終於看得到 Managed Hook 的拒絕
allowedHttpHookUrls/httpHookAllowedEnvVars 對 Managed Hook 的套用方式調整;HTTP Hook 的 headers 中 Content-Length、Transfer-Encoding 會被忽略v2.1.326HTTP Hook 的長度由 body 決定
claude -p 與 SDK 中長時間執行的 Hook 每 30 秒送出進度心跳v2.1.323宿主程式不會把它誤判為卡住
Agent SDK 的 Hook callback 支援 onFailure: "block"v2.1.317callback 失敗時阻擋動作而非放行
/hooks 會列出由 --settings 提供的 Hookv2.1.327以 --settings 測試 Hook 時可直接確認
/status 列出永遠不會命中的 matcherv2.1.327拼錯工具名稱(如 bash)的 Hook 不再無聲失效

最常見的「Hook 沒觸發」原因(官方 Debug your config 整理,第32章有完整排查流程):matcher 寫成 JSON 陣列而不是單一字串(若在 PreToolUse 或 PermissionRequest 下,同一個檔案的其他 Hook 也全部不載入);工具名稱小寫(matcher 區分大小寫,應為 Bash、Edit);把 Hook 寫在獨立檔案(專案與使用者層級只認 settings.json 的 "hooks" 鍵,只有 Plugin 會讀 hooks/hooks.json)。

v3.0 實測(第29.8章 T4):以 --settings 載入下列 Hook,要求 Claude 執行已被 allow 規則允許的 mkdir markerdir。有 Hook 時目錄未建立、permission_denials 列出 Bash;不帶 Hook 的對照組目錄建立、permission_denials 為空——證明攔截來自 Hook,而非其他原因。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "echo 'blocked by policy hook' >&2; exit 2" }
        ]
      }
    ]
  }
}

Code Mode 下的 Hook:Code Mode(第31章)中,程式碼裡的每個工具呼叫仍以原本的工具名稱(如 Bash)經過 deny/ask 規則與 PreToolUse Hook;但同一行指令可能以 cd 'app' && git push 的形式到達 Hook,因此Hook 必須逐段檢查複合指令。若要審查程式碼本身,以 matcher REPL 攔截,從 tool_input.code 讀取 JavaScript。下列腳本與測試已在 Git Bash+jq 1.8.1 實測(PASS=7 FAIL=0;把 exit 2 改成 exit 1 的反向測試 PASS=2 FAIL=5,證明測試會抓到回歸),撰寫期間測試也抓到第一版正規式漏掉 rm -fr 的缺陷:

#!/usr/bin/env bash
# PreToolUse hook(matcher: "REPL"):檢查 Code Mode 產生的 JavaScript
# 程式碼含受管制的指令(git push、rm -rf、curl | sh)時以 exit 2 拒絕,原因寫到 stderr 回饋給 Claude
set -euo pipefail
input=$(cat)
tool=$(printf '%s' "$input" | jq -r '.tool_name // empty')
[ "$tool" = "REPL" ] || exit 0
code=$(printf '%s' "$input" | jq -r '.tool_input.code // empty')
if [ -z "$code" ]; then
  echo "REPL 呼叫沒有 tool_input.code,無法審查,依政策拒絕" >&2
  exit 2
fi
if printf '%s' "$code" | grep -Eq 'git[[:space:]]+push|rm[[:space:]]+-([a-zA-Z]*[rR][a-zA-Z]*f|[a-zA-Z]*f[a-zA-Z]*[rR])|curl[^|]*[|][[:space:]]*(ba)?sh'; then
  echo "Code Mode 程式碼含受管制的指令(git push/rm -rf/curl | sh),請拆成一般工具呼叫由人工核准" >&2
  exit 2
fi
exit 0

對應的設定(放在使用者或 Managed 設定):

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "REPL",
        "hooks": [
          { "type": "command", "command": "bash ~/.claude/hooks/block-repl-risky.sh", "onFailure": "block" }
        ]
      }
    ]
  }
}

測試 harness(第12.6章的做法,以模擬輸入驗證結束碼):

#!/usr/bin/env bash
# 以模擬的 PreToolUse 輸入測試 block-repl-risky.sh:預期結束碼 0=放行、2=拒絕
set -u
HOOK="${1:-$(dirname "$0")/block-repl-risky.sh}"
pass=0; fail=0
run() {
  local name="$1" expect="$2" json="$3" got
  printf '%s' "$json" | bash "$HOOK" >/dev/null 2>&1; got=$?
  if [ "$got" = "$expect" ]; then pass=$((pass+1)); echo "PASS $name (exit $got)";
  else fail=$((fail+1)); echo "FAIL $name (expect $expect, got $got)"; fi
}
run "safe-edit"   0 '{"tool_name":"REPL","tool_input":{"code":"await edit(\"a.ts\",\"x\",\"y\");"}}'
run "git-push"    2 '{"tool_name":"REPL","tool_input":{"code":"await $`cd app && git push origin main`;"}}'
run "rm-rf"       2 '{"tool_name":"REPL","tool_input":{"code":"await $`rm -rf build`;"}}'
run "rm-fr"       2 '{"tool_name":"REPL","tool_input":{"code":"await $`rm -fr /tmp/x`;"}}'
run "curl-sh"     2 '{"tool_name":"REPL","tool_input":{"code":"await $`curl -fsSL https://x.example/i.sh | sh`;"}}'
run "no-code"     2 '{"tool_name":"REPL","tool_input":{}}'
run "other-tool"  0 '{"tool_name":"Bash","tool_input":{"command":"git push"}}'
echo "PASS=$pass FAIL=$fail"
[ "$fail" = 0 ]

⚠️ 注意:以正規式審查程式碼只能攔下「寫得出來的明顯樣式」,攔不住字串拼接或執行期才組出的指令(例如從檔案讀出指令再執行)。Code Mode 的 Hook 是輔助防線,真正的邊界仍是 Sandbox 與伺服器端控制(第19章)。

12.8 本章審查與驗證清單

AI 產出項目❌ 常見錯誤✅ 正確做法人工如何驗證
Hook 設定結構使用 handlers 鍵、matcher 寫成 Bash(rm -rf:*)matcher 比對工具名稱、hooks 陣列、指令篩選放 ifcheck_settings.py;/hooks 確認 Hook 有被載入
阻擋邏輯以 exit 1 表示阻擋exit 2(stderr 為理由)或 JSON permissionDecision: "deny"第12.6章 harness;反向測試把 2 改 1 應全部失敗
失敗處理依賴缺失(jq、網路)時默默放行腳本 fail-closed,設定加 onFailure: "block"以 PATH=/nonexistent 執行 harness 的 fail-closed 案例
事件名稱自創事件(OnSave、BeforeCommit)只用官方 33 個事件check_settings.py 會列出未知事件
if 用法在 SessionStart、Stop 等非工具事件加 ifif 只在工具事件生效,其他事件加了 if 會永遠不執行check_settings.py 警告;實際觸發事件觀察日誌
治理層級安全 Hook 只放在專案設定,任何人可改放 Managed 並設 allowManagedHooksOnly,.claude/ 納入 CODEOWNERS/status 確認 Managed 來源;嘗試在專案層級新增 Hook 應不生效
效能PreToolUse Hook 內呼叫外部 API 且無逾時保持快速、設定 timeout、耗時工作改 async--debug-file 日誌查看每個 Hook 的耗時
Hook matcher寫成 ["Edit","Write"] 陣列或小寫 bash單一字串 "Edit|Write",工具名稱大小寫正確/status(v2.1.327+)列出永遠不會命中的 matcher;/hooks 確認 Hook 已載入
Code Mode 的 Hook只對 Bash 寫 Hook,以為 Code Mode 也一樣逐條比對;或以為 REPL Hook 能攔住所有變形Bash Hook 要能處理 cd x && cmd 複合指令;另加 REPL matcher 審查程式碼;關鍵限制仍靠 Sandbox以 test_repl_hook.sh 跑正反向案例;把 exit 2 改成 exit 1 確認測試會失敗
Hook 攔截的證據只憑 Claude 回覆「已被 Hook 擋下」就認定 Hook 生效以產出物(檔案/目錄是否存在)與 permission_denials 判斷,並做不帶 Hook 的對照組依第29.8章 T4 的做法執行正向與對照組

第 13 章 MCP 整合

本章目標:正確設定 MCP Server(遠端 HTTP/SSE/WebSocket 與本機 stdio)、理解三種安裝範圍與優先順序,並以 Managed 設定建立「核准目錄」式的治理。讀完後,你應該能一眼看出 AI 產生的 .mcp.json 是否會被靜默略過。

13.1 MCP 概念

Model Context Protocol(MCP)是一套開放標準,讓 Claude Code(作為 Client)能以統一的工具呼叫介面,連接外部系統(作為 Server)。Server 可以是本機程式(stdio 傳輸)或遠端服務(HTTP、SSE、WebSocket 傳輸),對 Agent 而言,呼叫 MCP 工具與呼叫內建工具的方式一致,工具名稱格式為 mcp__<server>__<tool>,權限規則與 Hook 的 matcher 都用這個名稱。

13.2 設定與管理

# 遠端 HTTP Server(OAuth 由 Server 引導;SSE 端點 v2.1.265+ 會自動退回)
claude mcp add --transport http github https://api.githubcopilot.com/mcp/
claude mcp login github            # 免開 /mcp 面板完成 OAuth;SSH 遠端加 --no-browser

# 帶固定標頭的遠端 Server
claude mcp add --transport http corp-api https://mcp.corp.example/mcp \
  --header "Authorization: Bearer ${CORP_TOKEN}"

# 本機 stdio Server:-- 之後的內容原封不動交給 Server
# 注意:--env 後面不能緊接 Server 名稱(會被當成另一組 KEY=value),中間要隔一個選項
claude mcp add --env PG_READONLY_URL=postgres://... --transport stdio pg -- npx -y @modelcontextprotocol/server-postgres

# 專案共用(寫入 .mcp.json,提交版控)
claude mcp add --transport http jira --scope project https://jira-mcp.corp.example/mcp

claude mcp list                    # 列出並做健康檢查
claude mcp get github              # 查看單一 Server

一份可提交版控的專案 .mcp.json(已通過第30章 check_mcp.py 驗證):

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "Authorization": "Bearer ${GITHUB_PAT}"
      }
    },
    "jira": {
      "type": "http",
      "url": "https://jira-mcp.corp.example/mcp"
    },
    "postgres-readonly": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "${PG_READONLY_URL}"],
      "env": {}
    }
  }
}

⚠️ 勘誤:v1.3 的 .mcp.json 範例使用 "transport": "http"。JSON 鍵必須是 "type"(--transport 只是 CLI 旗標名稱);有 url 卻沒有 type 的項目會被當成 stdio Server 而略過,Claude Code 會提示 MCP server "<name>" has a "url" but no "type"。也就是說,照 v1.3 範例設定的 GitHub 與 Jira Server 從來不會連上。

**安裝範圍(Scope)**與優先順序:

範圍載入於與團隊共用儲存位置
Local(預設)只在目前專案否~/.claude.json 中該專案的項目
Project只在目前專案是(版控)專案根目錄 .mcp.json
User你所有的專案否~/.claude.json 頂層

同名 Server 只連一次,優先序為 Local > Project > User > Plugin 提供 > claude.ai Connector(整個項目採用最高來源,不跨層合併欄位);組織以 managedMcpServers 提供的 Server 則高於以上全部。注意 MCP 的「Local」存在 ~/.claude.json,與一般設定的 .claude/settings.local.json 不同。

環境變數展開:.mcp.json 的 command、args、env、url、headers 支援 ${VAR} 與 ${VAR:-預設值},讓團隊共用設定、各自提供金鑰;金鑰不要寫死在檔案中。

專案 Server 核准:.mcp.json 中的 Server 第一次出現時需經使用者核准(claude mcp list 顯示為 ⏸ Pending approval),以免 clone 下來的 repo 自動連到未知服務;claude mcp reset-project-choices 可重設選擇,enableAllProjectMcpServers 則一次信任全部(不建議在企業環境使用)。

13.3 整合案例

graph TB
    CC["Claude Code (MCP Client)"] --> GH["GitHub MCP Server"]
    CC --> GL["GitLab MCP Server"]
    CC --> JI["Jira MCP Server"]
    CC --> CF["Confluence MCP Server"]
    CC --> DB["Database MCP Server"]
    CC --> BR["Browser MCP Server"]
    CC --> FS["Filesystem MCP Server"]
整合對象典型用途權限建議
GitHub/GitLab讀取/建立 PR、Issue、CI 狀態細粒度 Token,限定 repo
Jira讀取需求、更新工單狀態先給唯讀,需要時才開寫入
Confluence讀取設計文件、補完知識庫唯讀
Database查詢資料結構、驗證遷移腳本只連唯讀帳號與非正式環境
Browser模擬使用者操作、驗證前端行為限定測試網域
Filesystem存取受限的額外檔案區域優先改用 --add-dir

13.4 工具延遲載入

MCP Server 可能註冊大量工具,Claude Code 預設以 Tool Search 延遲載入:Session 開始時只載入工具名稱與 Server 說明,Claude 需要時再透過 ToolSearch 載入完整定義,因此增加 MCP Server 對 Context 的影響很小(與第8章 Token 優化相呼應)。少數必須一開始就可用的 Server 可設 "alwaysLoad": true。MCP 工具描述與 Server 說明預設上限 2,048 字元,可用 CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH 調整。Microsoft Foundry 在 Azure 託管的部署不支援 Tool Search,會自動退回一次載入。

13.5 MCP 治理鍵補充

官方把組織的 MCP 管控整理成幾種模式,依需要的嚴格程度選擇:

模式效果設定
完全停用 MCP除少數例外外不載入任何 Servermanaged-mcp.json 放空的 Server 對應表
固定部署所有人取得同一組 Server,且不能新增managed-mcp.json 列出 Server
提供 Server所有人取得你列出的遠端 Server,同時保留自己的Managed 設定 managedMcpServers
核准目錄只能新增核准清單內的 Server,其餘一律封鎖allowedMcpServers + allowManagedMcpServersOnly: true
只允許 Plugin 的 Server不能透過 ~/.claude.json 或 .mcp.json 新增strictPluginOnlyCustomization 包含 mcp
黑名單封鎖已知有問題的 Server,其餘允許deniedMcpServers

「核准目錄」模式的 Managed 設定範例(已通過檢查工具驗證):

{
  "allowManagedMcpServersOnly": true,
  "allowedMcpServers": [
    { "serverUrl": "https://api.githubcopilot.com/*" },
    { "serverUrl": "https://*.corp.acme.example/*" }
  ],
  "deniedMcpServers": [
    { "serverName": "filesystem-root" },
    { "serverUrl": "https://*.untrusted.example.com/*" }
  ]
}

比對規則:serverUrl 支援萬用字元;只要清單中出現一筆 serverUrl,所有遠端 Server 都必須符合某個 URL 樣式(不能靠取一個被允許的名稱繞過);同理,出現一筆 serverCommand 後,所有 stdio Server 都必須完全符合某個列出的指令陣列(含參數)。以上範例沒有任何 serverCommand,因此第13.2章範例中的 stdio postgres-readonly Server 在這個政策下會被封鎖——這正是「核准目錄」的預期行為,要放行就必須把完整指令加入清單。deniedMcpServers 永遠優先於允許清單。

其他常用鍵:enabledMcpjsonServers/disabledMcpjsonServers(個別啟用或停用 .mcp.json 中的 Server)、allowAllClaudeAiMcps、disableClaudeAiConnectors(任何層級設為 true 都會生效)。

📌 實務建議:MCP Server 的認證憑證應採最小權限(例如 Jira 用只能讀的 Token),並維護一份「已核准 MCP Server」清單與對應的 claude mcp add 指令(官方沒有內建可瀏覽的 Server 目錄,請放在內部 Wiki),新增前需經過審查(第21章)。

⚠️ 注意:MCP Server 是一個新的信任邊界,一個被入侵或惡意的 MCP Server 可能竊取傳遞給它的 Context,也可能回傳夾帶指令的內容(Prompt Injection);本機 stdio Server 還以你的完整權限、在 Sandbox 之外執行。審查 MCP Server 的嚴謹度應等同於審查一個新的 CI Plugin。

實務案例:團隊同時串接 Jira 與 GitHub MCP,讓 Claude Code 能讀取工單的驗收條件、實作對應修改、並開出引用該工單編號的 PR;平台團隊以 allowedMcpServers 限定只允許公司 GitHub 與內部 Jira 端點,某位工程師嘗試加入來路不明的第三方 Server 時直接被擋下。

13.6 MCP 疑難排解

症狀排查
Server 沒出現在 /mcpclaude mcp list 看是否為 ⏸ Pending approval;用 check_mcp.py 檢查 type 是否缺漏
遠端 Server 連不上claude mcp get <name> 看健康檢查;確認 Proxy/防火牆;OAuth 過期時 claude mcp login <name>
-p 模式第一輪就找不到 MCP 工具--mcp-config 搭配 -p 會等待 Server 連線,最多 MCP_TIMEOUT(預設 30 秒);可調高 MCP_TIMEOUT 或 CLAUDE_CODE_MCP_STARTUP_WAIT_MS
CI 中 Server 設定錯誤卻沒有失敗以 --output-format stream-json 讀取 system/init 事件的 mcp_servers 與 mcp_server_errors 欄位,有錯誤就讓 CI 失敗(第29章)
Server 中途斷線Claude Code 會自動重連;放棄時會提示,可執行 /mcp reconnect all
工具一直要求核准被標為 requiresUserInteraction 的工具或組織設為 ask 的 Connector 工具,任何模式都會詢問

13.7 MCP 的 v3.0 變更:stdin 匯入、MCP Tasks 與核准名稱(v3.0 新增)

變更版本做法
claude mcp add-json <name> - 從 stdin 讀 JSONv2.1.327Token 不出現在指令列與 shell history;在 Claude Code Session 內執行會被拒絕(因為權限詢問看不到 Server 內容,v3.0 實測)
type 接受 streamable-http(http 的別名)文件說明從 MCP 規格或其他用戶端複製的設定可直接使用
MCP Tasks 背景化v2.1.319以 task 方式執行的呼叫立即轉背景;主對話中一般 MCP 呼叫超過 2 分鐘也會轉背景(第2.8章)
v1 MCP 用戶端移除,MCP_SDK_GENERATION=v1 改為 v2 相容模式v2.1.323依賴 v1 行為的舊 Server 需實測 OAuth 登入
.mcp.json 專案 Server 的核准以精確名稱比對v2.1.323以不同拼法寫的舊核准紀錄會再次詢問
完成 MCP 登入的工具一律要求確認(含 bypass 與 Auto)v2.1.323無人可問的模式(如 dontAsk)改用 /mcp 登入
claude mcp add/remove 以 project scope 執行時不再刪掉 .mcp.json 的其他頂層鍵(如 $schema)v2.1.327舊版本請在指令後以 git diff 檢查
管理員在 Session 中途新增 managed-mcp.json 時,會說明為何 MCP Server 停止載入v2.1.326—

一份可直接通過 check_mcp.py 的範例(Token 以環境變數展開,不寫死在檔案):

{
  "mcpServers": {
    "issue-tracker": {
      "type": "streamable-http",
      "url": "https://mcp.tracker.corp.example/mcp",
      "headers": { "Authorization": "Bearer ${TRACKER_TOKEN}" }
    }
  }
}

在一般終端機(不是 Claude Code Session 內)以 stdin 加入同一個 Server:

printf '%s' '{"type":"http","url":"https://mcp.tracker.corp.example/mcp","headers":{"Authorization":"Bearer ${TRACKER_TOKEN}"}}' \
  | claude mcp add-json --scope project issue-tracker -
git diff .mcp.json   # 確認只新增了這個 Server,其他鍵沒有被改動

MCP 排查四步(官方 Debug your config):/mcp 看狀態 → 專案 Server 被拒過就執行 claude mcp reset-project-choices 再重啟 → command/args 用相對路徑會依「啟動 Claude Code 的目錄」解析,請改絕對路徑 → 連上但工具數為 0 時以 claude --debug=mcp 啟動,在 ~/.claude/debug/<session-id>.txt 讀 Server 的 stderr。

13.8 本章審查與驗證清單

AI 產出項目❌ 常見錯誤✅ 正確做法人工如何驗證
.mcp.json 結構使用 "transport" 鍵、有 url 沒有 type"type": "http"/"sse"/"ws",stdio 需 commandpython check_mcp.py .mcp.json;claude mcp list
憑證處理Token 直接寫在 headers以 ${ENV_VAR} 展開,金鑰放 Secret Managercheck_mcp.py 會偵測疑似金鑰;git log -p .mcp.json
claude mcp add 指令stdio Server 忘了 --,或把 Server 名稱緊接在 --env 之後claude mcp add --env K=v --transport stdio <name> -- <command> [args]執行後 claude mcp get <name> 確認指令與參數
安裝範圍團隊要共用的 Server 用預設 Local 範圍共用的用 --scope project 並提交 .mcp.json另一位同事 clone 後 claude mcp list 看得到
治理設定允許清單只寫 serverName,以為能防止換 URL 繞過遠端用 serverUrl、本機用 serverCommand,並設 allowManagedMcpServersOnly在測試機嘗試加入未列出的 Server,確認被封鎖
資料庫類 Server連到正式環境的讀寫帳號只連唯讀帳號與非正式環境檢查連線字串使用的帳號權限
加入 MCP Server 的方式在指令列直接貼含 Token 的 JSON,留在 shell history用 ${VAR} 展開,或在一般終端機以 add-json <name> - 從 stdin 讀取檢查 shell history 與 .mcp.json 中沒有明文 Token;check_mcp.py 會抓寫死的金鑰
.mcp.json 位置與鍵名放在 .claude/mcp.json,或沿用 VS Code 格式的頂層 servers 鍵放 repo 根目錄 .mcp.json,Server 放在 mcpServers 下/mcp 看 Server 是否出現;check_mcp.py 會在缺少 mcpServers 時報錯

第 14 章 使用 Claude Code 開發 Web Application

本章目標:建立「先探索、再規劃、後實作、最後驗證」的標準開發流程,並讓 Claude 在宣告完成前自己跑過驗證。讀完後,你應該能為任一技術棧寫出附驗證條件的提示,並用 Stop Hook 或 /goal 把「測試通過」變成 Claude 結束工作的硬性條件。

14.1 通用工作流程

flowchart LR
    Explore["探索<br/>(Plan 模式讀程式)"] --> Plan["規劃<br/>(產出可審查的計畫)"]
    Plan --> Impl["實作<br/>(小步修改)"]
    Impl --> Verify["驗證<br/>(測試/建置/截圖)"]
    Verify -->|失敗| Impl
    Verify -->|通過| Review["人工 Review"]
    Review --> Commit["Commit / PR"]

不論技術棧為何,建議流程都是:先在 Plan 模式讓 Claude 理解現況並提出計畫 → 你審查計畫 → 切換到可編輯的模式實作 → 用專案既有建置/測試工具驗證 → 人工 Review → 提交,而不是一次性要求「做出完整功能」。官方最佳實務的第一條就是:給 Claude 一個它能自己執行的檢查(測試、建置、Linter、與 fixture 比對的腳本、截圖),否則「看起來完成了」就是它唯一的停止訊號,你會變成那個驗證迴圈。

14.2 Spring Boot(Java/Kotlin)

claude -p "依 CLAUDE.md 標註的 Spring Boot 與 Java 版本,建立訂單(Order)的建立與查詢 REST Controller,
DTO 使用 record,輸入加上 Bean Validation。完成後執行 ./mvnw test,
並把測試輸出的最後 20 行附在回報中;若有失敗,修正根本原因而不是刪除測試"

重點不是提示多長,而是三件事:版本以 CLAUDE.md 為準(避免模型依訓練資料猜版本)、明確的驗證指令、要求附上證據。

14.3 FastAPI(Python)

claude -p "用 FastAPI 建立商品庫存查詢 API,包含 Pydantic 模型驗證與 pytest 測試。
測試案例至少包含:庫存為 0、商品不存在回 404、數量為負數回 422。
完成後執行 pytest -q 並回報結果"

14.4 Vue3 / Angular

claude -p "建立一個 Vue 3 Composition API 元件,顯示分頁式商品列表,
沿用本專案既有的 Pinia store 慣例,並補上 Vitest 元件測試;完成後執行 npm run test:unit"

前端變更除了單元測試,還可以讓 Claude 透過 Claude in Chrome(--chrome)實際開啟頁面、截圖並與設計稿比對;需要先畫出幾個 UI 方案再挑選時,可用 /design(研究預覽)產生可編輯的 artboard。

📌 實務建議:在 CLAUDE.md 中明確標註框架版本與慣例(例如「本專案使用 Vue 3 Composition API,不使用 Options API」),避免 Agent 因訓練資料偏舊而產出過時寫法。

⚠️ 注意:永遠讓 Claude Code 執行專案既有的建置/測試指令做驗證,而不是只看程式碼「看起來合理」就視為完成。

實務案例:一個 FastAPI 微服務從一段需求描述開始,在同一個 Session 內先以 Plan 模式產出計畫、經工程師修改後才開始實作,逐步產出 Pydantic 模型、CRUD 邏輯與 pytest 測試,全程伴隨真實測試結果回饋,最終交付的程式碼一次通過 Code Review。

14.5 驗證驅動的開發流程:把「通過驗證」變成停止條件

依「要多強制」由弱到強,有四種方式讓 Claude 在完成前驗證自己的工作:

方式做法適用
寫在提示裡「實作後執行 npm test 並修到通過,附上輸出」任何單一任務
/goal/goal 所有 npm test 都通過且 npm run lint 無錯誤:每一回合後由獨立評估者檢查,未達成就繼續跨多回合的長任務
Stop Hook以腳本在 Claude 結束前執行檢查,沒通過就用 decision: "block" 要求繼續無人值守、需要確定性關卡
第二意見驗證用 Subagent 或 Dynamic Workflow 嘗試推翻結果,「做的人不改自己的考卷」高風險變更

以下是 Stop Hook 版本的驗證關卡(.claude/hooks/stop-gate.sh),已通過第12.6章 harness 測試(測試通過時允許結束、失敗時要求繼續、已在繼續回合時不再阻擋):

#!/usr/bin/env bash
# Stop hook:Claude 宣告完成前先跑測試,沒通過就要求它繼續修(確定性的驗證關卡)
# 測試指令由環境變數 STOP_GATE_CMD 指定,預設為 npm test
set -u
input="$(cat)"

# 已經是因為本 Hook 而繼續的回合時不再阻擋,避免無限循環
# (Claude Code 另有連續 8 次的硬上限)
if [ "$(printf '%s' "$input" | jq -r '.stop_hook_active // false')" = "true" ]; then
  exit 0
fi

cmd="${STOP_GATE_CMD:-npm test --silent}"
if output="$(bash -c "$cmd" 2>&1)"; then
  exit 0
fi

# 只回傳最後 40 行,避免把整份測試日誌塞進 Context
tail_out="$(printf '%s\n' "$output" | tail -n 40)"
jq -n --arg cmd "$cmd" --arg out "$tail_out" '{
  decision: "block",
  reason: ("驗證未通過(" + $cmd + ")。請修正根本原因後再結束,不可刪除或弱化測試。\n" + $out)
}'
exit 0
{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash",
            "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/stop-gate.sh"],
            "timeout": 600
          }
        ]
      }
    ]
  }
}

⚠️ 注意:Stop Hook 讓 Claude 「沒過就繼續」,但 Claude 可能為了通過而弱化或刪除測試。提示與 Hook 的理由文字都應明確禁止這種做法,並在 Review 時以 git diff --stat -- '*test*' 檢查測試檔是否被大幅刪改(第18章)。Claude Code 對 Stop Hook 有連續 8 次繼續的硬上限,避免無限循環。

隨附的 /verify Skill 會建置並實際執行應用程式來觀察結果,而不是只依賴測試;/run-skill-generator 可先教會 /run 與 /verify 如何啟動你的專案(第27.3章)。

14.6 本章審查與驗證清單

AI 產出項目❌ 常見錯誤✅ 正確做法人工如何驗證
實作提示「幫我做好訂單功能」,沒有驗證條件列出具體測試案例與驗證指令,要求附輸出檢查 Claude 回報中是否有實際的測試輸出
框架版本依模型記憶產生過時 API(javax.*、Options API)以 CLAUDE.md 標註的版本為準建置成功、無 deprecation 警告
「測試通過」的宣稱沒有證據就宣稱完成附上指令與輸出最後幾行自己在乾淨環境重跑一次
Stop Hook 驗證關卡沒有處理 stop_hook_active,或把整份測試日誌塞回 Context依範例處理繼續回合、只回傳最後數十行第12.6章 harness 的 stop-gate 案例
前端變更只看程式碼不看畫面以 Chrome 整合截圖與設計稿比對人工檢視截圖與互動流程

第 15 章 Legacy System 逆向工程

本章目標:以結構化流程讓 Claude Code 協助理解沒有文件的舊系統,並建立「每一張 AI 產出的圖表都能被追溯回原始碼」的驗證機制。讀完後,你應該能判斷 AI 的逆向分析哪些可信、哪些必須由 SME 核對。

15.1 分析方法

逆向工程不是「叫 Agent 讀完全部程式碼」,而是結構化的探索流程:

flowchart TD
    A["盤點目錄結構與技術棧"] --> B["定位進入點<br/>(Controller/Servlet/Main/批次排程)"]
    B --> C["追蹤關鍵業務流程"]
    C --> D["產出圖表<br/>(架構/循序/類別/ER)"]
    D --> E["逐項追溯驗證<br/>(每個節點對應檔案與行號)"]
    E --> F["與 SME 核對並沉澱為文件"]

建議以 Plan 模式(claude --permission-mode plan)進行逆向分析:Claude 只能讀取、不會修改任何檔案,大範圍搜尋會委派給唯讀的 Explore Subagent,不會淹沒主對話。對數千個檔案的系統做全面盤點時,可用 Dynamic Workflows(在提示中加上 ultracode)讓多個 Agent 分模組分析並交叉檢核彼此的結論(第26.3章)。

15.2 適用範圍與限制

涵蓋 Java Legacy、COBOL、VB、Delphi、ASP.NET WebForms、JSP/Struts 等系統。對冷僻語言(COBOL、Delphi)模型訓練資料較少,幻覺風險較高,務必加強人工核對;動態行為(反射、設定檔驅動的路由、資料庫中的 Stored Procedure 與 Trigger)也是靜態閱讀容易遺漏的地方,應另外以執行期資料(日誌、APM 追蹤)佐證。

15.3 範例 Prompt

claude --permission-mode plan -p "列出 /webapp 下所有 JSP 檔案及其對應的 Servlet Mapping,
以表格輸出:URL pattern / Servlet 類別 / 定義位置(檔案:行號)"

claude --permission-mode plan -p "追蹤從 OrderServlet.doPost 開始的呼叫鏈,一路到 DAO 層,
每一步都標註檔案路徑與行號;無法確定的呼叫(反射、設定檔決定)請明確標示「待確認」"

claude --permission-mode plan -p "依據 db/ddl/*.sql 產生 Mermaid ER 圖,
並列出每個關聯是由哪一行 FOREIGN KEY 推得;沒有外鍵、只能從命名猜測的關聯另外列出"

三個提示的共同點:要求每一個結論附上來源位置,並要求把「推測」與「有證據」分開。這是讓逆向成果可被驗證的關鍵。

15.4 產出範例

sequenceDiagram
    participant U as 使用者
    participant S as OrderServlet
    participant Svc as OrderService
    participant DAO as OrderDAO
    U->>S: HTTP POST /order
    S->>Svc: processOrder()
    Svc->>DAO: insertOrder()
    DAO-->>Svc: 結果
    Svc-->>S: 結果
    S-->>U: 回應頁面

📌 實務建議:產出的架構/循序圖務必交給熟悉該系統的資深同仁(SME)核對,AI 可能誤判隱含的控制流程(例如 COBOL 中的 GOTO 邏輯、JCL 的批次相依)。

⚠️ 注意:對 COBOL、Delphi 等模型訓練資料較少的語言,務必提高人工審查比例,不要把 AI 產出的圖表直接當作正式文件發布。

實務案例:一套 15 年歷史的 ASP.NET WebForms 理賠系統,透過分階段 Prompt 在 Plan 模式下產出理賠核准流程的架構圖與循序圖,每個節點都附檔案行號;資深同仁花半天逐一核對,修正了兩處 AI 誤判的頁面跳轉,成為團隊第一份可信賴的系統文件。

15.5 驗證 AI 逆向產出的方法

驗證項目方法
清單完整性(端點、批次、資料表)用確定性工具重算一次再比對:grep -rn "@WebServlet|<servlet-mapping>" src web.xml、grep -c "CREATE TABLE" db/ddl/*.sql
呼叫鏈正確性抽樣 3~5 條,依 AI 標註的檔案:行號逐一打開確認;有 IDE 的話用「Find Usages」交叉比對
圖表語法以 mermaid-cli(npx @mermaid-js/mermaid-cli -i x.mmd -o x.svg)實際渲染,避免無法顯示的圖表進入文件
推測與事實的分界檢查 AI 是否把「待確認」項目獨立列出;沒有任何「待確認」的大型分析反而可疑
執行期行為以日誌、APM 追蹤或測試環境實際操作,驗證關鍵流程確實走 AI 描述的路徑

15.6 本章審查與驗證清單

AI 產出項目❌ 常見錯誤✅ 正確做法人工如何驗證
端點/批次清單遺漏透過設定檔或反射註冊的進入點要求附來源位置,並另列「動態註冊」項目以 grep 重算清單數量並比對
呼叫鏈把推測的呼叫當成事實,沒有行號每一步標註檔案:行號,推測者標「待確認」抽樣打開檔案確認
ER 圖依欄位名稱猜關聯,卻沒有說明區分「有外鍵」與「依命名推測」比對 DDL 中的 FOREIGN KEY
分析過程在可編輯模式下逆向,Claude 順手「修正」舊程式逆向分析一律用 Plan 模式git status 確認沒有任何檔案被修改
圖表Mermaid 語法錯誤、文件中無法顯示以 mermaid-cli 渲染驗證檢查渲染輸出沒有 Syntax error

第 16 章 Framework 升級

本章目標:把框架升級拆成可驗證、可回滾的小批次,並把「確定性工具」與「AI」放在正確的位置。讀完後,你應該能設計一個由 Claude Code 協助、但每一步都有建置與測試把關的升級計畫。

16.1 通用升級方法論

flowchart TD
    A["盤點相依/API使用<br/>(確定性工具+AI 摘要)"] --> B["產生影響分析報告"]
    B --> C["機械式改寫<br/>(OpenRewrite 等工具優先)"]
    C --> D["AI 處理剩餘的非機械式修改<br/>(per module)"]
    D --> E["建置+回歸測試"]
    E --> F["合併"]
    F -.下一批.-> C

原則是:能用確定性工具完成的機械式改寫(套件更名、API 對應),優先交給工具,例如 OpenRewrite、ng update、官方遷移腳本;Claude Code 負責盤點、撰寫影響分析、處理工具無法自動完成的語意性修改,以及修正升級後的編譯錯誤與測試失敗。這樣產出的 diff 大部分可重現,Review 負擔也小得多。

16.2 各升級情境要點

升級類型關鍵變動建議的確定性工具
Spring Boot 2→3(或 3→4)javax.* → jakarta.*、Spring Security DSL 改寫、設定屬性更名OpenRewrite Spring recipes、spring-boot-properties-migrator
Java 8/11/17 → 21/25移除的舊 API、Record、Sealed Class、Virtual ThreadsOpenRewrite Java migration recipes、jdeprscan
Vue 2→3Options API → Composition API、全域 API 變更Vue 官方遷移建置(compat build)
Angular/React 升級Standalone Component、CLI 重大變更ng update、官方 codemod

16.3 範例 Prompt

claude --permission-mode plan -p "掃描整個專案中使用 javax.* 的 import,依模組分組列出檔案數,
並標出哪些屬於 OpenRewrite 無法自動處理的情況(例如反射字串、XML 設定)"

claude -p "OpenRewrite 已完成 jakarta 命名空間遷移。請只處理 order-service 模組中剩下的編譯錯誤,
每修一個錯誤就重新執行 ./mvnw -q -pl order-service compile,直到成功;不要修改其他模組"

claude -p "將這個 Vue 2 Options API 元件改寫為 Composition API,保持行為一致,
並先補上覆蓋現有行為的元件測試,改寫後測試必須全數通過"

大量模組的批次處理:同一種修改要套用到數十個模組時,可用 /batch(把工作拆成 5~30 個獨立單元,各自在 Worktree 中執行並開 PR,第26.4章);模組之間有相依順序時,改用 Dynamic Workflows 明確控制順序(第26.3章)。

📌 實務建議:永遠不要接受「一次性整個倉庫升級」的單一 Prompt,務必拆成模組分批進行,每批之間跑完整回歸測試再進下一批;改寫前先補「描述現有行為」的測試,才能證明改寫後行為不變。

⚠️ 注意:模型訓練資料對較新或冷門的升級路徑覆蓋率較低,務必拿生成的遷移步驟與官方升級指南交叉核對,不要盲信。

實務案例:某中型服務從 Spring Boot 2.7 升級到 3.x,先以 OpenRewrite 完成命名空間與設定屬性遷移(約 80% 的 diff),再讓 Claude Code 逐模組處理剩餘的 Security DSL 改寫與編譯錯誤,每個模組一個 PR、每個 PR 都有完整測試把關,避免了一次性大改造成的不可控風險。

16.4 驗證升級結果

驗證項目方法
編譯與相依完整建置(./mvnw -q verify、npm run build),並檢查相依樹沒有新舊版本並存(mvn dependency:tree | grep javax)
行為不變升級前後執行同一套回歸測試;改寫前先補行為測試
沒有偷偷降低標準git diff --stat -- '*Test*' '*.spec.*' 檢查測試檔是否被刪改;搜尋新增的 @Disabled、.skip(
棄用 API建置輸出不應有新增的 deprecation 警告
機械式改寫可重現對同一個基準 commit 重跑 OpenRewrite,結果應一致

16.5 本章審查與驗證清單

AI 產出項目❌ 常見錯誤✅ 正確做法人工如何驗證
升級計畫一次改完整個倉庫依模組分批、每批可獨立建置與測試檢查每個 PR 的範圍只涵蓋一個模組
機械式改寫讓 AI 手動改數百個 import優先使用 OpenRewrite/官方 codemod比對 diff 是否可由工具重現
修正測試失敗加上 @Disabled 或放寬斷言讓測試通過修正根本原因,測試不得被弱化git diff 搜尋 @Disabled、.skip(、刪除的斷言
遷移步驟引用不存在的設定屬性或 API與官方升級指南交叉核對建置與啟動應用程式,檢查啟動日誌的屬性警告

第 17 章 Git 整合

本章目標:建立 AI 協作的 Git 流程、了解 Auto Mode 對 Git 操作的預設行為,並正確使用 /code-review、ultrareview 與 Code Review 服務。讀完後,你應該能為團隊寫出「AI 不能做什麼」的 Git 規則,並以設定與 Hook 強制落實。

17.1 AI 協作流程

flowchart LR
    Edit["本機修改"] --> SelfReview["/code-review 本機快篩"]
    SelfReview --> MsgGen["Claude 產生 Commit Message"]
    MsgGen --> Commit["git commit"]
    Commit --> PRGen["Claude 產生 PR 描述"]
    PRGen --> PRCreate["gh pr create"]
    PRCreate --> AIReview["AI 預審<br/>(/code-review ultra 或 Code Review 服務)"]
    AIReview --> HumanReview["人工 Review"]
    HumanReview --> Merge["Merge"]

17.2 常用指令

git status && git diff
gh pr create --title "..." --body "..."
gh pr diff

# Session 內的審查
/code-review                 # 審查目前分支領先 upstream 的 commit 與未提交變更
/code-review high --fix      # 以較高推理強度審查,並把發現套用到工作目錄
/code-review 1234 --comment  # 審查 PR #1234,並把發現貼成行內留言(GitLab MR 用 !123 或網址)
/code-review ultra           # 升級為雲端多 Agent 深度審查(/ultrareview 為別名)
/security-review             # 針對目前分支相對預設分支的 diff 做安全審查

# 非互動(CI/腳本)
claude ultrareview 1234 --json --timeout 60
claude --from-pr 1234        # 找出建立這個 PR 的 Session 繼續工作

17.3 守則

Claude Code 應該遵守的 Git 安全守則:不自行強制推送(--force)、不跳過 Hook(--no-verify)、不修改既有歷史(amend 已推送的 commit),這些守則必須用設定與 Hook 強制落實,而不是只靠提示文字約束。

特別注意 Auto Mode 的預設行為:分類器預設會封鎖強制推送、git reset --hard、git clean -fd、對已推送或非本次 Session 建立的 commit 執行 --amend、合併沒有人工核准的 PR;但預設允許推送到目前 repo 的任何分支(包含 main)。若團隊不允許 AI 直接推送到受保護分支,必須自己加上規則:

{
  "permissions": {
    "ask": ["Bash(git push *)"],
    "deny": [
      "Bash(git push --force *)",
      "Bash(git push -f *)",
      "Bash(git push origin main)",
      "Bash(git push origin HEAD:main)",
      "Bash(git commit --no-verify *)"
    ]
  }
}

並在 Git 伺服器端開啟分支保護(Branch Protection/Protected Branches)——伺服器端保護才是最後防線,因為客戶端的字串規則無法窮舉所有寫法。

📌 實務建議:讓 Claude Code 在提交前先輸出 git diff --stat 給你確認範圍,再進行 commit,避免意外提交未預期的檔案。

⚠️ 注意:絕對不要靠「請禮貌地提醒 Agent 不要強制推送」來防呆,真正的防線是第5、12章談到的設定與 Hook 層級強制阻擋,加上伺服器端分支保護。

實務案例:一名工程師讓 Claude Code 草擬一次多檔案重構的 Commit Message 與 PR 描述(包含 Summary 與 Test Plan),大幅縮短了撰寫 PR 說明的時間;團隊同時在專案設定加入 "ask": ["Bash(git push *)"],讓每一次推送都需要人工確認。

17.4 Worktree 分支隔離與 /code-review

第9.8章介紹的 Worktree 機制,從 Git 的角度看就是「每個平行任務各自在獨立分支/獨立工作目錄上開發」,可以讓多個分支同時存在於磁碟上的不同路徑,搭配多個 Claude Code Session 平行開發時不會互相干擾。

程式碼審查有三種層次:

指令/服務執行位置用途與特性
/code-review [low|medium|high|xhigh|max](別名 /review)本機,以背景 Subagent 執行,不佔用主對話回報正確性錯誤,依模型與 effort 也涵蓋重用、簡化、效率建議;--fix 套用、--comment 貼到 PR/MR、--max-findings 調整數量;會讀 CLAUDE.md(不讀 REVIEW.md);--fix 的修改不在 Checkpoint 中
/code-review ultra(/ultrareview 為別名)與 claude ultrareview雲端沙箱中的多 Agent 審查較深入、找出的問題經過驗證;Pro/Max 有 3 次免費額度,之後需要用量額度;非互動版預設逾時 45 分鐘,--post 可把結果貼成 PR 留言
Code Review 服務(GitHub App)每個 PR 自動在雲端審查以 REVIEW.md 自訂審查重點(重要性定義、不要回報的項目、一定要檢查的項目),結果以行內留言與 Check run 呈現

📌 實務建議:日常開發中先用 /code-review 做即時的本機快篩,PR 開出前再跑一次 /code-review ultra(或交給 Code Review 服務)做較完整的雲端審查;若團隊文件或腳本中還留有 /ultrareview,功能相同但建議統一改為 /code-review ultra。

17.5 Commit 與 PR 的 AI 協作標註

attribution 設定控制 Claude 建立 commit 與 PR 時附加的歸屬資訊,方便事後追溯哪些變更有 AI 參與:

{
  "attribution": {
    "commit": "Co-Authored-By: Claude <noreply@anthropic.com>",
    "pr": "Generated with Claude Code",
    "sessionUrl": true
  }
}

v2.1.281 起可以直接設定 "attribution": false 隱藏全部歸屬,但較舊版本會略過含此值的整個設定檔;若設定檔會被多個版本共用,請保留物件寫法。企業若要求所有 AI 協作變更都必須標註,應把 attribution 放在 Managed 設定,並在 CI 檢查 commit trailer。

17.6 Git 與 Worktree 的權限行為變更(v3.0 新增)

v2.1.300~v2.1.327 有多項變更讓「過去不會問的 Git 動作」開始詢問或被拒,團隊的 Git 自動化腳本需要對照:

變更版本影響與做法
在非專案、也未信任的 repo 中執行唯讀 git 指令會先詢問v2.1.325需要跨 repo 查詢時,以 --add-dir <路徑> 加入;additionalDirectories 設定不會免除這個詢問
Sandbox 中 git worktree add/move/remove,以及在非本 Session 開啟的 Worktree 中 commit,一律以唯讀失敗v2.1.323建立 Worktree 請用 --worktree 或 Claude 的 EnterWorktree 工具
沙箱內的 git checkout、git stash 或自動 stash 的 pull 無法更新 .claude 等受保護檔案時,Claude 會收到說明v2.1.325不再無聲失敗
ExitWorktree 移除可能含未儲存工作的 Worktree 前會詢問;背景作業仍在其中執行時拒絕移除v2.1.326/v2.1.327防止誤刪未推送的 commit
sed -i 改走標準 Bash 權限詢問並照原樣執行,不再能被 /rewind 還原v2.1.309需要可回溯的修改請讓 Claude 用 Edit 工具
/install-github-app 修改 repo 前會先確認v2.1.327—
Claude Code 自己的 ripgrep 與多數內部 git 指令執行時不帶登入 Token 與 API Keyv2.1.323依賴這些環境變數的 git credential helper 或 Hook 會拿不到值,需改用自己的憑證來源
claude --worktree 在 HEAD 分離或位於其他分支時,結束時不會再未經詢問就移除 Worktree 與分支v2.1.304舊版本請先 push 再結束 Session
# 讓 Claude 在本 Session 唯讀查詢另一個 repo(例如共用的 API 定義),不必每次核准
claude --add-dir ../shared-api-contracts

# 平行開發一律使用獨立 Worktree,結束前先確認沒有未推送的 commit
claude --worktree feature-billing-export
git -C .claude/worktrees/feature-billing-export log --oneline @{u}.. 2>/dev/null || echo "尚未設定上游分支"

⚠️ 注意:sed -i 不能被 /rewind 還原這件事最容易被忽略。若團隊依賴 Checkpoint 回溯(第8.5章),請在 CLAUDE.md 寫明「修改檔案一律使用 Edit 工具,不要用 sed -i」,並以 PostToolUse Hook 稽核。

17.7 本章審查與驗證清單

AI 產出項目❌ 常見錯誤✅ 正確做法人工如何驗證
Git 防護設定以為 Auto Mode 會擋下推送到 main自行加上 ask/deny 規則,並開啟伺服器端分支保護在測試 repo 以 Auto Mode 要求推送到 main,確認被詢問或拒絕
Commit 內容一次提交包含無關檔案或產生檔提交前檢視 git diff --stat,只提交本次任務的檔案git show --stat HEAD
Commit Message/PR 描述描述與實際 diff 不符、誇大測試範圍依實際 diff 撰寫,Test Plan 只寫實際執行過的測試對照 PR 描述與 gh pr diff
審查指令使用已移除的 /pr-comments,或把 /ultrareview 當成另一套功能/code-review [level] [--fix|--comment]、/code-review ultra在目前版本實際執行
AI 審查結果把 AI 審查「沒問題」當成合併依據AI 審查只是輔助,仍需人工 Review檢查 PR 是否有人工核准紀錄
歸屬標註在共用設定檔寫 "attribution": false 導致舊版略過整個檔案共用設定使用物件寫法以舊版 Claude Code 開啟專案,/status 確認設定檔有載入
跨 repo 唯讀查詢把其他 repo 寫進 additionalDirectories 以為就能免詢問執行 gitv2.1.325 起需以 --add-dir 指名才免詢問在測試 Session 對該 repo 執行 git log,確認不再詢問
可回溯的修改讓 Claude 以 sed -i 大量改檔,事後想用 /rewind 還原sed -i 自 v2.1.309 起不能被 /rewind 還原;可回溯的修改用 Edit 工具改檔後執行 /rewind 檢查是否列出該修改

第 18 章 測試工程

本章目標:讓 Claude Code 產生「真的能抓到錯誤」的測試,而不只是「會通過」的測試。讀完後,你應該能辨識 AI 測試最常見的失敗模式(驗證現有行為、弱化斷言、過度 Mock),並用變異測試與 diff 檢查客觀衡量測試品質。

18.1 測試生成工作流程

flowchart TD
    A["選定模組"] --> B["分析現有程式碼/規格"]
    B --> C["產生測試骨架"]
    C --> D["人工檢視斷言正確性"]
    D --> E["執行測試"]
    E --> F["以變異測試衡量測試品質"]
    F -.存活的變異.-> C
    E -.失敗案例回饋.-> B

18.2 各類型測試

  • 單元測試:依框架慣例(JUnit 5/Mockito、pytest、Jest/Vitest)產生,涵蓋邊界條件與例外路徑
  • 整合測試:協助配置測試替身或容器化依賴(例如 Testcontainers),避免對外部服務的假設寫死在 Mock 中
  • E2E 測試:搭配 Playwright 等工具,依使用者流程描述生成腳本;也可搭配 Claude in Chrome(--chrome),讓 Claude 先在瀏覽器實際操作頁面驗證行為,再產生對應的自動化腳本

18.3 範例

claude -p "為 OrderService 撰寫 JUnit 5 測試,涵蓋 null 輸入、金額為 0、併發更新的邊界情況。
每個測試名稱描述「情境_預期結果」,斷言必須檢查具體數值而不是只檢查非 null。
完成後執行 ./mvnw -q test -Dtest=OrderServiceTest 並回報結果"

claude -p "依照這個使用者故事,產生對應的 Playwright E2E 測試腳本,
選擇器優先使用 getByRole/getByLabel,完成後以 npx playwright test 執行"

18.4 TDD 風格使用

可以先讓 Claude Code 根據規格寫出「應該失敗」的測試,確認它真的失敗(紅燈),再實作程式碼直到測試通過(綠燈),這個順序能讓測試真正驗證「正確行為」而非「現有行為」。實務上可以分兩個步驟、甚至兩個 Session 進行:第一步只允許修改測試檔,第二步只允許修改實作檔,避免同一個 Agent 同時改考題與答案。

📌 實務建議:務必人工確認測試斷言的「正確性」,而不只是「測試通過」——AI 有可能生成驗證現有(可能有 Bug)行為的測試。

⚠️ 注意:要明確防範 Agent 用「弱化斷言」或「跳過測試」的方式讓失敗測試變綠燈,而不是真正修正底層問題。Auto Mode 的分類器預設會封鎖「註解掉、刪除或強制通過保護安全行為(認證、存取控制、輸入驗證)的測試」,但一般商業邏輯的測試不在此列,仍需要 Review 把關。

實務案例:一個訂價計算函式採用 TDD 流程開發:先撰寫規格、讓 Claude Code 產生會失敗的測試並確認紅燈、再逐步實作直到全部通過,最後跑變異測試,存活的變異只剩 2 個(皆為等價變異),交付品質明顯優於先寫程式再補測試的做法。

18.5 驗證 AI 產生的測試品質

「測試全部通過」只代表測試與程式碼一致,不代表測試有價值。以下方法能客觀檢查:

檢查項目方法判讀
測試是否真的能抓到錯誤變異測試:Java 用 PIT(mvn org.pitest:pitest-maven:mutationCoverage)、JS/TS 用 Stryker、Python 用 mutmut存活的變異代表測試沒有檢查到該行為
是否被弱化git diff -- '*Test*' '*.spec.*' '*_test.py' 搜尋刪除的 assert、新增的 @Disabled/@Ignore/.skip(/xit(任何弱化都需要合理說明
是否只驗證現有行為故意在被測程式碼植入一個明顯錯誤(例如把 > 改成 >=),測試應該失敗植入錯誤後仍通過,代表測試沒有價值
是否過度 Mock檢查被測物件本身是否被 Mock、斷言是否只驗證 Mock 被呼叫「測 Mock 的測試」不測任何東西
覆蓋率JaCoCo、Istanbul/c8、coverage.py覆蓋率高不等於品質高,需與變異測試搭配
# 快速檢查一個 PR 是否弱化了測試
git diff origin/main...HEAD -- '*Test*.java' '*.spec.ts' | grep -E '^\-.*assert|^\+.*(@Disabled|\.skip\(|xit\()'

18.6 本章審查與驗證清單

AI 產出項目❌ 常見錯誤✅ 正確做法人工如何驗證
單元測試斷言assertNotNull(result) 之類不檢查具體值的斷言斷言具體數值、狀態與例外類型植入錯誤後測試應失敗;變異測試
修正失敗測試修改測試期望值以符合錯誤的實作先判斷是測試錯還是實作錯,回報給人決定檢查測試檔 diff 中期望值的變更是否有理由
跳過測試加上 @Disabled、.skip( 讓 CI 變綠不得跳過;確實無法修正時開 Issue 追蹤第18.5章的 git diff ... | grep 檢查
Mock 使用Mock 被測物件本身只 Mock 外部邊界(網路、時間、外部服務)Code Review 檢查 Mock 對象
E2E 選擇器使用脆弱的 CSS/XPath 選擇器優先 getByRole、getByLabel、data-testid重構 UI 樣式後測試仍應通過

第 19 章 SSDLC 整合

本章目標:把 Claude Code 放進 Secure SDLC 的正確位置——它是多層防護中的一層,而不是取代 SAST、SCA、Secret Scan 等專用工具。讀完後,你應該能設計「Hook → AI 審查 → OS Sandbox → 伺服器端控制」的多層防護,並知道每一層擋得住什麼、擋不住什麼。

19.1 定位

Claude Code 應被視為 Secure SDLC 中的一層輔助,而不是取代 SAST/DAST/Dependency Scan/Secret Scan 等專用工具。

flowchart TD
    R["需求"] --> D["設計"]
    D --> Dev["開發"]
    Dev --> T["測試"]
    T --> Dep["部署"]
    Dep --> Ops["維運"]
    D -.威脅建模協助.-> CC1["Claude Code"]
    Dev -.邊寫邊審查/Hook 阻擋.-> CC2["Claude Code"]
    T -.安全測試案例生成.-> CC3["Claude Code"]
    Dep -.掃描結果摘要與修補.-> CC4["Claude Code"]

19.2 各類掃描的協作方式

官方目前提供四種層次不同的安全審查工具,可依時機組合:

工具時機特性
security-guidance PluginClaude 寫程式的當下安裝後自動運作,讓 Claude 在同一 Session 中審查並修正自己引入的注入、不安全反序列化、不安全 DOM API 等問題(需 Python 3.7+)
/security-review開 PR 前,隨時手動執行對目前分支相對預設分支的 diff 做單次安全審查
Claude Security Plugin定期或重大變更前多 Agent 弱點掃描:建立架構與威脅模型、搜尋弱點、每個發現都獨立複核後才寫進報告,可把選定的發現轉成你自行套用的修補(需 Dynamic Workflows 與 Python 3.9+)
Code Review 服務每個 PR雲端自動審查,可用 REVIEW.md 指定一定要檢查的安全項目

與既有工具的分工:

  • SAST 風格:Claude 的審查擅長抓邏輯性問題(權限繞過、業務規則漏洞),Semgrep/CodeQL 等規則式工具擅長穩定、可重現地抓已知模式,兩者互補
  • Dependency Scan:讓 Agent 讀取 mvn dependency-check:check/npm audit --json 的輸出,摘要風險並提出升級方案,再以建置與測試驗證
  • Secret Scan:以第12章的 PreToolUse Hook(block-secrets.sh)阻擋寫入疑似金鑰,CI 再以 gitleaks 等工具做第二道掃描
claude -p "審查這次 diff 是否有 OWASP Top 10 相關風險,每個發現附檔案:行號與可重現的攻擊情境"
npm audit --json > audit.json && claude -p "閱讀 audit.json,依可利用性排序並提出最小升級方案"
mvn org.owasp:dependency-check-maven:check

19.3 兩層防護案例

第一層(Hook)擋下明顯的硬編碼金鑰格式;第二層(AI Review)抓出較隱晦的安全問題(例如邏輯上的權限繞過)。兩層搭配比單靠其中一層更可靠。

📌 實務建議:把 Claude Code 的安全審查當作 Semgrep/Snyk/OWASP ZAP 等專用工具的「額外一層」,而非取代品;並要求每個 AI 發現都附「可重現的攻擊情境」,沒有情境的發現優先度降低。

⚠️ 注意:涉及認證、加密、PII 的修改,即使 AI 審查說「沒問題」,仍必須經過資安團隊正式簽核,不能把 AI 的意見當作正式核准。

實務案例:一次提交中,PreToolUse Hook 先擋下了明顯的硬編碼資料庫密碼,/security-review 又額外抓出一個邏輯上的權限繞過風險,資安團隊依 AI 附上的攻擊情境在測試環境重現後確認屬實,兩層防護缺一不可。

19.4 Sandboxing:第三層防護

第一層(Hook)與第二層(AI Review)都是「邏輯層」的防護,攔不住的是指令本身在作業系統層級造成的破壞(例如誤刪專案外的檔案、意外連到未預期的網路位置、讀取 ~/.aws/credentials)。Sandboxing 以 OS 層級機制(macOS 為 Seatbelt,Linux/WSL2 為 bubblewrap+socat)限制 Bash 指令及其子程序,提供與邏輯層完全獨立的第三層防護。

flowchart LR
    L1["第一層:PreToolUse Hook<br/>(攔截已知危險指令)"] --> Action["工具呼叫實際執行"]
    L2["第二層:AI Review<br/>(抓邏輯/語意風險)"] --> Action
    L3["第三層:Sandboxing<br/>(OS 級檔案/網路邊界)"] --> Action
    L4["第四層:伺服器端控制<br/>(分支保護/IAM/網路出口)"] --> Action

預設限制(以 /sandbox 或 sandbox.enabled: true 開啟,預設關閉):

存取預設調整
寫入工作目錄、使用者暫存目錄、--add-dir 加入的目錄;受保護路徑仍拒絕寫入filesystem.allowWrite/denyWrite
讀取大部分檔案(包括 ~/.ssh、~/.aws/credentials 等憑證檔)filesystem.denyRead、credentials
網路沒有直接對外路由,經本機 Proxy 檢查允許的網域(預設為空)network.allowedDomains/deniedDomains
環境變數繼承 Claude Code 的環境(含其中的秘密)credentials.envVars、CLAUDE_CODE_SUBPROCESS_ENV_SCRUB

一份企業建議的 Sandbox 設定(已通過檢查工具與 SchemaStore schema 驗證):

{
  "sandbox": {
    "enabled": true,
    "failIfUnavailable": true,
    "autoAllowBashIfSandboxed": false,
    "allowUnsandboxedCommands": false,
    "excludedCommands": ["docker *"],
    "filesystem": {
      "allowWrite": ["/tmp/build"],
      "denyRead": ["~/.kube"]
    },
    "credentials": {
      "files": [
        { "path": "~/.aws/credentials", "mode": "deny" },
        { "path": "~/.ssh", "mode": "deny" }
      ],
      "envVars": [
        { "name": "GITHUB_TOKEN", "mode": "deny" },
        { "name": "NPM_TOKEN", "mode": "deny" }
      ]
    },
    "network": {
      "allowedDomains": ["registry.npmjs.org", "repo.maven.apache.org", "github.com", "*.corp.acme.example"]
    }
  }
}
  • failIfUnavailable: true:Sandbox 無法啟動(缺少相依套件或平台不支援)時直接拒絕啟動;沒有這個鍵時,Claude Code 會改以無 Sandbox 執行指令——這是企業治理最容易忽略的一點。
  • autoAllowBashIfSandboxed:v2.1.324 起預設 false,沙箱內的 Bash 指令仍走一般權限流程(由 allow 規則與權限模式決定)。本範例明確寫出 false,讓審查者一眼看出這是刻意的選擇;若要讓沙箱內指令免詢問,改為 true 並放在最高層級的 Managed 來源(第19.5章)。
  • allowUnsandboxedCommands: false:關閉「被 Sandbox 擋下後改在 Sandbox 外重試」的逃生門(嚴格模式)。
  • credentials:拒絕讀取憑證檔,並在每個 Sandbox 指令執行前移除指定的環境變數。
  • excludedCommands:無法在 Sandbox 中執行的工具(如 Docker)改在外部執行,但會走一般權限流程;必須涵蓋整串指令才會生效。

Sandbox 管不到的範圍(務必在治理文件中講清楚):

  • 內建的檔案與網路工具(Read、Edit、Write、WebFetch、WebSearch)走權限規則,不受 Sandbox 限制——denyRead 擋不住 Read 工具,allowedDomains 也不限制 WebFetch,要搭配 permissions.deny
  • Claude Code 啟動的其他程序:Hook、本機 MCP Server、Plugin monitor、LSP、狀態列指令、apiKeyHelper 都以你的完整權限在 Sandbox 外執行
  • 你在 ! Shell 模式中親手輸入的指令
  • 原生 Windows 不支援 Sandbox,需要時請在 WSL2 中執行 Claude Code

要把以上全部放進同一個邊界,請把 Claude Code 程序本身放進容器、VM 或 Sandbox Runtime 中執行(官方「Sandbox environments」、Dev Container 文件)。

📌 實務建議:Sandbox 適合作為「即使 Hook 規則寫得不夠完整也有底線」的防線,尤其是 CI/自動化情境(--max-budget-usd/--max-turns 限制的是時間與成本,Sandbox 限制的是破壞範圍,兩者互補不重複)。在 Auto Mode 搭配 Sandbox 時,需要連網的指令會在指令上宣告所需網域,由分類器連同指令一起審核,核准後只對該指令開放(v2.1.271+)。

⚠️ 注意:啟用 Sandbox 後,需要存取專案外資源(如內部套件登錄站)的工作流程可能因網域白名單未涵蓋而失敗,導入前應先盤點團隊實際需要連線的網域清單;以 touch ~/sandbox-probe 測試,應出現 Operation not permitted(macOS)或 Read-only file system(Linux/WSL2),代表 Sandbox 確實生效。

19.5 Sandbox 的 v2.1.300~v2.1.327 變更:自動放行預設翻轉與新鍵(v3.0 新增)

最重要的變更:sandbox.autoAllowBashIfSandboxed 自 v2.1.324 起預設為 false。 之前開啟 Sandbox 就等於「沙箱內的 Bash 免詢問」;現在沙箱只負責限制,要不要詢問由 allow 規則與權限模式決定(/sandbox 的 Mode 分頁稱為 regular permissions mode)。兩種模式的差異:

項目autoAllowBashIfSandboxed: true(自動放行模式)false(v2.1.324 起的預設)
沙箱內可執行的 Bash不詢問直接執行依 allow 規則與權限模式;Manual 模式下會詢問
deny 規則、帶內容的 ask 規則(如 Bash(git push *))仍然生效仍然生效
只有 Bash 的 ask 規則對沙箱內指令略過生效
無人值守流程沙箱內指令可自動執行需要核准的指令會被拒(-p)或停在詢問

遷移做法:要維持舊行為,在最高層級的 Managed 來源明確寫出兩個鍵(v2.1.325 起 Managed 開啟 Sandbox 時,必須在最高層級來源設定 autoAllowBashIfSandboxed: true 才會免詢問);repo 內的設定可以寫 deny 項目與這個值,若不希望 repo 改變它,就在 Managed 設定固定:

{
  "sandbox": {
    "enabled": true,
    "failIfUnavailable": true,
    "autoAllowBashIfSandboxed": true
  }
}

其他 Sandbox 變更:

變更版本說明
無效的 --settings(或 SDK 設定)若含 sandbox 鍵,拒絕啟動v2.1.323之前 -p 會在沒有 Sandbox 的情況下照常執行 Bash。v3.0 實測:結束碼 1,訊息為「sandbox required but unavailable … failed validation … Refusing to start without a working sandbox」
沙箱內的指令預設不能寫入部分敏感的家目錄資料夾v2.1.326確有需要時以使用者或 Managed 設定的 sandbox.filesystem.allowWrite 開放
透過可寫資料夾中的符號連結取得的寫入權限會被忽略v2.1.323(macOS/Linux/WSL)請直接授權真實路徑
沙箱拒絕寫入 --add-dir 加入目錄中的 .claude 設定、Skills、Agents、Commands 與 Hooksv2.1.325與啟動目錄的保護一致
sandbox.allowNestedUserNamespacesv2.1.305(Linux/WSL2)讓 Chromium、rootless podman 能在沙箱內建立 user namespace;等於關掉一道安全邊界,只能在使用者設定開啟,repo 不可開
sandbox.network.strictAllowlist—白名單外的主機直接拒絕,不依權限模式詢問;只認使用者、Managed 與 --settings
sandbox.network.tlsTerminate(實驗性)—讓沙箱 Proxy 終止 TLS,credentials 的 mask 項目需要它;只認使用者、Managed 與 --settings
被排除在沙箱外的指令,在 Sandbox 啟用但無法執行時寫入 write-list 路徑前會詢問,不再退回無沙箱執行v2.1.309—

⚠️ 注意:「Sandbox 開了就安全又不用按確認」這個印象在 v2.1.324 之後不再成立。升級後若發現 CI 或背景 Session 大量出現 permission_denials 的 Bash,第一個要檢查的就是這個鍵(第33章 check_upgrade.py 會標為 BREAK)。

19.6 本章審查與驗證清單

AI 產出項目❌ 常見錯誤✅ 正確做法人工如何驗證
安全審查結論「未發現安全問題」就放行AI 審查是額外一層,認證/加密/PII 變更仍需資安簽核檢查 PR 是否有資安團隊核准
AI 安全發現沒有證據與攻擊情境的泛泛建議每個發現附檔案:行號與可重現情境在測試環境依情境重現
Sandbox 設定只設 enabled: true,Sandbox 無法啟動時默默改成無 Sandbox加上 failIfUnavailable: true 與 allowUnsandboxedCommands: false在缺少 bubblewrap 的 Linux 測試機啟動,應拒絕啟動
憑證保護以為 Sandbox 預設會擋讀取 ~/.ssh以 credentials 或 filesystem.denyRead 明確拒絕Sandbox 中執行 cat ~/.ssh/id_rsa 應失敗
防護範圍說明宣稱 Sandbox 也保護 Hook、MCP Server 與 WebFetch這些在 Sandbox 外或走權限規則,需另外管控依第19.4章清單逐項確認對應的控制措施
平台假設在原生 Windows 團隊的文件中要求開啟 Sandbox原生 Windows 不支援,改用 WSL2 或容器在原生 Windows 執行 /sandbox 確認狀態
Sandbox 自動放行開了 sandbox.enabled 就假設沙箱內指令不會詢問v2.1.324 起需明確設 autoAllowBashIfSandboxed: true,且放在最高層級 Managed 來源/sandbox 的 Mode 分頁看實際模式;check_settings.py 對未明確設定發出警告
allowNestedUserNamespaces為了讓 E2E 測試的 Chromium 能跑,直接在專案設定開啟這會讓沙箱內程式碼有機會跑到沙箱外;只在個人設定、確有需要時開啟,或改在容器中執行 E2Echeck_settings.py --scope project 會警告;審查時確認風險接受紀錄
以 --settings 啟用 Sandbox設定檔有語法錯誤卻沒人發現v2.1.323 起含 sandbox 鍵的無效檔案會拒絕啟動;CI 要把啟動失敗當成錯誤處理第29.8章 T3a:結束碼 1;以 python -m json.tool 先驗證檔案

第 20 章 Token 與成本管理

本章目標:理解成本由哪些因子驅動、如何查看個人與組織用量、如何讓報表數字符合合約價,並建立可觀測的成本治理。讀完後,你應該能用 /usage 與 OpenTelemetry 指標定位「是什麼在燒額度」,而不是只看月底帳單。

20.1 成本驅動因子

graph LR
    Model["模型與 Effort"] --> Total["總成本"]
    Ctx["Context 大小<br/>(每次請求都送完整歷史)"] --> Total
    Turns["對話輪數與工具呼叫數"] --> Total
    Cache["Prompt Cache 命中率"] --> Total
    Sub["Subagent/Workflow/Agent Teams 數量"] --> Total
    Idle["閒置期間的排程任務與跨 Session 訊息"] --> Total

長時間開著的 Session 用量往往遠超過你的實際操作,常見原因:(1) 每次請求都會帶上完整對話,工具呼叫越多請求越多;(2) 休息超過快取有效期(訂閱約一小時、超出額度或 API 計費時五分鐘)後第一則訊息會快取失效、整段重算;(3) 排程任務(/loop、Cron)在閒置時仍定期送出完整 Context;(4) 其他 Session 傳來的訊息在閒置時被當作新回合處理。另外 Claude Code 有少量背景用量(為 --resume 摘要過往對話等),通常每個 Session 低於 0.04 美元。

20.2 查看用量

  • /usage(別名 /cost、/stats):顯示本 Session 的成本、方案用量上限與活動統計;Pro/Max/Team/Enterprise 可看到依 Skill、Subagent、Plugin、MCP Server 拆分的用量驅動因子。Session 的金額是本機依牌價估算,Pro/Max 訂閱者的費用已包含在訂閱中,該數字不代表帳單。v2.1.299 起還會對 max effort、Workflows、常駐 Context 與過大的工具結果提出警告。
  • 狀態列與 Spinner 旁的 Token 計數:即時看到目前回合的用量。
  • Team/Enterprise:管理後台可看團隊整體用量;透過第三方雲端部署 Claude apps gateway 時(第4.5.1章),可設定每位使用者的花費上限,/usage 與狀態列會顯示「已花費/上限」金額。
  • Claude Console(API 計費):第一次以 Console 登入時會自動建立名為「Claude Code」的 Workspace,可設定 Workspace 花費上限與速率上限;Console 儀表板可看每位成員的花費。

讓數字符合合約價:Claude Code 預設以牌價計算 /usage、狀態列與 OpenTelemetry 中的金額。若組織有合約價,以 Managed 設定 modelPricing 提供費率或折扣倍率(multiplier 大於 1 可用於內部分攤加成,v2.1.271+):

{
  "modelPricing": {
    "multiplier": 0.85,
    "overrides": {
      "claude-sonnet-4-6": { "input": 2.4, "output": 12, "cacheRead": 0.24, "cacheWrite": 3 }
    }
  }
}

API 組織的速率上限建議(官方建議值,依團隊規模給每人 TPM/RPM):

團隊規模每人 TPM每人 RPM
1-5 人200k-300k5-7
5-20 人100k-150k2.5-3.5
20-50 人50k-75k1.25-1.75
50-100 人25k-35k0.62-0.87
100-500 人15k-20k0.37-0.47
500 人以上10k-15k0.25-0.35

20.3 降低成本技巧

  • 從子目錄啟動、用 --add-dir 限定範圍,大範圍搜尋交給 Subagent(第8章)
  • 用 CLAUDE.md 減少重複解釋,但把多步驟程序移到 Skill,只在需要時載入(第11、27章)
  • 不相關的任務之間執行 /clear;修正兩次仍不對就 /clear 後重寫更好的初始提示
  • 選對模型與 Effort:Opus 5.5/Sonnet 5.5/Haiku 5.5 預設 medium,簡單任務可再調低;用 maxEffortLevel 為組織設上限
  • 減少 MCP 負擔:只啟用需要的 Server,善用 Tool Search 延遲載入
  • 長任務維持固定模型與 Effort,避免 Prompt Cache 失效
  • CI/自動化情境一律設定 --max-budget-usd 與 --max-turns(第29章)
  • Agent Teams 的 Token 消耗明顯高於單一 Session,只在真正需要互相協調時使用
claude -p "..." --max-budget-usd 5.0 --effort low

📌 實務建議:自動化腳本的成本上限應寫在腳本本身(--max-budget-usd),並在 Managed 設定以 maxEffortLevel 限制推理強度上限;--max-budget-usd 是依客戶端估算檢查,實際可能略為超過,要保留餘裕。

⚠️ 注意:不要為了省成本而一律調低 effort——複雜架構設計任務若用過低 effort,後續人工返工的時間成本往往遠高於省下的 API 費用。

實務案例:某團隊發現某月費用異常飆高,以 OpenTelemetry 的 claude_code.cost.usage 依使用者與 skill.name 拆解後,發現是一個常駐 Session 中的 /loop 每 5 分鐘送出一次 600K Token 的完整 Context;改為較長間隔並在任務完成後停止排程,成本隨即下降。

20.4 用量可視化:/usage、Analytics、OpenTelemetry

  • /usage:在 Session 內定位「是哪個機制在燒額度」。
  • Analytics Dashboard:Team/Enterprise 在 claude.ai/analytics/claude-code 查看組織用量趨勢、貢獻度指標與 PR 歸屬;Console 組織在 platform.claude.com/claude-code 查看團隊洞察。
  • 程式化報表:Enterprise 可用 Enterprise Analytics API,Console 組織可用 Claude Code Analytics API,取得逐使用者的每日用量與成本。
  • OpenTelemetry 匯出:所有供應商(含 Bedrock/Google Cloud/Foundry)皆可使用,把指標與事件送進企業既有的可觀測性平台(Grafana、Datadog 等)。

最小可用的 OpenTelemetry 設定(建議放在 Managed 設定的 env,Managed 設定 OTEL_EXPORTER_OTLP_ENDPOINT 後,開發者無法把個別訊號改送到其他 Collector):

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp        # otlp、prometheus、console、none
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector.corp.example:4317
claude

常用指標:

指標用途
claude_code.session.count採用率;設定完成後先確認這個指標有出現
claude_code.cost.usage(USD)成本,可依使用者、團隊、模型、skill.name、plugin.name、agent.name 拆分
claude_code.token.usageToken 用量,依 input/output/cache read/cache write 拆分
claude_code.lines_of_code.count修改行數
claude_code.commit.count/claude_code.pull_request.count對開發流程的影響
claude_code.code_edit_tool.decision編輯工具的權限決策次數(接受/拒絕)
claude_code.active_time.total活躍時間

📌 實務建議:平台團隊應優先導入 OpenTelemetry 匯出,把 Claude Code 用量併入既有監控告警規則(例如「單一使用者單日成本超過閾值」「某 Skill 用量突然倍增」),比每月人工檢視 Analytics Dashboard 更即時。Traces(CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1)目前為 Beta,可用於分析單一請求的耗時分佈。

⚠️ 注意:OpenTelemetry 的 user_prompt 事件可能含有提示內容,OTEL_LOG_TOOL_CONTENT=1 還會帶入工具輸出;匯出前應與資安、法遵確認欄位遮罩與保存政策。

20.5 OpenTelemetry 欄位變更與模型成本異動(v3.0 新增)

必須處理:claude_code.safety_event 已停止送出。 這個事件在 v2.1.307 新增,但 v2.1.312 起不再送出,也沒有設定可以重新開啟(v2.1.307~v2.1.311 的 Session 會在下次 feature flag 更新時停止)。若你在 v2.0 之後依此事件建立了告警,告警會靜默失效。改用 claude_code.tool_decision 事件:

屬性版本用途
decision—accept/reject
source—決定來自哪裡(規則、使用者、Hook 等)
classifier_verdictv2.1.301Auto Mode 分類器結果:allow、block、no_verdict(檢查無有效結果而拒絕)、unavailable(分類器請求失敗而拒絕);由權限規則決定時不出現
permission_modev2.1.301檢查開始時的權限模式(Manual 以 default 表示)
classifier_categoryv2.1.301分類器封鎖時命中的內建規則或政策名稱;需 OTEL_LOG_TOOL_DETAILS=1

其他觀測欄位變更:

變更版本
api_request 事件新增 cache_creation_5m_tokens、cache_creation_1h_tokens,可區分兩種快取寫入成本v2.1.300
Trace span 加入 OpenTelemetry GenAI 語意慣例屬性(gen_ai.provider.name、gen_ai.conversation.id、gen_ai.tool.name、error.type 等)v2.1.300
指標、事件、span 加入 anthropic.plan、anthropic.seat_type、anthropic.provider、anthropic.custom_base_urlv2.1.317
OTEL_RESOURCE_INCLUDE_HOST 可在資源屬性加入 host.name、host.id(預設關閉)v2.1.326
設了 otlp 端點但沒設 OTEL_EXPORTER_OTLP_PROTOCOL 時,預設改為 http/protobuf(之前會靜默失敗)v2.1.323
送往預設 localhost:4318 的匯出不再經過設定的代理v2.1.323
Managed 設定中的 PreToolUse Hook 拒絕時也會留下 tool_decisionv2.1.326

一個以 tool_decision 區分「分類器擋下」與「規則擋下」的查詢範例(以 Elasticsearch/OpenSearch 的 Query DSL 為例,欄位名稱依你的 Collector 對應調整):

{
  "query": {
    "bool": {
      "filter": [
        { "term": { "event.name": "tool_decision" } },
        { "term": { "decision": "reject" } },
        { "terms": { "classifier_verdict": ["block", "no_verdict", "unavailable"] } }
      ]
    }
  },
  "aggs": {
    "by_verdict": { "terms": { "field": "classifier_verdict" } },
    "by_mode": { "terms": { "field": "permission_mode" } }
  }
}

no_verdict 與 unavailable 突然增加,通常代表分類器服務或 Gateway 有問題(請求被丟棄),而不是使用者行為改變,應通知平台團隊而非資安團隊。

模型與成本異動:

項目內容
Fable 5.2(v2.1.321)成為 fable 別名的預設;1M Context;每百萬 Token 輸入 US$8/輸出 US$40,快取讀取 US$0.20
Opus 4.8 Fast Modev2.1.316 公告 2026-10-30 起棄用、2026-11-30 移除;移除後的 Fast Mode 請求會直接錯誤,不會退回標準 Opus 4.8,請改用 Opus 5.5
Fable 與用量點數依方案與席位,Fable 用量可能改從用量點數(usage credits)計費;-p 與 SDK 中不會詢問就直接計費
成本預算以 subagentPromptCacheTtl、CLAUDE_CODE_DISABLE_AGENT_PROGRESS_SUMMARIES 等新設定調整前,先建立基準(第8.6章)

20.6 本章審查與驗證清單

AI 產出項目❌ 常見錯誤✅ 正確做法人工如何驗證
成本報告把 /usage 的 Session 金額當成訂閱帳單說明那是牌價估算;有合約價時設定 modelPricing對照 Console 或後台帳單
自動化成本控制只設 --max-turns,沒有金額上限同時設 --max-budget-usd,並保留餘裕以 fixture 測試 gate 腳本對 error_max_budget_usd 的處理
OTel 設定只設 OTEL_EXPORTER_OTLP_ENDPOINT,忘了 CLAUDE_CODE_ENABLE_TELEMETRY=1依本章最小設定,放在 Managed env後端確認出現 claude_code.session.count
成本最佳化建議一律調低 effort 或換小模型依任務複雜度選擇,並以 maxEffortLevel 設上限比較調整前後的任務成功率與返工次數
異常用量排查只看總金額依 skill.name、agent.name、使用者拆分,檢查排程任務OTel 儀表板的拆分圖表
安全告警以 claude_code.safety_event 建立告警v2.1.312 起已停止送出;改以 tool_decision 的 decision=reject 與 classifier_verdict 建立在測試環境故意觸發一次拒絕,確認告警有收到;檢查 Collector 近期是否仍有 safety_event(應為 0)
Fast Mode 設定腳本或設定仍指定 Opus 4.8 的 Fast Mode2026-11-30 起會直接錯誤,改用 Opus 5.5搜尋設定與腳本中的 claude-opus-4-8 與 fastMode;以 /fast 確認目前模型
OTLP 匯出設定只設端點、不設協定,以為匯出正常明確設定 OTEL_EXPORTER_OTLP_PROTOCOL;v2.1.323 以前會靜默失敗在 Collector 端確認有收到資料,而不只看 Claude Code 沒報錯

第 21 章 團隊導入指南

本章目標:規劃從試點到全面導入的階段、治理角色與標準規範,並準備新機制上線前的治理檢查項。讀完後,你應該能產出一份有負責人、有驗收訊號、可被稽核的導入計畫。

21.1 分階段導入流程

flowchart TD
    P1["Phase 1:試點小組<br/>(5 人內、低風險專案)"] --> P2["Phase 2:標準化<br/>(CLAUDE.md 範本/共用 Subagent/Hook/檢查工具)"]
    P2 --> P3["Phase 3:推廣<br/>(Managed 設定/MCP 核准目錄/成本儀表板)"]
    P3 --> P4["Phase 4:治理常態化<br/>(每週版本追蹤/每季權限稽核)"]
階段主要工作進入下一階段的訊號
試點選低風險專案;建立 CLAUDE.md;記錄常見問題;決定預設權限模式策略試點成員連續數週主動使用,且有可量化的案例
標準化CLAUDE.md 範本、.claude/agents/、.claude/hooks/ 與第30章檢查工具進 CI新專案能在一天內套用範本並通過檢查
推廣Managed 設定交付、MCP 核准目錄、OpenTelemetry 儀表板、Champion 網絡各團隊有自己的 Champion,問題能在團隊內解決
常態化每週掃描 Changelog、每季權限與 Plugin 稽核、版本區間調整治理活動有固定負責人與紀錄

官方提供兩份可直接採用的推廣素材:給管理者的 Communications kit(上線公告範本、主管版與試點版公告、每週技巧推送主題、常見問題一句話回覆)與給工程師的 Champion kit(Champion 的角色、分享什麼、30 天推廣節奏、常見疑慮回應)。Champion kit 建議的 30 天節奏是:第 1 週建立頻道並張貼自己的實例與提示;第 2 週開始每週分享串、公開回答每個問題;第 3 週提供短時間結對、整理置頂 FAQ;第 4 週找出第二位 Champion,並向主管或管理者簡報哪些做法有效、哪些無效(成功訊號是頻道中的問題開始由其他人回答)。

21.2 治理模式

由小型跨職能小組(技術主管 + 資安 + DevOps/平台)負責核准:新增 MCP Server(第13章)、共用子 Agent(第10章)、企業 Hook 規則(第12章)、新的 Plugin 與 Marketplace(第27章)、Managed 設定變更(第5.5章)。所有核准都應留下紀錄(PR、工單),並對應到 Managed 設定或 repo 中的具體檔案。

21.3 權限管理

依第5章的設定優先順序分工:

層級負責人放什麼
Managed企業 IT/平台團隊安全底線:危險指令 deny 規則、allowManagedHooksOnly、disableBypassPermissionsMode、Sandbox 強制、版本區間、allowedProviders、maxEffortLevel、遙測
專案(.claude/settings.json)專案團隊(變更經 CODEOWNERS 審查)專案的允許清單、Hook、Plugin、MCP
本機(.claude/settings.local.json)與使用者個人不影響安全的偏好:主題、Effort、個人允許規則

21.4 標準規範

  • 強制使用 CLAUDE.md 範本(第11章),並以 /doctor prompt-audit 定期檢查
  • 共用的 Subagent、Skill、Hook、MCP 設定一律走 PR,CI 執行第30章的檢查工具
  • Prompt Library 走 PR 審查流程(第23章)
  • AI 協作產生的 Commit/PR 需註明(attribution 設定,第17.5章)
  • 強制人工 Review,AI 產出不可直接合併;AI 宣稱完成的工作必須附驗證證據(第14.5章)

📌 實務建議:先成立 5 人以內的試點小組驗證流程,標準成熟後才推廣到全公司,避免一開始就要求所有團隊同時改變習慣。

⚠️ 注意:若在 CLAUDE.md/Prompt Library 標準尚未成形前就全公司推廣,各團隊產出品質會明顯不一致,應先標準化再規模化。

實務案例:一個 200 人工程組織,從 5 人試點小組開始,一個季度內逐步推廣到全組織;過程中成立治理委員會核准新的 MCP Server 與共用子 Agent,並由每個團隊推派一位 Champion 依官方 30 天節奏帶動,避免了野蠻生長導致的治理真空。

21.5 新機制的治理檢查項

進階機制擴大了「自動化範圍」與「可能出錯範圍」,治理委員會在核准導入時應額外檢查:

機制核准重點
Auto Mode 成為內建起始模式(v2.1.283 起所有方案,第6.6章)是否明確決定沿用 auto、或以 Managed permissions.defaultMode 改為 default/acceptEdits;是否以 autoMode.environment 描述可信基礎設施;是否以 deny 規則補上分類器預設允許的高風險動作(如推送到受保護分支)
Agent Teams(第26.2章)是否評估過「多 Session 互相傳訊」放大錯誤傳播的風險;是否僅在非生產專案試行
Dynamic Workflows(第26.3章)存成指令的 Workflow 腳本是否經過 Code Review;是否設定 workflowSizeGuideline;是否需要以 disableWorkflows 暫時停用
跨 Session 訊息傳遞(第9.10章)是否已決定 crossSessionInbound 的組織預設值;是否需要以 isolatePeerMachines 強制人工核准跨機器訊息
Plugins 與 Marketplace(第27.4章)是否限定 strictKnownMarketplaces/維護 blockedMarketplaces;是否需要 strictPluginOnlyCustomization、disableSideloadFlags、disableCommandPluginSources;是否決定 syncClaudeAiSkills/syncClaudeAiPlugins 的政策
Claude Mods(v2.1.287+,第27.4章)Mods 可修改 Claude Code 更深層的行為(例如在權限檢查前核准動作),安裝來源與審查流程是否比一般 Plugin 更嚴格
供應商與模型治理是否以 allowedProviders 限制可用供應商、availableModels/deniedModels 限制模型、maxEffortLevel 限制推理強度
自架執行環境(第1.6章)是否已確認 claude self-hosted-runner 執行環境的網路與資料落地邊界符合企業要求
AGENTS.md 原生讀取(第11.7章)若 repo 同時給其他 AI 工具使用,是否決定 Project instructions 的組織預設
版本治理是否已設定 minimumVersion 與 requiredMinimumVersion/requiredMaximumVersion,並有每週追蹤 Changelog 的負責人

📌 實務建議:把這張表併入既有的「治理模式」(21.2章)核准清單,由同一個跨職能小組統一審查,避免新機制各自獨立核准造成治理碎片化。

21.6 Onboarding 工具箱

工具用途
/powerup以互動式小課程與動畫示範介紹功能,適合新人第一天
/team-onboarding分析你近 30 天的使用紀錄(指令、MCP Server 等),產生一份新同事可直接貼上當第一則訊息的設定指南
/insights產生 HTML 報告,分析你近期在哪些專案使用、常見卡關點與值得嘗試的功能(含 Auto Mode 能省下多少權限詢問的估算)
/init為新專案產生 CLAUDE.md 初稿
附錄F 新人檢查清單確認安裝、認證、設定與治理規範都已到位

21.7 v3.0 治理檢查項補充(v3.0 新增)

第21.5章的檢查項在 v3.0 需要補充以下項目,建議併入每季治理審查:

檢查項問題依據章節
Sandbox 自動放行autoAllowBashIfSandboxed 的值是刻意決定的嗎?寫在最高層級 Managed 來源嗎?19.5
模型白名單是否已加 enforceAvailableModels: true?是否有人仍依賴 best=Fable?5.6
無人值守 Session是否以 denyInsteadOfPrompting 讓無人回應的詢問直接拒絕?CI 是否檢查 permission_denials?5.8、29.8
寫入範圍高風險 repo 是否開啟 blockWritesOutsideWorkingDirectories(含 bypass 模式也生效)?5.8
Code Mode試點或封鎖的決定是否寫入政策?試點者是否有 REPL Hook?31
跨 Session 傳訊不需要時是否以 crossSessionInbound: "refuse" 與 deny 規則關閉?(v2.1.323 起傳訊上限為 100,000)9.11
代理設定是否仍有只設 ALL_PROXY 的機器?28.6
觀測告警是否仍依賴已停止送出的 safety_event?20.5
Plugin 版本相容內部 Plugin 是否宣告 engines["claude-code"]?pluginDigests 是否已移除?27.7
Projects是否有人以個人 Pro/Max 帳號的 Projects 處理公司 repo(不受 Managed 設定約束)?9.11

📌 實務建議:把上表轉成治理會議的固定議程,每項指定負責人並以「證據」結案(例如 /status 截圖、check_upgrade.py 輸出、Collector 查詢結果),而不是口頭回報「已處理」。

21.8 本章審查與驗證清單

AI 產出項目❌ 常見錯誤✅ 正確做法人工如何驗證
導入計畫只有時程,沒有負責人與進入下一階段的訊號每階段列出負責人、交付物與驗收訊號檢查計畫中每一列是否有可觀測的訊號
權限分層把安全底線放在專案設定安全底線放 Managed,專案設定經 CODEOWNERS 審查/status 確認 Managed 來源;檢查 CODEOWNERS
治理檢查表沿用 v1.3「Pro/Max/Team 才預設 Auto Mode」的前提依 v2.1.283 的行為重新決策以一般帳號新開 Session 觀察起始模式
推廣溝通自行從零撰寫公告與 FAQ以官方 Communications kit 與 Champion kit 為基礎客製對照官方素材確認關鍵訊息(安全、Review 要求)都有涵蓋
治理檢查表沿用 v2.0 的檢查表,未納入 v2.1.300 以後的預設值變更併入第21.7章補充項,並以證據結案抽查兩項:要求提供 /status 截圖與 check_upgrade.py 的輸出

第 22 章 Claude Code 最佳實務

本章目標:把前面各章的重點濃縮成可貼在團隊頻道的清單,並對照官方整理的常見失敗模式。每一條都對應到前面章節的具體做法與驗證方式。

22.1 20 個最佳實務

  1. 給 Claude 一個它能自己執行的驗證方式(測試、建置、Linter、截圖),並要求附上證據(第14.5章)
  2. 先探索、再規劃、後實作:大型變更先在 Plan 模式產出計畫並由人審查(第14.1章)
  3. 維護並持續更新 CLAUDE.md,每個檔案控制在 200 行以內(第11章)
  4. 每次 Diff 都人工 Review,AI 審查只是輔助
  5. 大型任務拆解成 Subagent,會寫檔的平行任務以 Worktree 隔離(第9章)
  6. 在 CLAUDE.md 中明確標註框架版本與慣例
  7. CI/自動化情境一律設定 --max-turns、--max-budget-usd、--permission-prompts none(第29章)
  8. 從子專案目錄啟動,必要時以 --add-dir 補充範圍
  9. 安全規則寫進 deny 規則與 Hook,並以 harness 測試 Hook(第12章)
  10. 子 Agent 採最小權限工具授權,審查類用 permissionMode: plan(第10章)
  11. MCP Server 維護核准目錄,以 allowedMcpServers 強制(第13章)
  12. 共用設定、Subagent、Skill 走 PR,CI 執行第30章的檢查工具
  13. 依任務複雜度選擇模型與 Effort,並以 maxEffortLevel 設組織上限
  14. 善用 Session 續接(-c/-r)與命名(-n)避免重複解釋
  15. 不相關的任務之間執行 /clear,修正兩次仍不對就重寫初始提示
  16. 企業層級用 Managed 設定強制安全底線,並以 /status 驗證交付來源
  17. 測試斷言正確性務必人工確認,搭配變異測試(第18章)
  18. 框架升級分批進行,機械式改寫優先交給確定性工具(第16章)
  19. 逆向工程產出要求附來源位置,並由 SME 核對(第15章)
  20. 每週追蹤 Changelog,定期回顧本清單與團隊教材是否過時(第1.7章)

22.2 20 個常見錯誤

  1. 一次性丟整個 Monorepo 給 Agent
  2. 盲信 AI 產出的安全相關程式碼
  3. 沒有證據就接受「已完成、測試通過」
  4. 子 Agent 工具授權過寬
  5. Hook 用 exit 1 表示阻擋(實際上不會阻擋)
  6. 未設定成本、輪數上限就跑自動化任務
  7. 平行 Sub Agent 沒有界定檔案所有權、也沒有用 Worktree
  8. CLAUDE.md 塞入過多巨大規格內容
  9. 把必須全程生效的規則放在有 paths 的 Rules,壓縮後消失
  10. 升級框架時一次性全倉庫重寫
  11. 對冷僻語言(COBOL 等)逆向工程結果未經核對
  12. 個人各自申請 API Key 而非用 Team/Enterprise
  13. 把 API Key 寫進程式碼、.mcp.json 或 .env 並提交版控
  14. 用「弱化斷言」或 @Disabled 讓失敗測試變綠燈
  15. MCP Server 未審查就接入,或連到正式環境的讀寫帳號
  16. 以為 Auto Mode 會擋下推送到 main,沒有自己加規則與伺服器端分支保護
  17. 設定檔寫 // 註解或拼錯鍵名,設定被靜默忽略
  18. 把 AI 審查意見當作正式資安簽核
  19. 只設 sandbox.enabled,沒有 failIfUnavailable,Sandbox 啟動失敗時無聲降級
  20. 推廣全公司前未先標準化 CLAUDE.md 與規範

22.3 20 個效能優化技巧

  1. 從子目錄啟動、以 --add-dir 補充,而非全庫掃描
  2. 大範圍搜尋交給 Explore Subagent,結果不淹沒主對話
  3. 長任務維持固定模型與 Effort,避免 Prompt Cache 失效
  4. CLAUDE.md 精簡,只放高頻重用內容;多步驟程序移到 Skill
  5. 簡單任務調低 --effort
  6. 善用 MCP Tool Search 延遲載入,只啟用需要的 Server
  7. 用 /context 與 /skill-doctor 找出 Context 佔用來源
  8. 適時用 /compact <重點>、Rewind 的 Summarize 或 /autocompact 管理長對話
  9. CI 中使用 --output-format json 與 --json-schema,減少下游解析失誤重跑
  10. 平行任務拆 Subagent 或背景 Session,縮短總時長
  11. 善用 Session 續接避免重新建立 Context
  12. 以 --mcp-config 加 --strict-mcp-config 限定當次需要的 MCP Server
  13. 避免在單一 Session 中混雜多個不相關主題
  14. 設定 fallbackModel,避免單一模型過載中斷任務
  15. 自動化腳本設定合理 --max-turns 避免低效迴圈
  16. 大量腳本化呼叫使用 --bare 加快啟動
  17. 多使用者腳本加 --exclude-dynamic-system-prompt-sections 提高快取共用
  18. 大型重構先產出計畫文件,再分批執行
  19. 以 /btw 問旁支問題,不增加主對話歷史
  20. 定期清理不再需要的背景 Session(claude rm)與排程任務
quadrantChart
    title 常見錯誤:影響程度 x 發生頻率
    x-axis 低頻率 --> 高頻率
    y-axis 低影響 --> 高影響
    "一次性丟整個Monorepo": [0.7, 0.4]
    "盲信AI安全程式碼": [0.4, 0.9]
    "沒有證據就接受完成": [0.6, 0.8]
    "API Key寫入版控": [0.2, 0.95]
    "子Agent權限過寬": [0.3, 0.6]
    "Hook用exit 1": [0.35, 0.75]

📌 實務建議:把本章三份清單印成團隊內部 Onboarding 文件的一部分,新人入職第一週就過一次。

⚠️ 注意:最佳實務清單會隨 Claude Code 版本演進而需要調整,建議每次重大版本更新後重新檢視本章內容是否仍然適用。

實務案例:某團隊導入前後對比:導入這些實務前,平均一個中型任務需要 15 輪互動且常需要重來;導入「先規劃」「要求驗證證據」「範圍限定」「Subagent 拆分」後,同類任務輪數明顯下降,且重工比例降低(為情境試算,非官方公布數據)。

22.4 官方整理的常見失敗模式

模式症狀修正
大雜燴 Session一個 Session 裡先做 A、再問無關的 B、再回到 A,Context 充滿不相關資訊不相關的任務之間 /clear
一再修正Claude 做錯、你修正、仍然錯、再修正,Context 被失敗的嘗試污染修正兩次仍不對,就 /clear 並把學到的東西寫進更好的初始提示
過度詳細的 CLAUDE.mdCLAUDE.md 太長,重要規則淹沒在雜訊中被忽略大幅刪減;Claude 本來就會做對的就刪掉,必須強制的改成 Hook
先信任再驗證的落差看起來合理的實作沒有處理邊界情況一律提供驗證方式(測試、腳本、截圖);無法驗證就不要出貨
無止盡的探索要 Claude「調查一下」卻沒限定範圍,讀了數百個檔案填滿 Context限縮調查範圍,或交給 Subagent 探索

22.5 本章審查與驗證清單

AI 產出項目❌ 常見錯誤✅ 正確做法人工如何驗證
團隊最佳實務文件條列空泛口號,沒有對應的做法每條連到具體設定、指令或檢查工具隨機抽 3 條,確認能找到對應的章節與驗證方式
失敗模式診斷把 Context 問題歸咎於模型能力先檢查是否屬於第22.4章的模式/context 檢查;改用 /clear 加更好的提示重試
清單時效性沿用舊版本的功能名稱(/vim、/pr-comments、project purge)每次大版本更新後對照 Changelog 修訂以 check_flags.py 掃描團隊文件

第 23 章 Claude Code Prompt Library

本章目標:建立可重用、可審查、內建驗證條件的提示範本庫。v2.0 的每個範本都加上「完成條件」與「證據要求」兩段,讓 AI 依範本產出時,人能直接用證據判斷結果是否正確。

23.1 分類架構

graph LR
    Root["Prompt Library"] --> Web["Web開發"]
    Root --> Review["Code Review"]
    Root --> Arch["架構設計"]
    Root --> Legacy["逆向工程"]
    Root --> Upgrade["Framework升級"]
    Root --> Test["測試"]
    Root --> Doc["文件生成"]
    Root --> Debug["除錯"]

一個好的範本由四部分組成:任務(做什麼)、限制(版本、範圍、不可做的事)、完成條件(可執行的檢查)、證據要求(回報時要附什麼)。

23.2 範本(可直接複製套用)

Web 開發

建立一個 {Framework} 的 {ResourceName} 模組,包含 CRUD API,
使用本專案 CLAUDE.md 中標註的版本與慣例,只修改 {目錄} 底下的檔案。
完成條件:{建置指令} 與 {測試指令} 皆成功。
回報時附上:新增/修改的檔案清單、測試指令輸出的最後 20 行。

Code Review(安全導向)

請審查這次 diff(相對於 {base 分支}),依 OWASP Top 10 檢查注入、權限繞過、敏感資料外洩風險。
只回報有證據的問題:每一項附檔案:行號、風險等級(high/medium/low)與可重現的攻擊情境。
沒有把握的項目另外列在「待確認」,不要混在結論中。

架構設計

依據以下需求描述,產出 C4 模型 Context 與 Container 層級的 Mermaid 圖,
並列出 3 個可能的架構決策(ADR)選項,每個選項說明取捨、成本與風險。
完成條件:Mermaid 圖能以 mermaid-cli 渲染成功。

逆向工程

(在 Plan 模式執行)列出 {目錄路徑} 下所有進入點檔案,並追蹤從 {EntryPoint} 開始的呼叫鏈,產出 Mermaid 循序圖。
每一步標註檔案:行號;無法從靜態程式碼確定的呼叫(反射、設定檔決定)標示「待確認」。

Framework 升級

(在 Plan 模式執行)掃描專案中所有 {舊API/套件} 的使用位置,依模組分組列出受影響檔案清單,
標出確定性工具(如 OpenRewrite)無法自動處理的情況,並產出分批遷移計畫(每批含可獨立測試的範圍)。

測試

為 {ClassName} 撰寫 {TestFramework} 測試,涵蓋正常案例、邊界案例與例外情況。
斷言必須檢查具體數值,不可只檢查非 null;不可修改被測程式碼。
完成條件:{測試指令} 全數通過。回報時附上測試輸出,並說明每個測試對應的需求。

文件生成

依據這個模組的程式碼,產出 README,包含:模組用途、對外介面、依賴關係圖(Mermaid)、已知限制。
文件中提到的每個指令都必須實際可執行;無法確認的內容標示「待確認」。

除錯

這是錯誤訊息與重現步驟:{錯誤輸出}。
先找出根本原因並說明證據(檔案:行號、日誌),再修正;不要壓制錯誤或加 try/catch 掩蓋。
完成條件:重現步驟不再出錯,且 {測試指令} 通過。

23.3 從範本升級為 Skill

當一個範本被頻繁使用、需要附帶腳本或檢查清單時,就應該升級成 Skill(第27章):範本文字放進 SKILL.md,{參數} 改用 $ARGUMENTS 或具名參數,需要的唯讀指令以 allowed-tools 預先核准,高風險操作加上 disable-model-invocation: true。範本庫與 Skill 可以並存:範本適合一次性、需要人調整的任務;Skill 適合標準化、可重複的流程。

📌 實務建議:把 Prompt Library 當成程式碼一樣版控管理,新範本要經過 PR 審查,並附上一次實際使用的輸出作為範例,避免劣質範本擴散到全團隊的使用習慣。

⚠️ 注意:範本會隨框架與 Claude Code 本身演進而過時,建議指派負責人定期驗證範本仍能產出正確結果。

實務案例:某團隊建立內部 Prompt 範本庫,與 CLAUDE.md 一起版控;加入「完成條件」與「證據要求」兩段後,Review 時不再需要自己重跑測試確認,直接檢查 Claude 附上的輸出即可,Review 時間明顯縮短。

23.4 本章審查與驗證清單

AI 產出項目❌ 常見錯誤✅ 正確做法人工如何驗證
新範本只有任務描述,沒有完成條件與證據要求依「任務、限制、完成條件、證據要求」四段撰寫PR 審查時檢查四段是否齊全
範本中的版本資訊寫死框架版本,日後過時引用 CLAUDE.md 標註的版本年度檢查範本是否仍引用正確
範本效果沒人驗證範本能否產出正確結果PR 附上一次實際使用的輸出由審查者以範本重跑一次比對

第 24 章 Claude Code + GitHub Copilot 協同開發

本章目標:讓 Claude Code 與 GitHub Copilot 在同一個團隊、同一個 repo 中互補而不互相干擾,特別是「兩套工具的指令檔如何維持單一事實來源」。

24.1 分工模式

Copilot 擅長「IDE 內的即時補全與小範圍修改」,Claude Code 擅長「終端機驅動的多檔案深度推理、可驗證的自動化流程」。兩者不是競爭關係,而是互補:Copilot 加速逐行撰寫,Claude Code 負責規劃、跨檔案一致性與驗證。

flowchart LR
    Plan["Claude Code 終端機<br/>(規劃/產生骨架)"] --> Editor["VS Code 編輯器<br/>(Copilot 即時補全/微調)"]
    Editor --> ReviewStep["Claude Code 終端機<br/>(/code-review、跑測試)"]
    ReviewStep --> Commit["Commit"]

24.2 實際工作流程

  1. 在 Claude Code 以 Plan 模式規劃功能、產生骨架與測試
  2. 切到 VS Code 編輯器,靠 Copilot 補全細節(如方法內部邏輯)
  3. 回到 Claude Code 執行 /code-review 與專案測試,確認整體一致性
  4. 提交 Commit

Claude Code 也有 VS Code 擴充套件,與終端機 Session 共用設定、CLAUDE.md 與 MCP Server;團隊可依個人習慣選擇在終端機或擴充套件面板中使用。

24.3 避免衝突

最常見的問題是兩套工具的指令檔內容分歧。建議以 AGENTS.md 作為共同的單一事實來源:Claude Code 自 v2.1.277 起在專案沒有 CLAUDE.md 時會直接讀取 AGENTS.md(第11.7章),GitHub Copilot 也支援讀取 AGENTS.md。實務做法:

做法適用情境
只維護 AGENTS.md,不放 CLAUDE.md兩套工具的規則完全相同
AGENTS.md 放共同規則,CLAUDE.md 第一行寫 @AGENTS.md,下方只放 Claude 專屬內容(Hook 說明、Skill 使用方式)有少量 Claude 專屬設定
保留 .github/copilot-instructions.md,並由 CI 檢查它與 AGENTS.md 的共同段落一致團隊已大量使用 Copilot 專屬指令

同一檔案盡量避免兩個工具同時編輯,採輪流操作而非同步編輯;Claude Code 修改後先 git diff 確認,再讓 Copilot 接手微調。

📌 實務建議:指定一份「規範來源」作為主文件(建議 AGENTS.md),其餘由它匯入或衍生,避免規則分裂。

⚠️ 注意:兩個 AI 工具同時對同一檔案做不同方向的修改,容易產生令人困惑的雙重編輯,建議明確劃分「誰在改、何時改」。

實務案例:前端團隊原本同時維護 CLAUDE.md 與 copilot-instructions.md,三個月後兩份檔案對「狀態管理一律用 Pinia」的描述出現矛盾;改為以 AGENTS.md 為唯一來源、CLAUDE.md 只保留 @AGENTS.md 與兩行 Claude 專屬說明後,問題不再發生。

24.4 本章審查與驗證清單

AI 產出項目❌ 常見錯誤✅ 正確做法人工如何驗證
指令檔架構兩份內容大量重複、各自演進AGENTS.md 為主,CLAUDE.md 以 @AGENTS.md 匯入Claude Code /memory 確認載入檔案;比對兩工具的行為
同時存在 CLAUDE.md 與 AGENTS.md以為 Claude 兩份都會讀預設只讀 CLAUDE.md;需要兩者都讀時設定 claude-md-and-agents-md 或使用匯入啟動訊息與 /memory 檢查
協作流程兩個工具同時編輯同一檔案輪流編輯,每次交接前 git diff檢查 commit 歷史是否出現互相覆蓋

第 25 章 Claude Code 企業級導入藍圖

本章目標:把前面各章的技術控制整合成一份企業藍圖:分層架構、組織分工、治理控制點與可稽核的 KPI。讀完後,你應該能向管理層說明「我們用哪些機制確保 AI 協作是可控、可追溯的」。

25.1 完整藍圖

graph TB
    Dev["開發層<br/>(Terminal / IDE / Desktop / CI)"] --> Agent["Claude Code Agent 層<br/>(主 Agent / Subagent / Workflow)"]
    Agent --> Gov["治理層<br/>(Managed 設定 / 權限模式 / Hooks / Sandbox)"]
    Gov --> Integ["整合層<br/>(MCP 核准目錄 / Plugin Marketplace)"]
    Integ --> Infra["資料/基礎設施層<br/>(Repo / 分支保護 / Secrets Manager / Gateway / OTel)"]

25.2 組織架構

建議設立中央「AI 賦能/平台」小組,負責維護 Managed 設定、共用 Subagent、CLAUDE.md 範本、MCP 核准目錄與第30章的檢查工具;各業務單位指派「AI Champion」負責推廣與第一線問題收集(第21.1章);資安團隊負責審查 Hook、Sandbox 與 Auto Mode 政策;法遵團隊負責資料保存與遙測欄位政策。

25.3 治理模式總結(彙整前述章節)

控制面主要機制章節
設定交付Server-managed/MDM/檔案型 Managed 設定,managedSourcesBehavior、policyHelper、跨來源鎖定鍵5.5、28.1
登入與供應商forceLoginMethod、forceLoginOrgUUID、allowedProviders、Claude apps gateway4.4、4.5.1
模型與推理availableModels、deniedModels、maxEffortLevel、組織模型治理(Enterprise)5.6、28.3.1
權限與模式deny/ask 規則、permissions.defaultMode、disableAutoMode、autoMode.environment、disableBypassPermissionsMode6.6
強制阻擋Managed Hook+allowManagedHooksOnly+onFailure: "block"12
隔離OS Sandbox(failIfUnavailable)、Worktree、容器/Dev Container19.4、9.8
擴充管控MCP 核准目錄、strictKnownMarketplaces、strictPluginOnlyCustomization13.5、27.4
版本minimumVersion、requiredMinimumVersion/requiredMaximumVersion3.9
可觀測性OpenTelemetry、Analytics、modelPricing20.4
伺服器端最後防線分支保護、CI 必要檢查、雲端 IAM、網路出口控管17.3、28.3

伺服器端治理(Enterprise 的組織模型限制、預設模型、Effort 上限)不涵蓋 Bedrock、Google Cloud、Foundry 與 Claude Platform on AWS;這些供應商需改用 Managed 設定的 availableModels、model 與 maxEffortLevel(第28.3.1章)。

25.4 KPI 與稽核

指標說明資料來源
採用率活躍使用 Claude Code 的工程師比例claude_code.session.count、Analytics
Review 通過率AI 協作 PR 一次通過 Review 的比例Git 平台 API+attribution 標註
驗證覆蓋率AI 協作 PR 中附有測試證據的比例PR 模板檢查
事故數AI 協作變更相關的生產事故數事故管理系統
成本效益每位使用者/每個 PR 的平均成本claude_code.cost.usage
政策有效性Hook 阻擋次數、Auto Mode 封鎖次數與誤判回報OTel 事件、/feedback 統計
設定合規檢查工具在 CI 的通過率、Managed 來源正確率CI 紀錄、claude_code.managed_settings_resolved 事件

📌 實務建議:治理設計從第一天就要可被稽核——記錄任何 AI 協作變更當時生效的 Managed 設定版本、Hook 與 MCP 組合(可由 OTel 的 managed_settings_resolved 事件取得),受監管產業(金融、醫療)的稽核需求會用到這份紀錄。

⚠️ 注意:再完整的藍圖如果沒有指定負責人與定期檢視週期,很容易變成束之高閣的文件,務必把「誰負責、多久檢視一次」寫進藍圖本身。

實務案例:某金融業組織從 5 人試點開始,歷時一年走到全組織導入與治理成熟,期間明確指定治理委員會、設定每季檢視週期,並以 OpenTelemetry 保留每次 Session 生效的 Managed 設定摘要供合規稽核使用。

25.5 本章審查與驗證清單

AI 產出項目❌ 常見錯誤✅ 正確做法人工如何驗證
導入藍圖只有架構圖,沒有對應的設定鍵與負責人每個控制面對應具體機制、章節與負責人隨機抽一個控制面,確認能在 Managed 設定中找到
KPI只有採用率與成本加入驗證覆蓋率、政策有效性、設定合規確認每個 KPI 都有可自動取得的資料來源
第三方雲端治理以為 Enterprise 後台的模型治理也涵蓋 Bedrock第三方供應商改用 Managed 設定在 Bedrock Session 中 /model 檢查可選模型

第 26 章 Agent 進階協作模式

本章目標:從企業場景的角度選擇與治理四種平行化機制(雲端長期協作的 Projects 見第9.11章),並學會 Agent Teams、Dynamic Workflows 與 /batch 的實務設計與成本控制。讀完後,你應該能為一個大型任務選出最輕量、最可審查的編排方式。

26.1 四種平行化機制總覽

第9章已分別介紹 Subagent、Agent View、Agent Teams、Dynamic Workflows 的基礎概念,本章從「企業場景下該選哪一種」的角度做總覽(v3.0 註:官方新增的第五種方式 Projects 目前只開放 Pro/Max/Ultra,且雲端 Thread 不套用企業 Managed 設定,因此本章的企業選型仍以這四種為主,Projects 的定位見第9.11章):

quadrantChart
    title 平行化機制選擇:協調需求 x 規模
    x-axis 小規模 --> 大規模
    y-axis 不需互相協調 --> 需要互相協調
    "Subagent": [0.2, 0.2]
    "Agent View": [0.5, 0.15]
    "Agent Teams": [0.4, 0.85]
    "Dynamic Workflows": [0.9, 0.4]
機制誰決定下一步中間結果放哪裡可重複的是什麼規模中斷時治理重點
SubagentClaude,逐回合Claude 的 ContextSubagent 定義每回合幾個委派任務重新開始該回合工具權限最小化(第9-10章)
Agent View你,自行派發各 Session 自己—數個獨立 Session各自繼續Supervisor 管控(disableAgentView、processWrapper)
Agent TeamsLead Agent,逐回合共用任務清單團隊定義少數長時間執行的隊友隊友繼續執行實驗性功能的試行範圍(26.2)
Dynamic Workflows腳本腳本變數編排邏輯本身每次數十到數百個 Agent同一 Session 可續跑腳本審查與規模上限(26.3)

選擇時可依三個問題快速判斷:誰負責協調?(Claude 在單一對話內→Subagent;你自己分派並事後查看→Agent View;Claude 規劃並監督一組工作者→Agent Teams;腳本掌握流程→Dynamic Workflows)工作者之間需要互相溝通嗎?(只有 Agent Teams 的隊友能直接互傳訊息;你自己各別啟動的 Session 要互通,用第9.10章的跨 Session 訊息傳遞)是否會動到同一批檔案?(會的話用 Worktree 隔離;Agent Teams 不會自動隔離,需要人工切分範圍)

26.2 Agent Teams 實務

Agent Teams 讓多個 Session 共享同一份任務清單,並透過訊息互相通知進度。由於是實驗性功能、預設關閉(CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 才啟用),企業導入時建議:

  • 先在非生產、低風險的內部專案試行,優先從「研究與審查」類任務開始(例如多個隊友各自從不同角度審查同一個 PR、以互相競爭的假設排查問題),而不是直接平行寫碼。
  • 明確指定誰可以啟用此功能(建議僅平台團隊或資深工程師),而非預設對全體開放。
  • 隊友繼承 Lead 的權限模式(dontAsk 除外);Lead 若以 --dangerously-skip-permissions 啟動,所有隊友也會如此。隊友的權限詢問會出現在 Lead Session。
  • 以 Hook 建立品質關卡:TeammateIdle(隊友即將閒置時以 exit 2 要求繼續)、TaskCreated、TaskCompleted(以 exit 2 阻止建立或完成並回饋理由)。
  • 用 --teammate-mode 決定隊友顯示方式(in-process 預設、tmux/iterm2 分割視窗;VS Code 整合終端機、Windows Terminal、Ghostty 不支援分割模式)。
  • 隊友的工作範圍應手動切分、避免同時觸及相同檔案。

已知限制:in-process 隊友無法透過 /resume、/rewind 還原;任務狀態可能延遲更新;一個 Session 只有一個團隊;隊友不能再建立隊友;Lead 固定不可轉移。

⚠️ 注意:舊版用來建立/刪除團隊的 TeamCreate/TeamDelete 工具已移除——啟用功能後每個 Session 都有一個隱含的團隊,直接請 Claude 產生隊友即可;若團隊文件或腳本中仍引用這兩個工具名稱,應更新。

26.3 Dynamic Workflows 實務

Dynamic Workflows 是由 Claude 撰寫、由執行環境在背景執行的 JavaScript 編排腳本,腳本掌握迴圈、分支與中間結果,取代讓模型逐回合即興決定派生順序。它的價值不只是「更多 Agent」,而是能把品質模式寫進程式:例如讓獨立的 Agent 互相對抗式審查彼此的發現後才回報、從多個角度起草計畫再比較。典型場景包括全庫規模的審查、數百檔案的遷移、需要來源交叉核對的研究。

ultracode: 稽核 src/routes/ 底下每一個 API 端點是否缺少授權檢查,
每個發現都由另一個 Agent 嘗試推翻,只回報推翻失敗的項目

執行環境的限制(不可調整的部分是安全設計):

限制說明
執行中不能要求使用者輸入只有 Agent 的權限詢問與用量上限等待會暫停;需要人工簽核的階段請拆成多個 Workflow
腳本本身不能存取檔案系統或 Shell讀寫與執行指令都由 Agent 進行,腳本只負責協調
不能載入模組含 import() 的腳本在執行前就失敗
同時執行的 Agent預設最多 16 個(CPU 較少時更少),CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTS 可設 1~256(v2.1.269+)
單一 parallel()/pipeline()最多 4,096 項
每次執行的 Agent 總數1,000 個(防止失控迴圈)

治理上,編排腳本本質上等同於「會自動消耗大量 Token 與工具呼叫的程式」,應該:

  • 存成指令的 Workflow(/workflows 中按 s,存到 .claude/workflows/)提交版控、走 PR 審查流程,與一般程式碼同等級對待
  • 以 workflowSizeGuideline(small<5、medium<10、large<50 個 Agent,unrestricted 不限)建議規模;這是給 Claude 的建議而非硬上限,Pro 方案在 v2.1.271+ 預設為 small
  • 先在小範圍(一個目錄、一個窄問題)試跑估算成本;排程超過 25 個 Agent 或預估超過 150 萬 Token 時,進度列會出現 Large workflow 警告
  • Workflow 中每個 Agent 的工具呼叫仍經過相同的權限檢查與 Sandbox;需要停用時,設定 disableWorkflows: true(Managed 設定可對全組織停用)
  • CLAUDE_CODE_WORKFLOW_SUBAGENT_MODEL 可讓 Workflow 的所有 Agent 使用同一個模型(v2.1.296+),控制成本

26.4 /batch:大規模 Worktree 隔離批次處理

/batch 是隨附的 Skill:先研究程式碼庫,把一個大任務拆成 5 至 30 個獨立單元,每個單元在獨立的 Worktree(第9.8章)中執行,完成後各自開出 PR,適合「同一種修改要套用到大量檔案/模組」的情境。

/batch 將 services/ 下所有模組的 javax.* import 替換為對應的 jakarta.*,每個模組各開一個 PR

📌 實務建議:/batch 適合「修改模式高度重複、模組之間互相獨立」的任務;若子任務之間有相依順序(必須先改 A 才能改 B),應改用 Dynamic Workflows 明確控制執行順序。

⚠️ 注意:/batch 會一次性開出大量 PR,務必事先與團隊溝通 Review 容量,避免造成 PR 隊列堵塞。

實務案例:某團隊用 /batch 將一個跨 20 個模組的命名空間遷移任務拆成 20 個獨立 Worktree 子任務,各自開 PR 後再依模組重要性排序逐一 Review,比單一 Session 序列處理的總時程縮短超過一半。

26.5 Dynamic Workflows 的開關、成本與 v3.0 行為變更(v3.0 新增)

控制方式範圍說明
disableWorkflows(Managed)全組織關閉 Dynamic Workflows
enableWorkflows個人預設除 Pro 方案外皆開啟;Pro 方案預設關閉。/config 的 Dynamic workflows 會寫入此鍵
CLAUDE_CODE_DISABLE_WORKFLOWS單次 Session優先於 enableWorkflows: true
workflowKeywordTriggerEnabled: false個人讓 ultracode 這個字可以正常輸入而不觸發 Workflow
subagentPromptCacheTtl任何設定檔Workflow 中的工作者屬於「主對話外」的請求,長時間 Workflow 可設 "1h"

v3.0 期間的行為變更:

  • v2.1.323:應用程式標記為「非使用者輸入」的提示,不再當成你的請求傳給 Workflow 的工作者(避免外部內容被當成指令)
  • v2.1.321:你停止或暫停執行中的 Workflow 時,Claude 會被告知,不再誤報 Workflow 仍在執行
  • v2.1.309:/claude-api Skill 建立的 Managed Agents 子 Agent 團隊改為預設開啟 Dynamic Workflows
{
  "disableWorkflows": true
}

上例放在 Managed 設定即可對全組織關閉;在試點期,建議改為「預設關閉、由試點成員在個人設定以 enableWorkflows: true 開啟」,並要求每次執行都以 /workflows 截圖記錄階段與工作者數量,作為成本評估的依據。

26.6 本章審查與驗證清單

AI 產出項目❌ 常見錯誤✅ 正確做法人工如何驗證
機制選擇為了「看起來先進」直接用 Agent Teams 或 Workflow從 Subagent 開始,只有在需要協調或規模超出時才升級設計文件是否說明為何較輕量的機制不夠
Workflow 啟動方式claude --bg -p "依 Workflow 腳本..."(--bg 不能配 -p,-p 的提示也不會觸發 ultracode)在互動 Session 輸入含 ultracode 的提示,或執行已存的 Workflow 指令/workflows 確認有執行紀錄
Workflow 腳本審查存檔的腳本未經審查就給全團隊用腳本放 .claude/workflows/ 並走 PR檢查 PR 紀錄
Agent Teams 權限Lead 以 bypass 模式啟動,所有隊友跟著繞過權限Lead 以受控模式啟動,必要時個別調整隊友檢查啟動指令與隊友的權限模式
/batch 的適用性有相依順序的修改用 /batch 平行處理有順序時改用 Workflow檢查各 PR 是否能獨立建置與測試
Workflow 開關以為在專案設定寫 enableWorkflows: false 就能對全組織關閉全組織關閉用 Managed 的 disableWorkflows;enableWorkflows 是個人偏好以一般帳號在該 repo 輸入 ultracode 測試是否觸發;/config 看 Dynamic workflows 列

第 27 章 Agent Skills 與 Plugin 生態

本章目標:分辨 CLAUDE.md、Skill、Subagent、Plugin、Mod 的定位,寫出正確的 SKILL.md,並建立 Plugin 與 Marketplace 的企業治理與品質評估流程。讀完後,你應該能審查一個 AI 產生的 Skill 或 Plugin,判斷欄位是否正確、權限是否最小、是否值得納入團隊。

27.1 Skills 與 CLAUDE.md/Subagent 的定位差異

機制載入時機適合內容
CLAUDE.md(第11章)每次 Session 啟動都載入少量、高頻率需要的事實性資訊(技術棧、建置指令、禁止事項)
Skill(SKILL.md)依需求才載入(被呼叫,或 Claude 依描述判斷相關時);Session 開始時只載入名稱與描述多步驟程序、檢查清單、長篇參考資料——CLAUDE.md 中「長成程序而非事實」的段落應該搬到 Skill
Subagent(第9-10章)被委派時才在獨立 Context 中執行需要獨立工具權限/獨立 Context 隔離的任務
Plugin啟用後提供其中的 Skill、Subagent、Hook、MCP Server、LSP 等元件可分發、可版本化的一組客製化
Mod(v2.1.287+)以 JavaScript/TypeScript 事件處理器在 Claude Code 內部執行的 Plugin繪製介面面板、改寫 Claude Code 自身介面、介入工具呼叫或請求

判斷原則:如果你發現自己在 CLAUDE.md 裡寫了一段「遇到 X 情況時依序執行 1、2、3 步驟」,這通常代表它該是一個 Skill,而不是繼續留在每次都載入的 CLAUDE.md 中。

27.2 SKILL.md 格式與存放層級

每個 Skill 是一個目錄,SKILL.md 為必要的進入點:

release-check/
├── SKILL.md           # 主要指令(必要)
├── checklist.md       # 給 Claude 參考的附加檔案
└── scripts/
    └── verify.sh      # Claude 可執行的腳本(以 ${CLAUDE_SKILL_DIR}/scripts/verify.sh 引用)

一份發版前檢查的 Skill(已通過第30章 check_agents.py skill 驗證):

---
name: release-check
description: 發版前檢查清單:確認版本號、CHANGELOG、測試與未提交變更。使用者說「準備發版」「release check」時使用。
when_to_use: 建立 release 分支或打 tag 之前
argument-hint: "[version]"
disable-model-invocation: true
allowed-tools: Bash(git status *) Bash(git log *) Bash(npm test *)
context: fork
---

## 目前狀態

- 未提交變更:!`git status --short`
- 最近 10 筆提交:!`git log --oneline -10`

## 檢查步驟

目標版本:$ARGUMENTS

1. 確認 `package.json` 的 version 等於目標版本;不一致就停止並回報。
2. 確認 `CHANGELOG.md` 最上方有該版本的段落,且每一條都對應到上方的提交。
3. 執行 `npm test`,任何失敗都要原文回報,不可自行修改測試。
4. 輸出一張表格:檢查項目/結果(通過、失敗)/證據(指令輸出或檔案行號)。

這份 Skill 示範了幾個重要設計:disable-model-invocation: true 讓它只能由人以 /release-check 1.4.0 觸發,避免模型誤判情境自動執行;allowed-tools 預先核准它需要的唯讀指令(只在呼叫的那一回合有效);context: fork 讓它在獨立的 Subagent 中執行,不佔用主對話 Context;!`git status --short` 會在 Skill 載入時先執行並把輸出注入內容。

常用 frontmatter 欄位(完整清單見官方 Skills 文件;拼錯的欄位同樣會被靜默忽略):

欄位說明
name/ 選單中的指令名稱,預設為目錄名稱
description做什麼、何時用;Claude 依此判斷何時套用。與 when_to_use 合計超過 1,536 字元會在清單中被截斷,重點放前面
when_to_use補充觸發情境或範例請求
argument-hint/arguments自動完成的參數提示;具名參數可用 $name 取代
disable-model-invocationtrue:只能由使用者以 /name 呼叫,也不會被預載進 Subagent
user-invocablefalse:從 / 選單隱藏,只給 Claude 使用(背景知識類)
allowed-tools/disallowed-tools呼叫的那一回合免詢問的工具/移除的工具
model/effort本回合使用的模型與推理強度
context/agent/backgroundcontext: fork 在 Subagent 中執行、agent 指定 Subagent 類型、background: false 等結果回來才繼續
paths只在處理符合 glob 的檔案時自動載入
hooksSkill 被呼叫後註冊、持續到 Session 結束的 Hook
shell!`cmd` 使用 bash(預設)或 powershell

字串替換:$ARGUMENTS、$0/$1、${CLAUDE_SKILL_DIR}、${CLAUDE_PROJECT_DIR}、${CLAUDE_SESSION_ID}、${CLAUDE_EFFORT},Plugin 中另有 ${CLAUDE_PLUGIN_ROOT}、${CLAUDE_PLUGIN_DATA}。

存放層級與同名時的優先序(企業 > 個人 > 專案,皆會取代同名的隨附 Skill,但不取代其別名):

層級路徑適用範圍
Enterprise透過 Managed 設定部署全組織
Personal~/.claude/skills/<name>/SKILL.md個人所有專案(雲端 Session 與 Routines 不會讀取)
Project.claude/skills/<name>/SKILL.md本專案(支援巢狀目錄,Monorepo 子套件可有自己的 Skill)
Plugin<plugin>/skills/<name>/SKILL.md以 plugin名:skill名 命名空間,不會與其他層級衝突
claude.ai 同步在 claude.ai 帳號啟用的 Skill(v2.1.275+ 同步到終端機)與其他同名時只能用完整名稱呼叫;可用 syncClaudeAiSkills: false 關閉

舊版 .claude/commands/<name>.md 自訂指令仍可正常運作,但若有同名 Skill,Skill 優先;建議新建內容統一改用 Skill 格式。新增或修改 Skill 後可執行 /reload-skills 立即生效,/skills 可依 Token 數排序檢視。

27.3 隨附 Skills(Bundled Skills)

每個 Session 預設都帶有一組隨附 Skill(以提示驅動 Claude 完成工作,與執行固定邏輯的內建指令不同),可用 disableBundledSkills 整體關閉:

Skill用途
/code-review [level|ultra]審查 diff 的正確性錯誤;ultra 觸發雲端多 Agent 審查(第17.4章)
/simplify以四個平行審查 Agent 找出可重用、可簡化的地方並套用
/batch大規模 Worktree 隔離批次處理(26.4)
/debug開啟除錯日誌並閱讀日誌協助排查
/doctor(別名 /checkup)安裝與設定健檢並提出修正;prompt-audit 檢查過時的提示寫法
/loop依固定或自我調節的間隔重複執行提示
/run、/verify實際建置並執行應用程式觀察結果,而非只依賴測試
/run-skill-generator教會 /run、/verify 如何從乾淨環境建置與啟動你的專案
/fewer-permission-prompts掃描近期 Transcript 中常見的唯讀指令,產生建議的允許清單寫入專案設定
/update-config以自然語言描述設定變更,由 Claude 編輯對應的設定檔
/claude-apiClaude API/Anthropic SDK 專案的參考與遷移
/design、/slides、/datavizUI 設計稿、簡報、圖表設計指引
/workflow-authoring撰寫 Dynamic Workflow 腳本的參考(僅在 Workflow 啟用時可用)

另外 /deep-research 是隨附的 Workflow(第26.3章),而非 Skill。

27.4 Plugins 生態與 Marketplace 治理

Plugin 是比 Skill 更大的封裝單位,可一次性打包 Skills、Subagent、Hooks、MCP Server、LSP 設定,透過 Marketplace 分發,也可從 .zip 檔案或 URL 載入。安裝時選擇範圍:User(你的所有專案)、Project(寫入提交版控的 .claude/settings.json,協作者仍需各自安裝)、Local(只有你、只在此 repo)。

claude plugin install code-review@claude-plugins-official     # 從官方 Marketplace 安裝
claude plugin install security-scan --marketplace acme-corp/claude-plugins   # 先加入 Marketplace 再安裝(v2.1.292+)
claude plugin details security-scan                             # 檢視元件清單與預估 Token 成本
claude --plugin-url https://plugins.corp.example/security-guidance.zip      # 僅本次 Session 載入

Marketplace 依名稱分為三級:Official(如 claude-plugins-official)、Community(如 claude-community),兩者都只接受來自 github.com/anthropics/ 的來源;其餘一律是 Third-party(包含你公司自己的 Marketplace)。無論哪一級,安裝的 Plugin 都能以你的使用者權限執行程式碼,請先依官方「Plugin security」指引審查。

企業治理鍵:

設定鍵用途
strictKnownMarketplaces允許清單:只能新增與安裝清單中的 Marketplace({ "source": "github", "repo": "org/repo" } 等格式)
blockedMarketplaces封鎖清單
extraKnownMarketplaces/enabledPlugins預先註冊 Marketplace、預先啟用(強制安裝)Plugin
pluginSuggestionMarketplaces限定 Claude 可主動建議安裝的 Plugin 來源
strictPluginOnlyCustomization鎖定 Skill、Agent、Hook、MCP 只能來自 Plugin/Managed,封鎖使用者/專案層級自建內容
disableSideloadFlags拒絕 --plugin-dir/--plugin-url 等單次側載旗標
disableCommandPluginSources封鎖 command 型 Plugin 來源
syncClaudeAiPlugins是否同步 claude.ai 帳號啟用的 Plugin
pluginConfigs → cc-plugin-sec-default@builtin 的 allowManagedModsOnly只允許組織自己的 Mods 執行(只從 Managed 設定讀取)
{
  "strictKnownMarketplaces": [
    { "source": "github", "repo": "anthropics/claude-plugins-official" },
    { "source": "github", "repo": "acme-corp/claude-plugins" }
  ],
  "disableSideloadFlags": true,
  "pluginConfigs": {
    "cc-plugin-sec-default@builtin": {
      "options": { "allowManagedModsOnly": true }
    }
  }
}

Mods(v2.1.287+)是在 Claude Code 內部執行 JavaScript/TypeScript 事件處理器的 Plugin,能繪製介面、改寫 Claude Code 自身介面、在權限檢查前介入工具呼叫,能力明顯大於一般 Hook 與 Skill。企業若尚未建立 Mods 的審查流程,建議先以 allowManagedModsOnly 只允許組織自己部署的 Mods。

27.5 團隊標準化建議

  • 把團隊共用 Skill 放進 .claude/skills/ 並提交版控,與第10.6章共用子 Agent 的做法一致——新人 clone 專案即自動取得。
  • 維護一份「已核准 Plugin Marketplace」清單,以 strictKnownMarketplaces 強制,新增前走第21章的治理審查流程。
  • Skill/Plugin 的 PR 在 CI 中執行 claude plugin validate <path> 與第30章的 check_agents.py skill。
  • Skill 與第23章 Prompt Library 的差異:Prompt Library 是「貼上去用」的範本文字,Skill 是「系統自動依描述載入或用 / 呼叫」的可執行程序,兩者可並存。
  • 定期用 /skill-doctor 找出很少用、卻佔用 Context 的 Skill 並停用。

📌 實務建議:CLAUDE.md 中只放「每次都要知道的事實」,把已經寫成多步驟程序的內容搬移到 Skill,可同時降低每次 Session 的基礎 Token 成本,並讓程序內容更容易被重用與版本管理。

⚠️ 注意:Plugin 從第三方 Marketplace 安裝等同於引入一個新的信任邊界(與第13章 MCP Server 的風險定位類似),務必走核准流程,不應讓任意工程師自行安裝未審查的 Plugin。

實務案例:某團隊將「部署前檢查清單」由原本貼在 CLAUDE.md 中的一大段文字,改寫成 release-check Skill(context: fork + disable-model-invocation: true),避免該清單佔用每次 Session 的基礎 Context,且只能由工程師明確輸入 /release-check 觸發,不會被模型誤判情境而自動執行。

27.6 以 claude plugin eval 評估 Plugin 品質

Plugin(或 Skill)到底有沒有讓 Claude 表現更好?v2.1.269 起可用 claude plugin eval 客觀量化:

cd my-plugin/
claude plugin eval init      # Claude 詢問「好的結果長什麼樣子」,草擬測試案例與評分器並試跑一次
claude plugin eval .         # 執行整套評估,終端機印出摘要表,evals/results/ 下產生 report.html

評估方式:每個案例預設執行 3 次,以評分器(可為確定性檢查或由模型評判)計分;同時在不載入 Plugin 的情況下重跑相同案例作為基準,報告會列出 WITH、W/OUT 兩個分數與差距 Δ——Δ 才代表 Plugin 的實際貢獻。注意每次執行都是真實的模型呼叫、會計入用量;在不受信任的 Plugin 目錄第一次執行會要求確認(CI 中以 --trust-plugin 回答),而且「評估通過」不等於安全審查通過。

27.7 Plugin 版本相容宣告、驗證與組織 Plugin(v3.0 新增)

engines["claude-code"](v2.1.323):Plugin 可在 plugin.json 宣告支援的 Claude Code 版本範圍(semver range)。超出範圍的版本不會安裝、更新或載入該 Plugin,安裝與更新時會挑選符合範圍的最新 Plugin 版本。企業內部 Marketplace 的 Plugin 若依賴 v2.1.323 以後的行為(例如 Sandbox 新語意),應宣告下限:

{
  "name": "acme-release-tools",
  "version": "1.4.0",
  "description": "產生版本說明與檢查發布清單的團隊 Skill",
  "author": { "name": "Acme Platform Team" },
  "engines": { "claude-code": ">=2.1.325" }
}

v3.0 實測 claude plugin validate(v2.1.327):

輸入結果
上方的 plugin.json + 一個 Skill✔ Validation passed,結束碼 0;另列出 Plugin Directory 上架所需但不影響結果的項目(缺 README、LICENSE、icon)
"engines": { "claude-code": "not-a-range" }✘ 錯誤「Must be a version range such as “>=2.1.0”」,結束碼 1
plugin.json 中寫 "agent": "reviewer"警告「Unknown field ‘agent’ — did you mean ‘agents’?」,該欄位不生效

claude plugin validate --strict 會把警告(含 v2.1.323 新增的 TypeScript Hooks 型別檢查結果)視為失敗;--profile directory 會把 Plugin Directory 拒收的問題視為失敗。內部 Marketplace 的 CI 建議至少使用 --strict。

其他 Plugin 治理變更:

變更版本
pluginDigests 棄用並忽略;Managed 設定宣告、啟用並列在 prependPlugins/appendPlugins 的遠端 Marketplace Plugin 視為組織所有v2.1.325
git submodule 不在 repo 記錄的 commit 上時,Marketplace 與 Plugin 安裝失敗v2.1.323
pluginTrustMessage(Managed)在 Plugin 信任警告中加入組織說明—
--plugin-dir 載入的 Plugin,其中的 .claude/skills 不再從上層目錄啟動的 Session 載入v2.1.325
~/.claude/plugins 內的 .claude/skills 不再於 Claude 處理該處檔案時載入v2.1.321
/plugin 與 claude plugin list 會指出被忽略的錯誤欄位(如格式錯的 author)v2.1.326
claude plugin install --json 的結果含 unsetOptionCount(尚未設定的 userConfig 數)v2.1.323
/skill-doctor 檢視每個 Skill 的觸發與內容問題v2.0 已收錄(第27章)
# 內部 Marketplace 的 Plugin CI:任何警告都視為失敗
claude plugin validate --strict ./plugins/acme-release-tools

27.8 本章審查與驗證清單

AI 產出項目❌ 常見錯誤✅ 正確做法人工如何驗證
SKILL.md frontmatterdisable_model_invocation、allowedTools 等拼法(被靜默忽略)依官方欄位名稱(連字號形式)python check_agents.py skill SKILL.md;claude plugin validate
高風險 Skill(部署、發版、資料異動)允許模型自動觸發加上 disable-model-invocation: true在對話中描述相關情境,確認 Claude 不會自動呼叫
allowed-tools給予 Bash 全部權限只列出需要的指令樣式,如 Bash(git status *)Code Review 比對 Skill 步驟與授權
Skill 描述冗長、重點在後面,被截斷關鍵用途放前面,合計不超過 1,536 字元/skills 檢視顯示的描述
Plugin 引入從未知 Marketplace 直接安裝以 strictKnownMarketplaces 限定,安裝前審查claude plugin details <name> 檢視元件與權限
Plugin 效益只憑感覺判斷 Plugin 有用以 claude plugin eval 看 Δ檢查報告中的 WITH/W/OUT 分數
Plugin 版本相容Plugin 依賴新版行為卻沒宣告版本範圍,舊版用戶端載入後行為異常在 plugin.json 宣告 engines["claude-code"] 下限claude plugin validate 驗證範圍格式;以低於下限的版本安裝,確認被拒
Plugin CI只執行 claude plugin validate,把警告當成通過內部 Marketplace 使用 --strict;要上架 Plugin Directory 再加 --profile directory故意放一個未知欄位,確認 CI 失敗

第 28 章 企業治理進階

本章目標:從平台團隊的角度,把 Managed 設定交付、Sandbox、網路與 Gateway、資料保存與合規、成本可視化整合成可運作的治理體系。讀完後,你應該能為受監管產業寫出一份「控制措施 → 設定 → 驗證方式」對照清單。

28.1 Managed Settings 完整交付架構

第5.5章已介紹交付機制與優先序,本節以完整架構圖彙整企業導入時應規劃的治理層:

graph TB
    subgraph 治理來源
        Remote["Server-managed<br/>(claude.ai 後台 / Claude apps gateway)"]
        Policy["平台原生政策<br/>(macOS plist / Windows HKLM)"]
        FileBased["檔案型 managed-settings.json<br/>+ managed-settings.d/"]
        HKCU["Windows HKCU<br/>(免提權,非 admin 來源)"]
    end
    Remote --> Combine["合併規則<br/>first-wins 預設 / merge 選用<br/>+ 跨來源鎖定鍵 + policyHelper"]
    Policy --> Combine
    FileBased --> Combine
    HKCU --> Combine
    Combine --> Effective["生效政策"]
    Effective --> Status["/status 的 Setting sources 與 Skipped sources"]

企業導入時建議由平台團隊統一決定交付方式:claude.ai 組織的使用者優先使用 Server-managed(一處修改、每小時同步、不需逐機部署),並以 MDM/檔案型交付作為備援,涵蓋走第三方雲端或關閉遙測的機器;多個團隊共同維護政策時,用 managed-settings.d/ 片段檔分工。若同時部署多個來源而希望合併,需明確設定 managedSourcesBehavior: "merge"(第5.5章)。

Corporate Launcher:企業若不想整體關閉 Agent View(disableAgentView)卻仍需要對背景 Agent 的執行程序加上企業自有的治理包裝,可改用 processWrapper 設定鍵,為 Supervisor、其 Worker 與其他受涵蓋的背景程序統一加上企業要求的啟動包裝程式。

Desktop 的 WSL Session:Claude Desktop 在偵測到組織管理的裝置(例如存在 C:\Program Files\ClaudeCode\managed-settings.json)時預設關閉 WSL Session;要開放時,在 HKLM\SOFTWARE\Policies\Claude 建立 disableWslSessions 並設為 false(REG_SZ)或 0(REG_DWORD),並部署 wslInheritsWindowsSettings: true 讓 WSL Session 繼承同一套政策。

Claude Code on the Web 有獨立的組織管理介面:管理後台的「Cloud environments」頁面可讓 Owner 建立組織共用的雲端環境(網路存取層級、環境變數、啟動腳本),預設環境在 claude.ai/admin-settings/claude-code 另外設定;雲端 Session 只會收到 Server-managed 設定,不會讀取本機設定檔中的 Plugin。

28.2 Sandboxing 深度

第19.4章已從 SSDLC 角度介紹 Sandbox,企業層級規劃時應額外考量:

  • 強制而非建議:在 Managed 設定同時設 sandbox.enabled: true 與 sandbox.failIfUnavailable: true,平台不支援或缺少相依套件時拒絕啟動,而非無聲降級;原生 Windows 不支援 Sandbox,若政策要求 Sandbox,Windows 使用者必須改在 WSL2 中執行。
  • 鎖定允許清單:sandbox.network.allowManagedDomainsOnly: true、sandbox.filesystem.allowManagedReadPathsOnly: true 讓只有 Managed 來源的網域與讀取路徑生效,使用者與專案無法自行放寬(這兩個鎖定鍵會從每一個 admin 來源讀取)。
  • 分組管理網域白名單:依專案類型(前端/後端/資料工程)分組維護 sandbox.network.allowedDomains,而非全公司一份清單;MCP Server 與 Plugin 呼叫的外部網域也要納入規劃。
  • 憑證保護:以 sandbox.credentials 拒絕讀取 ~/.aws/credentials、~/.ssh 等檔案並移除敏感環境變數;需要讓工具在 Sandbox 內使用憑證而不暴露明文時,可評估遮罩(mask)與 AWS 請求重新簽章功能。
  • 跨 Session 訊息:若 Bash 指令需要在 Sandbox 內連到本機通訊端(例如腳本回報訊息給自己的 Session),須設定 sandbox.network.allowUnixSockets 或 allowAllUnixSockets。
  • Sandbox 之外的程序:Hook、本機 MCP Server、LSP 等仍以完整權限執行;需要單一邊界時,把整個 Claude Code 放進容器或 VM(官方提供 Dev Container 範本與「Sandbox environments」指引)。

28.3 Network Config 與 LLM Gateway

大型企業常見需求是「所有對外的模型 API 呼叫都要經過集中的網路出口」。Claude Code 支援標準的 Proxy 環境變數與企業 CA:

{
  "env": {
    "HTTPS_PROXY": "http://proxy.corp.example:8080",
    "NODE_EXTRA_CA_CERTS": "/etc/ssl/certs/corp-root-ca.pem",
    "CLAUDE_CODE_CERT_STORE": "bundled,system"
  }
}

⚠️ 注意:Proxy、CA、mTLS 這類網路變數請寫在設定檔的 env(使用者或 Managed 設定),不要只在 Shell 中 export。背景 Agent 的 Supervisor 是所有終端機共用的一個程序,只會繼承第一個啟動它的 Shell 的環境;寫在設定檔中才能保證每個背景 Session 都拿到相同的網路設定。

需要放行的主要網域(完整清單見官方 Network configuration):

網域用途
api.anthropic.comClaude API 請求、feature flag、WebFetch 網域安全檢查(只送出主機名稱)
claude.ai、claude.com、platform.claude.comclaude.ai 與 Console 登入、OAuth Token 交換
downloads.claude.ai原生安裝程式、自動更新、Plugin 執行檔下載
mcp-proxy.anthropic.comclaude.ai 的 MCP Connector
registry.npmjs.org、github.comPlugin 安裝、npx 啟動的 MCP Server、GitHub 上的 Marketplace
raw.githubusercontent.com/release-notes 的 Changelog
Datadog intake 網域營運遙測與錯誤回報(僅直連 Anthropic API 時;可用 DISABLE_TELEMETRY、DISABLE_ERROR_REPORTING 關閉)

LLM Gateway 泛指任何用來統一路由/記錄多個 LLM 供應商呼叫的中介層,可以是企業自建或第三方產品,以 ANTHROPIC_BASE_URL(搭配 ANTHROPIC_AUTH_TOKEN)把 Claude Code 指向它;v2.1.273 起可用 CLAUDE_CODE_GATEWAY_HINT_HEADERS=1 送出請求分類等提示標頭,方便 Gateway 分組統計。Gateway 後的模型 ID 若 Claude Code 不認得,可用 CLAUDE_CODE_MAX_CONTEXT_TOKENS 修正 Context 視窗大小。Claude apps gateway(第4.5.1章)則是 Anthropic 官方、可自架的特定實作,額外提供 Server-managed 設定交付(可依 IdP 群組)、逐請求稽核紀錄與依使用者的花費上限。兩者可以並存,並非互斥。

📌 實務建議:已部署 LLM Gateway 的企業,應將 Claude Code 視為「眾多需要經過 Gateway 的 AI 用戶端之一」,並以 allowedProviders: ["customEndpoint"] 搭配 Managed env 固定 ANTHROPIC_BASE_URL,避免有人改成直連。

28.3.1 組織層級模型治理(Enterprise)

透過 claude.ai 或 Anthropic API 認證的 Enterprise 組織,可在管理後台直接進行伺服器端的模型治理,不需要部署設定檔:組織模型限制(停用特定模型)、組織預設模型(新 Session 起始模型,成員仍可切換,除非開啟啟動時覆寫)、組織 Effort 上限(依角色與模型限制可用的推理強度)。

⚠️ 注意:這套伺服器端治理不涵蓋 Amazon Bedrock、Google Cloud’s Agent Platform、Microsoft Foundry 與 Claude Platform on AWS 上的 Session;在這些供應商上,模型限制須透過 Managed 設定的 availableModels/deniedModels,預設模型以 model 鍵指定,推理強度上限以 maxEffortLevel(由客戶端強制,所有供應商皆有效,第5.6章)。

28.4 Zero Data Retention、稽核與合規

項目現況
商業帳號(Team、Enterprise、API)標準保存30 天
Zero Data Retention(ZDR)僅限符合資格的 Claude for Enterprise 帳號,不包含在標準 Enterprise 方案中、無法自行在後台開啟,需由 Anthropic 業務團隊確認資格後啟用;啟用後提示與回應即時處理、回應後不保存
HIPAA 設定Claude Enterprise 的組織設定,需簽署 BAA;套用後 Claude Code CLI 與 Desktop 的 Code 分頁(local mode)可在不啟用 ZDR 的情況下納入 BAA;VS Code/JetBrains 擴充套件不在 BAA 涵蓋範圍;內建起始權限模式改為 default
本機資料Transcript 以明文存在 ~/.claude/projects/,預設保留 30 天(cleanupPeriodDays),屬於需要納入端點資料保護的本機資料
遙測關閉以 Managed env 設定 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 關閉送往 Anthropic 的非必要流量(WebFetch 網域安全檢查不受影響,可另以 skipWebFetchPreflight 處理)

搭配第25.4章提到的 KPI 與稽核需求,建議:

  • 每次重大 Managed Settings 變更都保留版本紀錄,並以 OpenTelemetry 的 claude_code.managed_settings_resolved 事件記錄每個 Session 實際生效的來源與摘要。
  • 法遵團隊應將「ZDR 或 HIPAA 是否適用」「資料是否離開特定地理區域」「本機 Transcript 保存期限」列為導入前的強制檢查項,而非導入後才補做。
  • OpenTelemetry 的提示與工具內容欄位需依資料分類決定是否遮罩(第20.4章)。

28.5 Cost/Usage/Analytics 企業可視化(平台團隊視角)

第20.4章已介紹 /usage、Analytics Dashboard、OpenTelemetry 三種用量可視化手段,從平台團隊的角度,建議的落地順序是:

  1. 先導入 OpenTelemetry 匯出,併入既有監控告警(最快見效、不需要額外介面),並以 modelPricing 讓金額符合合約價
  2. 建立跨團隊的 Analytics Dashboard 週期性檢視(月度/季度),用於預算規劃而非即時告警
  3. 對異常用量的個案,再用 /usage 細到 Skill/Subagent/Plugin/MCP 層級的拆解去定位根因

⚠️ 注意:用量治理的目的是「及早發現異常」,不是「事後究責」,告警設計上應以「使用模式」(例如無範圍限定的全庫掃描、異常頻繁的排程任務)而非單純的金額門檻為主,否則正常的大型重構任務也會觸發誤報。

實務案例:某受監管產業企業在導入 Claude Code 前,先確認 Enterprise 方案的 HIPAA/ZDR 適用範圍與資料駐留區域符合法遵要求,規劃 Server-managed 為主、MDM 為備援的交付方式,並在 Managed 設定強制 Sandbox(含 failIfUnavailable)與遙測,整個治理架構在稽核審查時一次通過,沒有額外的補件來回。

28.6 v3.0 企業治理補充:代理、Server-managed 設定與 Policy Helper(v3.0 新增)

變更版本企業需要的動作
組織設定與政策請求不再使用只有 ALL_PROXY 的代理v2.1.323設定 HTTPS_PROXY;否則 Managed 設定可能取不到
TLS 檢查型代理後方的憑證自動修復,在只有 ALL_PROXY 時不執行v2.1.319同上,HTTPS_PROXY 指向代理的 http:// URL
ALL_PROXY 為唯一代理時,Plugin 下載改用 CONNECT 通道;不支援 CONNECT 的代理會失敗v2.1.325確認代理支援 CONNECT,或改設 HTTPS_PROXY
Team/Enterprise 登入的 Server-managed settings 不再需要使用者核准即套用;儲存的副本若無法驗證會被拒用v2.1.316發布前務必在測試組織驗證,因為使用者不會再看到核准提示
forceRemoteSettingsRefresh 只設在遠端 Managed 設定時,副本過期後仍會生效v2.1.314(修正)舊版本可能在伺服器不可達時「無政策」啟動,請升級
Managed 設定讀取失敗時,啟動請求不再從組織的代理與 CA 設定切換到使用者自訂的設定v2.1.323(修正)—
Managed 的 policyHelper 不再讀取使用者設定或 --settings 中的環境變數v2.1.323它需要的變數改寫在 Managed 的 env 或啟動它的 shell
Bedrock、Mantle、Vertex、Foundry 從 downloads.claude.ai 的簽章檔載入模型設定v2.1.311封閉網路需放行,或設 CLAUDE_CODE_MODEL_CATALOG=off
CLAUDE_CODE_DISABLE_FEATURE_FLAGS 只停止 feature flag 擷取,不關閉遙測v2.1.319注意部分功能(如 Code Mode)需要 feature flag
Claude apps gateway:attributionProject 命名計費群組、Gateway hint header 加入 Managed 設定 checksumv2.1.327適用於使用 Claude apps gateway 的組織
HIPAA 設定的組織,終端機與 VS Code 預設以 Auto Mode 啟動v2.1.326不允許時以 disableAutoMode 關閉
新供應商 anthropicGoogleCloudv2.1.307+不支援 Server-managed settings,必須用每台機器的 Managed 設定檔(第4.7章)

代理設定的正確寫法(Managed 設定或系統環境變數):

{
  "env": {
    "HTTPS_PROXY": "http://proxy.corp.example:8080",
    "NO_PROXY": "localhost,127.0.0.1,.corp.example"
  }
}

⚠️ 注意:Server-managed settings 自 v2.1.316 起不需使用者核准即生效,這提高了「發布錯誤設定」的影響面。建議比照程式碼變更:設定檔放在版本控制、經 PR Review、先發布到測試組織,並以第32.6章健康檢查腳本在數台機器上驗證後再推到正式組織。

28.7 本章審查與驗證清單

AI 產出項目❌ 常見錯誤✅ 正確做法人工如何驗證
網路設定只在 Shell export HTTPS_PROXY,背景 Agent 連不上寫在使用者或 Managed 設定的 env以 claude --bg 派發任務,確認背景 Session 能連線
放行清單只放行 api.anthropic.com依官方清單放行登入、更新、Plugin 相關網域首次啟動的連線檢查與 claude doctor 無錯誤
ZDR 說明宣稱 Enterprise 方案預設就是 ZDRZDR 需資格審核、由 Anthropic 個別啟用向帳號窗口取得書面確認
Sandbox 強制只在專案設定開 SandboxManaged 設定 enabled + failIfUnavailable + 允許清單鎖定在測試機刪除 bubblewrap 後啟動,應拒絕啟動
模型治理範圍以為後台的組織模型限制也適用 Bedrock第三方供應商改用 Managed 設定在 Bedrock Session 嘗試選擇被禁止的模型
稽核紀錄只靠人工記錄設定變更Managed 設定版控+OTel managed_settings_resolved 事件抽查一個 Session,能回溯當時生效的政策
代理設定只設定 ALL_PROXY,以為所有流量都會走代理組織設定與政策請求需要 HTTPS_PROXY(v2.1.323 起)check_upgrade.py --env 會對只有 ALL_PROXY 的環境標 BREAK;/status 確認 Managed 設定已載入
Server-managed 設定發布直接在正式組織修改,認為使用者會看到核准提示v2.1.316 起不需核准即生效;先在測試組織驗證在測試組織的機器執行 /status 與健康檢查腳本,確認設定內容與來源

第 29 章 Headless 與 CI/CD 自動化

本章目標:在沒有人值守的環境(CI、排程、腳本)中安全地使用 claude -p,並讓 pipeline 依「結構化、可驗證」的結果決定成敗。讀完後,你應該能寫出一個有成本上限、有權限邊界、會正確處理失敗的 CI 審查關卡,並用離線 fixture 證明它的判斷邏輯正確。

29.1 何時使用 Headless 模式

方式適用說明
claude -pShell 腳本、CI job、排程任務與互動 Session 同一個引擎,以旗標控制輸出格式、權限與上限
Claude Code GitHub Action/GitLab CIPR 審查、Issue 分流、@claude 留言觸發官方整合,底層同樣執行 Claude Code
Agent SDK(TypeScript/Python)需要程式化控制工具、權限回呼、串流訊息的應用claude -p 能做的 SDK 都能做,並可自訂工具與權限邏輯
Routines(雲端)依排程、GitHub 事件或 API 在雲端執行不受本機開關機影響,需要 claude.ai 帳號

29.2 claude -p 基本用法與輸出格式

# 純文字(預設)
claude -p "總結這個專案"

# 單一 JSON 結果:result、session_id、is_error、subtype、total_cost_usd 等欄位
claude -p "總結這個專案" --output-format json | jq -r '.result'

# 結構化輸出:結果放在 structured_output,符合你給的 JSON Schema
claude -p "列出 auth.py 的主要函式名稱" --output-format json \
  --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}' \
  | jq '.structured_output'

# 串流:每行一個 JSON 事件,最後一行是 result
claude -p "解釋遞迴" --output-format stream-json --verbose --include-partial-messages

json 結果的關鍵欄位(Agent SDK 的 result message 型別):

欄位意義
type/subtyperesult;success 或錯誤類型 error_max_turns、error_max_budget_usd、error_during_execution、error_max_structured_output_retries
is_error是否以錯誤結束——CI 一定要檢查這個欄位,不能只看結束碼或 result 是否有字
result最終文字回覆
structured_output使用 --json-schema 時的結構化結果
total_cost_usd客戶端依牌價估算的成本
num_turns、session_id輪數、Session ID(可用 -r 接續)

stream-json 的第一個事件 system/init 會列出 mcp_servers、mcp_server_errors、plugins、plugin_errors:設定錯誤的 MCP Server 或 Plugin 會被略過、run 仍正常結束,CI 應主動檢查這些欄位,有錯誤就讓 job 失敗。

29.3 安全的非互動執行

非互動模式有幾個與互動模式不同、容易被忽略的行為:

行為影響對策
不顯示工作區信任對話框,直接視為信任repo 中 .claude/settings.json 的 Hook、MCP 設定會照常執行只在信任的 repo 執行;陌生 repo 先審查 .claude/,或加 --bare/--settings '{"disableAllHooks": true}'
設定檔驗證失敗時靜默忽略拼錯的 deny 規則、無效的 Hook 不會報錯,防護默默失效CI 先執行第30章的檢查工具,再執行 claude doctor 看有無被略過的設定
沒有人回答權限詢問預設送給 SDK host 或 --permission-prompt-tool,沒有 host 時拒絕明確加上 --permission-prompts none(v2.1.259+)
內建起始模式為 default(會抓 feature flag 的 Session)第三方供應商或關閉遙測時可能是 auto一律以 --permission-mode 明確指定
ultracode 關鍵字不會觸發 Workflow-p 傳入的提示不算「你親自輸入」需要 Workflow 時改以互動方式或 Agent SDK 標記人類輸入

建議的「最小權限 CI 呼叫」組合:

claude -p "<任務>" \
  --output-format json \
  --permission-mode plan \
  --permission-prompts none \
  --allowedTools "Bash(git diff *)" "Bash(git log *)" Read Grep Glob \
  --max-turns 15 \
  --max-budget-usd 2.00
  • 唯讀審查用 plan 模式,需要修改檔案的任務才用 acceptEdits,並只在隔離的容器中考慮 bypassPermissions。
  • --allowedTools 只列出必要工具;需要完全移除某工具時用 --disallowedTools(例如 "mcp__*")。
  • 共用機器上的評估腳本用 --restricted:移除執行指令的工具、不讀使用者與專案設定、拒絕 bypassPermissions。
  • 大量呼叫追求速度時用 --bare(不探索 Hook、Skill、Plugin、MCP、CLAUDE.md)。
  • 多使用者共用的腳本加 --exclude-dynamic-system-prompt-sections,提高 Prompt Cache 共用率。

29.4 CI 審查關卡:結構化結果與離線驗證

以下腳本以 --json-schema 要求 Claude 回傳固定結構的審查結果,再依結果決定 pipeline 成敗:結束碼 0 通過、1 有 high 等級問題、2 Claude 執行失敗或輸出不符格式。腳本可接受一個既有的輸出檔作為參數,讓判斷邏輯可以在不呼叫 API 的情況下被測試:

#!/usr/bin/env bash
# CI 審查關卡:以 claude -p 取得結構化審查結果,依結果決定 pipeline 成敗。
# 用法:
#   bash claude-gate.sh                 # 實際呼叫 claude -p(CI 中使用)
#   bash claude-gate.sh result.json     # 以既有輸出檔重跑判斷邏輯(離線測試用)
# 結束碼:0 = 通過;1 = 有 high 等級問題;2 = Claude 執行失敗或輸出格式不符
set -u
MAX_COST_USD="${MAX_COST_USD:-2.00}"

SCHEMA='{"type":"object","properties":{"verdict":{"type":"string","enum":["pass","fail"]},"findings":{"type":"array","items":{"type":"object","properties":{"severity":{"type":"string","enum":["high","medium","low"]},"file":{"type":"string"},"line":{"type":"integer"},"summary":{"type":"string"}},"required":["severity","file","summary"]}}},"required":["verdict","findings"]}'

if [ $# -ge 1 ]; then
  out="$(cat "$1")"
else
  out="$(claude -p "審查目前分支相對於 origin/main 的 diff,只回報有證據的問題" \
    --output-format json \
    --json-schema "$SCHEMA" \
    --permission-mode plan \
    --permission-prompts none \
    --allowedTools "Bash(git diff *)" "Bash(git log *)" Read Grep Glob \
    --max-turns 15 \
    --max-budget-usd "$MAX_COST_USD")" || { echo "claude 執行失敗" >&2; exit 2; }
fi

# 1. 基本健全性:必須是 JSON,且不是錯誤結果
if ! printf '%s' "$out" | jq -e . >/dev/null 2>&1; then
  echo "輸出不是合法 JSON" >&2; exit 2
fi
if [ "$(printf '%s' "$out" | jq -r '.is_error // false')" = "true" ]; then
  echo "Claude 回報錯誤:$(printf '%s' "$out" | jq -r '.subtype // "unknown"')" >&2; exit 2
fi

# 2. 結構化結果必須存在(--json-schema 的輸出在 structured_output)
if ! printf '%s' "$out" | jq -e '.structured_output.verdict' >/dev/null 2>&1; then
  echo "缺少 structured_output.verdict" >&2; exit 2
fi

cost="$(printf '%s' "$out" | jq -r '.total_cost_usd // 0')"
high="$(printf '%s' "$out" | jq '[.structured_output.findings[] | select(.severity == "high")] | length')"
echo "成本(客戶端估算):USD $cost;high 等級問題:$high 筆"
printf '%s' "$out" | jq -r '.structured_output.findings[] | "- [\(.severity)] \(.file):\(.line // "?") \(.summary)"'

[ "$high" -eq 0 ] || exit 1
exit 0

以三份 fixture(模擬 claude -p 的輸出)離線驗證判斷邏輯,實測結果:

Fixture內容結束碼輸出
gate-pass.jsonverdict: pass,只有 low 等級發現0high 等級問題:0 筆
gate-fail.json有一筆 high(字串拼接 SQL)1列出 high 與 medium 發現
gate-error.jsonis_error: true、subtype: error_max_turns2Claude 回報錯誤:error_max_turns
非 JSON 文字模擬輸出被截斷2輸出不是合法 JSON
# 在 CI 中先跑 gate 腳本的單元測試,再跑真正的審查
for f in pass fail error; do bash ci/claude-gate.sh test/fixtures/gate-$f.json; echo "$f -> $?"; done

📌 實務建議:AI 審查關卡建議先以「只報告、不阻擋」(allow_failure: true)試行數週,統計誤報率後再改為阻擋;high 等級的定義要寫進提示與 REVIEW.md,避免各次執行標準不一。

29.5 GitHub Actions

最快的設定方式是在 Claude Code 中執行 /install-github-app,它會引導安裝 Claude GitHub App 並設定 workflow 與 Secret。手動設定時,以官方的 anthropics/claude-code-action@v1 為基礎:

name: Claude PR Review
on:
  pull_request:
    types: [opened, synchronize]

permissions:
  contents: read
  pull-requests: write
  id-token: write

jobs:
  review:
    runs-on: ubuntu-latest
    timeout-minutes: 20
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 0
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: |
            審查這個 PR 的 diff(相對於 ${{ github.base_ref }}),
            只回報有檔案路徑與行號佐證的問題,依 high / medium / low 分級。
          claude_args: >-
            --model sonnet
            --max-turns 15
            --allowedTools "Bash(git diff *)" "Bash(git log *)" Read Grep Glob
  • id-token: write 是 Action 預設以 GitHub App 認證所需的權限;pull-requests: write 讓它能留言。
  • 有 prompt 輸入時,Action 以自動化模式在任何事件執行;沒有 prompt 時則回應留言中的 @claude。
  • claude_args 把 CLI 旗標傳給底層的 Claude Code;純文字提示預設沒有 Shell 或 GitHub API 權限,必須以 --allowedTools 或 settings 輸入授予。
  • 使用 Bedrock/Google Cloud 等供應商時,請參考官方「GitHub Actions with cloud providers」設定 OIDC。

29.6 GitLab CI/CD

以下 job 在 MR pipeline 中安裝 Claude Code 並執行第29.4章的 gate 腳本(ANTHROPIC_API_KEY 設為 masked、protected 的 CI/CD 變數):

stages:
  - review

claude-review-gate:
  stage: review
  image: node:24-bookworm-slim
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
  variables:
    GIT_DEPTH: "0"
    MAX_COST_USD: "2.00"
  before_script:
    - apt-get update -qq && apt-get install -y -qq git curl jq >/dev/null
    - curl -fsSL https://claude.ai/install.sh | bash
    - export PATH="$HOME/.local/bin:$PATH"
    - claude --version
  script:
    - git fetch origin "$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
    - bash ci/claude-gate.sh
  allow_failure: false
  timeout: 20m

⚠️ 注意:官方 GitLab 範例使用 Alpine 映像檔,Alpine 需要額外安裝 libgcc、libstdc++、ripgrep 並設定 USE_BUILTIN_RIPGREP=0(第3.4章);本範例改用 Debian 系的 node:24-bookworm-slim 避開這些相依問題。原生安裝程式把 claude 放在 ~/.local/bin,要手動加入 PATH。

29.7 Agent SDK 簡介

當你需要的不只是「跑一次、拿結果」,而是要在自己的應用程式中控制 Agent——自訂工具、以回呼決定權限(canUseTool)、即時處理串流訊息、管理多個 Session——就改用 Agent SDK(TypeScript 與 Python)。SDK 與 claude -p 共用同一個引擎與設定系統,本手冊的權限、Hook、Sandbox、Subagent 觀念都適用;預設的起始權限模式與 Fork Mode 行為和 -p 相同(default、Fork Mode 關閉)。

29.8 Headless 的 v3.0 變更與實測結果(v3.0 新增)

v3.0 依 v2.0 附錄G.4 的待查項目,以本機 Claude Code v2.1.327、--model haiku 實際執行下列測試(全部在隔離的暫存目錄中執行,輸入一律 < /dev/null,總成本約 US$0.02)。判斷依據是產出物(檔案是否建立)與結果 JSON 欄位,不是模型的自述——模型在被拒後有時仍會宣稱「已完成」,這是 Headless 驗證最常見的陷阱。

#測試指令重點實際結果結論
T2denyInsteadOfPrompting--settings 設 true,要求以 Write 建立 hello.txt檔案未建立;permission_denials 列出 Write;結束碼 0、is_error=false被拒
T2c對照組(不帶設定)同上同樣被拒在 -p 中需要核准的呼叫本來就會被拒;這個鍵的價值在互動/無人值守 Session、Subagent 與 Teammate
T3a無效 --settings+sandbox 鍵JSON 含 // 註解與 "sandbox":{"enabled":true}結束碼 1;「sandbox required but unavailable … failed validation … Refusing to start without a working sandbox」v2.1.323 新行為確認
T3b無效 --settings(無 sandbox 鍵)JSON 含 // 註解結束碼 0、照常回答、stderr 無任何訊息無效設定仍被靜默略過
T4PreToolUse Hook 封鎖allow 規則允許 mkdir markerdir,Hook exit 2目錄未建立;permission_denials 列出 BashHook 生效
T4c對照組(無 Hook)同上目錄建立;permission_denials 為空證明攔截來自 Hook
T4’allow 規則與重導向allow Bash(echo *),指令 echo hi > marker.txt被拒(有無 Hook 皆同)含輸出重導向的指令不被 Bash(echo *) 涵蓋
T5blockWritesOutsideWorkingDirectories--dangerously-skip-permissions,要求寫 ../outside.txt檔案未建立;permission_denials 列出 Write;Claude 回報原因為該設定bypass 模式下仍被擋(對照組見附錄H.4)
T6mcp add-json <name> -在 Claude Code Session 內以 stdin 傳入結束碼 1;「Reading the JSON from stdin is refused inside a Claude Code session」只能在一般終端機使用
T7claude auth status—JSON 含 loginExpiresAtv2.1.318 新欄位確認
T8不完整的 --allowedTools--allowedTools "Bash(git status"結束碼 0,stderr 無警告警告只在互動啟動顯示,CI 不能依賴

-p 結果 JSON 的欄位(v2.1.327 實測,節錄與 CI 有關者):is_error、subtype、result、num_turns、terminal_reason、permission_denials、modelUsage(鍵名即實際使用的模型)、total_cost_usd、usage、session_id、credential_expires_at、safety_stops、subagent_stats、stop_reason。

CI 結果判斷關卡:上表 T2、T4 顯示「結束碼 0、is_error=false,但任務根本沒完成」是常態。以下 gate_result.py 把這些情況轉成 CI 失敗,並已用上面的真實輸出驗證:

#!/usr/bin/env python3
"""判斷一次 `claude -p --output-format json` 的結果能否讓 CI 通過。

用法:python gate_result.py RESULT.json [--allow-model claude-haiku-5-5 ...] [--allow-denials]
失敗條件(任一成立即結束碼 1;檔案無法解析為結束碼 2):
  1. is_error 為 true,或 subtype 不是 success
  2. terminal_reason 不是 completed(例如 max_turns、被中斷)
  3. permission_denials 非空(代表有動作被拒,任務很可能沒完成),除非 --allow-denials
  4. modelUsage 出現未列在 --allow-model 的模型(設定擋掉指定模型時,-p 可能改用別的模型)
  5. credential_expires_at 在 7 天內到期(只警告,不影響結束碼)
"""
import argparse, json, sys
from datetime import datetime, timezone, timedelta


def main():
    ap = argparse.ArgumentParser()
    ap.add_argument("result")
    ap.add_argument("--allow-model", action="append", default=[])
    ap.add_argument("--allow-denials", action="store_true")
    a = ap.parse_args()
    try:
        d = json.load(open(a.result, encoding="utf-8"))
    except (OSError, json.JSONDecodeError) as e:
        print(f"[ERROR] 無法解析 {a.result}:{e}")
        sys.exit(2)
    problems = []
    if d.get("is_error") or d.get("subtype") != "success":
        problems.append(f"is_error={d.get('is_error')} subtype={d.get('subtype')}")
    if d.get("terminal_reason") not in (None, "completed"):
        problems.append(f"terminal_reason={d.get('terminal_reason')}")
    denials = d.get("permission_denials") or []
    if denials and not a.allow_denials:
        tools = sorted({x.get("tool_name", "?") for x in denials})
        problems.append(f"permission_denials={len(denials)}({', '.join(tools)})")
    if a.allow_model:
        extra = sorted(set(d.get("modelUsage", {})) - set(a.allow_model))
        if extra:
            problems.append(f"使用了未允許的模型:{', '.join(extra)}")
    exp = d.get("credential_expires_at")
    if exp:
        t = datetime.fromisoformat(exp.replace("Z", "+00:00"))
        if t - datetime.now(timezone.utc) < timedelta(days=7):
            print(f"[WARN] 登入憑證將於 {exp} 到期,請更新 CI 使用的憑證")
    cost = d.get("total_cost_usd")
    for p in problems:
        print(f"[FAIL] {p}")
    print(f"{'FAIL' if problems else 'PASS'} turns={d.get('num_turns')} cost_usd={cost}")
    sys.exit(1 if problems else 0)


if __name__ == "__main__":
    main()

以實測輸出執行的結果:

$ python gate_result.py t3b.out --allow-model claude-haiku-5-5
PASS turns=1 cost_usd=0.008120700000000002          # 結束碼 0
$ python gate_result.py t2.out --allow-model claude-haiku-5-5
[FAIL] permission_denials=1(Write)
FAIL turns=2 cost_usd=0.00222714                    # 結束碼 1
$ python gate_result.py t4c.out --allow-model claude-sonnet-5-5
[FAIL] 使用了未允許的模型:claude-haiku-5-5
FAIL turns=2 cost_usd=0.00203576                    # 結束碼 1
$ python gate_result.py t3a.err
[ERROR] 無法解析 t3a.err:Expecting value: line 2 column 1 (char 1)   # 結束碼 2

在 CI 中的用法:

claude -p --model sonnet --max-turns 8 --max-budget-usd 2 \
  --permission-prompts none --allowedTools "Read" "Grep" "Bash(npm test *)" \
  --output-format json "執行單元測試並摘要失敗原因" < /dev/null > result.json || true
python gate_result.py result.json --allow-model claude-sonnet-5-5

v3.0 期間其他 Headless 行為變更:

變更版本
未指定權限模式的 -p/SDK,在第三方供應商、遙測關閉或全新安裝時以 default(Manual)啟動v2.1.302
--permission-mode auto 在 Auto Mode 不可用時改以 Manual 啟動v2.1.323
設定擋掉指定模型時,-p 文字輸出會在 stderr 警告(之前會靜默改用其他模型)v2.1.323
取得模型設定卡住(例如代理)時,-p 等待 10 秒後不帶設定繼續,不再卡死v2.1.327
長時間 Hook 每 30 秒送出心跳v2.1.323
在掛載進容器的 Worktree/Submodule 中,.claude/settings.local.json 的 allow 規則要等資料夾受信任後才套用v2.1.325
--no-session-persistence 的長工具結果會在正常結束、Ctrl+C 或 SIGTERM 時刪除v2.1.323
非互動啟動遇到無效的 ~/.claude.json 時不再以預設值覆蓋,而是失敗並說明如何還原v2.1.318

29.9 本章審查與驗證清單

AI 產出項目❌ 常見錯誤✅ 正確做法人工如何驗證
CI 中的 claude -p 指令沒有 --max-turns/--max-budget-usd,或用 bypassPermissions第29.3章的最小權限組合check_flags.py 掃描 CI 檔;Code Review 檢查權限
結果判斷只看結束碼或 result 是否非空檢查 is_error、subtype 與 structured_output以第29.4章三份 fixture 測試 gate 腳本
設定錯誤偵測假設 MCP/Plugin 設定錯誤會讓 run 失敗讀 system/init 的 mcp_server_errors、plugin_errors故意放一個缺 type 的 MCP 設定,確認 CI 失敗
陌生 repo 的自動化對外部貢獻者的 PR 直接執行 claude -p審查 .claude/ 變更,或以 --bare/停用 Hook 執行檢查 workflow 是否在 fork PR 上執行、是否有 .claude/ 變更審查
GitHub Action 設定缺少 id-token: write 或給予過寬的 contents: write依任務給最小權限檢查 workflow 的 permissions 區塊
GitLab 映像檔用 Alpine 卻沒裝 musl 相依套件改用 Debian 系映像檔或補齊相依job 中 claude --version 成功
CI 成功判斷只看 claude -p 的結束碼或 is_error同時檢查 terminal_reason、permission_denials 與 modelUsage(第29.8章 gate_result.py)以被拒的實測輸出(如 T2)餵給關卡,確認 CI 會失敗
無效的 --settings以為檔案寫錯 -p 一定會報錯只有含 sandbox 鍵時拒絕啟動;其他情況靜默略過在 CI 先以 python -m json.tool 與 check_settings.py 驗證設定檔
模型自述依 Claude 的最終回覆判斷「已建立檔案」以產出物與 permission_denials 判斷,必要時做對照組檢查檔案是否真的存在;比對有無設定的兩次執行結果

第 30 章 AI 產出驗證方法論

本章目標:把前面各章「本章審查與驗證清單」中的驗證方式,整理成一套可重複、可自動化的方法與工具。本章附上的四支檢查工具與一支 Hook 測試 harness,都是本手冊實際用來驗證所有範例的程式;讀完後,你應該能把它們放進自己 repo 的 CI,讓 AI 產生的 Claude Code 設定在合併前就被客觀檢查。

30.1 為什麼需要專門的驗證方法

Claude Code 的設定與擴充有一個共同特性:錯誤通常不會報錯,而是靜默失效。

錯誤Claude Code 的反應後果
settings.json 拼錯鍵名(disallowAllHooks)忽略該鍵以為停用了 Hook,其實沒有
Hook 用 handlers 而非 hooks視為無效設定「安全 Hook」從未執行
Hook 以 exit 1 表示阻擋當成非阻擋錯誤,動作照常執行危險指令沒有被擋下
.mcp.json 寫 transport 而非 type當成 stdio 而略過MCP Server 從未連上
Subagent 欄位寫成 permission-mode靜默忽略未知欄位審查用 Subagent 以預設模式執行
claude -p 讀到無效設定檔靜默略過整個檔案CI 中的 deny 規則全部失效

這些都是 AI 很容易產生、人工審查也很容易看漏的錯誤。因此驗證不能只靠「看起來合理」,而要分層:

flowchart LR
    L1["第 1 層:文件比對<br/>(對照官方文件與版本)"] --> L2["第 2 層:靜態檢查<br/>(結構、鍵名、旗標)"]
    L2 --> L3["第 3 層:執行驗證<br/>(harness、fixture、實跑)"]
    L3 --> L4["第 4 層:反向測試<br/>(故意放入錯誤,確認檢查會失敗)"]

第 4 層最常被省略,卻最重要:一個從來不會失敗的檢查工具,無法證明它真的有在檢查。本章每一支工具都附上反向測試的實際結果。

30.2 驗證工具總覽

工具檢查對象主要檢查項目對應章節
check_settings.pysettings.json、managed-settings.json嚴格 JSON、未知鍵(對照官方約 245 個鍵)、Hook 結構與事件名稱、權限規則格式、defaultMode 陷阱5、6、12、19
check_agents.py.claude/agents/*.md、SKILL.mdfrontmatter 必填與未知欄位、name 規則、模型/模式/effort 值10、27
check_mcp.py.mcp.json、--mcp-configtype 缺漏、transport 誤用、欄位、未加密端點、寫死的金鑰13
check_flags.py任何文件或腳本提到的 claude 旗標是否存在於 --help 與官方 CLI reference6、29
test_hooks.sh.claude/hooks/*.sh以模擬輸入驗證 exit code 與 JSON 決策、fail-closed12、14
claude-gate.sh + fixtureCI 審查關卡結果判斷邏輯(通過/失敗/錯誤/格式不符)29
SchemaStore schemasettings.json官方發布的 JSON Schema(可能落後最新版本)5
actionlintGitHub Actions workflowworkflow 語法與 action 輸入29
check_upgrade.py(v3.0)settings/managed 設定、plugin.json、CI 腳本v2.1.300~v2.1.327 會改變行為的設定(BREAK)與需人工確認的項目(CHECK)33
gate_result.py(v3.0)claude -p --output-format json 的結果is_error、terminal_reason、permission_denials、模型白名單、登入到期29
claude-healthcheck.sh(v3.0)開發機或 CI Runner版本下限、登入狀態、claude doctor 的 Invalid settings、各層設定檔32
block-repl-risky.sh + test_repl_hook.sh(v3.0)Code Mode 的 REPL Hook受管制指令的攔截與結束碼12、31

這些工具都只依賴 Python 3 標準函式庫與 PyYAML(check_agents.py),以及 bash 與 jq(Hook 測試)。check_settings.py 需要同目錄下的 settings-keys.txt(從官方 Settings reference 擷取的鍵名清單,每次 Claude Code 大版本更新時重新產生)。

30.3 check_settings.py:設定檔檢查

#!/usr/bin/env python3
"""檢查 Claude Code settings.json(含 managed-settings.json)是否符合官方結構。

用法:python check_settings.py [--keys settings-keys.txt] [--scope project|local|user|managed] FILE...
檢查項目:
  1. 必須是嚴格 JSON(不可有 // 註解或尾逗號)
  2. 頂層鍵與 permissions/sandbox/autoMode 等子鍵必須是官方文件列出的鍵
  3. hooks 結構:事件名稱、matcher 群組、hooks 陣列、type 與必要欄位、onFailure/shell 值
  4. permissions.defaultMode 值,以及專案層級設 auto/bypassPermissions 無效的陷阱
  5. (v3.0)已移除/棄用的鍵、專案層級無效的鍵與 env 變數、Sandbox 自動放行預設翻轉(v2.1.324)
結束碼:0 = 無錯誤;1 = 有錯誤(警告不影響結束碼)
"""
import argparse, json, os, re, sys

HOOK_EVENTS = {
    "SessionStart", "Setup", "UserPromptSubmit", "UserPromptExpansion", "PreToolUse",
    "PermissionRequest", "PermissionDenied", "PostToolUse", "PostToolUseFailure",
    "PostToolBatch", "Notification", "MessageDisplay", "SubagentStart", "SubagentStop",
    "TaskCreated", "TaskCompleted", "Stop", "StopFailure", "TeammateIdle",
    "InstructionsLoaded", "ConfigChange", "CwdChanged", "DirectoryAdded", "FileChanged",
    "WorktreeCreate", "WorktreeRemove", "PreCompact", "PostCompact", "PreModelSwitch",
    "PostModelSwitch", "Elicitation", "ElicitationResult", "SessionEnd",
}
HANDLER_REQUIRED = {"command": ["command"], "http": ["url"], "mcp_tool": ["server", "tool"],
                    "prompt": ["prompt"], "agent": ["prompt"]}
HANDLER_FIELDS = {"type", "command", "args", "if", "timeout", "statusMessage", "once", "async",
                  "asyncRewake", "shell", "onFailure", "url", "headers", "allowedEnvVars",
                  "server", "tool", "input", "prompt", "model"}
MODES = {"default", "manual", "acceptEdits", "plan", "auto", "dontAsk", "bypassPermissions"}
# 子鍵不在 settings-keys.txt 標題中、但官方文件明確列出的欄位
EXTRA_CHILDREN = {
    "permissions": {"disableAutoMode"},
    "autoMode": {"environment", "allow", "soft_deny", "hard_deny"},
}
VALIDATE_CHILDREN = {"permissions", "sandbox", "sandbox.network", "sandbox.filesystem",
                     "autoMode", "worktree", "attribution", "policyHelper"}
# v3.0:官方 Settings reference 仍列出、但已移除或棄用的鍵(寫了不會生效)
REMOVED_KEYS = {"permissionExplainerEnabled": "v2.1.257 移除", "taskOutputMaxChars": "v2.1.277 移除",
                "teammateDefaultModel": "v2.1.234 移除", "subagentStatusLine": "v2.1.323 移除"}
DEPRECATED_KEYS = {"includeCoAuthoredBy": "改用 attribution", "keybindingFlavor": "已無作用",
                   "disableArtifact": "改用 enableArtifact", "pluginDigests": "v2.1.325 起忽略"}
# v3.0:repo 內的 project/local 設定無法生效的鍵(只認 user、managed 或 --settings)
NOT_FROM_PROJECT = {"permissions.denyInsteadOfPrompting", "sandbox.network.strictAllowlist",
                    "sandbox.allowNestedUserNamespaces"}
# v3.0:project/local 設定的 env 區塊中會被丟棄的變數(節錄官方清單中最常被誤用者)
PROJECT_IGNORED_ENV = {"CLAUDE_CONFIG_DIR", "CLAUDE_CODE_TMPDIR", "CLAUDE_CODE_ENABLE_TELEMETRY",
                       "OTEL_EXPORTER_OTLP_ENDPOINT", "OTEL_LOG_USER_PROMPTS", "OTEL_LOG_TOOL_DETAILS",
                       "CLAUDE_CODE_OAUTH_TOKEN", "CLAUDE_CODE_PROCESS_WRAPPER",
                       "CLAUDE_CODE_EXPERIMENTAL_CODE_MODE"}


def load_keys(path):
    keys = set()
    with open(path, encoding="utf-8") as f:
        for line in f:
            if line.strip():
                keys.add(line.strip())
    return keys


def check_hooks(hooks, err, warn):
    if not isinstance(hooks, dict):
        err("hooks 必須是物件(事件名稱 → 陣列)"); return
    for event, groups in hooks.items():
        if event not in HOOK_EVENTS:
            err(f"hooks:未知事件名稱 {event!r}")
        if not isinstance(groups, list):
            err(f"hooks.{event} 必須是陣列"); continue
        for gi, g in enumerate(groups):
            where = f"hooks.{event}[{gi}]"
            if not isinstance(g, dict):
                err(f"{where} 必須是物件"); continue
            if "handlers" in g:
                err(f"{where}:鍵名應為 \"hooks\",不是 \"handlers\"")
            if "hooks" not in g or not isinstance(g.get("hooks"), list):
                err(f"{where}:缺少 hooks 陣列"); continue
            m = g.get("matcher")
            if isinstance(m, str) and "(" in m:
                warn(f"{where}:matcher {m!r} 含括號;matcher 比對工具名稱,權限規則語法請放在 handler 的 \"if\"")
            for hi, h in enumerate(g["hooks"]):
                hw = f"{where}.hooks[{hi}]"
                t = h.get("type")
                if t not in HANDLER_REQUIRED:
                    err(f"{hw}:type 必須是 {sorted(HANDLER_REQUIRED)} 之一,實際為 {t!r}"); continue
                for req in HANDLER_REQUIRED[t]:
                    if req not in h:
                        err(f"{hw}:type={t} 缺少必要欄位 {req!r}")
                for k in h:
                    if k not in HANDLER_FIELDS:
                        err(f"{hw}:未知欄位 {k!r}")
                if "onFailure" in h and h["onFailure"] not in ("continue", "block"):
                    err(f"{hw}:onFailure 只能是 continue 或 block")
                if "onFailure" in h and t not in ("command", "http"):
                    warn(f"{hw}:onFailure 只對 command/http hook 生效")
                if "shell" in h and h["shell"] not in ("bash", "powershell"):
                    err(f"{hw}:shell 只能是 bash 或 powershell")
                if "if" in h and event not in ("PreToolUse", "PostToolUse", "PostToolUseFailure",
                                                "PermissionRequest", "PermissionDenied"):
                    warn(f"{hw}:if 只在工具事件生效,{event} 上這個 hook 永遠不會執行")


def check_file(path, keys, scope):
    errors, warns = [], []
    err = lambda m: errors.append(m)
    warn = lambda m: warns.append(m)
    raw = open(path, encoding="utf-8").read()
    try:
        data = json.loads(raw)
    except json.JSONDecodeError as e:
        hint = "(JSON 不支援 // 註解)" if re.search(r'^\s*//', raw, re.M) else ""
        return [f"不是合法 JSON:{e}{hint}"], []
    if not isinstance(data, dict):
        return ["頂層必須是物件"], []
    top = {k.split(".")[0] for k in keys}
    for k, v in data.items():
        if k == "$schema":
            continue
        if k in REMOVED_KEYS:
            err(f"{k!r} 已移除({REMOVED_KEYS[k]}),寫了也不會生效")
        elif k in DEPRECATED_KEYS:
            warn(f"{k!r} 已棄用:{DEPRECATED_KEYS[k]}")
        elif k not in top:
            err(f"未知頂層鍵 {k!r}")
    if scope in ("project", "local"):
        for dotted in NOT_FROM_PROJECT:
            node = data
            for part in dotted.split("."):
                node = node.get(part) if isinstance(node, dict) else None
            if node is not None:
                warn(f"{dotted} 在 {scope} 設定中不會生效,請放在使用者、managed 設定或 --settings")
        env = data.get("env", {})
        if isinstance(env, dict):
            for name in env:
                if name in PROJECT_IGNORED_ENV or name.startswith("CLAUDE_AX_"):
                    warn(f"env.{name} 在 {scope} 設定中會被丟棄(repo 不可控制),請改放使用者或 managed 設定")
    sb = data.get("sandbox")
    if isinstance(sb, dict) and sb.get("enabled") is True and "autoAllowBashIfSandboxed" not in sb:
        warn("sandbox.enabled=true 但未明確設定 autoAllowBashIfSandboxed:v2.1.324 起預設為 false,"
             "沙箱內的 Bash 會改走一般權限流程;要沿用免詢問行為請明確設為 true")
    for parent in VALIDATE_CHILDREN:
        node = data
        for part in parent.split("."):
            node = node.get(part) if isinstance(node, dict) else None
        if not isinstance(node, dict):
            continue
        allowed = {k[len(parent) + 1:].split(".")[0] for k in keys if k.startswith(parent + ".")}
        allowed |= EXTRA_CHILDREN.get(parent, set())
        for child in node:
            if child not in allowed:
                err(f"{parent} 底下未知鍵 {child!r}")
    perms = data.get("permissions", {})
    mode = perms.get("defaultMode") if isinstance(perms, dict) else None
    if mode is not None and mode not in MODES:
        err(f"permissions.defaultMode 值 {mode!r} 不合法")
    if scope in ("project", "local") and mode in ("auto", "bypassPermissions"):
        warn(f"專案層級的 defaultMode={mode} 不會生效(官方限制),請改放使用者或 managed 設定")
    if isinstance(perms, dict):
        for lst in ("allow", "ask", "deny"):
            for rule in perms.get(lst, []) or []:
                if not re.match(r'^[A-Za-z_][\w*-]*(\(.*\))?$', rule):
                    err(f"permissions.{lst} 規則格式錯誤:{rule!r}")
    if "hooks" in data:
        check_hooks(data["hooks"], err, warn)
    return errors, warns


def main():
    here = os.path.dirname(os.path.abspath(__file__))
    ap = argparse.ArgumentParser()
    ap.add_argument("--keys", default=os.path.join(here, "settings-keys.txt"))
    ap.add_argument("--scope", default="user", choices=["user", "project", "local", "managed"])
    ap.add_argument("files", nargs="+")
    a = ap.parse_args()
    keys = load_keys(a.keys)
    bad = 0
    for f in a.files:
        errors, warns = check_file(f, keys, a.scope)
        status = "FAIL" if errors else "OK"
        print(f"[{status}] {f}")
        for e in errors:
            print(f"   錯誤:{e}")
        for w in warns:
            print(f"   警告:{w}")
        bad += bool(errors)
    sys.exit(1 if bad else 0)


if __name__ == "__main__":
    main()
python check_settings.py --scope project .claude/settings.json
python check_settings.py --scope managed /etc/claude-code/managed-settings.json

本手冊第5、6、12、13、19章的 7 份設定範例皆通過檢查;另外以 SchemaStore 的 claude-code-settings.json schema 交叉驗證,唯一差異是 schema 尚未收錄 v2.1.295 新增的 onFailure。值得注意的是 SchemaStore schema 不會抓出未知的頂層鍵(例如 disallowAllHooks)與 sandbox.enable 這類拼錯的子鍵,這正是需要自寫檢查工具的原因。

30.4 check_agents.py:Subagent 與 Skill 檢查

#!/usr/bin/env python3
"""檢查 Subagent 定義檔(.claude/agents/*.md)與 Skill(SKILL.md)的 frontmatter。

用法:python check_agents.py agent  FILE...
      python check_agents.py skill  FILE...
重點:Claude Code 對拼錯或不認得的欄位「靜默忽略」,不會報錯,所以要用工具抓。
需要 PyYAML(pip install pyyaml)。
"""
import re, sys
import yaml

AGENT_FIELDS = {"name", "description", "tools", "disallowedTools", "model", "permissionMode",
                "maxTurns", "skills", "mcpServers", "hooks", "memory", "background",
                "omitClaudeMd", "effort", "isolation", "color", "initialPrompt",
                "experimental", "autoCompactWindow"}
SKILL_FIELDS = {"name", "description", "when_to_use", "argument-hint", "arguments",
                "disable-model-invocation", "user-invocable", "allowed-tools",
                "disallowed-tools", "model", "effort", "context", "agent", "background",
                "hooks", "paths", "shell", "metadata", "license", "compatibility"}
MODEL_ALIASES = {"sonnet", "opus", "haiku", "fable", "inherit", "best", "opusplan"}
MODES = {"default", "manual", "acceptEdits", "plan", "auto", "dontAsk", "bypassPermissions"}
EFFORTS = {"low", "medium", "high", "xhigh", "max"}
COLORS = {"red", "blue", "green", "yellow", "purple", "orange", "pink", "cyan"}


def frontmatter(path):
    text = open(path, encoding="utf-8").read()
    m = re.match(r'^---\r?\n(.*?)\r?\n---\r?\n(.*)$', text, re.S)
    if not m:
        raise ValueError("找不到以 --- 包住的 YAML frontmatter")
    data = yaml.safe_load(m.group(1)) or {}
    if not isinstance(data, dict):
        raise ValueError("frontmatter 必須是 YAML 物件")
    return data, m.group(2)


def check_agent(d, body):
    e = []
    for req in ("name", "description"):
        if not d.get(req):
            e.append(f"缺少必填欄位 {req}")
    name = str(d.get("name", ""))
    if ":" in name:
        e.append("name 不可包含 ':'(保留給 plugin 命名空間)")
    if len(name) > 256:
        e.append("name 超過 256 字元")
    if name == "fork":
        e.append("name 不可使用保留字 fork")
    for k in d:
        if k not in AGENT_FIELDS:
            e.append(f"未知欄位 {k!r}(會被靜默忽略,請確認拼字與大小寫)")
    model = d.get("model")
    if model is not None and model not in MODEL_ALIASES and not str(model).startswith("claude-"):
        e.append(f"model 值 {model!r} 不是別名或完整模型 ID")
    if "permissionMode" in d and d["permissionMode"] not in MODES:
        e.append(f"permissionMode 值 {d['permissionMode']!r} 不合法")
    if "effort" in d and d["effort"] not in EFFORTS:
        e.append(f"effort 值 {d['effort']!r} 不合法")
    if "color" in d and d["color"] not in COLORS:
        e.append(f"color 值 {d['color']!r} 不合法")
    if "isolation" in d and d["isolation"] != "worktree":
        e.append("isolation 目前只接受 worktree")
    if "memory" in d and d["memory"] not in ("user", "project", "local"):
        e.append("memory 只接受 user/project/local")
    if "maxTurns" in d and not (isinstance(d["maxTurns"], int) and d["maxTurns"] > 0):
        e.append("maxTurns 必須是正整數")
    if "cacheTtl" in d:
        e.append("cacheTtl 必須寫在 experimental 底下")
    if not body.strip():
        e.append("本文(系統提示)是空的")
    return e


def check_skill(d, body):
    e = []
    for k in d:
        if k not in SKILL_FIELDS:
            e.append(f"未知欄位 {k!r}(會被靜默忽略)")
    desc = str(d.get("description", "")) + str(d.get("when_to_use", ""))
    if not d.get("description"):
        e.append("建議填寫 description,否則 Claude 只能用本文第一行判斷何時使用")
    if len(desc) > 1536:
        e.append("description + when_to_use 超過 1,536 字元,清單中會被截斷")
    for b in ("disable-model-invocation", "user-invocable", "background"):
        if b in d and not isinstance(d[b], bool):
            e.append(f"{b} 必須是布林值 true/false")
    if "context" in d and d["context"] != "fork":
        e.append("context 目前只接受 fork")
    if "background" in d and d.get("context") != "fork":
        e.append("background 只在 context: fork 時有作用")
    if "effort" in d and d["effort"] not in EFFORTS:
        e.append(f"effort 值 {d['effort']!r} 不合法")
    if "shell" in d and d["shell"] not in ("bash", "powershell"):
        e.append("shell 只接受 bash 或 powershell")
    return e


def main():
    if len(sys.argv) < 3 or sys.argv[1] not in ("agent", "skill"):
        print(__doc__); sys.exit(2)
    kind, files, bad = sys.argv[1], sys.argv[2:], 0
    for f in files:
        try:
            d, body = frontmatter(f)
            errs = check_agent(d, body) if kind == "agent" else check_skill(d, body)
        except Exception as ex:  # YAML 語法錯誤等
            errs = [str(ex)]
        print(f"[{'FAIL' if errs else 'OK'}] {f}")
        for x in errs:
            print(f"   錯誤:{x}")
        bad += bool(errs)
    sys.exit(1 if bad else 0)


if __name__ == "__main__":
    main()
python check_agents.py agent .claude/agents/*.md
python check_agents.py skill .claude/skills/*/SKILL.md

30.5 check_mcp.py:MCP 設定檢查

#!/usr/bin/env python3
"""檢查 .mcp.json/--mcp-config 檔案的結構。

用法:python check_mcp.py FILE...
最常見的錯誤:遠端 server 寫了 url 卻沒寫 "type"(Claude Code 會當成 stdio 而略過),
或把 CLI 的 --transport 誤寫成 JSON 鍵 "transport"。
"""
import json, re, sys

REMOTE_TYPES = {"http", "streamable-http", "sse", "ws"}  # streamable-http 為 http 的別名(MCP 規格名稱)
COMMON = {"type", "alwaysLoad", "timeout", "bareElicitationCapability"}
REMOTE_FIELDS = COMMON | {"url", "headers", "headersHelper", "oauth"}
STDIO_FIELDS = COMMON | {"command", "args", "env"}


def check(path):
    e = []
    try:
        data = json.load(open(path, encoding="utf-8"))
    except json.JSONDecodeError as ex:
        return [f"不是合法 JSON:{ex}"]
    servers = data.get("mcpServers")
    if not isinstance(servers, dict) or not servers:
        return ["缺少 mcpServers 物件"]
    for name, s in servers.items():
        w = f"mcpServers.{name}"
        if not re.match(r'^[A-Za-z0-9_-]+$', name):
            e.append(f"{w}:名稱只建議使用英數、底線與連字號")
        if "transport" in s:
            e.append(f"{w}:JSON 鍵應為 \"type\",\"transport\" 是 CLI 旗標 --transport 的名稱")
        t = s.get("type")
        if "url" in s and t not in REMOTE_TYPES:
            e.append(f"{w}:有 url 時必須設定 type 為 http/sse/ws(目前 {t!r},會被當成 stdio 而略過)")
        if t in REMOTE_TYPES:
            for k in s:
                if k not in REMOTE_FIELDS:
                    e.append(f"{w}:遠端 server 不認得欄位 {k!r}")
            if not str(s.get("url", "")).startswith(("https://", "http://", "wss://", "ws://", "${")):
                e.append(f"{w}:url 格式不正確")
            if str(s.get("url", "")).startswith("http://") and "localhost" not in s["url"]:
                e.append(f"{w}:非本機的 http:// 端點未加密,請改用 https://")
        elif t in (None, "stdio"):
            if "command" not in s:
                e.append(f"{w}:stdio server 必須有 command")
            for k in s:
                if k not in STDIO_FIELDS and k != "transport":
                    e.append(f"{w}:stdio server 不認得欄位 {k!r}")
        else:
            e.append(f"{w}:未知 type {t!r}")
        blob = json.dumps(s)
        if re.search(r'(ghp_[A-Za-z0-9]{20,}|sk-ant-[A-Za-z0-9_-]{20,}|AKIA[0-9A-Z]{16})', blob):
            e.append(f"{w}:疑似把金鑰寫死在設定檔,請改用 ${{ENV_VAR}} 展開")
    return e


bad = 0
for f in sys.argv[1:]:
    errs = check(f)
    print(f"[{'FAIL' if errs else 'OK'}] {f}")
    for x in errs:
        print(f"   錯誤:{x}")
    bad += bool(errs)
sys.exit(1 if bad else 0)

30.6 check_flags.py:CLI 旗標比對

#!/usr/bin/env python3
"""比對文件中出現的 claude CLI 旗標,是否存在於本機 --help 或官方 CLI 參考。

用法:python check_flags.py --known help_dir_or_file... -- DOC.md
做法:
  1. 從 --known 指定的檔案收集所有 --flag
     (例如 claude --help 與各子指令 --help 的輸出、官方 CLI reference)
  2. 從 DOC.md 中「含 claude 的指令行」與行內程式碼收集 --flag
  3. 列出 DOC 有、已知清單沒有的旗標(可能是錯字、已移除或文件幻覺)
"""
import os, re, sys

FLAG = re.compile(r'(?<![\w-])--[a-z][a-z0-9-]*[a-z0-9]')


def collect_known(paths):
    known = set()
    for p in paths:
        files = [os.path.join(p, f) for f in os.listdir(p)] if os.path.isdir(p) else [p]
        for f in files:
            if os.path.isfile(f):
                known |= set(FLAG.findall(open(f, encoding="utf-8", errors="ignore").read()))
    return known


def collect_doc(path):
    found = {}
    text = open(path, encoding="utf-8").read()
    for n, line in enumerate(text.splitlines(), 1):
        candidates = []
        # 只認獨立的 claude 指令,避免 claude-runbook.md 這類檔名造成誤報
        if re.search(r'(?<![\w/.-])claude(?=\s|$)', line):
            candidates += FLAG.findall(line)
        for code in re.findall(r'`([^`]+)`', line):
            if code.startswith("--"):
                candidates += FLAG.findall(code)
        for c in candidates:
            found.setdefault(c, n)
    return found


def main():
    if "--" not in sys.argv:
        print(__doc__); sys.exit(2)
    i = sys.argv.index("--")
    known_args = [a for a in sys.argv[1:i] if a != "--known"]
    known = collect_known(known_args)
    bad = 0
    for doc in sys.argv[i + 1:]:
        found = collect_doc(doc)
        unknown = {f: n for f, n in found.items() if f not in known}
        print(f"{doc}:旗標 {len(found)} 個,已知 {len(found) - len(unknown)} 個,未知 {len(unknown)} 個")
        for f, n in sorted(unknown.items(), key=lambda x: x[1]):
            print(f"   第 {n} 行:{f}")
        bad += len(unknown)
    sys.exit(1 if bad else 0)


if __name__ == "__main__":
    main()
# 先傾印本機 help,再比對文件或腳本
mkdir -p help && claude --help > help/root.txt
for c in agents mcp plugin auth doctor ultrareview; do claude $c --help > help/$c.txt; done
python check_flags.py --known help -- docs/claude-runbook.md ci/claude-gate.sh

以本手冊為例:v2.0 全文提到的所有 claude 旗標,與 Claude Code v2.1.296 的 --help 輸出及官方 CLI reference 比對後未知旗標為 0(第30.7章附反向測試)。注意這個工具只檢查「旗標存不存在」,--bg 不能搭配 -p 這類組合錯誤仍需要第6章的知識與實際執行來發現。

30.7 反向測試:證明檢查工具會失敗

以 v1.3 手冊中實際寫錯的範例與常見的 AI 錯誤作為反向 fixture,2026-10-14 實際執行結果如下(節錄):

$ python check_settings.py --scope project neg/settings-*.json
[FAIL] neg/settings-comment.json
   錯誤:不是合法 JSON:Expecting value: line 1 column 1 (char 0)(JSON 不支援 // 註解)
[OK] neg/settings-project-auto.json
   警告:專案層級的 defaultMode=bypassPermissions 不會生效(官方限制),請改放使用者或 managed 設定
[FAIL] neg/settings-unknown.json
   錯誤:未知頂層鍵 'disallowAllHooks'
   錯誤:permissions 底下未知鍵 'denny'
   錯誤:sandbox 底下未知鍵 'enable'
   錯誤:permissions.defaultMode 值 'manuall' 不合法
   錯誤:hooks.PreToolUse[0].hooks[0]:onFailure 只能是 continue 或 block
   錯誤:hooks:未知事件名稱 'OnSave'
[FAIL] neg/settings-v13-hooks.json
   錯誤:hooks.PreToolUse[0]:鍵名應為 "hooks",不是 "handlers"
   錯誤:hooks.PreToolUse[0]:缺少 hooks 陣列

$ python check_mcp.py neg/mcp-v13.json
[FAIL] neg/mcp-v13.json
   錯誤:mcpServers.github:JSON 鍵應為 "type","transport" 是 CLI 旗標 --transport 的名稱
   錯誤:mcpServers.github:有 url 時必須設定 type 為 http/sse/ws(目前 None,會被當成 stdio 而略過)
   錯誤:mcpServers.secret:疑似把金鑰寫死在設定檔,請改用 ${ENV_VAR} 展開

$ python check_agents.py agent neg/agent-bad.md
[FAIL] neg/agent-bad.md
   錯誤:name 不可包含 ':'(保留給 plugin 命名空間)
   錯誤:未知欄位 'permission-mode'(會被靜默忽略,請確認拼字與大小寫)
   錯誤:model 值 'gpt-5' 不是別名或完整模型 ID
   錯誤:effort 值 'extreme' 不合法
   錯誤:cacheTtl 必須寫在 experimental 底下

$ python check_agents.py skill neg/skill-bad.md
[FAIL] neg/skill-bad.md
   錯誤:未知欄位 'disable_model_invocation'(會被靜默忽略)
   錯誤:background 只在 context: fork 時有作用
   錯誤:effort 值 'turbo' 不合法

$ bash test_hooks.sh neg/hooks        # block-dangerous.sh 的 exit 2 改成 exit 1
FAIL  force push 長旗標 (rc=1, want=2, ...)
...
PASS=11 FAIL=7

每一支工具都在正向範例上通過、在反向 fixture 上失敗,才能證明它們確實在檢查。團隊自行擴充檢查規則時,也應同時新增一份會觸發該規則的反向 fixture。

30.8 CI 整合

把檢查工具放在 repo 的 tools/claude-checkers/,並在變更 .claude/、.mcp.json、CLAUDE.md 的 PR 上自動執行(已通過 actionlint 檢查,並在模擬 repo 中逐步實跑通過):

name: Claude Code config lint
on:
  pull_request:
    paths:
      - ".claude/**"
      - ".mcp.json"
      - "CLAUDE.md"
      - "tools/claude-checkers/**"

permissions:
  contents: read

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-python@v6
        with:
          python-version: "3.12"
      - name: Install dependencies
        run: |
          pip install pyyaml
          sudo apt-get update -qq && sudo apt-get install -y -qq jq
      - name: Check settings files
        run: |
          python tools/claude-checkers/check_settings.py --scope project .claude/settings.json
          if [ -f .claude/settings.local.json ]; then echo "::error::settings.local.json 不應提交版控"; exit 1; fi
      - name: Check MCP config
        run: |
          if [ -f .mcp.json ]; then python tools/claude-checkers/check_mcp.py .mcp.json; fi
      - name: Check subagents and skills
        run: |
          shopt -s nullglob globstar
          agents=(.claude/agents/**/*.md)
          skills=(.claude/skills/*/SKILL.md)
          if [ ${#agents[@]} -gt 0 ]; then python tools/claude-checkers/check_agents.py agent "${agents[@]}"; fi
          if [ ${#skills[@]} -gt 0 ]; then python tools/claude-checkers/check_agents.py skill "${skills[@]}"; fi
      - name: Test hooks
        run: bash tools/claude-checkers/test_hooks.sh .claude/hooks
      - name: CLAUDE.md size budget
        run: |
          lines=$(wc -l < CLAUDE.md)
          echo "CLAUDE.md: $lines lines"
          if [ "$lines" -gt 200 ]; then echo "::warning::CLAUDE.md 超過 200 行,建議拆分到 .claude/rules/ 或 Skill"; fi

30.9 人工 Review 檢查表(適用於變更 .claude/ 的 PR)

工具抓得到結構錯誤,抓不到「意圖錯誤」。以下項目仍需要人工判斷:

檢查項目要問的問題
權限變更新增的 allow 規則是否過寬(Bash(*)、Bash(python *))?是否移除或放寬了既有的 deny?
Hook 變更阻擋邏輯有沒有對應的 harness 測試案例(應阻擋+應放行)?依賴缺失時是否 fail-closed?
Subagent/Skill工具授權是否符合任務最小需求?高風險 Skill 是否 disable-model-invocation: true?
MCP Server是否在核准目錄中?憑證是否以環境變數提供、權限是否最小?
CLAUDE.md新增內容是否真的「每次都需要」?是否應改放 Rules 或 Skill?
版本相依是否使用了需要較新版本的功能?Managed 的版本區間是否涵蓋?
證據PR 是否附上檢查工具與 harness 的執行結果?

30.10 v3.0 新增工具:check_upgrade.py 與檢查規則更新(v3.0 新增)

v3.0 對既有工具的更新(第30.3、30.5章的原始碼已同步為新版):

工具新增檢查依據
check_settings.py已移除的鍵報錯(subagentStatusLine 等)、棄用的鍵警告(includeCoAuthoredBy、pluginDigests 等);專案層級不生效的鍵(denyInsteadOfPrompting、strictAllowlist、allowNestedUserNamespaces)與 env 變數警告;sandbox.enabled 未明確設定 autoAllowBashIfSandboxed 時警告settings-reference(249 個鍵,重新擷取 settings-keys.txt)
check_mcp.py接受 type: "streamable-http"(http 的別名)mcp
check_agents.py無需修改:Subagent 19 個、Skill 20 個 frontmatter 欄位與官方完全一致sub-agents、skills
Hook 事件清單無需修改:仍為 33 個事件hooks

check_settings.py 對一份「把新治理鍵放錯層級」的專案設定所產生的結果(反向 fixture):

[FAIL] neg/v3-project-bad.json
   錯誤:'subagentStatusLine' 已移除(v2.1.323 移除),寫了也不會生效
   警告:'includeCoAuthoredBy' 已棄用:改用 attribution
   警告:permissions.denyInsteadOfPrompting 在 project 設定中不會生效,請放在使用者、managed 設定或 --settings
   警告:sandbox.network.strictAllowlist 在 project 設定中不會生效,請放在使用者、managed 設定或 --settings
   警告:env.CLAUDE_CODE_EXPERIMENTAL_CODE_MODE 在 project 設定中會被丟棄(repo 不可控制),請改放使用者或 managed 設定
   警告:env.OTEL_EXPORTER_OTLP_ENDPOINT 在 project 設定中會被丟棄(repo 不可控制),請改放使用者或 managed 設定
   警告:sandbox.enabled=true 但未明確設定 autoAllowBashIfSandboxed:v2.1.324 起預設為 false,沙箱內的 Bash 會改走一般權限流程;要沿用免詢問行為請明確設為 true

check_upgrade.py:升級到 v2.1.300~v2.1.327 前的唯讀相容性掃描,供第33章的升級流程使用。BREAK 代表「行為已改變、必須處理」(結束碼 1),CHECK 代表「需要人工確認」:

#!/usr/bin/env python3
"""升級到 Claude Code v2.1.300~v2.1.327 前的相容性掃描(只讀,不修改任何檔案)。

用法:python check_upgrade.py [--env] FILE...
  FILE   settings.json、managed-settings.json、plugin.json 或 shell/CI 腳本
  --env  一併檢查目前行程的環境變數(ALL_PROXY、MCP_SDK_GENERATION 等)
每個發現標示 BREAK(行為已改變,必須處理)或 CHECK(需人工確認)。
結束碼:0 = 沒有 BREAK;1 = 至少一個 BREAK
"""
import argparse, json, os, re, sys

FINDINGS = []


def add(level, where, msg):
    FINDINGS.append((level, where, msg))


def walk_rules(perms):
    for lst in ("allow", "ask", "deny"):
        for rule in (perms.get(lst) or []):
            yield lst, rule


def check_settings(path, data):
    sb = data.get("sandbox")
    if isinstance(sb, dict) and sb.get("enabled") is True and "autoAllowBashIfSandboxed" not in sb:
        add("BREAK", path, "sandbox.enabled=true 但未設 autoAllowBashIfSandboxed:v2.1.324 起預設 false,"
            "沙箱內 Bash 會開始跳出權限詢問(無人值守時會被拒)")
    perms = data.get("permissions") if isinstance(data.get("permissions"), dict) else {}
    for lst, rule in walk_rules(perms):
        if lst == "allow" and re.match(r'^Bash\([A-Z_][A-Z0-9_]*=\*', rule):
            add("CHECK", path, f"allow 規則 {rule!r} 在變數值使用 *:v2.1.323 起啟動時會警告,請改成明確的值")
        if lst == "allow" and re.match(r'^Bash\([^ )]+\*\)$', rule):
            add("CHECK", path, f"allow 規則 {rule!r} 為黏著式萬用字元:v2.1.323 起部分情況改為詢問,請改成 'Bash(cmd *)'")
    if "subagentStatusLine" in data:
        add("BREAK", path, "subagentStatusLine 已於 v2.1.323 移除,設定不再生效")
    if "pluginDigests" in data:
        add("BREAK", path, "pluginDigests 已於 v2.1.325 棄用並忽略,改以 managed 設定宣告與啟用的遠端 Marketplace 管理")
    if "agent" in data and path.endswith("plugin.json"):
        add("CHECK", path, "plugin.json 的 agent 不是有效欄位(claude plugin validate 判為未知欄位、不生效),"
            "子 Agent 請放 agents/ 目錄")
    env = data.get("env") if isinstance(data.get("env"), dict) else {}
    check_env_map(path, env)
    if path.endswith("plugin.json") and "engines" not in data:
        add("CHECK", path, "plugin.json 沒有 engines[\"claude-code\"]:v2.1.323 起可宣告支援的版本範圍,避免舊版載入")


def check_env_map(where, env):
    if env.get("ALL_PROXY") and not (env.get("HTTPS_PROXY") or env.get("https_proxy")):
        add("BREAK", where, "只設定 ALL_PROXY:v2.1.319 起憑證自動修復、v2.1.323 起組織設定與政策請求都不再使用它,請加設 HTTPS_PROXY")
    if env.get("MCP_SDK_GENERATION") == "v1":
        add("CHECK", where, "MCP_SDK_GENERATION=v1:v1 MCP 用戶端已移除,v2.1.323 起改為 v2 相容模式,請實測 OAuth 登入")
    if env.get("CLAUDE_CODE_DISABLE_1M_CONTEXT") is None and env.get("ANTHROPIC_BASE_URL"):
        add("CHECK", where, "使用自訂 ANTHROPIC_BASE_URL:v2.1.323 起無法辨識的模型 ID 預設視為 1M 視窗,"
            "若後端模型視窗較小請設 CLAUDE_CODE_DISABLE_1M_CONTEXT=1")


def check_script(path, text):
    for n, line in enumerate(text.splitlines(), 1):
        if re.search(r'claude\s+remote-control\b.*--(no-)?sandbox\b', line):
            add("BREAK", f"{path}:{n}", "claude remote-control 的 --sandbox/--no-sandbox 已於 v2.1.300 移除,傳入會直接結束")
        if re.search(r'claude\s+mcp\s+add-json\s+\S+\s+-\s*$', line.strip()):
            add("CHECK", f"{path}:{n}", "claude mcp add-json <name> - 從 stdin 讀取(v2.1.327+),在 Claude Code Session 內會被拒絕")
        if re.search(r'--permission-mode\s+auto', line) and re.search(r'\s-p\b|--print', line):
            add("CHECK", f"{path}:{n}", "-p 搭配 --permission-mode auto:Auto Mode 不可用時(v2.1.323 起)改以 Manual 啟動,"
                "需核准的動作會被拒,請檢查 permission_denials")


def main():
    ap = argparse.ArgumentParser()
    ap.add_argument("--env", action="store_true")
    ap.add_argument("files", nargs="*")
    a = ap.parse_args()
    for f in a.files:
        raw = open(f, encoding="utf-8").read()
        if f.endswith(".json"):
            try:
                data = json.loads(raw)
            except json.JSONDecodeError as e:
                has_sb = '"sandbox"' in raw
                add("BREAK" if has_sb else "CHECK", f,
                    f"不是合法 JSON({e.msg}):" + ("含 sandbox 鍵,v2.1.323 起以 --settings 傳入會拒絕啟動"
                                                    if has_sb else "以 --settings 傳入時會被靜默略過"))
                continue
            if isinstance(data, dict):
                check_settings(f, data)
        else:
            check_script(f, raw)
    if a.env:
        check_env_map("環境變數", dict(os.environ))
    for level, where, msg in FINDINGS:
        print(f"[{level}] {where}:{msg}")
    breaks = sum(1 for x in FINDINGS if x[0] == "BREAK")
    print(f"BREAK={breaks} CHECK={len(FINDINGS) - breaks}")
    sys.exit(1 if breaks else 0)


if __name__ == "__main__":
    main()

正向(第5.8章的 v3.0 Managed 範例)與反向(舊版設定+舊 CI 腳本+兩份無效 JSON)測試結果:

$ python check_upgrade.py fixtures/v3-managed.json fixtures/v3-user.json
BREAK=0 CHECK=0                                                          # 結束碼 0

$ python check_upgrade.py neg/upgrade-old-managed.json neg/upgrade-old-ci.sh bad-sandbox.json bad-nosandbox.json
[BREAK] neg/upgrade-old-managed.json:sandbox.enabled=true 但未設 autoAllowBashIfSandboxed:v2.1.324 起預設 false,沙箱內 Bash 會開始跳出權限詢問(無人值守時會被拒)
[CHECK] neg/upgrade-old-managed.json:allow 規則 'Bash(PORT=* npm run dev)' 在變數值使用 *:v2.1.323 起啟動時會警告,請改成明確的值
[CHECK] neg/upgrade-old-managed.json:allow 規則 'Bash(ls*)' 為黏著式萬用字元:v2.1.323 起部分情況改為詢問,請改成 'Bash(cmd *)'
[BREAK] neg/upgrade-old-managed.json:subagentStatusLine 已於 v2.1.323 移除,設定不再生效
[BREAK] neg/upgrade-old-managed.json:pluginDigests 已於 v2.1.325 棄用並忽略,改以 managed 設定宣告與啟用的遠端 Marketplace 管理
[BREAK] neg/upgrade-old-managed.json:只設定 ALL_PROXY:v2.1.319 起憑證自動修復、v2.1.323 起組織設定與政策請求都不再使用它,請加設 HTTPS_PROXY
[BREAK] neg/upgrade-old-ci.sh:3:claude remote-control 的 --sandbox/--no-sandbox 已於 v2.1.300 移除,傳入會直接結束
[CHECK] neg/upgrade-old-ci.sh:4:-p 搭配 --permission-mode auto:Auto Mode 不可用時(v2.1.323 起)改以 Manual 啟動,需核准的動作會被拒,請檢查 permission_denials
[BREAK] bad-sandbox.json:不是合法 JSON(Expecting property name enclosed in double quotes):含 sandbox 鍵,v2.1.323 起以 --settings 傳入會拒絕啟動
[CHECK] bad-nosandbox.json:不是合法 JSON(Expecting property name enclosed in double quotes):以 --settings 傳入時會被靜默略過
BREAK=6 CHECK=4                                                          # 結束碼 1

⚠️ 注意:check_upgrade.py 的規則是從 Changelog 與官方文件整理出的「已知會改變行為的項目」,不是完整的相容性證明。它能保證這些已知項目不被漏掉;未知的變更仍要靠第33.5章的升級後實測。

30.11 本章審查與驗證清單

AI 產出項目❌ 常見錯誤✅ 正確做法人工如何驗證
新的檢查規則只寫規則,沒有反向 fixture每條規則至少一份會觸發它的反向 fixture執行反向 fixture,確認工具回報 FAIL
鍵名清單settings-keys.txt 多個版本沒更新每次大版本更新後從官方 Settings reference 重新擷取比對新舊清單差異,並重跑所有正向範例
CI 設定檢查只在本機跑、沒進 CI依第30.8章 workflow 在 PR 自動執行開一個故意寫錯的 PR,確認 CI 失敗
驗證範圍以為通過檢查工具就代表設定正確工具驗結構,人工驗意圖(第30.9章)依人工檢查表逐項確認
升級前掃描升級後才發現 Sandbox 開始詢問、代理失效升級前以 check_upgrade.py 掃描所有設定與 CI 腳本,處理所有 BREAK以第30.10章的反向 fixture 執行,確認 BREAK 數量與結束碼 1
已移除與棄用的鍵以為鍵還列在 Settings reference 就代表有效官方仍列出部分已移除的鍵(例如 taskOutputMaxChars),檢查工具需另外維護移除/棄用對照表以 neg/v3-project-bad.json 執行 check_settings.py,確認對已移除鍵報錯

第 31 章 Code Mode 與 Advisor:實驗性功能的導入評估

本章目標:讀完本章,你能說明 Code Mode 與 Advisor 各自改變了什麼、需要哪些條件、有哪些限制;能為組織寫出「試點或封鎖」的政策與對應設定;並能為 Code Mode 建立可被測試的 Hook 防線。兩者都標示為實驗性,任何版本都可能改變或移除,本章的建議以「可回退」為前提。

31.1 Code Mode 是什麼

一般情況下,Claude 每次只要求一個工具呼叫(Bash、Read、Edit…),讀完結果再決定下一步。開啟 Code Mode(v2.1.323+)後,Claude 改為寫一段 JavaScript,由 Claude Code 在你的 Session 中以 REPL 工具執行;一段程式碼可以平行執行多個指令、把前一個結果餵給下一個呼叫,並只把需要的部分回傳給 Claude。例如「把重試次數從 3 改成 5 並跑測試」可能變成:

const files = await $`rg -l "function retryPolicy" src`.text();
const target = files.trim().split("\n")[0];
await edit(target, "maxAttempts: 3", "maxAttempts: 5");
({ edited: target, tests: $`npm test -- retryPolicy`.nothrow() });

對話中你看到的仍是各個工具呼叫(例如 Edit 的 diff),程式碼本身要按 Ctrl+O 開啟 Transcript 檢視,展開 Code 列才看得到。適合的任務:同一修改重複套用到許多檔案、搜尋結果需要先過濾再給 Claude 看、多個彼此獨立的指令可同時執行。

31.2 啟用條件與限制

條件要求
版本v2.1.323 以上(與 Agent Teams 併用需 v2.1.326 以上),且為 native build
帳號與供應商Claude 訂閱或 Console 帳號,直接連 Anthropic API;Gateway、Bedrock、Claude Platform on AWS、Google Cloud(兩種)、Foundry 皆不可
組織未使用 HIPAA 設定或 Zero Data Retention
模型Opus 5.5、Sonnet 5.5、Haiku 5.5 或 Fable 5.2
介面終端機的互動 claude Session;-p、Agent SDK、VS Code 面板、Desktop、雲端 Session 都不支援
Windows需安裝 Git for Windows
其他設定apiKeyHelper、OpenTelemetry 匯出、DISABLE_TELEMETRY(關閉 feature flag 擷取)會讓 Code Mode 無法啟動

限制:Code Mode Session 只能在終端機、且 Code Mode 開啟時才能 resume;不能移到 Desktop 或轉為背景 Session,/fork 也不能啟動背景副本;不能使用 Remote Control、Claude in Chrome 與 Computer Use;等待中的程式碼最多執行 10 分鐘(背景執行最多 2 小時,需以 Auto 或 bypassPermissions 模式啟動)。

開啟與關閉:以環境變數 CLAUDE_CODE_EXPERIMENTAL_CODE_MODE=1 開啟,只認 shell、使用者設定與 --settings(專案與 Managed 設定不能替你開啟);任何來源(含 Managed)設為 0 都會讓它保持關閉。

# 試用一次(只影響這次啟動)
CLAUDE_CODE_EXPERIMENTAL_CODE_MODE=1 claude
# 第一次會要求確認「Yes, turn on Code Mode」,之後在 Session 頂端看到:
# Code Mode (experimental) is on · this session can be resumed only with Code Mode on
$env:CLAUDE_CODE_EXPERIMENTAL_CODE_MODE = "1"
claude

啟動失敗時,Session 頂端會顯示「Code Mode (experimental) isn’t available」與原因,/status 也會列出;常見原因與處理見官方 Code Mode 頁的對照表(例如「it only works directly with the Anthropic API」代表設了雲端供應商或自訂 ANTHROPIC_BASE_URL)。

31.3 權限、Hook 與稽核

Code Mode 不會繞過權限系統,但審查的粒度改變了:

權限模式審查方式
Auto分類器審查每一段程式碼(而非每個工具呼叫);執行期才算出的值(例如從搜尋結果取出的路徑)分類器看不到
其他模式程式碼不經審查就開始執行,其中每個「該模式下會詢問」的工具呼叫各自詢問你
所有模式程式碼中的每個工具呼叫,仍以原本的工具名稱經過 deny/ask 規則與 PreToolUse Hook

因此企業需要兩道 Hook:既有的 Bash Hook 必須能處理 cd 'app' && git push 形式的複合指令;另加一個 matcher 為 REPL 的 Hook 直接審查 tool_input.code。第12.7章提供了已測試的 block-repl-risky.sh 與測試 harness,並說明它的極限:正規式攔不住字串拼接或執行期組出的指令。Bash 規則比對的是指令文字,不論有無 Code Mode,Claude 都可能以規則未涵蓋的形式執行被拒的指令;不依賴指令文字的限制請用 Sandbox(第19章)。

稽核時要知道:Transcript 中每段程式碼是一列 Code,展開才看得到內容;若 PreToolUse Hook 無法執行或逾時,你會看到工具呼叫被拒;UserPromptSubmit Hook 可能擋下程式碼的輸出。

31.4 企業政策:封鎖或試點

封鎖(建議作為預設):在 Managed 設定加入下列內容。已經在 Code Mode 中的使用者會維持到結束或重啟,之後就無法再開啟,也無法 resume 先前的 Code Mode Session。注意 Managed 設定只能封鎖、不能替使用者開啟 Code Mode。

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_CODE_MODE": "0"
  }
}

試點:選 3~5 位熟悉 Hook 與權限設定的成員,條件如下:

  1. Managed 設定不設 0;試點者在個人設定設 1
  2. 試點者的使用者設定必須安裝第12.7章的 REPL Hook,並以 test_repl_hook.sh 驗證
  3. 只在非正式環境的 repo 使用;需要背景執行的長時間程式碼,評估是否接受 Auto 或 bypassPermissions 模式的風險
  4. 每週回報:任務類型、工具呼叫數變化、被 Hook 攔下的次數、是否發生「分類器看不到執行期值」的案例

📌 實務建議:Code Mode 需要 feature flag 擷取,且與 OpenTelemetry 匯出互斥——這代表試點期間試點者的 Session 不會出現在你的 OTel 儀表板。若稽核政策要求所有 Session 都必須有遙測,就只能封鎖。

31.5 Advisor 工具

Advisor(實驗性)讓 Session 的主模型在關鍵時刻向一個更強(或同級)的 Advisor 模型諮詢:通常是在決定方法之前、錯誤反覆出現時,以及宣告完成之前。適合「大部分回合是例行工作、但計畫品質決定成敗」的長任務,例如大型重構、反覆出現的除錯。

項目說明
供應商Anthropic API、Claude Platform on AWS、Claude Models on Google Cloud(Anthropic 代管;後兩者需 v2.1.300+);Bedrock、Google Cloud’s Agent Platform、Foundry 不可用
開啟方式/advisor <模型>(存成使用者設定的 advisorModel)、設定檔 advisorModel、單次 Session 的 --advisor <模型>(不列在 --help)
模型限制Advisor 的排名必須不低於主模型;例如主模型 Sonnet 5.5 可接受 Fable、Opus 5 以上、Sonnet 5.5
白名單不會呼叫被 availableModels 排除的 Advisor;--advisor 指定被排除的模型時直接結束
成本Advisor 讀取對話,以 Advisor 模型的費率另計 Token;訂閱方案計入用量上限,Fable Advisor 可能改計用量點數
關閉/advisor off;全面停用設 CLAUDE_CODE_DISABLE_ADVISOR_TOOL=1(advisorModel 被忽略、--advisor 不生效)

常見組合:Sonnet 主模型+Opus Advisor(例行工作用 Sonnet,計畫與完成檢查交給 Opus);Haiku+Opus(成本最低的強規劃組合);Opus+Opus(高風險任務的獨立複核)。

{
  "advisorModel": "opus"
}

⚠️ 注意:何時諮詢由模型自行決定,沒有設定可以強制或限制呼叫次數;要讓它更常或更少諮詢,只能在 Prompt 中說明。因此 Advisor 不能取代人工 Review 與 CI 關卡,它是降低「計畫錯誤」機率的輔助,不是品質保證。

31.6 導入評估清單

評估項目Code ModeAdvisor
供應商是否支援只支援直連 Anthropic APIAnthropic API、Claude Platform on AWS、Google Cloud(Anthropic 代管)
與遙測政策是否衝突是:不能與 OTel 匯出、DISABLE_TELEMETRY 併用否
是否改變權限審查粒度是:Auto 模式審查整段程式碼否
是否需要新 Hook是:REPL matcher否
成本影響可能減少回合數增加 Advisor Token
建議預設Managed 封鎖,小規模試點個人選用,白名單控管 Advisor 模型

31.7 本章審查與驗證清單

AI 產出項目❌ 常見錯誤✅ 正確做法人工如何驗證
Code Mode 政策設定在 repo 的 .claude/settings.json 寫 CLAUDE_CODE_EXPERIMENTAL_CODE_MODE: "1" 讓全員開啟專案與 Managed 設定都不能開啟;Managed 只能以 0 封鎖check_settings.py --scope project 會警告;以一般帳號啟動確認沒有出現 Code Mode 提示
Code Mode 的 Hook只靠 Bash Hook,或以為 REPL Hook 可攔住所有危險程式碼Bash Hook 處理複合指令+REPL Hook 審查程式碼+Sandbox 作為真正邊界執行 test_repl_hook.sh 正反向測試;以 Ctrl+O 展開 Code 列人工檢視
Code Mode 與遙測宣稱「試點期間的 Session 都有 OTel 紀錄」Code Mode 無法與 OTel 匯出併用,試點 Session 沒有遙測在試點者的 Session 執行 /status,確認遙測與 Code Mode 狀態
Advisor 設定在 Bedrock 環境設定 advisorModel 期待生效Advisor 只支援 Anthropic API、Claude Platform on AWS、Google Cloud(Anthropic 代管)Session 啟動時是否出現「Advisor Tool (experimental) is on」通知;/advisor 印出目前設定
Advisor 的角色把 Advisor 當成品質保證,取消人工 ReviewAdvisor 只是模型自行決定何時諮詢的輔助確認 PR 流程與 CI 關卡沒有因導入 Advisor 而移除

第 32 章 設定除錯與健康檢查

本章目標:當 CLAUDE.md、設定、Hook、MCP 或 Skill「好像沒生效」時,能依固定順序找出原因:先確認實際載入了什麼,再比對優先順序,最後以乾淨設定對照測試。並能在開發機與 CI Runner 上執行一支不呼叫模型的健康檢查腳本。本章整理自官方 Debug your configuration 頁面,並以 v2.1.327 實測補上兩個官方沒有明說的陷阱。

32.1 先看實際載入了什麼

設定問題九成是「檔案沒載入、從預期外的位置載入,或被另一個檔案覆寫」。先用以下指令看實際狀態,不要先改設定:

指令看什麼
/context(全螢幕用 /context all)Context 中的系統提示、工具、MCP 工具、子 Agent(含來源)、記憶檔、Skills、對話;先確認 CLAUDE.md/Rules/Skill 有沒有在裡面
/memory使用者與專案層級實際載入的記憶檔路徑、Auto Memory 資料夾與開關
/skills專案、使用者與 Plugin 來源的 Skills
/hooks目前生效的 Hook(v2.1.327 起含 --settings 提供的)
/mcp已連線的 MCP Server 與狀態
/permissions目前生效的 allow/deny 規則
/status生效的設定來源(含 Managed);v2.1.327 起另列損壞的 Agent/Skill/Command/Output Style、快捷鍵錯誤、不可用的 Sandbox、被忽略的權限設定與永遠不會命中的 Hook matcher
/doctor完整檢查並提出修正(套用前會詢問)
/debug [問題描述]開啟本 Session 的除錯紀錄,並請 Claude 依紀錄與設定路徑診斷
claude doctor(終端機)不開 Session 的唯讀診斷:安裝健康與無效的設定檔

32.2 設定沒生效的排查順序

flowchart TD
    A["症狀:設定/CLAUDE.md/Hook 沒生效"] --> B["/context 與 /status<br/>確認是否載入、來源為何"]
    B -->|沒載入| C["檢查位置與檔名<br/>(32.5 常見原因表)"]
    B -->|有載入但被覆寫| D["比對優先順序<br/>Managed > --settings > Local > Project > User"]
    B -->|有載入也沒被覆寫| E["claude --safe-mode<br/>排除客製化干擾"]
    E -->|問題消失| F["逐一恢復 CLAUDE.md/Hook/MCP/Plugin 找出元凶"]
    E -->|問題仍在| G["乾淨設定目錄對照測試<br/>(32.4)"]
    G -->|問題消失| H["原因在使用者或專案設定"]
    G -->|問題仍在| I["檢查 Managed 設定與環境變數<br/>/status、env"]

兩個重要觀念:設定檔儲存後會在檔案穩定一小段時間後自動套用到執行中的 Session,不需重啟(即使 .claude/ 是 Session 開始後才建立的);而 ~/.claude.json 與 ~/.claude/settings.json 是兩個不同的檔案——前者存 App 狀態與介面開關,permissions、hooks、env 寫在前者完全不會生效。

32.3 MCP 與 Hook 的排查

元件症狀檢查
MCP專案 Server 沒出現一次性核准被拒過 → claude mcp reset-project-choices 後重啟並核准
MCP某些目錄啟動就失敗command/args 用了相對路徑,會依啟動目錄解析 → 改絕對路徑
MCP已連線但 0 個工具/mcp 選 Reconnect;仍為 0 則 claude --debug=mcp,讀 ~/.claude/debug/<session-id>.txt 中 Server 的 stderr
MCP環境變數沒傳進 ServerServer 設定沒寫 env,且 Claude Code 傳給 stdio Server 的環境已移除部分敏感變數
Hook/hooks 看不到Hook 寫在獨立檔案(只有 Plugin 讀 hooks/hooks.json);或寫在 Skill frontmatter 但該 Skill 尚未被呼叫
Hook看得到但不觸發matcher 是陣列、工具名稱小寫或拼錯;以 claude --debug 觀察 Hook 評估過程

32.4 乾淨設定對照測試

第一步:claude --safe-mode。停用 CLAUDE.md、Skills、Plugins、Hooks、MCP、自訂指令與 Agent、Output Styles、快捷鍵等客製化;登入、模型、內建工具與權限照常。注意:Managed Hook 與 Managed 的設定政策仍然套用,Managed 的 Plugin、Skill、CLAUDE.md 與 MCP 則會關閉。問題消失,代表原因在被停用的項目之一。

第二步:乾淨的設定目錄。在沒有任何 Claude Code Session 執行時:

mkdir -p ~/claude-clean/empty && cd ~/claude-clean/empty
CLAUDE_CONFIG_DIR=~/claude-clean/config claude --setting-sources user
New-Item -ItemType Directory -Force "$HOME/claude-clean/empty" | Out-Null
Set-Location "$HOME/claude-clean/empty"
$env:CLAUDE_CONFIG_DIR = "$HOME/claude-clean/config"
claude --setting-sources user
# 結束後務必還原,否則同一個 PowerShell 視窗之後的 claude 都會用乾淨目錄
Remove-Item Env:CLAUDE_CONFIG_DIR

第一次啟動會重新走首次設定畫面,這是乾淨目錄生效的證據。Managed 設定仍會套用,以 claude.ai 帳號登入時連接器也仍會載入。若問題消失,把 ~/.claude.json 與 ~/.claude 內的檔案一次一個複製進 ~/claude-clean/config 找出元凶;若問題仍在,原因在使用者與專案設定之外——用 /status 檢查 Managed 設定,並檢查 shell 的環境變數。

32.5 常見原因對照表

症狀原因修正
Hook 從不觸發matcher 是 JSON 陣列單一字串,以 | 分隔多個工具,例如 "Edit|Write"
Hook 從不觸發matcher 用 , 分隔、版本早於 v2.1.191改用 | 或升級
Hook 從不觸發matcher 小寫("bash")區分大小寫:Bash、Edit、Write、Read
全域的權限或 Hook 被忽略寫在 ~/.claude.json改寫到 ~/.claude/settings.json
settings.json 的值好像被忽略settings.local.json 設了同一個鍵Local 覆寫 Project,兩者都覆寫 User
Skill 沒出現在 /skills檔案放在 .claude/skills/name.md改為資料夾:.claude/skills/name/SKILL.md
Skill 出現但 Claude 從不呼叫disable-model-invocation: true,或描述與你的說法不符/skills 中「user-only」標記代表 Claude 不會自行觸發
子目錄 CLAUDE.md 好像被忽略子目錄檔案按需載入請 Claude 讀取該子目錄的其他檔案
子 Agent 忽略 CLAUDE.md內建 Explore/Plan 不讀;自訂子 Agent 設了 omitClaudeMd把約束寫進委派 Prompt
.mcp.json 的 Server 從不載入放在 .claude/ 下,或用了 VS Code 的 servers 鍵repo 根目錄 .mcp.json,鍵為 mcpServers
在 settings.json 寫 mcpServers 沒作用settings.json 不讀這個鍵用 .mcp.json 或 claude mcp add --scope user
Bash(rm *) 擋不住 /bin/rm 或 find -deleteBash 規則比對指令字串,不是實際執行檔以 PreToolUse Hook 或 Sandbox 限制
(v3.0 實測)拼錯的頂層鍵(如 permisions)claude doctor 與 /status 都不會報,整個區段靜默無效以 check_settings.py 檢查未知鍵(第30.3章)
(v3.0 實測)claude doctor 回報 Invalid settings 但腳本判定成功claude doctor 在設定檔是無效 JSON 時結束碼仍為 0腳本要檢查輸出中的「Invalid settings」,不能只看結束碼

32.6 一鍵健康檢查腳本

下列腳本不呼叫模型、不修改任何檔案,可放進新人 Onboarding、開發機定期檢查或 CI Runner 的第一步。它整合版本下限、登入狀態與到期日(不印 email)、claude doctor、以及第30章的 check_settings.py/check_upgrade.py/check_mcp.py。在 Git Bash(Windows)與 Linux 皆可執行;Windows 上 python3 可能是 Microsoft Store 的佔位程式,請以 PYTHON=python 指定。

#!/usr/bin/env bash
# claude-healthcheck.sh:不呼叫模型、不修改任何檔案的本機健康檢查
# 用法:[PYTHON=python] bash claude-healthcheck.sh [最低版本,預設 2.1.325] [檢查工具目錄,預設 ./checkers]
# 結束碼:0 = 全部通過;1 = 至少一項 FAIL
set -u
MIN="${1:-2.1.325}"
CHK="${2:-./checkers}"
PY="${PYTHON:-python3}"   # Windows 上 python3 可能是 Store 佔位程式,可設 PYTHON=python
export PYTHONIOENCODING=utf-8
fail=0
ok()  { echo "[ OK ] $*"; }
bad() { echo "[FAIL] $*"; fail=1; }

# 1. 版本是否達到團隊下限
ver=$(claude --version 2>/dev/null | awk '{print $1}')
if [ -z "$ver" ]; then bad "找不到 claude 指令"; exit 1; fi
lowest=$(printf '%s\n%s\n' "$MIN" "$ver" | sort -V | head -n1)
if [ "$lowest" = "$MIN" ]; then ok "版本 $ver(下限 $MIN)"; else bad "版本 $ver 低於下限 $MIN,請執行 claude update"; fi

# 2. 登入狀態與到期日(只印需要的欄位,不印 email)
claude auth status 2>/dev/null | "$PY" -c '
import json, sys
from datetime import datetime, timezone
d = json.load(sys.stdin)
print("[INFO] loggedIn=%s authMethod=%s apiProvider=%s" % (d.get("loggedIn"), d.get("authMethod"), d.get("apiProvider")))
exp = d.get("loginExpiresAt")
if exp:
    days = (datetime.fromisoformat(exp.replace("Z", "+00:00")) - datetime.now(timezone.utc)).days
    print("[INFO] 登入將於 %d 天後到期(%s)" % (days, exp))
sys.exit(0 if d.get("loggedIn") else 1)
' || bad "尚未登入或無法讀取 claude auth status"

# 3. claude doctor(唯讀診斷)。實測 v2.1.327:設定檔是無效 JSON 時結束碼仍為 0,
#    只在輸出列出「Invalid settings」,所以必須檢查輸出內容,不能只看結束碼
doc=$(claude doctor 2>&1 </dev/null)
if printf '%s' "$doc" | grep -q "Invalid settings"; then
  bad "claude doctor 列出 Invalid settings:"
  printf '%s\n' "$doc" | sed -n '/Invalid settings/,/^$/p' | sed 's/^/       /'
else ok "claude doctor 未列出無效設定"; fi

# 4. 以第30章工具檢查使用者、專案、本機設定檔
check() { # $1=檔案 $2=scope
  [ -f "$1" ] || return 0
  if "$PY" "$CHK/check_settings.py" --scope "$2" "$1" >/dev/null; then ok "check_settings $2:$1"
  else bad "check_settings $2:$1(執行 $PY $CHK/check_settings.py --scope $2 $1 看細節)"; fi
  if "$PY" "$CHK/check_upgrade.py" "$1" >/dev/null; then ok "check_upgrade:$1"
  else bad "check_upgrade:$1 有升級後會改變行為的設定"; fi
}
check "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/settings.json" user
check ".claude/settings.json" project
check ".claude/settings.local.json" local
[ -f .mcp.json ] && { "$PY" "$CHK/check_mcp.py" .mcp.json >/dev/null && ok "check_mcp:.mcp.json" || bad "check_mcp:.mcp.json"; }

[ "$fail" = 0 ] && echo "RESULT=PASS" || echo "RESULT=FAIL"
exit "$fail"

v3.0 在 v2.1.327 上的三次實測(路徑已縮寫):

# 情境 1:正常的專案設定
[ OK ] 版本 2.1.327(下限 2.1.325)
[INFO] loggedIn=True authMethod=claude.ai apiProvider=firstParty
[INFO] 登入將於 25 天後到期(2026-12-13T06:10:19.982Z)
[ OK ] claude doctor 未列出無效設定
[ OK ] check_settings user:~/.claude/settings.json
[ OK ] check_upgrade:~/.claude/settings.json
[ OK ] check_settings project:.claude/settings.json
[ OK ] check_upgrade:.claude/settings.json
RESULT=PASS                                   # 結束碼 0

# 情境 2:專案設定是無效 JSON(尾逗號)
[FAIL] claude doctor 列出 Invalid settings:
       Invalid settings
       - …\.claude\settings.json: Invalid or malformed JSON
[FAIL] check_settings project:.claude/settings.json(執行 python ./checkers/check_settings.py --scope project .claude/settings.json 看細節)
RESULT=FAIL                                   # 結束碼 1

# 情境 3:版本下限 2.1.400+舊版專案設定
[FAIL] 版本 2.1.327 低於下限 2.1.400,請執行 claude update
[FAIL] check_settings project:.claude/settings.json(…)
[FAIL] check_upgrade:.claude/settings.json 有升級後會改變行為的設定
RESULT=FAIL                                   # 結束碼 1

⚠️ 注意:本腳本的第一版以 claude doctor 的結束碼判斷;實測情境 2 的 claude doctor 結束碼為 0,第一版因此會把無效設定判為通過——這正是 32.5 表中最後一列的陷阱。任何「AI 寫的檢查腳本」都要用反向案例驗證過,才能放進 CI。

32.7 本章審查與驗證清單

AI 產出項目❌ 常見錯誤✅ 正確做法人工如何驗證
設定問題的診斷一開始就修改設定或重灌先 /context、/status 看實際載入狀態,再依 32.2 流程縮小範圍要求診斷報告附上 /status 與 /context 的輸出
健康檢查腳本以 claude doctor 的結束碼判斷設定是否有效檢查輸出中的「Invalid settings」,並以 check_settings.py 補抓拼錯的鍵放一份尾逗號的設定檔,確認腳本回報 FAIL
乾淨設定測試在 PowerShell 設了 CLAUDE_CONFIG_DIR 後忘記還原測試後 Remove-Item Env:CLAUDE_CONFIG_DIR在同一視窗執行 claude auth status,確認 configDirectory 已回到原處
診斷結論以 --safe-mode 正常就斷定「Managed 設定沒問題」Safe mode 仍套用 Managed Hook 與政策;Managed 問題要看 /status在 Safe mode 中執行 /status 確認 Managed 來源

第 33 章 v2.1.300~v2.1.327 升級指引與相容性

本章目標:把 v2.1.299 → v2.1.327 的升級當成一次受控變更:先掃描會改變行為的設定,依風險分級處理,分階段推出,最後以實測證明升級成功。本章的流程與工具也適用於之後的每一次大版本升級。

33.1 升級風險分級

等級變更版本不處理的後果遷移做法
BREAKsandbox.autoAllowBashIfSandboxed 預設 falsev2.1.324沙箱內 Bash 開始詢問;無人值守流程被拒明確設定 true(最高層級 Managed 來源)或接受新行為並補 allow 規則(19.5)
BREAK只有 ALL_PROXY 時組織設定與政策請求不走代理v2.1.323Managed/Server-managed 設定可能取不到加設 HTTPS_PROXY(28.6)
BREAKclaude_code.safety_event 停止送出v2.1.312安全告警靜默失效改用 tool_decision(20.5)
BREAKsubagentStatusLine 移除、pluginDigests 忽略v2.1.323/v2.1.325設定不再生效刪除並改用替代做法(5.8、27.7)
BREAKremote-control 的 --sandbox/--no-sandbox 移除v2.1.300腳本直接失敗改在設定寫 sandbox.enabled
BREAKOpus 4.8 Fast Mode 移除(2026-11-30)公告 v2.1.316請求直接錯誤改用 Opus 5.5
BREAK含 sandbox 鍵的無效 --settings 拒絕啟動v2.1.323CI 啟動失敗(這是正確的失敗)修正 JSON,CI 先驗證設定檔
CHECKbest 改指 opus、fable 改指 Fable 5.2v2.1.321成本與能力假設改變檢查腳本中的別名,需要特定版本就寫完整 ID
CHECKAuto Mode 不可用時改以 Manual 啟動v2.1.323-p 任務未完成但結束碼 0CI 以 gate_result.py 檢查 permission_denials(29.8)
CHECK未知模型 ID 預設 1M 視窗v2.1.323Gateway 後小視窗模型長對話失敗設 CLAUDE_CODE_DISABLE_1M_CONTEXT=1(2.8)
CHECKBash allow 規則的萬用字元判斷更嚴格(Bash(ls*)、Bash(PORT=* …))v2.1.323部分指令開始詢問改寫成 Bash(ls *) 與明確值
CHECK未信任 repo 的唯讀 git 指令會詢問v2.1.325跨 repo 查詢被打斷以 --add-dir 指名(17.6)
CHECKv1 MCP 用戶端移除v2.1.323舊 Server 的 OAuth 登入可能失敗實測登入流程(13.7)
CHECKServer-managed settings 不需使用者核准即套用v2.1.316錯誤設定立即影響全員先發布到測試組織(28.6)

33.2 升級前掃描

以第30.10章的 check_upgrade.py 掃描所有會被載入的設定檔與 CI 腳本,並對執行環境的變數做 --env 檢查:

python check_upgrade.py \
  /etc/claude-code/managed-settings.json \
  ~/.claude/settings.json \
  .claude/settings.json .claude/settings.local.json \
  .claude-plugin/plugin.json \
  ci/*.sh
python check_upgrade.py --env          # 在 CI Runner 與代表性開發機上各執行一次

結束碼 1(有 BREAK)就不進入下一階段。CHECK 項目逐一由負責人在升級工單上註記「已確認不受影響」或「已調整」。

33.3 分階段升級流程

flowchart LR
    S0["0 掃描<br/>check_upgrade.py"] --> S1["1 處理 BREAK<br/>設定 PR + Review"]
    S1 --> S2["2 試點<br/>3-5 台開發機 latest 通道"]
    S2 --> S3["3 實測<br/>33.5 驗收腳本"]
    S3 -->|通過| S4["4 調整版本區間<br/>minimumVersion 與 stable 通道"]
    S3 -->|失敗| S1
    S4 --> S5["5 全面推出<br/>健康檢查 32.6"]
階段產出(結案證據)
0 掃描check_upgrade.py 的完整輸出存檔
1 處理 BREAK設定變更的 PR 連結,Review 通過
2 試點試點機器清單與 claude --version
3 實測33.5 各項的結果 JSON 與 gate_result.py 輸出
4 版本區間Managed 設定中 minimumVersion、autoUpdatesChannel 的變更 PR
5 全面推出健康檢查腳本在代表性機器上的 RESULT=PASS 紀錄

33.4 遷移範例

Sandbox(維持免詢問)——舊設定:

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

新設定(放在最高層級的 Managed 來源):

{
  "sandbox": { "enabled": true, "failIfUnavailable": true, "autoAllowBashIfSandboxed": true }
}

代理——舊:"env": { "ALL_PROXY": "http://proxy.corp.example:8080" };新:

{
  "env": {
    "ALL_PROXY": "http://proxy.corp.example:8080",
    "HTTPS_PROXY": "http://proxy.corp.example:8080"
  }
}

Bash allow 規則——舊:"Bash(ls*)"、"Bash(PORT=* npm run dev)";新:

{
  "permissions": {
    "allow": ["Bash(ls *)", "Bash(PORT=3000 npm run dev)"]
  }
}

CI 腳本——舊:

claude remote-control --no-sandbox --name ci-runner
claude -p --permission-mode auto --max-turns 5 "Run the unit tests and summarize failures"

新(Sandbox 改由設定控制;結果交給關卡判斷):

claude remote-control --settings ci/remote-control-settings.json --name ci-runner
claude -p --permission-mode auto --max-turns 5 --output-format json \
  "Run the unit tests and summarize failures" < /dev/null > result.json || true
python gate_result.py result.json

33.5 升級後實測

升級到新版本後,在試點機器上依第29.8章的做法,至少重跑下列四項(每項含對照組),把結果 JSON 存成升級工單的附件:

項目預期判斷依據
基本 -p 呼叫is_error=false、modelUsage 為預期模型gate_result.py --allow-model … 結束碼 0
團隊的封鎖 Hook有 Hook 被拒、無 Hook 的對照組成功產出物+permission_denials
Sandbox 行為依你在 33.1 的決定:免詢問或依規則詢問/sandbox Mode 分頁;-p 的 permission_denials
Managed 設定載入/status 列出預期的 Managed 來源截圖或 claude doctor 輸出

📌 實務建議:把 33.2 的掃描與 33.5 的實測寫成固定的「升級 Runbook」,每次調整 minimumVersion 前都執行一次。v3.0 的經驗是:真正會出事的不是新功能,而是預設值的翻轉與被靜默忽略的設定。

33.6 本章審查與驗證清單

AI 產出項目❌ 常見錯誤✅ 正確做法人工如何驗證
升級計畫只列新功能,沒有列預設值變更與移除項目以 33.1 的 BREAK/CHECK 分級,每項有遷移做法與負責人對照 check_upgrade.py 的輸出,確認每個 BREAK 都有對應處理
遷移設定為了維持舊行為把 autoAllowBashIfSandboxed: true 寫在 repo 設定放在最高層級 Managed 來源,並記錄風險接受以一般帳號開啟 /sandbox 檢查 Mode;/status 看設定來源
升級驗收以「升級後大家沒抱怨」當作驗收33.5 的四項實測+結果 JSON 存檔檢查升級工單是否附上結果 JSON 與 gate_result.py 輸出
版本區間直接把 minimumVersion 拉到最新版試點與實測通過後再調整,並保留回退版本檢查 Managed 設定 PR 的時間是否晚於實測紀錄

附錄 A:常見問題 FAQ

Q1:Claude Code 可以離線使用嗎? 不行,目前需要連線到 Anthropic(或企業設定的第三方雲端,如 Bedrock/Google Cloud’s Agent Platform/Foundry,或企業的 LLM Gateway)才能運作。需要放行的網域見第28.3章。

Q2:為什麼長對話後 Agent 好像「忘記」之前的決定? 這通常是 Context 壓縮(第8.2章)造成的:根目錄 CLAUDE.md 與沒有 paths 的 Rules 會在壓縮後重新載入,但對話中提過的決定與有 paths 的 Rules 會被摘要掉。重要約束請寫進根目錄 CLAUDE.md。

Q3:Claude Code CLI 與 Claude 桌面版/網頁版有什麼不同? 它們共用同一個引擎。CLI 功能最完整(腳本化、Agent SDK、第三方供應商);Desktop 提供圖形化 Diff、多 Session、App 預覽;網頁版在雲端執行、離線後持續運作。詳見第1.6章。

Q4:費用突然飆高該怎麼排查? 先用 /usage 看是哪個 Skill/Subagent/Plugin/MCP 在消耗;再檢查是否有排程任務(/loop)在閒置時反覆送出完整 Context、或有失控的背景任務;組織層級以 OpenTelemetry 依使用者與 skill.name 拆解(第20章)。

Q5:MCP Server 連不上怎麼辦? 先用 claude mcp list/claude mcp get <name> 看狀態;最常見的原因是 .mcp.json 寫了 url 卻沒有 "type": "http"(會被當成 stdio 略過),或專案 Server 還沒核准(第13.6章)。

Q6:個人 API Key 和 Team/Enterprise 帳號可以混用嗎? 技術上可以,但要注意:環境中有 ANTHROPIC_API_KEY 時,Claude Code 在你核准一次後會優先使用 API Key 而非訂閱登入(第4.6章)。企業治理上不建議混用。

Q7:子 Agent 一直沒被自動選用? 檢查 description 是否具體描述用途與時機;也可以在提示中用 @ 選單指定,或以 --agent 讓整個 Session 以該子 Agent 執行(第10.3章)。也要確認 frontmatter 沒有拼錯而被靜默忽略。

Q8:可以強制阻止 Agent 執行某些危險指令嗎? 可以,以 permissions.deny(第6.6.3章)擋常見寫法、PreToolUse Hook(第12章,記得用 exit 2)做進一步判斷、Sandbox(第19.4章)限制破壞範圍,三層搭配,再加上伺服器端的分支保護。

Q9:什麼時候該用 Agent Teams 或 Dynamic Workflows,而不是派生幾個 Subagent? 工作者之間需要互相協調時考慮 Agent Teams(實驗性);需要數十到數百個 Agent、或希望編排邏輯可重複審查時考慮 Dynamic Workflows;單純的側支任務用 Subagent 即可(第26章)。

Q10:Skill 跟 Subagent 該怎麼選? 需要「獨立工具權限/獨立 Context」用 Subagent;需要「可重用的多步驟程序或檢查清單」用 Skill(第27.1章)。

Q11:公司要求啟用 Sandbox 或 Zero Data Retention,該怎麼設定? Sandbox 以 Managed 設定 sandbox.enabled 加上 failIfUnavailable: true 強制(原生 Windows 不支援,需用 WSL2,第19.4、28.2章);ZDR 不包含在標準 Enterprise 方案中,需由 Anthropic 確認資格後個別啟用(第28.4章)。

Q12:Auto Memory 跟 CLAUDE.md 重複了嗎? 不重複:CLAUDE.md 是你寫給 Claude 的規則(建置指令、規範);Auto Memory 是 Claude 自己記下的偏好、糾正、進行中的工作與外部資源位置,並且刻意不記能從程式碼推導的內容(第11.5章)。

Q13:執行 /agents 沒有跳出管理面板,是不是壞掉了? 不是。v2.1.198 起 /agents 不再開啟面板,請直接請 Claude 建立子 Agent 檔案,或編輯 .claude/agents/(第10.3章)。

Q14:為什麼 Subagent 執行時看起來像是「背景執行」? 互動式 Session 的 Fork Mode 預設開啟(v2.1.232 起),Claude 派生的 Subagent 一律在背景執行;權限提示會出現在主 Session(第9.4章)。

Q15:我的 Claude Code 一啟動就是 Auto Mode,是被入侵了嗎? 不是。v2.1.283 起,終端機與 VS Code 互動 Session 的內建起始模式在所有方案上都是 auto。想改回逐次詢問,在使用者或 Managed 設定加 "permissions": {"defaultMode": "default"}(狀態列會顯示 manual mode);注意寫在專案設定的 auto/bypassPermissions 不會生效(第6.6章)。

Q16:/fork、/subtask、/branch 有什麼不同? /subtask 啟動繼承完整上下文的 Subagent、結果回到目前對話;/fork 把整個 Session 複製成新的背景 Session;/branch 在目前終端機分出另一條對話並切換過去。Agent View 關閉時 /fork 會退回舊行為(第9.9章)。

Q17:我自己開的兩個終端機 Session 可以互相通知進度嗎? 可以,這是「跨 Session 訊息傳遞」:macOS/Linux/WSL2 需 v2.1.224+、原生 Windows 需 v2.1.234+。執行 /list-agents 看可觸及的 Session,或在提示中用 @ 指定對象(第9.10章)。

Q18:claude ultrareview、/code-review、/code-review ultra、/ultrareview 是同一個功能嗎? /code-review(別名 /review)是本機背景審查;/code-review ultra、/ultrareview(別名)與 claude ultrareview(非互動)是同一套雲端多 Agent 深度審查(第17.4章)。

Q19:我寫的 Hook 好像從來沒擋下過任何東西? 最常見的三個原因:(1) 設定用了 handlers 而不是 hooks,或 matcher 寫成 Bash(rm -rf:*);(2) 腳本以 exit 1 表示阻擋(只有 exit 2 會擋);(3) 依賴的 jq 不存在而腳本默默放行。用第12.6章的 harness 測試,並加上 "onFailure": "block"。

Q20:repo 裡已經有給其他 AI 工具用的 AGENTS.md,還需要 CLAUDE.md 嗎? 不一定。v2.1.277 起,專案沒有 CLAUDE.md 時 Claude Code 會直接讀 AGENTS.md;兩者都存在時預設只讀 CLAUDE.md,可在 CLAUDE.md 中寫 @AGENTS.md 或在 /config 的 Project instructions 調整(第11.7章)。

Q21:預設模型是哪一個?我需要手動選 Fable 嗎? default 在 Anthropic API 與各訂閱方案皆為 Opus 5.5(Foundry 為 Sonnet 4.5)。Fable 5.2 是最強的模型、適合長時間自主任務,但不是任何方案的預設,需以 /model fable 或 --model fable 明確選擇;best 自 v2.1.321 起等同 opus,不會自動選到 Fable(第5.6章)。

Q22:我在 settings.json 寫了 effortLevel,為什麼 Opus 5.5 沒有套用? 使用者設定中的 effortLevel 是 v2.1.251 以前 /effort 寫入的舊格式,對 Opus 5.5 之後的模型不生效;請用 /effort 為該模型儲存等級(寫入 modelSettings),或把 effortLevel 寫在專案、Managed 設定中(第5.6章)。


附錄 B:詞彙表 Glossary

術語說明
AgentClaude Code 的主互動 Session,具備自主規劃與工具呼叫能力
Sub Agent(Subagent)由主 Agent 派生、擁有獨立 Context 與工具權限的子工作者(第9、10章)
MCPModel Context Protocol,連接外部系統的開放標準(第13章)
Hook在生命週期事件中執行的腳本、HTTP 端點、MCP 工具或提示,用於治理與自動化;command Hook 以 exit 2 阻擋(第12章)
CLAUDE.md每次 Session 自動載入的專案上下文檔案(第11章)
AGENTS.md多種 AI 編碼工具共用的指令檔;Claude Code v2.1.277 起在沒有 CLAUDE.md 時直接讀取(第11.7章)
Context Window模型單次可處理的內容上限;目前主力模型為 1M Token
Compaction(壓縮)把較舊的對話摘要化以釋放 Context;另有閒置壓縮(Idle Compaction)在快取過期前自動進行(第8.2章)
Token模型計算內容長度與成本的基本單位
Tool Calling模型請求執行環境執行特定動作的協定機制
Permission Mode控制動作執行前是否詢問的模式:default(Manual)、acceptEdits、plan、auto、dontAsk、bypassPermissions(第6.6章)
Manual 模式default 權限模式在介面上的名稱,CLI 接受 manual 作為別名(v2.1.200+)
Auto Mode由獨立分類器模型在動作執行前審核、取代逐次詢問的權限模式;v2.1.283 起為終端機互動 Session 的內建起始模式(第6.6章)
Protected Paths.git、.claude 等除 bypassPermissions 外任何模式都不會自動核准寫入的路徑(第6.6章)
Critical Paths根目錄、家目錄、工作目錄等 rm/rmdir 的目標;任何 allow 規則或 Hook 都無法自動核准(第6.6章)
Settings Precedence多層設定合併時的優先順序:Managed > --settings > Local > Project > User(第5.2章)
Managed Settings企業透過 Server-managed、MDM、檔案型等管道強制套用、具最高優先序的設定(第5.5章)
Effort控制模型推理強度與成本的等級:low~max,另有 ultracode(第5.6章)
ultracode開啟自動 Dynamic Workflow 編排的設定;也是在提示中觸發 Workflow 的關鍵字(第26.3章)
FableClaude 最強的模型系列(Fable 5.2/5.1/5),適合長時間自主任務,不是任何方案的預設模型
Code Mode實驗性功能:Claude 改寫 JavaScript 一次呼叫多個工具,由 REPL 工具執行(第31章)
Advisor實驗性工具:主模型在關鍵時刻向更強的 Advisor 模型諮詢(第31.5章)
Projectsclaude.ai/code 與 Desktop 的長期協作對話,由 Claude 協調多個雲端 Thread 平行執行(第9.11章)
MCP Task執行超過門檻(預設 2 分鐘)的 MCP 工具呼叫自動轉為背景任務,結果以通知回傳(第13.7章)
SSDLCSecure Software Development Lifecycle,安全軟體開發生命週期
Agent View以 claude agents 開啟,集中監看與派發多個獨立背景 Session 的介面(研究預覽,第9.5章)
Supervisor託管背景 Session 的常駐程序,以 claude daemon 指令管理
Agent Teams多個 Session 共享任務清單並互相傳訊息協作的實驗性機制(第9.6、26.2章)
Dynamic Workflows由 Claude 撰寫、在背景執行的 JavaScript 編排腳本,可協調數十到數百個 Subagent(第9.7、26.3章)
WorktreeGit 的多工作目錄機制,讓平行任務在檔案系統層級彼此隔離;.worktreeinclude 可複製 gitignore 檔案(第9.8章)
Fork Subagent繼承主對話完整上下文的 Subagent,以 /subtask 啟動(第9.9章)
Fork Mode控制 Claude 能否自主派生 Fork、以及 Subagent 是否一律背景執行的開關,互動 Session 預設開啟
/fork//branch/fork 把整個 Session 複製成背景 Session;/branch 在目前終端機分出另一條對話(第9.9章)
跨 Session 訊息傳遞(Cross-session Messaging)讓 Claude 在你各別啟動的 Session 之間傳遞純文字訊息,經 ListAgents/SendMessage 運作(第9.10章)
Skill(SKILL.md)依需求載入的可重用程序,可被模型自動觸發或以 /skill-name 呼叫(第27章)
Plugin封裝 Skill、Subagent、Hook、MCP、LSP 的可分發單位,透過 Marketplace 安裝(第27.4章)
Mod以 JavaScript/TypeScript 事件處理器在 Claude Code 內部執行、能改寫介面與介入工具呼叫的 Plugin(v2.1.287+)
Sandbox作業系統層級的檔案/網路存取限制(macOS Seatbelt、Linux/WSL2 bubblewrap),原生 Windows 不支援(第19.4章)
Auto MemoryClaude 自動記錄的跨 Session 筆記(user/feedback/project/reference 四類),索引為 MEMORY.md(第11.5章)
.claude/rules/CLAUDE.md 的模組化延伸,可依 paths frontmatter 只在處理符合的檔案時載入(第11.6章)
Managed Policy CLAUDE.md部署在作業系統固定路徑、對全機所有使用者強制套用且無法排除的 CLAUDE.md(第11.2章)
Claude apps gateway官方可自架閘道,讓第三方雲端部署也能取得 Server-managed 設定、IdP 身分稽核與花費上限(第4.5.1章)
LLM Gateway統一路由/記錄多個 LLM 供應商呼叫的中介層之通用概念(第28.3章)
Corporate Launcher以 processWrapper 為背景 Agent 相關程序加上企業啟動包裝程式的治理機制(第5.4、28.1章)
自架執行環境(Self-hosted Environments)讓雲端 Session 執行在企業自有基礎設施的部署方式,以 claude self-hosted-runner 建置(第1.6章)
Headless 模式以 claude -p 非互動執行,用於腳本與 CI(第29章)
Agent SDK以 TypeScript/Python 程式化建構 Agent 的函式庫,與 claude -p 共用引擎(第29.7章)
反向測試(Negative Testing)故意放入錯誤,確認檢查工具會失敗,以證明檢查有效(第30.7章)

附錄 C:版本紀錄 Version History

版本日期說明
v1.02026-06-18首版發布,依官方文件與實務經驗整理完成 25 章內容
v1.12026-06-18對齊官方文件 2026-06 第24週(v2.1.176)內容:新增第26-28章(Agent進階協作模式/Agent Skills與Plugin生態/企業治理進階);修正 disallowAllHooks 應為 disableAllHooks 等設定鍵命名;補充第1.6、3.5、4.5、5.5、6.6、8.5、9.5-9.8、10.4-10.6、13.5、17.4、19.4、20.4、21.5 章節;目錄改為兩層巢狀連結
v1.22026-07-03對齊官方文件 2026-07 第27週(v2.1.199)內容,逐章核對並修正/擴充。修正 3 處明確錯誤:(1)第6.6章 Auto Mode 啟用方式(原「claude auto-mode enable」指令不存在,實為權限模式之一,且權限模式已由 3 種增為 6 種);(2)第10.3章「/agents 開啟管理面板」的說法已過時(v2.1.198 起不再開面板);(3)第11.2章本機限定檔名誤植(應為 CLAUDE.local.md,非 .claude.local.md)。新增章節:11.5 Auto Memory、11.6 .claude/rules/、4.5.1 Claude apps gateway、9.9 Fork Subagent、28.3.1 組織層級模型治理。大幅擴充:第5.4/5.5章設定鍵與 Managed 交付細節、第6章 CLI 指令與旗標(新增 claude gateway/mcp login/daemon status 等指令與 --bare/--teleport/--tools 等十餘個旗標)、第10.1章 Subagent frontmatter 完整欄位、第9章背景 Subagent 與巢狀派生行為。全文模型代稱由 claude-sonnet-4-6 更新為 claude-sonnet-5;同步修正目錄錨點與部分 Markdown 格式問題
v1.32026-08-14對齊官方文件與 Claude Code v2.1.224+ 內容(截至本次更新之官方 What’s New/CLI Reference/Settings/Agents/Admin Setup 頁面),逐章核對並修正/擴充。修正 4 處明確錯誤:(1)第9.4、9.9、10章 Subagent 巢狀派生深度上限,原「固定 5 層」已查無官方依據,官方文件實為「預設 3 層,可用 CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH 調整」;(2)第9.9章 Fork 機制大改版——/fork 自 v2.1.212 起不再是「繼承完整上下文的 Subagent」,該功能已改名 /subtask,/fork 重新定義為「複製整個 Session」(Agent View 關閉時例外退回舊行為);(3)第5.3/5.4章 effortLevel、modelOverrides 兩鍵經查證官方 Settings 文件已無依據,予以移除並修正範例;(4)第5.4/6.6章 autoMode 子鍵原寫作 classifyAllShell,官方文件實為 environment/allow/soft_deny/hard_deny。最重大變更:Auto Mode 已於 2026-08-14(本版更新當日) 成為 Pro/Max/Team 方案的預設權限模式(原僅為選擇性開通功能),第6.6章大幅改寫;Bedrock/Vertex/Foundry 亦已於 v2.1.207 起免除 CLAUDE_CODE_ENABLE_AUTO_MODE=1 的 Opt-in 需求。新增章節:9.10 跨 Session 訊息傳遞(Cross-session Messaging,全新官方功能,v2.1.224+)。新增內容:第1.6章自架執行環境(claude self-hosted-runner)、Desktop iOS 模擬器與內建瀏覽器、Artifacts MCP 連接器與公開分享;第4.4章 forceLoginMethod/forceLoginOrgUUID 涵蓋範圍細節;第5.4/28.1章 Corporate Launcher(processWrapper)、Cloud environments 組織雲端環境管理介面;第5.5章 env 跨 Managed 來源合併行為(v2.1.223+);第6.4/27.3章 claude doctor//doctor//checkup、claude import;第6.5章 --cloud 取代 --remote(列為棄用別名)、--append-subagent-system-prompt、--allow-dangerously-skip-permissions;第17.4章 /code-review 背景 Subagent 執行、/code-review ultra 與已棄用的 /ultrareview 別名;第19.2/27.4章 Claude Security Plugin、disableCommandPluginSources;第20.4/28.5章 Enterprise/Console Analytics API;第28.3章 LLM Gateway 與 Claude apps gateway 的概念釐清。全文交叉核對 TOC 錨點與 Markdown 格式(含 Blockquote 空行、表格對齊)問題
v2.02026-10-14對齊官方文件(2026-10-14 下載,逐章對照 121 頁)與 Claude Code v2.1.299 Changelog,並以本機 v2.1.296 的 --help 比對所有旗標,以「企業標準技術白皮書」等級全面改寫。結構:每章開頭新增「本章目標」、每章結尾新增「本章審查與驗證清單」(AI 產出項目/常見錯誤/正確做法/人工如何驗證);新增第29章 Headless 與 CI/CD 自動化、第30章 AI 產出驗證方法論、附錄G 查證紀錄;目錄改為三層並以 Hugo 實際錨點重建。修正明確錯誤(節錄,完整見附錄G.2):第12.4章 Hooks 設定誤用 handlers 鍵且 matcher 寫權限規則(原範例從未生效);第13.2章 .mcp.json 誤用 transport 鍵(Server 會被略過);第5.3章推翻 v1.3 對 effortLevel/modelOverrides/autoMode.classifyAllShell 的錯誤勘誤;第4.3章 ANTHROPIC_AUTH_TOKEN 用途誤植;第3.1章 npm 需 Node.js 22+(原寫 18);第6.4章 claude project purge 改為 claude purge、auto-mode reset 語意與 ultrareview 逾時(45 分鐘);第6.6章 Auto Mode 預設允許推送到任何分支、-p 達封鎖門檻不會中止、default 模式改稱 Manual;第7章權限對話框按鍵;第9.10章跨 Session 訊息已支援原生 Windows 與第三方供應商;第11.5章 Auto Memory 記錄範圍;第9.3章 claude kill 為 stop 別名;第26.3章 Workflow 的啟動方式。新增內容:預設模型 Opus 5.5/Sonnet 5.5/Haiku 5.5/Fable 5.1 與 Effort 解析(5.6)、v2.1.283 起 Auto Mode 為所有方案的內建起始模式(6.6.2)、權限規則語法與 autoMode 客製(6.6.3、6.6.4)、Slash Commands 速查(6.7)、內建工具與平台差異(2.6)、Session 儲存(2.7)、版本追蹤(1.7)、企業部署與版本鎖定(3.9)、認證優先順序(4.6)、managedSourcesBehavior/allowedProviders/maxEffortLevel/modelPicker、AGENTS.md(11.7)、Monorepo 記憶治理(11.8)、Hook 測試 harness(12.6)、Stop Hook 驗證關卡(14.5)、測試品質驗證(18.5)、Sandbox 的 failIfUnavailable 與管不到的範圍(19.4)、claude plugin eval(27.6)、Mods 與 allowManagedModsOnly(27.4)、網路放行清單與背景 Agent 的網路變數(28.3)、HIPAA 設定(28.4)。所有設定、Hook、MCP、Subagent、Skill、CI 範例皆以第30章工具實測,並以反向 fixture 證明檢查有效

| v3.0 | 2026-11-18 | 對齊官方文件(2026-11-18 下載 llms.txt 所列全部 205 頁)與 Claude Code v2.1.327 Changelog(v2.1.300~v2.1.327 約 380 項非修正類變更逐項分類),旗標以本機 v2.1.327 的 --help 全量比對。結構:保留第1~30章標題(錨點不變),各章以「(v3.0 新增)」小節補充並擴充審查清單;新增第31章 Code Mode 與 Advisor、第32章 設定除錯與健康檢查、第33章 v2.1.300~v2.1.327 升級指引、附錄H v3.0 查證紀錄。修正(節錄,完整見附錄H.2):fable 別名改為 Fable 5.2、best 改為等同 opus;只設 availableModels 不會約束 Default(需 enforceAvailableModels);平行方式由四種增為五種(Projects);allowedProviders 補 anthropicGoogleCloud;Sandbox 範例明確寫出 autoAllowBashIfSandboxed(v2.1.324 預設翻轉)。新增:v2.1.300~v2.1.327 變更地圖(1.8)、新設定鍵與已移除鍵(5.8)、Auto Mode 行為變更(6.6.5)、旗標補遺(6.8)、Projects(9.11)、Hook 行為與 Code Mode 的 REPL Hook(12.7)、MCP 變更(13.7)、Sandbox 變更(19.5)、OTel safety_event 停止送出(20.5)、Headless 實測(29.8)、check_upgrade.py(30.10)。驗證:8 項 claude -p --model haiku 實測(含對照組)、claude plugin validate 與 claude doctor 實測,發現並記錄 3 個官方未明說的行為(-p 中 denyInsteadOfPrompting 無額外效果、claude doctor 對無效 JSON 結束碼為 0、plugin.json 的 agent 為未知欄位) |

本手冊內容以穩定概念與指令為主;Claude Code 本身版本演進快速,建議定期關注官方 Changelog 與 What’s New 週報,並對照本手冊內容是否需要更新。v2.0 起,所有變更均逐項比對官方文件原文後才寫入,並在附錄G記錄依據來源、已執行的驗證與尚未驗證的項目;對官方頁面未明確標註版本號的細節,本手冊不臆測精確版本號。


附錄 D:學習路線圖

flowchart TD
    W1["第1週:安裝/認證/設定/指令<br/>(第1-7章)"] --> W2["第2週:Context/Agent/CLAUDE.md/Hook/MCP<br/>(第8-13章)"]
    W2 --> W3["第3週:情境實戰<br/>(第14-19章)"]
    W3 --> W4["第4週:成本/團隊/最佳實務<br/>(第20-25章)"]
    W4 --> W5["第5週:進階生態與企業治理<br/>(第26-28章)"]
    W5 --> W6["第6週:自動化與驗證<br/>(第29-30章)"]
    W6 --> W7["第7週:除錯、實驗功能與升級<br/>(第31-33章)"]
角色第1-2週重點第3-4週重點第5-6週重點
初階工程師安裝、基本指令、快捷鍵、CLAUDE.mdWeb 開發與驗證驅動流程(14.5)、測試品質(18.5)Skills 基礎(27.1-27.3)
架構師架構原理、MCP、Agent 系統逆向工程、Framework 升級、企業藍圖Agent 進階協作(第26章)
DevOps/SRE設定管理、權限模式、HooksSSDLC 與 Sandbox、成本管理Headless 與 CI/CD(第29章)、網路與 Gateway(28.3)
資安/稽核權限模式與 Auto Mode(6.6)、Hooks(第12章)SSDLC(第19章)、Git 守則(17.3)企業治理進階(第28章)、驗證方法論(第30章)
工程主管全章節速覽團隊導入、企業藍圖第21.5、21.7章治理檢查項、第33章升級程序、附錄H
平台/AI賦能團隊全章節速覽團隊導入、最佳實務第26-33章全章(Workflow 審查、Plugin 治理、Managed 交付、CI 檢查工具、Code Mode 政策、升級相容性)

每章結尾的「本章審查與驗證清單」可直接作為學習後的自我檢核:能說出每一列「人工如何驗證」的具體做法,代表已掌握該章。


附錄 E:與其他 AI 編碼工具比較表

⚠️ 本表只描述 2026-11 時各工具的定位,各產品功能每月變動;導入選型請以當下官方文件實測為準。

維度Claude Code CLICursorGitHub CopilotGemini CLI/Codex CLI
介面形態終端機為主,另有 Desktop/VS Code/JetBrains/Web 共用引擎IDE ForkIDE 行內 + Chat/Agent 模式,另有 Copilot CLI終端機
Agent 自主性高:背景 Session、Subagent、Agent Teams、Dynamic Workflows中高中高中高
Context 處理動態探索整個專案,不需預建索引;主力模型(Opus 5.5/Sonnet 5.5/Haiku 5.5/Fable 5.2)皆有 1M Token 上下文專案索引工作區索引與開啟分頁動態讀取
專案指令檔CLAUDE.md、.claude/rules/,並原生讀取 AGENTS.md規則檔copilot-instructions.md、AGENTS.mdAGENTS.md 等
MCP/外部整合原生支援,含核准目錄等企業管控支援支援支援
企業治理完整:多管道 Managed 設定、權限模式與 Auto Mode 分類器、Hooks、OS Sandbox、Gateway、OTel中等企業版有原則管控依產品而定
自動化claude -p、Agent SDK、GitHub Action、GitLab CI、Routines有限Copilot coding agent、ActionsCLI 腳本化
定價模式訂閱/API 用量/企業席位/雲端供應商訂閱制訂閱制API 用量或訂閱
適合場景大型重構、逆向工程、可驗證的自動化流程、企業治理要求高的環境IDE 內快速迭代即時補全與 IDE 內協作終端機任務自動化

附錄 F:Checklist(新人加入檢查清單)

安裝與認證

  • 已依第3章完成安裝,claude --version 在團隊規定的版本區間內,claude doctor 無錯誤
  • 已完成 claude auth login,claude auth status 的 authMethod 為團隊規定的登入方式
  • 已確認環境中沒有殘留的 ANTHROPIC_API_KEY 搶先使用(第4.6章)

設定與 CLAUDE.md

  • 已閱讀專案 .claude/settings.json,並以 /status 確認 Managed 設定來源
  • 已閱讀專案 CLAUDE.md(或 AGENTS.md),並以 /memory 確認實際載入的檔案
  • 已知道設定優先順序(Managed > --settings > Local > Project > User)
  • 已知道設定檔是嚴格 JSON,拼錯的鍵會被靜默忽略

權限與安全

  • 已了解六種權限模式,知道目前 Session 的起始模式(v2.1.283 起預設 auto)與如何切換(Shift+Tab)
  • 已知道安全規則由 deny 規則、Hook 與 Sandbox 強制,而非僅靠口頭約定
  • 已知道 Auto Mode 預設允許推送到任何分支,團隊的推送規則寫在哪裡
  • 已了解所有 AI 協作的程式碼變更仍需人工 Review

Agent、MCP 與擴充

  • 已了解 Subagent、Agent View、Agent Teams、Dynamic Workflows 的差異(第9.1章)
  • 已知道團隊共用子 Agent 在 .claude/agents/、Skill 在 .claude/skills/
  • 已了解已核准的 MCP Server 與 Plugin Marketplace 清單

日常操作

  • 會用 Esc 中斷、Esc Esc 回溯、/clear 切換任務
  • 會用 Plan 模式先規劃,並要求 Claude 附上驗證證據(第14.5章)
  • 已知道從第23章 Prompt Library 取用範本
  • 已知道平行任務應以 Worktree 隔離(第9.8章)

自動化(DevOps/平台人員)

  • CI 中的 claude -p 都設定了 --max-turns、--max-budget-usd、--permission-prompts none 與最小 --allowedTools
  • CI 檢查 is_error 與結構化結果,而不只看結束碼(第29.4章)
  • 變更 .claude/ 的 PR 會執行第30章的檢查工具

平台/企業治理團隊

  • 已確認 Managed 設定交付管道、managedSourcesBehavior 策略,並能用 /status 查驗(第5.5、28.1章)
  • 已決定 Auto Mode 起始模式政策(沿用 auto 或以 permissions.defaultMode 改回),並以 autoMode.environment 描述可信基礎設施(第6.6章)
  • 已在 Managed 設定強制 Sandbox(含 failIfUnavailable),並規劃原生 Windows 使用者的替代方案(第19.4、28.2章)
  • 已設定 allowedProviders、availableModels/deniedModels、maxEffortLevel(第4.4、5.6章)
  • 已建立已核准 Plugin Marketplace 清單與 Mods 政策(allowManagedModsOnly,第27.4章)
  • 已將 Agent Teams/Dynamic Workflows/跨 Session 訊息傳遞納入治理檢查項(第21.5章)
  • 已導入 OpenTelemetry 並以 modelPricing 校正金額(第20.4章)
  • 已確認 ZDR/HIPAA 適用範圍與本機 Transcript 保存期限(第28.4章)
  • 已指派每週追蹤 Changelog 與調整版本區間的負責人(第1.7、3.9章)

v3.0 新增檢查項

  • 升級前已執行 check_upgrade.py 並處理所有 BREAK(第33章)
  • 已決定 sandbox.autoAllowBashIfSandboxed 的值並寫在最高層級的 Managed 來源(第19.5章)
  • 只設定 ALL_PROXY 的環境已補上 HTTPS_PROXY(第28.6章)
  • 模型白名單已加 enforceAvailableModels: true,並以 /model 選 Default 驗證(第5.6章)
  • 已決定 Code Mode 政策(試點或以 Managed env 設 0 封鎖),並為 REPL 工具加上 Hook(第31章)
  • 新人知道設定沒生效時的排查順序:/context → /status → claude doctor → --safe-mode → 乾淨設定(第32章)
  • CI 的結果判斷關卡會檢查 permission_denials 與 terminal_reason,不只看結束碼(第29.8章)

附錄 G:v2.0 查證紀錄

本附錄記錄 v2.0 每一項內容的依據來源、已執行的驗證與尚未驗證的項目,供讀者判斷可信度,也作為下一次改版的起點。

G.1 官方文件對照範圍

查證日期 2026-10-14。官方 llms.txt 共列出 222 頁,本次下載其中 124 頁的原始 Markdown 逐章對照(另含 Changelog 至 v2.1.299 與 What’s New W13~W37):

章節對照的官方頁面
1 介紹overview、platforms、features-overview、how-claude-code-works、desktop、remote-control、routines、artifacts、claude-tag、slack、chrome、computer-use、whats-new(W33~W37)
2 架構how-claude-code-works、tools-reference、context-window、sessions、claude-directory
3 安裝setup、quickstart、troubleshooting
4 認證authentication、third-party-integrations、amazon-bedrock、google-vertex-ai、microsoft-foundry、claude-apps-gateway、claude-apps-gateway-config、claude-apps-gateway-spend-limits、gateways
5 設定settings、settings-reference(全部 245 個鍵與子鍵)、managed-settings、server-managed-settings、model-config、admin-setup
6 CLIcli-reference、commands、permission-modes、permissions、auto-mode-config、env-vars
7 快捷鍵interactive-mode、keybindings、terminal-config、fullscreen
8 Contextcontext-window、prompt-caching、checkpointing、memory
9-10 Agentagents、sub-agents、agent-view、agent-teams、workflows、worktrees、cross-session-messaging
11 CLAUDE.mdmemory、large-codebases
12 Hookshooks(全 33 個事件)、hooks-guide
13 MCPmcp、managed-mcp
14-18 實戰best-practices、common-workflows、goal、code-review、ultrareview
19 SSDLCsecurity、security-guidance、claude-security、sandboxing、sandbox-environments、devcontainer
20 成本costs、analytics、monitoring-usage
21-25 導入admin-setup、champion-kit、communications-kit、feature-availability
26-27 進階workflows、agent-teams、skills、plugins/overview、plugins/install、plugins/org、plugins/security、plugins/create、plugins/manifest-reference、plugins/marketplace-reference、plugins/cli-reference、plugin-evals、plugins/mods/overview、plugins/mods/admin
28 治理managed-settings、network-config、corporate-launcher、data-usage、zero-data-retention、hipaa-setup、llm-gateway、cloud-environments、self-hosted-environments
29 Headlessheadless、github-actions、gitlab-ci-cd、agent-sdk/overview、agent-sdk/agent-loop、agent-sdk/typescript;另比對 anthropics/claude-code-action@v1 的 action.yml

未逐頁對照的主要區塊:Agent SDK 其餘 30 頁、Mods 的介面/事件/API 細節頁、Claude apps gateway 部署細節(AWS/GCP)、自架執行環境的部署與設定細節頁、LLM Gateway 協定細節、Desktop 細部頁面。這些內容超出本手冊 CLI 範疇,僅在相關章節提及並指向官方文件。

G.2 v1.3 → v2.0 修正清單

#章節v1.3 內容v2.0 內容依據
112.4Hooks 設定使用 "handlers" 陣列,matcher 寫 "Bash(rm -rf:*)"鍵名為 "hooks";matcher 比對工具名稱;權限規則放 handler 的 "if"hooks(Configuration)
213.2.mcp.json 使用 "transport": "http"必須為 "type": "http",有 url 無 type 會被當成 stdio 略過mcp
35.3、5.4以「查無依據」移除 effortLevel、modelOverrides,並稱 autoMode.classifyAllShell 不存在三者皆為有效設定鍵settings-reference
45.3、6.6JSON 範例第一行放 // 註解設定檔為嚴格 JSON;-p 模式會靜默略過無效檔案settings、cli-reference
54.3ANTHROPIC_AUTH_TOKEN 註解為 OAuth Token為 LLM Gateway 用的 Bearer Token;OAuth Token 用 CLAUDE_CODE_OAUTH_TOKENauthentication
63.1npm 安裝需 Node.js 18+Node.js 22+setup
76.4claude project purgeclaude purgecli-reference、本機 --help
86.4claude auto-mode reset 清除快取的分類器判斷從使用者設定移除 autoMode 區段cli-reference
96.4claude ultrareview 預設逾時 30 分鐘45 分鐘;新增 --postcli-reference
106.6Pro/Max/Team 自 2026-08-14 預設 autov2.1.283 起所有方案的終端機互動 Session 內建起始模式皆為 autopermission-modes
116.6.1Auto Mode 預設封鎖直接推送到 main預設允許推送到目前 repo 任何分支(部署目標名稱的分支另行判斷)permission-modes
126.6.1-p 達封鎖門檻會中止 Session該動作不執行、Claude 繼續工作,Session 不中止permission-modes
136.5、6.6--permission-mode 稱 default 為預設模式介面名稱為 Manual,manual 為別名(v2.1.200+)permission-modes、本機 --help
146.5範例 claude --worktree ../billing-fix --tmux -p--worktree 接名稱/PR,不是路徑cli-reference
159.5、26.3範例 claude --bg -p "..."--bg 不可與 -p 併用cli-reference
167.3權限詢問按 y/n/a方向鍵選擇+Enter;y/n 預設綁定已於 v2.1.280 移除keybindings
179.3claude kill 為強制終止kill 是 stop 的別名cli-reference
189.10原生 Windows 與 Bedrock 等供應商不支援跨 Session 訊息原生 Windows v2.1.234+ 支援;同機傳訊所有供應商可用(v2.1.248+)cross-session-messaging
1910.1name 僅限小寫字母與連字號最多 256 字元、不可含 :sub-agents
2011.5Auto Memory 記錄建置指令與除錯線索只記 user/feedback/project/reference 四類,不記可從程式碼推導的內容memory
2126.3以 claude --bg -p "依本機 Workflow 腳本..." 啟動 Workflow以 ultracode 關鍵字、/effort ultracode 或已存的 Workflow 指令啟動;-p 提示不會觸發workflows
221.6、4.5「Vertex AI」官方已改稱 Google Cloud’s Agent Platform(環境變數仍為 CLAUDE_CODE_USE_VERTEX)google-vertex-ai
23全書模型代稱 claude-sonnet-5、預設 Sonnet 5/Opus 5default=Opus 5.5;別名對應 Opus 5.5/Sonnet 5.5/Haiku 5.5/Fable 5.1model-config
248.5Rewind 只有「Summarize up to here」另有 Restore code/conversation 的組合與「Summarize from here」checkpointing
255.5四種來源「套用第一個回傳非空設定的來源」預設 first-wins,另有 managedSourcesBehavior: "merge"、managed-settings.d/、Skipped sourcesmanaged-settings

G.3 已執行的驗證

驗證項目工具與環境結果
設定範例(7 份:專案、本機、Managed、Hooks、Auto Mode、MCP 政策、Sandbox)check_settings.py(Python 3.12)全數 OK
設定範例對照官方 JSON SchemaSchemaStore claude-code-settings.json + jsonschema全數通過,唯一差異為 schema 未收錄 onFailure(v2.1.295 新增)
手冊內所有 json 區塊(28 個)extract_blocks.py:JSON 解析+設定類區塊執行 check_settings0 個問題
手冊內所有 bash 區塊(51 個)bash -n 語法檢查0 個問題(修正 1 處佔位符語法)
yaml 區塊與 CI 範例PyYAML;actionlint 1.7.12全數通過
GitHub Action 輸入比對 anthropics/claude-code-action@v1 的 action.ymlprompt、anthropic_api_key、claude_args 皆存在
Hook 腳本(3 支)test_hooks.sh(Git Bash、jq 1.8.1)PASS=18 FAIL=0;反向測試(exit 2→1)PASS=11 FAIL=7
.mcp.json 範例check_mcp.pyOK;v1.3 範例被正確判定為錯誤
Subagent(2 份)與 Skill(1 份)check_agents.py(PyYAML 6.0.3)全數 OK;反向 fixture 全數被抓出
CI 審查關卡判斷邏輯claude-gate.sh + 3 份 fixture + 非 JSON 輸入結束碼 0/1/2/2 皆符合預期
CI 設定檢查 workflow在模擬 repo 中逐步執行全部步驟通過
CLI 旗標(全文 109 個)check_flags.py 比對本機 Claude Code v2.1.296 的 --help(19 個子指令)與官方文件未知 0 個;反向測試中故意拼錯的 enable-automode、max-turnz 兩個旗標皆被抓出
Mermaid 圖表(34 張)mermaid-cli 11.17.2(與網站的 mermaid@11 同大版本)全數渲染成功,無 Syntax error
目錄錨點Hugo v0.151.0 實際建置後比對所有 href="#..." 與標題 id見 G.5

G.4 尚未驗證與待查項目

依「只做離線驗證、不呼叫 claude -p」的範圍決定,以下項目僅以官方文件為依據、未實際執行:

#項目原因下次建議
1claude -p 的實際輸出欄位與 --json-schema 行為不呼叫 API以 --max-budget-usd 0.5 實跑一次,用輸出取代 fixture
2Auto Mode 分類器的實際封鎖/放行行為需要真實 Session以測試 repo 逐項驗證第6.6.1章清單
3Sandbox 實際限制(failIfUnavailable、credentials)本機為原生 Windows,不支援 Sandbox在 WSL2/Linux 實測第19.4章範例
4Agent Teams、Dynamic Workflows、/batch 實際執行需要真實 Session 與用量於試點專案小規模執行並記錄成本
5GitHub Actions/GitLab CI 範例在真實 runner 上執行需要 CI 環境與 API Key在測試 repo 實跑
6第12.4章 PowerShell Hook 所引用的 block-rm.ps1本手冊未提供該腳本補上 PowerShell 版本並以 Pester 測試
7v2.1.297~v2.1.299 新功能(閒置壓縮門檻變數、CLAUDE_CODE_DISABLE_FILE_MENTIONS、Agent View 中的 /effort)本機版本為 v2.1.296升級後實測
8claude plugin eval每次執行皆為真實模型呼叫以小型 Plugin 試跑
9隱藏旗標(--teammate-mode、--system-prompt-file 等 33 個未列於本機 --help)只以官方 CLI reference 確認存在實際執行確認接受
10第1.3章與附錄E的競品定位他廠產品功能變動快,未逐一查證選型時另行實測

G.5 目錄與格式驗證

  • 目錄由 build.py 依標題自動產生三層(章 → 節 → 小節),位於 <!-- TOC-AUTO-BEGIN --> 與 <!-- TOC-AUTO-END --> 之間。
  • 以 Hugo v0.151.0 實際建置網站,解析輸出 HTML,逐一比對頁面中每個 href="#..." 是否對應到實際產生的標題 id。
  • 以 repo 的 check-toc.ps1、check-md.ps1、test-mermaid-syntax.ps1 檢查目錄完整性與 Markdown 格式。

驗證結果(2026-10-14):

檢查v1.3v2.0
Hugo 輸出頁面的標題 id 數—269
頁內連結(href="#...")總數/不重複/無法解析—536/270/0
目錄項目數/與 Hugo 標題 id 不符兩層目錄265(三層)/0
內文「第 X.Y 章」文字引用/指向不存在的節—115/0
check-toc.ps1 [A] 連結無對應標題/[B] 編號標題未收錄/[C] 重複錨點—無/無/無
check-md.ps1 未標語言的程式碼區塊(MD040)70
check-md.ps1 其他格式問題6(MD032)0
test-mermaid-syntax.ps1—未發現語法問題
檔案編碼無 BOM、CRLF無 BOM、CRLF(全部行尾一致)

附錄 H:v3.0 查證紀錄

本附錄記錄 v3.0(v2.1.299 → v2.1.327)每一項內容的依據、已執行的驗證與尚未驗證的項目;v2.0 的紀錄保留在附錄G,兩者合併閱讀即為完整的查證歷史。

H.1 官方文件對照範圍

查證日期 2026-11-18。以 Invoke-WebRequest 下載官方 llms.txt 所列的全部 205 頁英文原始 Markdown(v2.0 時為 222 頁中的 124 頁;What’s New 每週子頁已不再列於索引)。Changelog 取 v2.1.300~v2.1.327 共 2,535 行,濾除 Fixed 類與 VS Code/Web/Desktop/Slack 等非 CLI 項目後,逐項分類約 380 條。

章節v3.0 主要對照頁面v3.0 處理
1、2overview、agents、whats-new、changelog、code-mode、mcp新增 1.8、2.8
3setup、troubleshoot-install、changelog新增 3.11
4authentication、claude-models-on-google-cloud-anthropic-managed、google-vertex-ai新增 4.7;修正 4.4 供應商清單
5settings、settings-reference(249 個鍵)、model-config、managed-settings新增 5.8;修正 5.6 別名、Effort、白名單
6cli-reference、commands、permission-modes、permissions、auto-mode-config+本機 --help新增 6.6.5、6.8
7、8interactive-mode、keybindings、settings-reference、context-window、prompt-caching新增 7.6、8.6
9、10agents、claude-projects、sub-agents、cross-session-messaging新增 9.11、10.7;修正 9.1
11memory、debug-your-config新增 11.9
12hooks、hooks-guide、debug-your-config、code-mode新增 12.7
13mcp、managed-mcp新增 13.7
14~16、18、22~25best-practices、common-workflows(以 Changelog 差異與關鍵字比對)未發現受 v2.1.300~v2.1.327 影響的敘述,本次未逐段改寫
17worktrees、permissions、changelog新增 17.6
19sandboxing、settings-reference新增 19.5;修正 19.4 範例
20monitoring-usage、costs、model-config新增 20.5
21admin-setup新增 21.7
26、27workflows、plugins/manifest-reference、plugins/org、plugin-evals新增 26.5、27.7
28network-config、managed-settings、server-managed-settings、hipaa-setup新增 28.6
29、30headless、cli-reference+實測新增 29.8、30.10;更新 30.3、30.5 原始碼
31~33(新)code-mode、advisor、debug-your-config、changelog新章

H.2 v2.0 → v3.0 修正清單

#章節v2.0 內容v3.0 內容依據
15.6、附錄A、B、Efable=Fable 5.1fable=Fable 5.2(v2.1.321+;Claude apps gateway 仍為 Fable 5)model-config、Changelog v2.1.321
25.6best 在有 Fable 權限時等於 fablev2.1.321 起 best 等同 opusmodel-config
35.6、5.9以 availableModels/deniedModels 鎖定模型另需 enforceAvailableModels: true,否則 Default 仍解析為帳號預設model-config
45.6Effort 預設表未含 Fable 5.2Fable 5.2 預設 mediummodel-config
54.4allowedProviders 值清單 8 個補上 anthropicGoogleCloudsettings-reference
69.1、9 與 26 章目標平行化機制四種官方列為五種(新增 Projects)agents
719.4Sandbox 範例未寫 autoAllowBashIfSandboxed(當時預設 true)明確寫出 false 並說明 v2.1.324 預設翻轉settings-reference
86.4add-json 只能以參數傳 JSONv2.1.327 起可用 - 從 stdin 讀取(Session 內拒絕)Changelog、本機實測
930.3檢查工具不認識已移除鍵與專案層級限制新增移除/棄用對照與範圍警告settings-reference
1030.5check_mcp.py 不接受 streamable-http接受(http 的別名)mcp

H.3 已執行的驗證

驗證項目工具與環境結果
CLI 旗標與子指令本機 v2.1.327 claude --help+21 個子指令 --help,對照官方 cli-reference手冊缺 9 個旗標與 4 個子指令用法,已補於 6.8;--advisor 確認為隱藏旗標
設定鍵自 settings-reference 重新擷取 249 個鍵手冊未提及 88 個(多為介面類),治理相關者補於 5.8、7.6、8.6
Subagent/Skill/Hook 欄位官方欄位表 vs check_agents.py、check_settings.pySubagent 19/Skill 20 個欄位、Hook 33 個事件,與工具完全一致
claude -p 實測(haiku)T2~T8,含 T2c、T4c 對照組,結果見第29.8章全數記錄;總成本約 US$0.02
claude doctor 實測尾逗號 JSON、拼錯的頂層鍵無效 JSON 列為 Invalid settings 但結束碼 0;拼錯的鍵不報
claude plugin validate 實測正確 Plugin、錯誤 engines、plugin.json 中的 agent0/1 結束碼與訊息見第27.7章
check_settings.py、check_mcp.py、check_upgrade.py正向 3 份、反向 4 份 fixture正向 OK;反向全部被抓出(BREAK=6、CHECK=4)
block-repl-risky.shtest_repl_hook.sh(Git Bash、jq 1.8.1)PASS=7 FAIL=0;反向 PASS=2 FAIL=5;過程中發現並修正 rm -fr 漏攔
gate_result.pyT2、T3b、T4、T4c 實測輸出+非 JSON結束碼 0/1/1/0/2 皆符合預期
claude-healthcheck.sh正常、無效 JSON、版本下限三種情境PASS/FAIL/FAIL;發現 python3 Store 佔位程式問題並以 PYTHON 變數解決
全文程式碼區塊見 H.5見 H.5

H.4 尚未驗證與待查項目

附錄G.4(v2.0 待查)的狀態:

G.4 #項目v3.0 狀態
1claude -p 實際輸出欄位✅ 已實測(第29.8章),欄位清單已更新;--json-schema 仍未測
2Auto Mode 分類器實際行為⬜ 未測(實測中分類器擋下了本機以 --dangerously-skip-permissions 執行的對照組,屬預期的保護行為)
3Sandbox 實際限制⬜ 本機為原生 Windows,仍未測;T3a 只驗證了「無效設定拒絕啟動」
4Agent Teams、Dynamic Workflows、/batch⬜ 未測
5真實 CI Runner⬜ 未測
6PowerShell 版 block-rm.ps1⬜ 仍未提供
7v2.1.297~v2.1.299 新功能🟡 本機已是 v2.1.327;相關旗標已通過 --help 比對,行為未逐一實測
8claude plugin eval⬜ 未測(每次皆為真實模型呼叫)
9隱藏旗標🟡 --advisor 已由官方文件確認為隱藏旗標;其餘未實測
10競品定位⬜ 未查證

v3.0 新增的待查項目:

#項目原因下次建議
11T5 的對照組(bypass 模式、無 blockWritesOutsideWorkingDirectories)Auto Mode 分類器拒絕在本 Session 執行 --dangerously-skip-permissions 的對照組由人工在隔離 VM 執行
12claude mcp add-json <name> - 的成功路徑只能在 Claude Code Session 外執行由人工在一般終端機執行並 git diff .mcp.json
13Code Mode 實際執行與 REPL Hook 的真實輸入格式需互動終端機;Hook 只以官方文件描述的 tool_input.code 模擬試點時以 claude --debug 記錄真實 Hook 輸入
14Advisor、Projects、Claude Models on Google Cloud(Anthropic 代管)需對應帳號、方案或雲端合約有環境時實測
15OTEL_RESOURCE_INCLUDE_HOST 的值格式、attributionProject 設定只見於 Changelog,Settings reference 與 env-vars 頁未列待官方文件補上後確認
16Sandbox 自動放行預設翻轉的實際體驗需 macOS/Linux/WSL2在 WSL2 以第19.5章範例對照 true/false

H.5 目錄與格式驗證

  • 目錄由 toc.py 依標題自動重建三層(章 → 節 → 小節),位於 <!-- TOC-AUTO-BEGIN --> 與 <!-- TOC-AUTO-END --> 之間;重建前先證明腳本能 0 差異重現 v2.0 的目錄,確保既有錨點不變。
  • 以 Hugo 實際建置網站到暫存目錄,解析輸出頁面,逐一比對每個 href="#..." 與實際產生的標題 id,並比對 Markdown 端計算的 slug 與 HTML id。
  • 以 repo 的 check-toc.ps1、check-md.ps1、test-mermaid-syntax.ps1(pwsh 7)檢查,並與 v2.0 基線比較。

驗證結果(2026-11-18):

檢查v2.0v3.0
Hugo 輸出頁面的標題 id 數(重複)269323(0)
頁內連結總數/不重複/無法解析536/270/0642/324/0(另有主題的 #top,屬預期)
Markdown slug 與 Hugo 標題 id 不符—0/323
目錄項目數/不在 Hugo 標題 id 中265/0317/0
內文「第 X 章」「第 X.Y 章」引用/指向不存在的章節115/0(只計 X.Y)459/0(含整章引用)
check-toc.ps1 [A]/[B]/[C]無/無/無無/無/無
check-md.ps1 MD040/其他格式問題0/00/0
test-mermaid-syntax.ps1未發現語法問題未發現語法問題
Mermaid 圖(mermaid-cli 11.17,與網站 mermaid@11 同大版本)34 張全數成功36 張全數成功,無 Syntax error
程式碼區塊自動檢查28 JSON、51 bash193 個區塊:47 JSON(其中 41 份設定經 check_settings.py)、66 bash(bash -n)、6 Python(編譯)、3 YAML、4 份 frontmatter(check_agents.py),0 個問題
check_upgrade.py 掃描全文 JSON—只有第33.4章刻意示範的「舊設定」1 項 BREAK
check_flags.py109 個旗標、未知 0122 個旗標、已知 113;其餘 9 個皆非 claude 旗標或刻意記錄:git --amend/--no-verify、brew --cask、/code-review 的 --fix/--comment/--max-findings、說明文字中的 --flag,以及記錄為「已移除」的 remote-control --sandbox/--no-sandbox
表格欄數不一致/表格前缺空行—0/0
隱形字元(U+200B~200D、2060、FEFF、202A~202E、2066~2069)—0
檔案編碼無 BOM、CRLF無 BOM、CRLF(全部行尾一致,無單獨 CR)

本手冊全文完成。 最後更新:2026-11-18 手冊版本:v3.0(對齊 Claude Code v2.1.327)