Claude Code 完整指南：從 MCP、Hooks 到 Workflows 與企業部署

這份文件是什麼

這是一份持續更新的參考文件，不是一次性的教學文章。Claude Code 更新得非常快：光是 2026 年 8 月中到 9 月中這 30 天，npm 上就發了 29 個正式版本。

所以我想透過這一份文件，持續記錄更新的過程，一方面也會是我自己的筆記。

這一頁的方法是：

• 頁首永遠標示對應的 CLI 版本與最後更新日期。看到日期太舊，就知道要回去查官方文件。
• 每個章節都有獨立錨點，可以直接深連結到某一節。

資料來源：npm 上 @anthropic-ai/claude-code 的版本發布紀錄（2026-09-14 查詢）

60 秒快速上手

如果你只想先把 Claude Code 跑起來、看看它的輸出，請依序進行：

# 1. Install (pick one)
curl -fsSL https://claude.ai/install.sh | bash   # macOS, Linux, WSL
irm https://claude.ai/install.ps1 | iex          # Windows PowerShell
brew install --cask claude-code                  # Homebrew
winget install Anthropic.ClaudeCode              # WinGet
npm install -g @anthropic-ai/claude-code         # npm (Node.js 22+)

# 2. Verify: prints a version followed by (Claude Code)
claude --version
claude doctor                                    # optional full check

# 3. Launch in your project (first run opens a browser to log in)
cd ~/your-project && claude

# 4. Ask your first question
> what does this project do?

# Switch accounts later, inside Claude Code
/login

Claude Code 會自己讀需要的專案檔案，不用手動把程式碼貼給它。

裝之前，先確認兩件事

• 系統：macOS 13.0 以上、Windows 10 1809 以上（或 Windows Server 2019 以上）、Ubuntu 20.04 以上、Debian 10 以上、Alpine Linux 3.19 以上，記憶體 4 GB 以上
• 帳號：需要 Claude 的 Pro、Max、Team、Enterprise 訂閱，或是 Claude Console 帳號

選哪一種安裝方式

前兩個是官方建議的原生安裝，會在背景自動更新。Homebrew 和 WinGet 不會自動更新，後續需要自己跑 brew upgrade claude-code 或 winget upgrade Anthropic.ClaudeCode。用 npm 裝的話，不要加 sudo。

用 Homebrew 安裝的話，claude-code 使用的是 stable 版本，通常比最新版晚一週左右，但會跳過有重大問題的版本。想拿到最新版，請改裝 claude-code@latest。

打開之後，先知道預設是 Auto mode

Pro、Max、Team 方案在終端機裡，預設是 Auto mode，由分類器幫你審核動作，大部分的檔案修改和指令都不會再問你。不過剛安裝完的第一個 session，可能還是 Manual mode。

想改成由你確認，可以按 Shift+Tab 切到 Manual，但這只會影響這一次對話；想每次都從 Manual 開始，可以看後面〈權限系統與 auto mode〉那一章。

下一步

可以先挑一個專案打開，問問它「這個專案在做什麼？」，確認它讀得到檔案、回答得出來。用順了，再把外部工具接進來。

資料來源：Claude Code 官方文件〈Quickstart〉、〈Advanced setup〉 的 System requirements、Install with npm 各節（2026-09-15 查詢）；〈Choose a permission mode〉 的 Which mode a session starts in 一節（2026-09-15 查詢）

什麼是 MCP（Model Context Protocol）

如果你用過 Claude Code 串外部工具，大概都遇過同一件事：MCP 發展太快，每隔幾天就冒出新的，根本不知道該裝哪一個。

先談談 MCP 是什麼。它就像一個插頭：別人把工具寫好、做成統一的規格，你只要插上去，Claude Code 就能透過同一套方法去讀資料、操作工具。在沒有 MCP 之前，每接一個工具，都得自己串接一次。

我自己使用都比較保守，不會隨意安裝別人的東西。最後面會留下來的 MCP，都是我大概審核過、或是很多人推薦的；看起來很新、比較少人使用的，我都會在觀望一陣子。

那什麼時候才需要接 MCP 呢？官方文件給的判斷很實際：當你發現自己一直把別的工具裡的資料，複製貼上到對話裡，例如 issue 追蹤系統、監控儀表板，就是該接的時候。接上之後，Claude 可以直接讀取、操作那個系統，不用再靠你轉貼資訊。

MCP 的兩端：Host、Client、Server

MCP 要能用，兩端都要有東西。MCP 裡有三個角色：

也就是說，你在 Claude Code 裡掛了三個 MCP，背後就是三條各自獨立的連線。

插上去之後，拿得到什麼

Server 可以提供三種東西，在 Claude Code 裡的用法不一樣：

1. Tools（工具）：可以執行的動作，例如查資料庫、呼叫 API、操作檔案。Claude 會自己判斷什麼時候呼叫。
2. Resources（資源）：提供內容的資料來源，例如檔案內容、資料庫紀錄。在提示裡輸入 @，就能像引用檔案一樣引用它。
3. Prompts（提示範本）：寫好的提示範本，在 Claude Code 裡會變成指令。輸入 / 就看得到，名稱格式是 /servername:promptname。

下一步

如果你是剛開始，建議只做一件事：挑一個你每天都在用的工具，像 Notion 或 GitHub，先把它的 MCP 接起來，確定用得順，再加第二個。怎麼接，下一章繼續聊。

資料來源：Claude Code 官方文件〈Connect Claude Code to tools via MCP〉、MCP 官方文件〈Architecture overview〉

怎麼在 Claude Code 裡設定 MCP

如果你設定好 MCP，換到另一個專案就不見了；或是同事 clone 專案下來，莫名其妙也多了你的 server，問題大概都出在同一個地方：作用域。

同一個 server 可以存在三個不同的地方，存在哪裡，決定了它在哪些專案生效、會不會分享給別人。

三個作用域

這裡有一個很容易搞混的地方：MCP 的 local 雖然叫 local，但不是存在專案裡的 .claude/settings.local.json，而是存在你家目錄的 ~/.claude.json。官方文件也特別提醒了這一點。

加 server 的時候，需要用 --scope 來指定：

# local (default): only you, only this project
claude mcp add --transport http stripe https://mcp.stripe.com

# project: written to .mcp.json, shared with the team
claude mcp add --transport http shared-server --scope project https://example.com/mcp

# user: only you, across all your projects
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

別人專案裡的 MCP，不會直接跑

前一章有提到，我不會隨意安裝別人的東西。Claude Code 在這件事上也一樣保守。

project 作用域的 server 寫在 .mcp.json 裡，會跟著 repo 一起被 clone 下來。所以官方基於安全考量，在互動模式下使用這些 server 之前，會先問你要不要核准。

幾個要注意的細節：

• clone 下來的 repo，沒辦法自己核准自己。 就算 repo 裡的 .claude/settings.json 寫了 enableAllProjectMcpServers，在你信任這個資料夾之前也會被忽略，server 會停在「⏸ Pending approval」。
• 非互動模式會直接載入。 用 claude -p、Agent SDK 或雲端執行時，沒辦法跳出確認視窗，project 的 server 會直接載入。在這些情境跑別人的專案，要先看過 .mcp.json 裡寫了什麼。
• 想重新選擇，執行 claude mcp reset-project-choices。

四種連線方式

判斷方式很簡單：遠端服務先用 HTTP；要跑本機程式用 stdio；只有 server 需要主動推東西過來，才考慮 WebSocket。

API key 不要直接寫進 .mcp.json

.mcp.json 會進 git。把 key 直接寫進去，等於公開給所有看得到 repo 的人。改用環境變數：

{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}

• ${VAR}：換成環境變數 VAR 的值
• ${VAR:-預設值}：有設就用，沒設就用預設值
• 可以用在 command、args、env、url、headers 這幾個欄位

需要登入的遠端 server

很多雲端的 MCP 需要驗證，Claude Code 支援 OAuth 2.0。加完 server 之後，在 Claude Code 裡輸入 /mcp，照瀏覽器的步驟登入就好。登入後 token 會自動更新；要撤銷授權，也是在 /mcp 選單裡清除。

下一步

先用 claude mcp add 接一個 HTTP 的 server，例如 Notion：

claude mcp add --transport http notion https://mcp.notion.com/mcp

接著在 Claude Code 裡輸入 /mcp，看它有沒有連上。連不上的話，繼續看下一章。

資料來源：Claude Code 官方文件〈Connect Claude Code to tools via MCP〉 的 Installing MCP servers、MCP installation scopes、Project server approvals and workspace trust、Environment variable expansion in .mcp.json、Authenticate with remote MCP servers 各節

常見問題排查

MCP 加完了，Claude 還是說找不到工具？先別急著刪掉重裝，照下面的順序一步一步查。

1. 先看狀態

claude mcp list 會在每個 server 旁邊標出狀態：

要注意：看到 ✘，是 Claude Code 連不上那個 server，不是 list 指令本身壞掉。

2. 環境變數沒設到

設定裡用了 ${VAR}，但這個變數沒設、也沒給預設值時，Claude Code 還是會載入 server，只是會在 claude mcp list 和 /mcp 裡跳出警告，告訴你缺的是哪個變數。這時候 ${VAR} 會原封不動被當成文字用，server 當然連不上。

所以看到警告，就把那個變數補上，或改成 ${VAR:-預設值}。

3. 自己寫的 stdio server：stdout 被弄髒了

如果 server 是你自己寫的 stdio 程式，要特別注意：stdio 是透過標準輸入、標準輸出來傳 MCP 訊息，MCP 規格規定 server 不能往 stdout 印任何不是 MCP 訊息的東西。多一行 console.log，就可能讓連線壞掉。

除錯訊息一律寫到 stderr，規格允許用 stderr 記 log。

4. 掛很多 MCP，會不會吃掉 context？

影響很小。Claude Code 預設開啟 tool search：一開始只載入工具名稱和 server 的說明，完整的工具定義，等 Claude 真的需要時才去找。官方也說明，每個 server 沒有固定的工具數量上限，實際的限制是 context window 的額度。

想知道每個 server 提供了幾個工具，在 /mcp 面板裡可以看到。

下一步

遇到問題，先跑一次 claude mcp list，從狀態判斷是要登入、要核准，還是要補環境變數。

資料來源：Claude Code 官方文件〈Connect Claude Code to tools via MCP〉 的 Server status、Configuration warnings、Tool availability、Scale with MCP tool search 各節；MCP 規格〈stdio transport〉

CLAUDE.md 與記憶系統

如果你每開一個新對話，都要再跟 Claude 講一次「這個專案用 pnpm」「測試指令是這個」，問題不在 Claude 記性差，而是每個 session 本來就是從一個全新的 context window 開始。

要讓它記得，Claude Code 有兩套機制。可以把它想成新人到職：CLAUDE.md 是你寫給它的交接手冊，每天上班先讀一遍；auto memory 是它自己的工作筆記，被你糾正過的事情，它會自己記下來。

兩套記憶的差別

兩者對 Claude 來說都是 context，不是強制設定。它會盡量照做，但沒有保證。不管 Claude 怎麼判斷都一定要擋下來的動作，要用 PreToolUse hook。

CLAUDE.md 放哪裡

CLAUDE.md 可以放在四個地方，放哪裡決定了誰會讀到：

它們是疊加，不是覆蓋

知道放哪裡之後，下一個問題是：好幾份同時存在時，聽誰的？

答案是全部接在一起讀，不會互相覆蓋：

• 往上找：從你啟動 Claude Code 的目錄開始，往上每一層的 CLAUDE.md 和 CLAUDE.local.md 都會在啟動時載入。
• 由遠到近：越靠近你啟動位置的檔案，排在越後面讀。同一層裡，CLAUDE.local.md 排在 CLAUDE.md 後面。
• 子目錄晚點才讀：底下子目錄的 CLAUDE.md 不會一開始就載入，要等 Claude 讀到那個子目錄的檔案時才會帶進來。

因為是接在一起讀，兩份檔案如果寫了互相矛盾的規則，Claude 可能隨便挑一條照做。所以要定期回頭檢查，把過時或衝突的指令刪掉。

用 /init 起頭

不知道從何寫起，就在專案裡執行 /init。Claude 會分析你的程式碼，產生一份包含 build 指令、測試方式、專案慣例的 CLAUDE.md。如果已經有 CLAUDE.md，它會提出改進建議，不會直接覆蓋。

產生之後再自己補上 Claude 從程式碼看不出來的事情。想要更完整的流程，可以先設定 CLAUDE_CODE_NEW_INIT=1，/init 會一步步問你要設定 CLAUDE.md、skills 還是 hooks，最後給你一份提案確認過才寫檔。

怎麼寫才有效

CLAUDE.md 每個 session 都會載入、吃掉 token，所以寫法直接影響 Claude 照不照做。官方文件給了幾個方向：

• 長度：每份控制在 200 行以內。越長越佔 context，遵守度也越低。
• 結構：用 markdown 標題和條列分組，不要寫成一大段。
• 具體到可以驗證：

什麼時候該加一條？文件的判斷很實用：同一個錯誤 Claude 犯第二次、你發現自己又在對話裡打了上次打過的糾正，就寫進去。反過來，多步驟的流程、或只跟某一部分程式碼有關的規則，放到 skill 或 .claude/rules/ 會比較適合。

用 @ 把其他檔案拉進來

CLAUDE.md 可以用 @路徑 引用其他檔案，啟動時會一起展開載入：

See @README for project overview and @package.json for available npm commands for this project.

# Additional Instructions
- git workflow @docs/git-instructions.md

• 相對路徑是相對於寫這行的檔案，不是你的工作目錄。
• 被引用的檔案可以再引用別的，最多四層。
• 只是想提到路徑、不想引用，就用反引號包起來，例如 `@README`。
• 專案的 CLAUDE.md 引用到工作目錄以外的檔案，第一次會跳出核准視窗；拒絕的話，這些引用就不會載入。
• 拆成 import 只是比較好整理，不會省 context，被引用的檔案一樣在啟動時載入。

AGENTS.md：v2.1.277 起原生支援

很多 repo 已經有一份 AGENTS.md，給 Codex、Cursor、Gemini 這些 Agent 看。以前 Claude Code 不讀它，只能在 CLAUDE.md 第一行寫 @AGENTS.md 把它引用進來；從 v2.1.277 開始，專案裡沒有 CLAUDE.md 的時候，Claude Code 會直接讀 AGENTS.md。

三件事要先分清楚：

• 不是合併，是替代。 邏輯是「沒有 CLAUDE.md 才讀 AGENTS.md」。兩份都在的時候，讀的仍然是 CLAUDE.md，AGENTS.md 會被忽略。
• 想兩份都留著，還是用 @AGENTS.md。 在 CLAUDE.md 第一行引用，內容只維護 AGENTS.md 一份，Claude Code 專屬的規則寫在下面。這也是跨 Agent 比較穩的寫法，不會因為某一個 Agent 的支援狀況而變。
• Bedrock、Vertex、Foundry 還沒有。 走這三個平台的 session 目前不吃這個機制。團隊裡有人走雲端廠商，CLAUDE.md 就得留著。

要改讀哪一份，到 /config 的 Project instructions 切換。

auto memory：Claude 自己的筆記

auto memory 預設是開的。你糾正它、或確認某個做法是對的，它會判斷值不值得記，存到 ~/.claude/projects/<project>/memory/：

~/.claude/projects/<project>/memory/
├── MEMORY.md           # Index, one line per entry, loaded every session
├── user_role.md        # One memory
├── feedback_testing.md # One memory
└── ...

• 記什麼：分成 user（你的角色與偏好）、feedback（你的糾正）、project（進行中的工作、期限、決策）、reference（外部資訊在哪裡找）四種。能從程式碼看出來的、CLAUDE.md 已經寫的，它不會記。
• 怎麼載入：啟動時只讀 MEMORY.md 的前 200 行或 25KB，其他主題檔案等需要時才讀。
• 只在這台電腦：不會同步到其他電腦或雲端環境。
• 怎麼關：在 /memory 裡切換，或在專案設定寫 "autoMemoryEnabled": false，也可以設定環境變數 CLAUDE_CODE_DISABLE_AUTO_MEMORY=1。

你跟 Claude 說「記住，一律用 pnpm」，它會存進 auto memory。想寫進 CLAUDE.md，要明講「把這個加到 CLAUDE.md」。

用 /memory 和 /context 檢查

• /memory：列出使用者和專案層級的 CLAUDE.md、CLAUDE.local.md 等檔案，選了就用編輯器打開，還不存在的會直接建立。也可以在這裡開關 auto memory、打開 auto memory 資料夾，看看它到底記了什麼。
• /context：看這個 session 實際載入了哪些檔案，列在 Memory files 底下。Claude 沒照 CLAUDE.md 做的時候，先來這裡確認檔案有沒有被讀到。

下一步

如果你的專案還沒有 CLAUDE.md，建議只做一件事：在專案根目錄執行 /init，打開產生的檔案，刪掉看不懂或用不到的，再補一條你最常重複講的糾正。下次開新 session 時執行 /context，確認它出現在 Memory files 裡。

資料來源：Claude Code 官方文件〈How Claude remembers your project〉 的 CLAUDE.md vs auto memory、CLAUDE.md files、Auto memory、View and edit with /memory、Troubleshoot memory issues 各節（2026-09-15 查詢）。AGENTS.md 一節的事實來自 Claude Code CHANGELOG 的 2.1.277（2026-09-19 查詢）

權限系統與 auto mode

用 Claude Code 一陣子，大概會卡在兩種極端：每跑一個指令都跳出來問，按到手痠；或是乾脆全部放行，又擔心它哪天把不該刪的東西刪掉。

這兩件事其實分開管。權限模式像大樓的保全等級，決定整體要多嚴；權限規則像門禁名單，指定哪幾扇門一定能進、一定要問、絕對不能進。先選好模式，再用規則補上你在意的那幾件事。

六種權限模式

default 在 CLI 裡顯示的名稱是 Manual。另外有一條不管哪個模式都成立：deny 規則一定會擋，連 bypassPermissions 也一樣。

用 Shift+Tab 切換

對話進行中，按 Shift+Tab 就會輪流切換。從 auto 按第一下會回到 default，接著依序是 default → acceptEdits → plan，auto mode 可用的話會排在 plan 後面，再回到 default。切到哪個模式，狀態列會顯示 ⏸ manual mode on、⏵⏵ accept edits on、⏸ plan mode on 或 ⏵⏵ auto mode on。

兩個模式不在這個循環裡：dontAsk 只能用 --permission-mode dontAsk 啟動；bypassPermissions 要啟動時就開（例如 --dangerously-skip-permissions），才會出現在循環裡。想直接用某個模式開始，也是帶參數，例如 claude --permission-mode plan。

auto mode 怎麼運作

auto mode 是把「問你」這件事，交給另一個模型（分類器）來判斷。每個動作會照這個順序處理，先符合的先算：

1. 符合你寫的 allow、ask、deny 規則，直接照規則走
2. 讀取、在工作目錄裡改檔案，直接放行（寫入 .git、.claude 這類受保護路徑除外）
3. 其他的，交給分類器判斷
4. 分類器擋下來，Claude 會收到原因，自己改用別的做法

分類器預設會擋的，例如：curl | bash 這種下載後直接執行、把敏感資料送到外部、正式環境部署和 migration、force push、git reset --hard。預設放行的，例如：工作目錄裡的檔案操作、安裝 lock file 裡已宣告的套件、唯讀的 HTTP 請求、push 到你正在工作的 repo 的任何分支。完整清單可以執行 claude auto-mode defaults 看。

幾個限制要先知道：

• 不保證安全。 官方的說法是：用在你信得過大方向的任務，不要拿來取代敏感操作的審查。
• 太寬的 allow 規則會暫時失效。 進入 auto mode 時，Bash(*)、Bash(python*) 這類等於放行任意程式的規則會被拿掉，離開 auto mode 才恢復；Bash(npm test) 這種範圍窄的規則不受影響。
• 在對話裡講「不要 push」有用，但不牢靠。 分類器會把它當成擋下的訊號，可是它是每次從對話紀錄重讀的，context 被壓縮掉那句話就沒了。要確定擋住，寫成 deny 規則。
• 連續被擋會退回手動。 連續 3 次或整個 session 累計 20 次被擋，auto mode 會暫停、改回問你，這兩個數字不能調。被擋的動作會列在 /permissions 的 Recently denied 分頁，按 r 可以手動核准重跑。
• 模型有限制。 在 Anthropic API 上要 Claude Opus 4.6、Sonnet 4.6 以上，或 Fable 模型。

分類器跑在你這邊，還是伺服器那邊

分類器本身也是一次模型呼叫。跑在本機，等於每個需要判斷的動作都多付一次 token；這筆錢以前是算在你頭上的。

v2.1.278 起，Claude API 與 Enterprise 使用者，以及 Bedrock、Vertex、Foundry 和 gateway，預設改用伺服器端的分類器，這段 overhead 不計費。 真的退回計費版本時，畫面會跳警告告訴你。

• 想退回本機分類器（限 Bedrock、Vertex、Foundry、gateway）：設 CLAUDE_CODE_AUTO_MODE_SERVER=0。
• 想確認這個 session 跑在哪一邊：輸入 /status，看 Auto mode server 那一列。

auto mode 另外三個要知道的改動

都是 v2.1.271 之後陸續加的，實際用起來會踩到：

• 沙箱模式下的網域，改成逐指令審核。 Bash、PowerShell、Monitor 多了 allowed_domains：一條指令要連哪幾個主機，就跟著這條指令一起被審，而且只為它打開，其他主機照樣拒絕。不用再為了一次 curl 把整個網域永久放行。
• skill 和 slash command 裡的 ! 指令不再交給分類器。 改用 default 模式的權限規則判斷；沒有規則可判的，就變成一個要你看過的工具呼叫。你寫在 skill 裡的 !`git diff HEAD`，受的是 permissions 的管轄，不是分類器的。
• subagent 的結果會被隔離看待。 subagent 回報給主對話，走的是專用的交還呼叫、由分類器審查；v2.1.278 起結果還會被加上「這是 subagent 輸出」的標頭並縮排。目的是同一件事：subagent 撈回來的文字，不能冒充成你下的指令。

一開 Claude Code 會是哪個模式

在終端機開新 session 時，照這個順序決定：

1. 啟動參數 --permission-mode 或 --dangerously-skip-permissions
2. 設定檔裡的 permissions.defaultMode
3. 內建預設值

內建預設值依方案不同：Pro、Max、Team 在終端機或 VS Code 擴充套件裡是 auto；Enterprise、Claude Console API key、claude -p 都是 default。另外，剛安裝或升級完的第一個 session，也可能是 default。

這裡有一個很容易踩的地方："auto" 寫在專案的 .claude/settings.json 或 .claude/settings.local.json 不會生效，要寫在 ~/.claude/settings.json。反過來，想讓自己每次都從 Manual 開始，也是在這裡寫 {"permissions": {"defaultMode": "default"}}。

allow、ask、deny 規則怎麼寫

規則的格式是 Tool 或 Tool(條件)。三種清單的意思：allow 不問直接做、ask 每次都問、deny 直接擋。

判斷順序固定是 deny → ask → allow，先符合的就決定結果，寫得比較精確也不會插隊。所以 deny 了 Bash(aws *)，就算另外 allow 了 Bash(aws s3 ls)，也一樣會被擋。

{
  "permissions": {
    "allow": ["Bash(npm run *)", "Bash(git commit *)"],
    "deny": ["Bash(git push *)"]
  }
}

常用的寫法：

寫 Bash 規則要注意三件事：

• * 放在子指令後面。 Bash(git log *) 只放行 git log；Bash(git *) 等於放行所有 git 指令。
• 串起來的指令會拆開檢查。 Bash(safe-cmd *) 不會放行 safe-cmd && other-cmd，每一段都要符合。
• Bash 規則不是安全邊界。 Bash(git push *) 擋得住 git push origin main，擋不住 git -C . push origin main。真的要擋，官方建議搭配 sandbox 或 PreToolUse hook。

Read、Edit 的路徑寫法也要小心：// 開頭才是檔案系統的絕對路徑，~/ 是家目錄，單一個 / 開頭是相對於設定檔的位置。所以 /Users/alice/file 不是絕對路徑，要寫 //Users/alice/file。規則是 Claude Code 在執行，不是模型自己遵守。寫在 CLAUDE.md 的「不要做什麼」只會影響 Claude 想怎麼做，不會真的擋住。

規則寫在哪個設定檔

不管寫在哪一層，只要有一層 deny，其他層就放行不了。例如 user 設定 allow、project 設定 deny，結果是擋下；反過來也一樣。想知道每條規則來自哪個檔案，輸入 /permissions 就看得到。

下一步

先打開 Claude Code，看狀態列顯示的是哪個模式，再輸入 /permissions 看看已經存了哪些規則。接著挑一件你絕對不希望發生的事，例如讀到 .env，在 ~/.claude/settings.json 的 deny 加上 Read(./.env)。先把 deny 寫好，再決定要不要放心用 auto mode。

資料來源：Claude Code 官方文件〈Choose a permission mode〉 的 Available modes、Which mode a session starts in、Switch permission modes、Eliminate permission prompts with auto mode 各節，以及〈Configure permissions〉 的 Manage permissions、Permission rule syntax、Tool-specific permission rules、Settings precedence、Project allow rules and workspace trust 各節（2026-09-15 查詢）。分類器跑在哪裡、allowed_domains、! 指令與 subagent 交還這幾段的事實，來自 Claude Code CHANGELOG 的 2.1.271 與 2.1.278（2026-09-19 查詢）

Hooks：確定性的那一層

如果你在 CLAUDE.md 寫過「改完檔案記得跑 formatter」「不要動 .env」，大概都遇過同一件事：寫了，但沒辦法保證 Claude 每一次都照做。

Hooks 就是解決這件事的。它像是裝在流程上的感應器：你先決定裝在哪個點，例如「Claude 改完檔案之後」，只要走到那個點，你寫好的 shell 指令就一定會跑，不用 Claude 記得，也不看它當下怎麼判斷。

為什麼叫「確定性」

官方文件的說法很直接：hooks 讓某些動作一定會發生，而不是靠 LLM 自己選擇要不要做。寫在 CLAUDE.md 的規則，是 Claude 讀了之後自己判斷；寫成 hook，是 Claude Code 在固定的時間點直接執行，還可以在工具執行前把它擋下來。所以判斷方式很簡單：「每次都要」「絕對不行」的事，交給 hook；需要看情況的，留在 CLAUDE.md。

最常用的三個事件

Hook 要掛在某個「事件」上。官方列了三十幾個，剛開始只要認得這三個：

設定檔怎麼寫

Hook 寫在 settings 檔的 hooks 裡，一共三層：事件 → matcher（篩選條件）→ 要執行的指令。下面是官方的「改完檔案自動跑 Prettier」：

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

Claude Code 會把事件資料用 JSON 從 stdin 丟給你的指令，所以這裡用 jq（macOS 用 brew install jq 安裝）取出剛改的檔案路徑，再交給 Prettier。至於寫在哪個檔案：放在 ~/.claude/settings.json 對你所有專案生效；放在專案的 .claude/settings.json 只對這個專案生效，而且可以進 git 分享給團隊；不想分享就放 .claude/settings.local.json。設定完輸入 /hooks 確認有出現，這個選單只能看、不能改，要改就直接編輯 JSON，或請 Claude 幫你改。

matcher：只在需要的時候觸發

沒寫 matcher（或寫 ""、"*"），每次事件都會觸發。PreToolUse、PostToolUse 的 matcher 比對的是工具名稱：

• 只有英文、數字、_、-、|、,：完全比對。Edit|Write 就是只比對這兩個工具。
• 含其他字元：當成正規表示式，而且不限定頭尾。Edit.* 會連 NotebookEdit 也比對到，要完全符合就寫 ^Edit$。
• 大小寫有差，打錯 hook 就不會觸發。Stop 則不支援 matcher，每次都會跑。
• Claude 也可能用 Bash 跑指令改檔案，只比對 Edit|Write 會漏掉這些情況。

怎麼擋下一個動作

你的指令用**結束碼（exit code）**告訴 Claude Code 接下來怎麼做：

最常踩到的是第三行：Unix 習慣用 exit 1 表示失敗，但在 hooks 裡它擋不住東西。要擋，一定用 exit 2。同一個 exit 2 在其他事件也不一樣：PostToolUse 只會把 stderr 給 Claude 看；Stop 則是不讓 Claude 停下來，stderr 變成它要繼續做的理由。想要更細的控制，就改成 exit 0，並在 stdout 輸出 JSON。例如 PreToolUse 回傳 "permissionDecision": "deny"（包在 hookSpecificOutput 裡）拒絕，並用 permissionDecisionReason 告訴 Claude 原因。官方建議一個 hook 只選一種方式：exit 2，或 exit 0 加 JSON。

完整範例：不讓 Claude 改 .env

先建立 .claude/hooks/protect-files.sh，再執行 chmod +x .claude/hooks/protect-files.sh 讓它可以執行：

#!/bin/bash
INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
FILE_PATH="${FILE_PATH//\\//}"
PROTECTED_PATTERNS=(".env" "package-lock.json" ".git/")
for pattern in "${PROTECTED_PATTERNS[@]}"; do
  if [[ "$FILE_PATH" == *"$pattern"* ]]; then
    echo "Blocked: $FILE_PATH matches protected pattern '$pattern'" >&2
    exit 2
  fi
done
exit 0

接著在 .claude/settings.json 註冊成 PreToolUse hook：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-files.sh"
          }
        ]
      }
    ]
  }
}

$CLAUDE_PROJECT_DIR 是這次 session 開始時的專案根目錄，用它就不怕工作目錄換了找不到腳本。最後請 Claude 在 .env 加一行註解，它應該會被擋下，並收到 Blocked: 那段訊息。

安全提醒

• 它有你帳號的完整權限。 你能刪的檔案，hook 都能刪。加進設定之前，指令要自己看過、測過。
• 路徑打錯，保護就默默失效。 腳本找不到只算非阻擋錯誤，動作照樣執行。跑到逾時被取消的 PreToolUse hook 也一樣不會擋。設好之後，第一次一定要實際觸發一次確認。
• 別人的 repo 小心 -p。 互動模式下，你信任這個資料夾之前 hook 不會跑；但 claude -p 或 SDK 會直接視為信任。跑之前先看過 .claude/ 裡的設定，或加上 --settings '{"disableAllHooks": true}' 關掉。
• Hook 只能收緊，不能放寬。 PreToolUse 回 deny，就算在 bypassPermissions 模式也會擋；但回 allow 蓋不過 settings 裡的 deny 規則。

下一步

如果你是剛開始，建議只做一件事：把「改完檔案自動跑 Prettier」那段貼進專案的 .claude/settings.json，輸入 /hooks 確認有出現，再請 Claude 改一個 JS 檔，看格式有沒有自動整理好。跑順了，再加上擋 .env 的 PreToolUse hook。

資料來源：Claude Code 官方文件〈Automate actions with hooks〉 的 Auto-format code after edits、Block edits to protected files、How hooks work、Filter hooks with matchers、Configure hook location、Limitations and troubleshooting 各節，以及〈Hooks reference〉 的 Matcher patterns、Exit code 2、Exit code 2 behavior per event、Stop、Security considerations 各節（2026-09-15 查詢）

Skills 如何運作

如果你用 Claude Code 一段時間，大概都遇過同一件事：同一份檢查清單、同一套部署步驟，每開一次新對話就要再貼一次；或是 CLAUDE.md 越寫越長，塞滿只有某些時候才用得到的流程。

Skill 就是拿來解決這件事的。它像書架上的操作手冊：Claude 平常只看得到書背上的簡介，遇到用得上的情況，才把整本拿下來照著做。你也可以直接點名，要它翻哪一本。

官方文件給的判斷很實際：當你一直把同樣的指示、清單或多步驟流程貼進對話，或 CLAUDE.md 裡某一段已經從「事實」長成「流程」，就是該寫成 skill 的時候。

跟 CLAUDE.md、slash command、subagent 差在哪

• CLAUDE.md：內容一直都在對話裡。Skill 平常只放描述，完整內容用到才載入，所以很長的參考資料，沒用到的時候幾乎不佔成本。
• Slash command（自訂指令）：已經併進 skill。.claude/commands/deploy.md 和 .claude/skills/deploy/SKILL.md 都會產生 /deploy，用起來一樣，舊的 .claude/commands/ 檔案也照常能用。Skill 多了三件事：可以放輔助檔案的資料夾、用 frontmatter 控制誰能呼叫、讓 Claude 在相關時自動載入。新寫的建議直接用 skill。
• Subagent：skill 預設在你目前的對話裡執行，讀得到前面聊過的內容。frontmatter 加上 context: fork，就改成開一個新的 subagent 去跑，SKILL.md 的內容變成它的任務，但它看不到你的對話紀錄，所以指示要能獨立成立。反過來，subagent 也可以用 skills 欄位預先載入 skill，當參考資料用。

最小可用範例

下面這個 skill 會整理 git 還沒 commit 的變更，並標出有風險的地方。先建資料夾，放在個人 skill 的位置，所有專案都能用：

mkdir -p ~/.claude/skills/summarize-changes

把這段存成 ~/.claude/skills/summarize-changes/SKILL.md：

---
description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff.
---

## Current changes

!`git diff HEAD`

## Instructions

Summarize the changes above in two or three bullet points, then list any risks you notice such as missing error handling, hardcoded values, or tests that need updating. If the diff is empty, say there are no uncommitted changes.

!`git diff HEAD` 這一行，Claude Code 會先執行指令，把輸出換進去，Claude 拿到的就是你實際的 diff，不是用猜的。

打開一個 git 專案、隨便改一個檔案，執行 claude，有兩種測法：問一句跟描述相符的話，例如 What did I change?，讓 Claude 自己載入；或直接輸入 /summarize-changes。

SKILL.md 的結構

一份 SKILL.md 分兩部分：上面 --- 包起來的 YAML frontmatter，告訴 Claude 什麼時候用；下面的 markdown 內容，是執行時照著做的指示。frontmatter 必須從檔案第一行的 --- 開始，不然整份檔案都會被當成內容。

所有欄位都是選填，官方只建議一定要寫 description。比較常用到的幾個：

description 決定 Claude 會不會自動用

在一般對話裡，所有 skill 的描述都會載入，讓 Claude 知道有哪些可以用；完整內容要等被呼叫才載入。也就是說，Claude 要不要自己用某個 skill，只能看 description，寫法直接決定 skill 會不會被用到：

• 關鍵用途寫在最前面。 description 加上補充觸發情境的 when_to_use 欄位，在清單裡超過 1,536 字元會被截掉。skill 裝很多時，清單還有總預算，會先刪掉最少用的 skill 的描述。
• 放進使用者自然會講的關鍵字。 沒觸發時，先問 Claude What skills are available? 確認它看得到，再調整描述或換個問法。
• 太常被觸發，就把描述寫得更具體，或乾脆加上 disable-model-invocation: true。

兩個控制欄位的差別如下。部署、commit 這類有副作用的流程，官方建議用 disable-model-invocation: true，你不會希望 Claude 覺得程式碼看起來好了，就自己去部署。

放在哪裡

放的位置，決定哪些 session 載入得到：

• 同名時，個人蓋過專案（組織部署的企業 skill 又蓋過個人）；plugin 的 skill 有前綴，不會跟別人撞名。
• 個人 skill 不會跟著上雲。 Cowork 和雲端 session 不會讀你電腦上的 ~/.claude/skills/。
• 反過來，claude.ai 上啟用的會同步下來。 v2.1.275 起，用 claude.ai 帳號登入的終端機 session，會把你在帳號上啟用的 skill 和 plugin 同步進來。不想要就在設定寫 "syncClaudeAiSkills": false（plugin 的開關是 syncClaudeAiPlugins）。要注意同步下來的是副本：直接改那個資料夾裡的檔案不會存回你的帳號。
• 改完不用重開。 在 ~/.claude/skills/ 或專案的 .claude/skills/ 裡新增、修改、刪除 skill，當下的 session 就會生效；只有原本不存在的最上層 skills 資料夾，第一次建立時要重開 Claude Code。

怎麼手動呼叫

輸入 / 加上 skill 名稱。個人和專案 skill 的指令名稱來自資料夾名稱，frontmatter 的 name 只改顯示名稱。後面接的文字會帶進 $ARGUMENTS，要拿單一參數就用 $0、$1：

---
name: fix-issue
description: Fix a GitHub issue
disable-model-invocation: true
---

Fix GitHub issue $ARGUMENTS following our coding standards.

執行 /fix-issue 123，Claude 收到的就是「Fix GitHub issue 123 following our coding standards.」。內容裡沒有放任何參數位置的話，Claude Code 會在最後補上 ARGUMENTS: <你輸入的文字>，不會漏掉。

真實案例：一份正式的 skill 長什麼樣

上面的範例只有一個檔案。實際在用的 skill 會長成什麼樣，可以直接看 Cloudflare 開源的 security-audit-skill，它把 coding agent 變成資安稽核員，是 Cloudflare 內部漏洞探勘系統的單一 repo 起點版。

它值得看的地方，剛好對應這一章前面講過的幾件事：

• description 直接界定兩種模式。 同一份 skill，回答資安問題時只當參考資料用，明確要求「稽核整個 codebase」時才跑完整的六階段流程。載入 skill 不等於授權它動手，這條界線就寫在 description 和內容開頭的 Operating modes。
• 參考資料拆成多檔，用到才讀。 SKILL.md 只有 192 行，放原則、術語和流程總覽；記憶體安全、AI 與 LLM、HTTP 與身分驗證、供應鏈、雲端部署等十個領域各自一個檔案，由 SKILL.md 指路，稽核的目標用不到就不會載入。整份加起來約 1,778 行，平常不佔 context。
• 資料夾裡可以放程式。 除了 markdown，還有一份 JSON schema 和兩支零依賴的 Node 驗證腳本，流程跑到特定階段就執行它們，檢查產出的 findings.json 和覆蓋率紀錄格式對不對。skill 不是只能放指示。
• subagent 分工寫進流程。 找漏洞和驗證漏洞規定由不同的 agent 做，負責驗證的那一個，任務是想辦法推翻前一個的結論。它用 parent、Task tool 這種中性講法描述角色，所以沒有綁定 Claude Code。

安裝用 Skills CLI，對應前面「放在哪裡」那一節的兩種位置：

# project-level
npx skills add https://github.com/cloudflare/security-audit-skill --skill security-audit

# personal, all projects
npx skills add https://github.com/cloudflare/security-audit-skill --skill security-audit --global

授權是 MIT，可以直接把它的 SKILL.md 當範本，看一份正式的 skill 怎麼把「什麼時候該用」和「照著做什麼」分開寫。

下一步

建議只做一件事：找一段你最常貼進對話的指示，照上面的範例在 ~/.claude/skills/ 建一個個人 skill。先用 /skill-name 跑一次確認內容對，再開新對話，用自然的問法看 Claude 會不會自己載入；不會的話，回頭改 description。

資料來源：Claude Code 官方文件〈Extend Claude with skills〉 的 Create your first skill、Choose where skills load、Frontmatter reference、Control who invokes a skill、Pass arguments to skills、Edit a skill during a session、Run skills in a subagent、Troubleshooting 各節（2026-09-15 查詢）。真實案例一節的事實來自 cloudflare/security-audit-skill 的 README 與 SKILL.md（2026-09-19 查詢）。claude.ai 同步一段的事實來自 Claude Code CHANGELOG 的 2.1.275（2026-09-19 查詢）

Subagents 與平行化

如果你讓 Claude Code 跑過測試、翻過一大包 log，大概都遇過同一件事：事情做完了，對話也被一堆之後不會再看的輸出塞滿，後面的回答開始變慢、變鈍。

Subagent 就是用來解決這件事的。它像是你派出去跑腿的助理：你交代一件事，它自己去翻檔案、跑指令，回來只交一頁摘要給你。翻過的那些資料留在它那邊，不會堆到你的桌上。

為什麼能省主對話的 context

每個 subagent 都有自己獨立的 context window，也有自己的 system prompt、可用工具和權限。它開始工作時，看不到你們前面的對話，也看不到 Claude 已經讀過的檔案。它拿到的是：

工作中讀的檔案、跑出來的輸出，都留在 subagent 的 context 裡，回到主對話的只有最後的結果。所以如果有一條規則一定要讓 subagent 知道，例如「不要動 vendor/ 資料夾」，委派的時候要在 prompt 裡再講一次。

內建的 subagent

不用設定，Claude 會在適合的時候自己派出去：

Explore 和 Plan 為了快、為了省，會跳過 CLAUDE.md 和 git status。它們也是一次性的，不會回傳 agent ID，做完就沒辦法接著做；需要中途追問的工作，要用 general-purpose 或自訂的 subagent。

自訂 subagent：放在哪裡

Subagent 就是一個有 YAML frontmatter 的 Markdown 檔。放在哪裡，決定誰用得到；同名的時候，優先順序高的贏：

專案用的放 .claude/agents/ 並進版控，整個團隊都能用；個人常用的放 ~/.claude/agents/。兩個資料夾都會往下掃子資料夾，但 subagent 的身分只看 name 欄位，跟放在哪個子資料夾無關。

檔案長這樣

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.

frontmatter 管設定，下面的內文就是這個 subagent 的 system prompt。只有 name 和 description 是必填，其他常用的欄位：

/agents 不再開精靈，直接請 Claude 建

v2.1.197 以前，/agents 會開一個互動式的建立精靈；從 v2.1.198 開始，執行它只會提醒你：直接請 Claude 建立，或自己編輯 .claude/agents/。檔案格式和存放位置都沒變。所以最快的方式，就是跟 Claude 說：

Create a personal code-improver subagent in ~/.claude/agents/ that scans files and suggests improvements. Make it read-only and have it use Sonnet.

檔案存檔後幾秒內就會生效，不用重開。例外是 agents 資料夾在 session 開始時還不存在，這時候要重開 Claude Code 才讀得到。建好之後有三種叫法：在 prompt 裡直接點名（由 Claude 決定要不要派）；輸入 @ 從選單挑，例如 @"code-reviewer (agent)" look at the auth changes，保證這次一定用它；或用 claude --agent code-reviewer 讓整個 session 都換成它的 system prompt、工具限制和模型。

平行執行

Subagent 分前景和背景。前景會卡住主對話直到做完；背景可以同時跑，遇到需要權限的工具呼叫，會在主對話跳出來問你，並標出是哪個 subagent 在問。互動模式預設開啟 fork mode，Claude 派出去的 subagent 會在背景跑；正在跑的任務也可以按 Ctrl+B 丟到背景。

彼此不相依的調查，就可以一次派好幾個：

Research the authentication, database, and API modules in parallel using separate subagents

每個 subagent 各查各的，最後由 Claude 整合。不過結果還是會回到主對話，派很多個、每個都回一大篇，一樣會吃掉 context，委派時可以要求只回報重點。同時跑的數量預設上限是 20 個，超過會出現 Concurrent subagent limit reached，可以用 CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS 調整。

什麼時候該用、什麼時候不該用

如果你要的是可以重複使用、但在主對話裡跑的流程，用 Skills 比較適合；只是想針對對話裡已經有的內容問個問題，用 /btw 就好。

下一步

先做一個唯讀的 code reviewer：請 Claude 在 ~/.claude/agents/ 建一個只有 Read, Grep, Glob 工具的 subagent，改完程式後輸入 @ 挑它出來 review。確定它回報的內容用得上，再開始試著一次派多個 subagent 平行查資料。

資料來源：Claude Code 官方文件〈Create custom subagents〉 的 Built-in subagents、Quickstart: create your first subagent、Configure subagents、Work with subagents 各節（2026-09-15 查詢）

成本控制與 context 管理

如果你讓 Claude Code 開著一整天，大概會遇到一件事：明明只問了一行問題，用量卻比你以為的多很多。

原因出在 context。context 就像一本對話筆記本：你每問一句，Claude Code 都要把整本筆記本重新交給 Claude 看一次。筆記本越厚，每次交出去的成本就越高。所以控制成本，說穿了就是管好這本筆記本的厚度。

先看用了多少

要管厚度，得先知道現在有多厚。官方文件提到這幾個工具：

/usage 最上面的 Session 區塊長這樣：

Total cost:            $0.55
Total duration (API):  6m 20s
Total duration (wall): 6h 33m 10s
Total code changes:    0 lines added, 0 lines removed
Usage by model:
   claude-sonnet-4-6:  1.2k input, 5.3k output, 940.0k cache read, 50.0k cache write ($0.55)

看這個畫面要知道三件事：

• 金額是估算。 Claude Code 用 token 數量乘上定價，在本機算出來的。正式帳單以 Claude Console 的 Usage 頁面為準。
• 訂閱方案不用看這個金額。 Pro、Max 的用量包含在訂閱裡，Session 的金額跟帳單無關。同一個畫面會另外顯示方案用量條、活動統計和用量拆解。
• /clear 會歸零。 /clear 會開一個新 session，金額從 $0 重新算。v2.1.211 以前的版本不會歸零，會一路累加到 Claude Code 關掉為止。

如果你是 Pro、Max、Team 或 Enterprise 方案，/usage 的用量拆解更有用。它會列出 skills、subagents、plugins 和各個 MCP server 各佔多少百分比；長 context、cache miss 這類行為只要佔最近用量 10% 以上，也會被標出來，並附上減少的建議。按 d 或 w 可以切換最近 24 小時和最近 7 天。這些數字只來自這台電腦的 session 紀錄，其他裝置和 claude.ai 的用量不會算進去。

context 是怎麼被吃掉的

知道用了多少之後，下一個問題是：為什麼會這麼多？官方文件列出 session 開久了用量會往上爬的幾個原因：

第一項最常被忽略。Claude Code 有 prompt caching，重複的內容會用比較便宜的 cache 費率讀取，但也只是便宜，不是免費。在開了一整天的 session 裡問一行問題，一樣會為整段對話消耗用量。

除了對話本身，CLAUDE.md 在 session 一開始就會載入。MCP 的工具定義預設是延遲載入，在 Claude 真的用到某個工具之前，只有工具名稱和 server 說明會進 context。

/clear 和 /compact：換一本新的，還是把舊的濃縮

判斷方式很簡單：接下來要做的事，需不需要前面的對話？ 不需要就 /clear。官方文件也提到，API 或雲端方案的費用異常偏高，通常就是 session 開很久都沒清。用 /clear 之前，可以先用 /rename 幫 session 取個名字，之後想回來，用 /resume 就找得到。

用 /compact 時，可以在後面告訴 Claude 要保留什麼：

/compact Focus on code samples and API usage

也可以寫在專案根目錄的 CLAUDE.md，讓每次摘要都照這個方向：

# Compact instructions

When you are using compact, please focus on test output and code changes

另外，Claude Code 在對話接近 context 上限時，會自動做一次 compaction。看到 auto-compact 的警告不代表用量到上限，只是 context 快滿了。

選對模型

API 或雲端方案費用偏高的另一個常見原因，是一直把 Opus 當預設模型。官方的建議是：大部分寫程式的工作交給 Sonnet，它比 Opus 便宜；Opus 留給複雜的架構決策或多步驟推理。

• 對話中途換模型：/model
• 設定預設模型：/config
• 簡單的 subagent 任務：在 subagent 設定裡寫 model: haiku

extended thinking 也會花錢。thinking 的 token 是用 output token 計費，預設的預算依模型不同，一次請求可能到數萬 token。不需要深度推理的簡單工作，可以用 /effort 或在 /model 裡調低 effort level，或是在 /config 關掉 thinking。Fable 模型固定使用 extended thinking，關不掉。

減少 token 的具體做法

下一步

下次打開 Claude Code，先做兩件事：輸入 /context，看看 context 被什麼佔掉；再輸入 /model，確認預設模型不是一直停在 Opus。之後每次要換到不相關的工作，就先 /rename，再 /clear。

資料來源：Claude Code 官方文件〈Manage costs effectively〉 的 Track your costs、When a developer asks about a limit、Reduce token usage、Why usage climbs in a long session 各節（2026-09-15 查詢）

Session 管理與 Checkpoint 回溯

如果你照前一章的建議，換工作前先 /clear，大概會遇到下一個問題：昨天那段對話，今天還接得回來嗎？

接得回來。Claude Code 每一段對話都會存成一個 session，像一本一本的筆記本，放在你電腦上。只要知道怎麼翻回去，就不用擔心關掉視窗會弄丟前面的脈絡。同一套機制還可以往回退：Claude 改壞了檔案，可以退回到某一則訊息之前的狀態。

先幫 session 取名字

沒取名字也接得回去，但清單上全是機器產生的標題，你會認不出哪一本是哪一本。取名有幾個時機：

claude -n auth-refactor     # name it at startup

/rename auth-refactor

在 session 選擇器裡把游標移到某一段對話，按 Ctrl+R 也可以改名。另外，在 plan mode 裡接受一份計畫時，如果這段對話還沒有名字，Claude Code 會自動幫它取。

沒取名字的 session 會拿到兩個標籤：一個是工作目錄名稱加兩個字的尾碼，例如 my-app-3f，這個只是顯示用，不能拿來接回去（v2.1.196 起）；另一個是 Haiku 這類模型看你第一句話產生的標題，這個可以直接拿來接。

名字撞到的時候不用擔心蓋掉：如果這台機器上有另一段還在跑的對話已經用了這個名字，Claude Code 會保留原本那段的名字，把新的這段改成加上兩個字尾碼的變體，例如 auth-refactor-graceful-unicorn，並且告訴你。

三種接回去的方法

--continue 會跳過用 claude -p、Agent SDK 建立的 session，也會跳過第一句是 /loop 的。已經跑完的背景 session，要 v2.1.257 以後才接得回來。

選擇器預設只看目前這個工作樹，以及你用 /add-dir 加進來的目錄。找不到的時候，按 Ctrl+W 擴大到這個 repo 的所有 worktree，按 Ctrl+A 擴大到這台機器上的所有專案。用 session ID 接的話，v2.1.223 之後會先找目前專案和它的 worktree，找不到再找其他專案；更早的版本只找目前這個目錄，所以得回到當初那個目錄才接得到。

還有兩個平常用不到、但知道了會有用的參數：--session-id 可以自己指定這段對話的 ID，要是合法的 UUID；--fork-session 會在接回來的同時開一個新的 session ID，原本那段保持原樣，適合想從同一個起點試另一個方向。

接回來會恢復什麼

有幾種情況模型不會照舊：原本那個模型已經停用、availableModels 不允許、啟動時用 --model 或 ANTHROPIC_MODEL 指定了別的，或是在 Bedrock、Google Cloud、Microsoft Foundry 這類用部署 ID 的平台上。

不是每個啟動參數都會恢復。 如果這段對話靠的是 --mcp-config、--settings、--plugin-dir、--fallback-model，或是用 --add-dir 加進來的目錄，接回來的時候要自己再帶一次。對話進行到一半用 /add-dir 加的目錄也不會回來。settings.json、settings.local.json 這些設定檔則是每次啟動都重讀。

權限模式的部分，跟第 7 章那張表接得上：在終端機裡，原本停在 bypassPermissions 或 plan 模式的，接回來會變成新 session 本來就會啟動的模式；原本是 auto 的，帳號條件還符合就還是 auto；原本是 Manual 的，接回來也是 Manual，除非設定檔裡的 defaultMode 另有指定。

如果原本那段有用到 --agent，而那個 agent 在原本的目錄或現在的目錄都找不到，Claude Code 會顯示警告，然後用預設工具把對話接回來。

另外，原本在跑的工具呼叫不會續跑。當機前跑到一半的指令，接回來不會重新執行也不會補完，Claude 會在沒有那段輸出的情況下繼續。

隔太久才接回來，會問你要不要先濃縮

Pro 和 Max 方案，接回一段超過一小時沒動、而且超過 10 萬 token 的對話時，Claude Code 會在你送出第一句話之前跳一個對話框，三個選項：

• 從摘要恢復：等於立刻跑一次 /compact，token 便宜很多，但摘要省掉的細節就不在脈絡裡了
• 完整恢復：原封不動載回來，之後每一次請求的 token 都照對話大小算
• 不再詢問：這次完整恢復，以後不再跳這個對話框

改壞了：用 /rewind 退回去

每送出一則訊息、開始新的一輪，Claude Code 就存一個 checkpoint。要退回去的時候輸入 /rewind，或在輸入框沒有字的時候按兩下 Esc（輸入框裡有字的話，按兩下 Esc 是清空，清掉的字會進輸入歷史，按 Up 叫得回來）。

選單裡有六個選項：

如果那個 checkpoint 沒有追蹤到任何檔案變動，選單就只會出現 Restore conversation、兩個摘要選項和 Never mind。

摘要不會動到磁碟上的檔案，原本的訊息也還留在謄本裡。想指定摘要的重點，把游標移到 Summarize 那一列、直接打字再按 Enter；用數字鍵選的話會直接摘要，不帶你的指示。

還有一個救援用的入口：如果你在同一個 Claude Code 程序裡先前跑過 /clear，rewind 選單最上面會多一列 /resume <session-id> (previous session)，選它就能回到 /clear 之前那段對話。這一列只在你離開 Claude Code 或接了別段 session 之前有效，需要 v2.1.191 以上。

Checkpoint 救不回來的東西

這部分要先知道，不然會把它當成萬能的還原點：

• Bash 指令改的檔案不算。 Claude 跑 rm、mv、cp 動到的檔案，rewind 退不回來。只有透過 Claude 檔案編輯工具直接改的才會被追蹤。
• Subagent 改的通常退不回來。 只有 context: fork 而且在前景跑的 skill，編輯是在自己那一輪裡進行，rewind 才退得掉；其他 subagent（包含預設在背景跑的 fork skill、背景的 /code-review --fix）改的檔案要靠 git 還原。
• 外部的改動不算。 你自己在 Claude Code 外面改的、另一段對話同時改的，通常不會被記錄。
• 插隊送出的訊息沒有 checkpoint。 你在 Claude 工作到一半排進去的訊息，會併進當時那一輪，選單上不會出現。要退的話，退到開啟那一輪的那則提示，整輪一起退掉。
• Symlink 和硬連結會被跳過。 選 Restore code 時會跳過這些路徑並顯示 Restored the code, but skipped N files，那些檔案維持現在的內容。想知道跳過了哪些，先用 /debug 開除錯紀錄，紀錄在 ~/.claude/debug/<session-id>.txt。

官方文件也講得很直接：checkpoint 是為了在同一段對話裡快速還原而設計的，長期的版本歷史和協作還是要交給 git。所以會大改的工作，開始之前先 commit 一次，rewind 留給同一段對話裡的小失誤。

存在哪、留多久

謄本預設放在 ~/.claude/projects/<專案>/<session-id>.jsonl，<專案> 是工作目錄路徑把非英數字元換成 - 之後的名字。每一行是一個 JSON 物件，但這是內部格式、會隨版本改變，要匯出請用 /export，不要自己寫程式去解析。

Checkpoint 的檔案快照保留最近 100 個，而且會跟著上面那個 30 天的保留期被清掉。快照被清掉之後再去 rewind，會失敗並出現 No files were restored。真的有需要留久一點，就把 cleanupPeriodDays 調大。

下一步

下次開始工作前先做一件事：用 claude -n <工作名稱> 開，或是進去之後馬上 /rename。這樣明天用 claude --resume 就認得出哪一段是哪一段。接著找一個改壞的時機按兩下 Esc，把 rewind 的六個選項看過一次，知道哪一個只退對話、哪一個連檔案一起退，真的需要的時候才不會慌。

資料來源：Claude Code 官方文件〈Sessions〉的 Resume a session、What a resumed session restores、Permission mode on resume、Resume from a summary、Name your sessions、Where transcripts are stored、Where the session picker looks 各節，以及〈Checkpointing〉的 Automatic tracking、Rewind and summarize、Rewind past a cleared conversation、How checkpoints work、Limitations、Not a replacement for version control 各節（2026-09-18 查詢）

Plugins 與 Marketplace

第 9、10 章寫完 skill 和 subagent 之後，大概會遇到同一個問題：這些東西都躺在自己的 ~/.claude/ 底下，換一台電腦、或是想給同事用，要一個一個複製資料夾。

Plugin 就是把它們打包起來的方式。一個 plugin 是一個可以獨立帶著走的套件，裡面可以同時放 skill、subagent、hook、MCP server 和預設設定；marketplace 則是放這些套件的清單，你指向一個來源，就能從裡面挑要裝的東西。

一個 plugin 可以裝什麼

放在 plugin 根目錄底下，各自對應一種功能：

plugin 裡的 skill 會被加上前綴，叫法變成 /<plugin 名稱>:<skill 名稱>。如果整包只有一個 skill，也可以不開 skills/，直接把 SKILL.md 放在根目錄。

裝別人的 plugin

輸入 /plugin 會開一個面板，分成 Discover、Installed、Marketplaces、Errors、Stats 幾個頁籤，用點的就可以。習慣打指令的話：

/plugin install github@claude-plugins-official   # install from a marketplace
/plugin list --enabled                           # what is on right now
/plugin disable <name>@<marketplace>             # turn it off, keep it installed
/plugin uninstall <name>@<marketplace>

官方 marketplace 叫 claude-plugins-official，由 Anthropic 維護，第一次啟動互動模式時會自動註冊；沒有自動裝好的話，手動加回來：

/plugin marketplace add anthropics/claude-plugins-official
/plugin marketplace add anthropics/claude-plugins-community   # community one, add it yourself

marketplace 的來源可以是 GitHub 的 owner/repo、Git URL、遠端網址，或是本機路徑。另外還有 /plugin marketplace list、update <名稱>、remove <名稱> 可以管理。

第一次在某個目錄裝 plugin 時，Claude Code 會問你信不信任這個目錄；在 git repo 裡回答一次，整個 repo 都算數。

這裡可以比較保守一點。plugin 能同時帶 hook 和 MCP server，等於裝進來的東西會在你電腦上跑指令。裝之前先看來源：官方 marketplace、或是很多人在用的比較安心；看起來很新、還沒什麼人用過的，先把它的 hooks/ 和 .mcp.json 打開來看過再決定。

v2.1.271 之後，安裝這一段的安全性補了幾個洞，值得知道：

• npm 來源的 plugin 不再執行安裝腳本。 改成用 npm pack --ignore-scripts 抓下來、再驗證完整性，所以套件裡的 postinstall 不會在你電腦上跑。
• --marketplace 可以一次帶過。 /plugin install <plugin> --marketplace <來源>，還沒加過的 marketplace 會先問你要不要加，不用分兩步。
• CI 裡不要用 -y。 claude plugin install 和 claude plugin update 支援 --accept-command <sha256>：只接受前一次 --json 顯示過的那一條指令，內容變了就不會通過，等於幫自動化留一道核對。
• claude.ai 帳號上啟用的 plugin 會同步到終端機，跟第 9 章的 skill 同步是同一套機制，"syncClaudeAiPlugins": false 可以關掉。

裝完之後改了 plugin 的內容，不用重開：

/reload-plugins            # apply changes in the current session
/reload-plugins --force    # when the cache needs rebuilding too

自己包一個

目錄長這樣：

my-plugin/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   └── hello/
│       └── SKILL.md
├── agents/
├── hooks/
│   └── hooks.json
└── .mcp.json

plugin.json 最少要有這些欄位：

{
  "name": "my-plugin",
  "description": "What this plugin does",
  "version": "1.0.0",
  "author": { "name": "Your Name" }
}

version 可以不寫，不寫的話會用 git SHA 當版本。name 同時決定 skill 的前綴，所以取名要短一點。

開發過程不用先發布，直接指向本機資料夾就能測：

claude --plugin-dir ./my-plugin     # load one plugin for this session
claude --plugin-dir ./plugins       # v2.1.265+: load every plugin in the folder
claude plugin validate ./my-plugin  # check the structure and schema

指向資料夾的時候，Claude Code 會先看這一層有沒有 plugin 的內容，沒有的話就把它當成「裝很多 plugin 的資料夾」，每個有 .claude-plugin/plugin.json 的子資料夾各算一個 plugin。

用 claude plugin eval 驗收

skill 和 hook 寫好之後，最難的是判斷它到底有沒有讓 Claude 表現得更好。claude plugin eval 就是在做這件事：拿一組測試案例跑你的 plugin，每個案例預設跑三次，還會跑一輪沒有裝 plugin 的對照組，最後報告兩邊的差距。需要 v2.1.269 以上。

claude plugin eval init                        # interview, writes cases and graders
claude plugin eval .                           # run every case
claude plugin eval . --runs 1 --ablation none  # single arm, cheaper
claude plugin eval . --trust-plugin            # for CI, skips the trust prompt

案例放在 evals/<案例名稱>/，裡面 prompt.md 寫提示詞，graders/ 底下一個檔案一個評分器。評分器有六種：

跑完會在 evals/results/<時間戳>/ 產生 aggregate-result.json 和 report.html。結束碼可以直接接 CI：0 是全部達標，1 是沒過門檻或信任提示被拒，2 是只跑完一部分（例如成本上限、認證失敗）。

有幾件事要先知道：每一次 eval 和每一次評分模型呼叫都要算錢；eval 跑在隔離的環境裡，你的個人設定、其他 plugin、記憶和 MCP server 都不會載入，所以測到的是這個 plugin 自己的效果。

下一步

先從裝一個開始：輸入 /plugin，從官方 marketplace 挑一個你每天都會用到的（例如跟 GitHub 有關的），裝起來用一週，確定用得順再加第二個。等到你自己的 ~/.claude/skills/ 裡有兩三個常用的 skill，就把它們搬進一個 plugin 資料夾，用 claude --plugin-dir 在本機測過，再決定要不要放上 marketplace 給別人用。

資料來源：Claude Code 官方文件〈Create plugins〉的 Create your first plugin 各節、〈Discover and install prebuilt plugins〉的安裝與 marketplace 各節，以及〈Test plugins with evals〉的 Requirements、Graders、Run evals 各節（2026-09-18 查詢）。安裝安全性一節的事實來自 Claude Code CHANGELOG 的 2.1.271 與 2.1.275（2026-09-19 查詢）

模型、Effort 等級與 Fast mode

上一章講到用 plugin 把工具打包，但工具再齊，最後決定答案品質和帳單金額的還是兩件事：用哪個模型，以及讓它想多久。

Claude Code 把這兩件事拆開了。模型決定底子，effort 等級決定它在回答之前願意花多少力氣思考。搞懂這兩個，比一直在 Opus 和 Sonnet 之間猶豫有用。

現在有哪些模型

不用背完整的 model ID，記別名就好：default、best、fable、opus、sonnet、haiku、opusplan，以及長 context 版本的 sonnet[1m]、opus[1m]。

別名實際會對到哪一個模型，看你走哪個平台：

預設用哪一個則看方案：Max、Team Premium、Enterprise 和 API 是 Opus 5；Pro 和 Team Standard 是 Sonnet 5。

要換模型的方法由近而遠：/model <別名> 只改這一次對話、claude --model <別名> 開的時候指定、環境變數 ANTHROPIC_MODEL、settings.json 的 model，最後是 ANTHROPIC_DEFAULT_MODEL（v2.1.236 起，只影響新對話的預設值）。

opusplan 這個別名值得記：規劃的時候用 Opus，進到實作再換回 Sonnet，適合會先想清楚再動手的工作。

Effort 等級：讓它想多久

同一個模型，可以調它思考的力氣：

大部分模型預設是 high，Opus 4.7 預設是 xhigh。切換方式：

claude --effort xhigh                  # at startup
export CLAUDE_CODE_EFFORT_LEVEL=medium # environment variable

/effort          # interactive slider
/effort high     # set it directly

設定檔裡對應的是 effortLevel（預設值）、modelSettings（每個模型各自記住的等級）、maxEffortLevel（上限）。

思考本身是要算錢的：thinking token 按 output token 計費。所以簡單的工作調到 low 或 medium，比一直用 high 省，而且快。想整個關掉延伸思考，設 MAX_THINKING_TOKENS=0（Fable 例外）。

ultracode 不是 effort 等級，而是一個組合：xhigh 的思考力氣，加上自動用 dynamic workflow 去協調一整批 subagent。下一章會專門講。

Fast mode：同一個 Opus，快 2.5 倍

Fast mode 不是換模型，是同一個 Opus 走另一套 API 設定，把速度排在成本前面，回應最快可以到 2.5 倍。支援 Opus 5 和 Opus 4.8，Sonnet 和 Haiku 沒有。這是研究預覽，功能、價格、開放範圍都可能改。

價格是每百萬 token 輸入 10 美元、輸出 50 美元。要注意的是啟用的那一刻，整個對話的 context 會以未快取的價格算一次輸入，所以要開就在對話一開始開，開到一半才開比較貴。

/fast        # toggle
/fast on     # in a cloud session

設定檔裡 fastMode 決定預設開不開，fastModePerSessionOptIn 可以要求每次對話都手動開一次（v2.1.257 起）。

Pro 和 Max 要先在 Settings 的 Usage 開啟使用額度，Team 和 Enterprise 要由擁有者在 Admin Settings 開。Bedrock、Google Cloud Agent Platform、Microsoft Foundry、Claude Platform on AWS 都不支援。

模型掛掉時的備援

主模型過載、暫時不可用、或遇到不值得重試的伺服器錯誤時，可以自動換一個接手：

claude --fallback-model sonnet,haiku

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

一條鏈最多三個模型，切換只影響當下那一輪，subagent 也會跟著套用。認證、帳單、流量限制、請求太大這幾種錯誤不會觸發備援，因為換模型也解決不了。

另外還有一種依內容自動切換：例如 Fable 5.1 和 Fable 5 遇到生物學會轉給 Opus 5、遇到資安會轉給 Opus 4.8；Opus 5 遇到資安轉 Opus 4.8，遇到生物學則是拒絕。不想要這個行為，在 /config 裡關掉切換模型那一項，或設 "switchModelsOnFlag": false。

怎麼配比較省

平常留在預設模型就好，不用一直切。真的要想清楚的工作（架構、難查的 bug）再切 opusplan 或把 effort 調到 xhigh；改個文案、跑個測試這種降到 medium，省下來的是時間也是錢。Fast mode 適合趕時間的時候，而且要在對話開頭就開，開到一半比較貴。

下一步

現在就做一次盤點：輸入 /model 看目前是哪一個、輸入 /effort 看在哪一格。接著挑一件你今天做過的小工作，把 effort 降到 medium 重跑一次，比較結果有沒有變差。用不到高 effort 的工作能降下來，/context 和帳單都會好看一點。

資料來源：Claude Code 官方文件〈Model configuration〉的 Model Aliases、Model Resolution by Provider、Effort Levels、Fallback Model Chains、Automatic Model Fallback 各節，以及〈Fast mode〉全文（2026-09-18 查詢）

Worktrees 與多個 session 同時開工

第 10 章的 subagent，解決的是「一件事分很多步驟」。但如果你手上同時有兩件不相干的事——一邊改登入流程、一邊修 CI，開兩個視窗各跑一個 Claude Code，兩邊改同一份工作目錄，改到一半就會互相踩到。

Git worktree 是原本就有的解法：同一個 repo，多開幾個工作目錄，各自待在自己的分支上，歷史和遠端共用。Claude Code 把它接了進來，每一段對話可以待在自己的 worktree 裡，彼此的檔案不會打架。

開一個 worktree 進去工作

claude --worktree auth-refactor   # create a named worktree and start there
claude -w auth-refactor           # same thing, short form
claude --worktree                 # no name: one is generated, e.g. bright-running-fox
claude --worktree "#1234"         # branch from a PR

預設會建在 repo 根目錄的 .claude/worktrees/<名稱>/，分支叫 worktree-<名稱>。這個資料夾要加進 .gitignore。

已經在對話裡了才想隔離，也可以直接請 Claude 開一個，它會用 EnterWorktree 建。要看現在有哪些、想手動清掉，就用原本的 git 指令：

git worktree list
git worktree remove <path>

從哪個分支長出來，以及怎麼清掉

預設是從預設分支開新的；想從你現在的 HEAD 長出來，改設定：

{ "worktree": { "baseRef": "head" } }

離開的時候：乾淨的、沒命名的 worktree 會自動移除；有命名或有改動的，會問你要留還是要刪。claude -p 這種非互動模式不會做清理，要自己 git worktree remove。subagent 和背景 session 用掉的 worktree，則會照 cleanupPeriodDays 定期清掉。

還有一個很實用的檔案：.worktreeinclude。worktree 是新的工作目錄，被 git 忽略的檔案不會跟著過去，所以 .env 這類東西會不見。用 .gitignore 的語法把它們列進來，每開一個新的 worktree 就會複製一份：

.env
.env.local
config/secrets.json

接回 worktree 裡的 session 需要 v2.1.212 以上，舊版對謄本位置的追蹤會出問題。

用 agent view 看全部的 session

同時跑好幾段對話之後，下一個問題是：哪一段跑完了、哪一段在等你回答？

claude agents              # full-screen dashboard
claude agents --cwd <path> # only sessions under this directory
claude agents --json       # for scripts

畫面上每一段對話前面有狀態符號：✽ 執行中、✻ 在等你輸入、∙ 閒置、✢ 排程中（會顯示倒數）、✓ 完成、✗ 失敗。常用的鍵：Enter 或 → 進去那一段、Space 開關預覽、Ctrl+R 改名、Ctrl+X 停止（再按一次刪除）、Ctrl+S 切換分組方式、? 看全部快捷鍵。

不想進畫面，也有對應的指令：

claude attach <id>     # open that session in this terminal
claude logs <id>       # print its recent output
claude stop <id>       # stop it
claude rm <id>         # remove it from the list
claude daemon status   # check the supervisor process

Agent teams：讓好幾個 session 互相協調

再上一層是 agent teams：一段對話當隊長，負責分工和彙整，其他隊友各自有獨立的 context，可以直接互相傳訊息。這個功能預設關閉，要自己打開：

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

打開之後，用自然語言描述任務和你要的角色，Claude 會把隊友建起來。任務放在共用的任務清單裡，有待處理、進行中、完成三種狀態，也可以設相依性——前一件沒完成，後面那件就不能被認領；檔案鎖則用來避免同時改同一個檔。任務和信箱分別放在 ~/.claude/tasks/{team-name}/ 和 ~/.claude/teams/{team-name}/inboxes/。

隊友要顯示在哪裡可以選：預設 in-process 全部跑在同一個終端機裡；auto 在 tmux 或 iTerm2 底下會自動分割視窗；也可以指定 tmux 或 iterm2（iTerm2 需要 v2.1.186 以上，還要裝 it2 和 iTerm2 的 Python API）。VS Code 的內建終端機、Windows Terminal、Ghostty 不支援分割視窗。

限制要先知道：/resume 和 /rewind 接不回隊友，接回來的對話裡隊友已經不在了；claude -p 底下隊友會退化成一般的 subagent；隊友不能再生隊友；一段對話只能有一個 team。

四種平行方式，怎麼挑

成本上要有心理準備：subagent 的結果會收斂回主對話，相對省；agent teams 每個隊友都是獨立的執行個體，token 會明顯多很多。

下一步

下次同時有兩件事要做的時候，第二件不要另外開視窗，改成 claude -w <名稱> 開一個 worktree 進去。記得先把 .claude/worktrees/ 加進 .gitignore，並且在 .worktreeinclude 裡列上 .env。兩邊都跑起來之後，另開一個終端機輸入 claude agents，看著狀態符號決定先回哪一邊。

資料來源：Claude Code 官方文件〈Run parallel sessions with worktrees〉的 Start Claude in a worktree、Customize worktree creation、Copy gitignored files into worktrees、Clean up worktrees 各節，〈Agent View〉的 Opening Agent View、Key Commands、State Icons、Keyboard Shortcuts 各節，以及〈Orchestrate teams of Claude Code sessions〉的 Enable agent teams、Assign and claim tasks、Choose a display mode、Compare with subagents、Limitations 各節（2026-09-18 查詢）

自動化：headless 模式、CI 與排程

前面講的都是你坐在終端機前面、一句一句跟它講。但有些工作不需要你在場：每天早上整理昨天的 issue、每次開 PR 自動跑一輪 review、把一段固定的檢查排進 CI。

這一章講的是把 Claude Code 從對話工具變成可以被呼叫的程式：怎麼在沒有人互動的情況下跑、怎麼接進 GitHub、怎麼排時間自己跑。

headless 模式：claude -p

加上 -p（或 --print）就不會進互動介面，跑完直接輸出結果，成功回傳 0、失敗回傳非 0，可以直接接在 shell script 裡。

claude -p "summarise today's git log" --output-format json
cat error.log | claude -p "what failed here?"   # stdin, up to 10MB

--output-format 有 text（預設）、json、stream-json 三種。要固定輸出格式，可以用 --json-schema 搭配 --output-format json。

權限這裡要特別小心：-p 預設是 Manual 模式，沒有人可以按同意，所以要嘛先開權限，要嘛明講不准問：

claude -p "run the tests" --allowedTools "Read,Bash"   # pre-approve
claude -p "..." --permission-mode dontAsk               # no prompts
claude -p "..." --permission-prompts none               # refuse everything that needs asking

還有一個讓 CI 跑得更快、更穩的參數：--bare。它會跳過 hook、skill、自訂指令、subagent、plugin、MCP server、auto memory 和 CLAUDE.md 的自動載入，等於一個乾淨的環境，換到哪台機器結果都一樣。要注意 bare 模式不讀 OAuth 登入和系統鑰匙圈，得自己設 ANTHROPIC_API_KEY。

跑完離開的時候：背景的 Bash 任務會在結果回傳後幾秒內結束，subagent 和 workflow 會等它們做完，但最多等 10 分鐘（CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS 可以調）。要接續前一次的對話，--continue 和 --resume <session-id> 在 -p 底下一樣能用。

接進 GitHub Actions

比較快的裝法是在互動模式裡輸入 /install-github-app：它會幫你裝 GitHub App、加好認證用的 secret，並開一個加入 workflow 檔的 PR。需要 GitHub CLI 和 repo 的管理權限。手動裝的話，就是自己裝 App、加 ANTHROPIC_API_KEY 或 CLAUDE_CODE_OAUTH_TOKEN 這個 secret、把 workflow 檔複製進去。

workflow 有兩種跑法，差別只在有沒有給 prompt：

• 沒給 prompt：互動模式，等別人在 issue 或 PR 留言 @claude 才動作
• 有給 prompt：自動模式，事件一觸發就跑，不等人

誰可以觸發也有限制：預設要有寫入權限的人才行，其他人要列進 allowed_non_write_users；機器人帳號要列進 allowed_bots。

走雲端廠商的話，在 workflow 裡改用對應的開關：Bedrock 用 use_bedrock: "true" 搭配 OIDC 的 AWS_ROLE_TO_ASSUME、Google Cloud Agent Platform 用 use_vertex: "true" 搭配 Workload Identity Federation、Microsoft Foundry 用 use_foundry: "true" 搭配 Entra 應用程式的那組變數。

認證的東西一律走 GitHub Secrets，不要寫進檔案；workflow 的權限給到剛好夠用就好；Claude 開出來的變更，合併前還是要自己看過。

排程：讓它自己定時跑

雲端的排程叫 routines，可以在 claude.ai/code/routines 建立，或在 CLI 用 /schedule。它跑在 Anthropic 託管的雲端環境（或組織自架的環境），不需要你的電腦開著。觸發方式有三種：

一次性的執行時間到了會自動停用，而且不算進每日上限。環境預設允許套件管理器、雲端 API 這類常見網域，要加自訂網域就到環境設定的 Network access 改。

如果只是想在「這一段對話裡」重複做一件事，用 /loop 就好，不用開雲端排程：

/loop 5m <prompt>   # every five minutes
/loop <prompt>      # Claude picks the interval, between 1 minute and 1 hour

也可以直接講「三點提醒我檢查部署」，它會建一個提醒。這類排程任務七天後過期，接回對話時沒過期的會一起回來，對話結束就全部清掉。

Channels：從 Telegram 之類的地方丟工作進來

Channels 讓 Telegram、Discord、iMessage 的訊息可以送進一段正在跑的對話，等於你人在外面也能丟工作給它。這是研究預覽，需要 Bun，Bedrock、Vertex、Foundry 不支援。

/plugin install telegram@claude-plugins-official
/telegram:configure <token>
/telegram:access pair <code>

安全機制要看清楚：每個 channel 有自己的寄件者允許清單，只有名單上的 ID 送得進來；Telegram 和 Discord 用配對碼把人加進名單，iMessage 是自己跟自己的對話自動允許、其他聯絡人手動加。/telegram:access policy allowlist 可以鎖成只有名單內能用。名單上的人還可以遠端核准工具呼叫，所以這份名單要當成權限清單看待，不要隨便加人。Team 和 Enterprise 預設關閉，要由 Owner 在後台開 channelsEnabled。

下一步

先從最小的一步開始：把你每天都會手動做一次的檢查，寫成一行 claude -p，加上 --allowedTools 只給它讀的權限，跑跑看輸出對不對。確定穩定之後，再決定要放進 CI、還是做成 routine 讓它自己定時跑。動到 GitHub Actions 之前，先確認 secret 設好了，而且 workflow 的權限沒有開太大。

資料來源：Claude Code 官方文件〈Headless mode〉的 Basic usage、Start faster with bare mode、Get structured output、Auto-approve tools、Background tasks at exit 各節，〈GitHub Actions〉的 Setup、Interactive and automation modes、Protect your credentials 各節，〈Routines〉的 Add a schedule trigger、Add an API trigger、Add a GitHub trigger、Usage and limits 各節，〈Scheduled tasks〉的 /loop 與 Seven-day expiry 各節，以及〈Channels〉的 Supported channels、Security、Enterprise controls 各節（2026-09-18 查詢）

Dynamic Workflows 與 ultracode

第 10 章的 subagent 是「派一個人去查」，一次派三五個還行。但如果你要的是「把 500 個檔案都掃過一遍」「同一個問題從六個角度各查一次再交叉驗證」，靠主對話一輪一輪決定下一步，中間結果會塞爆 context，錯一個地方還得從頭來。

Dynamic workflow 換一種做法：Claude 先幫你寫一份 JavaScript 腳本，由腳本決定要派幾個 agent、誰先誰後、結果怎麼收；腳本在背景執行，你的對話還可以繼續用。中間結果存在腳本的變數裡，不佔你的 context。

什麼時候用 workflow，什麼時候用 subagent

會派到幾十個 agent、而且流程固定的工作，才值得走 workflow。

怎麼啟動

比較簡單的方式是在句子裡加上 ultracode 這個關鍵字，Claude 就會為這件事寫一份 workflow 腳本。其他方式：

關鍵字只有在真人輸入時才會觸發（互動輸入、IDE 擴充、Remote Control，以及 Agent SDK 裡標成 { kind: "human" } 的輸入），-p、webhook、PR 留言、排程任務裡打了也不算（v2.1.210 起）。這是刻意的：避免別人在 issue 留言裡塞一個關鍵字，就讓你的自動化跑掉一大筆 token。

看到關鍵字被標起來但這次不想用，按 Option+W（macOS）或 Alt+W 取消；想整個關掉就到 /config 裡關 Ultracode keyword trigger。

跑之前 Claude 會先給你計畫：auto 模式第一次會問，manual 模式每次都問，bypass 模式不問。

腳本長什麼樣

腳本開頭一定是一個 meta 區塊，而且必須是純粹的物件字面量，裡面有 name 和 description。寫成變數或函式呼叫，這個 workflow 就不會出現在 / 的自動完成清單裡。

常用的函式有五個：

有兩個限制會讓習慣寫 Node 的人踩到：腳本裡不能動態載入模組，有 import() 會在執行前就失敗；Date.now()、Math.random()、沒帶參數的 new Date() 也會直接拋錯。需要時間戳就從外面用 args 傳進去。要做的事一律放進 agent 的任務裡，腳本只負責調度。

schema 驗證失敗會重試，五次還是不過就回傳錯誤，次數可以用 MAX_STRUCTURED_OUTPUT_RETRIES 調。

規模、成本與中斷後怎麼接

預設同時跑 16 個 agent（會依 CPU 縮減），可以用 CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTS 調成 1 到 256（需要 v2.1.269 以上）。單次 parallel 或 pipeline 最多 4,096 項，超過會直接拒絕而不是默默截斷；一次執行最多 1,000 個 agent，避免迴圈失控。預估會用到 25 個 agent 或 150 萬 token 時會跳警告，但不會擋下來。

設定檔裡的 workflowSizeGuideline 可以給 Claude 一個規模上的方向：small 少於 5 個、medium（預設，Pro 方案是 small）少於 10 個、large 少於 50 個、unrestricted 不限制。

省錢的關鍵在 prompt cache：同一批 agent 共用前綴時，第二個之後的可以讀快取，預設會錯開 5 秒讓第一個先建立快取（CLAUDE_CODE_WORKFLOW_PREFIX_STAGGER_MS）。快取預設留 5 分鐘，subagentPromptCacheTtl 可以設成 1h——走 API 計費時，一小時的快取寫入費率比較高，要自己權衡。

跑到一半撞到用量上限時，執行會暫停而不是失敗，額度重置後自動接著跑（需要 v2.1.271 以上、互動模式，而且開了 autoContinueAtUsageLimit）。最多等兩次，第三次就會失敗。

要接著跑沒跑完的：已完成的 agent 直接回傳存好的結果，被中斷或失敗的會重跑，而且它後面的 agent 也會一起重跑。結果存在 ~/.claude/projects/<session>/，找不到存檔的話會回報 nothing to resume，不會默默從頭開始。

所有付費方案、API、Bedrock、Google Cloud Agent Platform、Microsoft Foundry 都能用；Pro 要先在 /config 打開，組織管理員可以用 managed settings 整個關掉。

下一步

第一次先不要自己寫腳本。挑一件你平常會叫 Claude 做、但每次都嫌慢的大工作，例如「把整個 repo 掃一遍找出還在用舊 API 的地方」，在句子裡加上 ultracode，看它給的計畫派了幾個 agent、分成哪幾個階段。覺得規模太大就先把 workflowSizeGuideline 設成 small，等熟悉了再放寬。

資料來源：Claude Code 官方文件〈Orchestrate subagents at scale with dynamic workflows〉的 When to use a workflow、Have Claude write a workflow、Let Claude decide with ultracode、Where the keyword works、What the saved script looks like、Edit a saved script、Behavior and limits、Prompt caching in a fan-out、Set a size guideline、When a run hits your usage limit、Resume after a pause 各節（2026-09-18 查詢）

除了終端機，還可以在哪裡用

到這裡為止，整份文件講的都是終端機裡的 Claude Code。但同一個帳號、同一套設定，其實可以在 IDE、桌面應用、瀏覽器、手機甚至 Slack 上用，各自能做的事不太一樣。

這一章是一張對照表，幫你決定哪個情境該用哪一個。

VS Code 與 JetBrains

VS Code 需要 1.94 以上，在擴充套件市集搜 Claude Code 就能裝。裝完可以直接在編輯器裡看行內 diff、用 @ 提到檔案、審閱計畫、開多個分頁各跑一段對話，也看得到歷史對話。限制是有些 CLI 專用的指令用不到（例如 /plugin、/resume），而且擴充套件內附的 CLI 只給圖形介面用，終端機要自己另外裝。

JetBrains 系列（IntelliJ、PyCharm、WebStorm 等）要先裝好 CLI，再從 JetBrains Marketplace 裝外掛並重開 IDE，用 Cmd+Esc 或 Ctrl+Esc 叫出來。它會用 IDE 自己的 diff 檢視器顯示變更、自動把你選取的程式碼帶進對話，也讀得到 IDE 的 lint 和語法錯誤。遠端開發要在遠端主機裝外掛；WSL2 預設的 NAT 網路要另外開防火牆規則。

兩者都要 Pro、Max、Team、Enterprise 其中一種付費方案，或 Claude Console 帳號，不需要 API key。

桌面應用

從 claude.com/download 下載。除了排工作區、開預覽伺服器，比較特別的是電腦控制：可以點擊、輸入、拖曳、按快捷鍵、開原生應用程式，macOS 上還能在背景執行。要在 Settings 的 General 裡開啟，macOS 還要給輔助使用和螢幕錄製權限。

這是研究預覽，而且電腦控制沒有沙箱，只開放 Pro 和 Max，Team、Enterprise 不支援。終端機裡也有對應的功能：輸入 /mcp 找到 computer-use 啟用，限 macOS、限互動模式（-p 不能用），同一時間只有一段對話能鎖住螢幕。

雲端 session 與 Slack

雲端 session 跑在 Anthropic 託管的環境（或組織自架的），你的電腦關掉它還在跑。從瀏覽器開 claude.ai/code，或在終端機下 claude --cloud "任務說明"。它適合同時丟好幾個任務出去，環境裡已經備好 git、npm、Python 這些工具，接上 GitHub App 之後還能自動修 PR。限制是只支援 GitHub（含 GitHub Enterprise Server），GitLab、Bitbucket 不行；用量跟你其他的使用共用額度；組織有設 IP 白名單的話會被擋掉。

Slack 是在頻道裡 @Claude 把工作丟出去，它會自己讀 thread 的上下文，然後路由到雲端 session 去做，可以開 PR，紀錄一樣留在 claude.ai/code。限制不少：只支援 GitHub、一段對話只能開一個 PR、只能在信任的對話裡用、私訊不支援；Team 和 Enterprise 正在轉往 Claude Tag。

Remote Control：用手機接回本機那一段

這個跟雲端 session 不一樣，要分清楚：Remote Control 是你本機正在跑的那一段對話，透過 claude.ai/code 或手機 App 遠端接上去。程式還是在你電腦上跑，檔案和工具都在本機，所以本機的 MCP server 照樣能用。

claude remote-control      # standby mode in a local terminal
claude --remote-control    # start an interactive session with it on

已經在對話裡的話輸入 /remote-control，VS Code 裡是 /rc。連上之後對話進度會跨裝置同步，可以從任何一台裝置送訊息，也能附檔案或照片、看 git diff；斷線會自動重連，中間的訊息會排隊等接上。Bedrock、Vertex AI、Foundry 不支援；Team 和 Enterprise 預設關閉，要管理員開。

Chrome 擴充套件

裝 Chrome 擴充套件（Chrome、Edge、Brave、Arc、Vivaldi、Opera 都可以，需要 1.0.36 以上），終端機下 claude --chrome 就能操作瀏覽器：點擊、輸入、截圖、讀 console、填表單、上傳檔案、錄 GIF，也能在你已經登入的網站上做事。輸入 /chrome 可以看狀態或設成預設啟用。WSL 不支援；要用 /login 登入，API key 認證不行；Bedrock、Vertex、Foundry 也不支援。

對照表

session 在各平台之間怎麼移動：--teleport 把雲端 session 拉回本機終端機接著跑，但這是單向的，之後的變更不會同步回雲端；--cloud 從終端機開一段新的雲端 session；桌面應用的 Continue in 選單可以把本機這段送上雲端；VS Code 也接得回雲端 session，同樣是接回來之後就不再同步回 claude.ai。

下一步

不用每個都裝。先挑一個最接近你工作方式的：整天在 IDE 裡就裝 IDE 擴充；常常需要離開座位就先試 Remote Control，在本機下 claude remote-control，用手機接上去看看順不順。等真的遇到「電腦要關機但工作還沒跑完」，再去開雲端 session。

資料來源：Claude Code 官方文件〈VS Code〉、〈JetBrains IDEs〉、〈Desktop〉、〈Claude Code on the web〉、〈Remote control〉、〈Claude Code with Chrome〉、〈Computer use〉、〈Slack〉各頁的 Prerequisites、Get started、Capabilities、Limitations 各節（2026-09-18 查詢）

settings.json 的全貌

前面幾章零散地提過不少設定：權限寫在 permissions、hook 寫在 hooks、保留天數是 cleanupPeriodDays。但同一個設定可以寫在好幾個檔案裡，寫錯地方就不會生效——第 7 章那個 auto 只有寫在使用者層才有用的例子，就是這麼來的。

這一章把整個設定系統攤開來看：有哪幾層、誰蓋過誰、常用的鍵有哪些。

五層設定，誰蓋過誰

由高到低，上面的蓋過下面的：

環境變數不在這個堆疊裡，而是一個鍵一個鍵各自決定：例如 ANTHROPIC_MODEL 會蓋過設定檔的 model，而 ANTHROPIC_DEFAULT_MODEL 只有在設定檔沒寫的時候才生效。

檔案怎麼來的

三種檔案的產生方式不太一樣：使用者設定在你第一次執行 /config 時建立；專案本地設定在你第一次核准一個常駐權限時自動建立，而且 Claude Code 會幫你加進 .gitignore；專案共用設定要自己建。

格式是嚴格的 JSON，不能寫 // 註解，也不能有多餘的逗號。可以加一行 $schema 指向 https://json.schemastore.org/claude-code-settings.json，編輯器就會幫你檢查拼字。

常用的鍵

清單型的鍵（像 permissions.allow）各層是合併的，不是覆蓋；單一值的鍵才是高層蓋低層。這點決定了你要把規則寫在哪：整個團隊都該遵守的 deny 規則放專案共用設定，你個人的習慣放使用者設定。

設定沒生效的時候

先別急著改檔案，三個指令會告訴你發生什麼事：

/config    # open the config UI; also /config verbose=true for one-liners
/status    # shows which settings files were loaded (the Setting sources line)

claude doctor   # find broken or invalid settings files

/status 的 Setting sources 那一行最有用：它列出這次實際載入了哪些檔案。你以為會生效的那個檔案沒出現在清單裡，問題通常就在路徑或層級寫錯了。JSON 格式壞掉的話，claude doctor 會指出來。

三個檔案各放什麼

• ~/.claude/settings.json：權限的預設模式、模型和 effort 的偏好，這些跟著人走。
• .claude/settings.json：這個專案的 hook、deny 規則、要求大家一致的設定，進版控。
• .claude/settings.local.json：只有這台機器會用到的東西，例如本機的測試網址，不進版控。

下一步

現在就跑一次 /status，看看 Setting sources 列出哪些檔案，跟你以為的有沒有出入。接著打開 ~/.claude/settings.json，把 $schema 那一行加上去，之後打錯字編輯器會直接標出來。真的改壞了，claude doctor 會告訴你壞在哪。

資料來源：Claude Code 官方文件〈Settings〉的 Settings files and precedence、Find or create your settings files、Use the /config menu 各節，以及〈Settings reference〉各設定鍵說明（2026-09-18 查詢）

企業部署與資安

前一章的五層設定裡，最高的那一層是受管設定。個人用不太到，但如果你接的案子是企業客戶，或是公司要把 Claude Code 發給整個團隊，問題就會變成：能不能規定大家只能用某幾個模型？能不能禁止某些指令？資料會不會外流？

這一章整理管理員那一側的東西，個人使用者知道有這些機制就好。

受管設定放哪裡

想拆成多個檔案，就在同一個位置開 managed-settings.d/ 資料夾放 *.json，會照檔名順序合併。

發送方式有四種，差別在多久生效：檔案改了立刻生效；MDM 或作業系統政策、Windows 登錄檔約 30 分鐘；claude.ai 後台的伺服器端設定約 60 分鐘（啟動時讀一次，之後每小時輪詢）。

多個受管來源同時存在時，managedSourcesBehavior 決定怎麼處理：預設 first-wins，用優先權最高的那個來源；設成 merge 則是逐鍵合併，單一值取高層的、清單合併、鎖定取最嚴格的。優先權由高到低是伺服器端、MDM、managed-settings.json 檔案、Windows HKCU 登錄檔。

管理員可以鎖哪些東西

有一批設定只有受管來源能設，使用者改不掉：

• 權限：permissions.deny、allowManagedPermissionRulesOnly、permissions.disableBypassPermissionsMode
• MCP：allowedMcpServers、deniedMcpServers、managedMcpServers、allowManagedMcpServersOnly
• 模型：availableModels、enforceAvailableModels、modelPicker
• 沙箱：sandbox.filesystem.allowManagedReadPathsOnly、sandbox.network.allowManagedDomainsOnly
• Plugin 與 marketplace：blockedMarketplaces、strictKnownMarketplaces、allowManagedHooksOnly、allowedChannelPlugins
• 登入與版本：forceLoginMethod、disableSideloadFlags、requiredMinimumVersion、requiredMaximumVersion

實務上最值得先設的是三個：permissions.deny 擋掉絕對不能碰的路徑和指令、disableBypassPermissionsMode 不讓人整個跳過權限檢查、requiredMinimumVersion 避免有人卡在有問題的舊版本。

走 Bedrock 或 Vertex

企業客戶常見的需求是走自己的雲端帳號。兩邊都是設環境變數：

export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=us-east-1
export AWS_PROFILE=my-profile
export ANTHROPIC_DEFAULT_OPUS_MODEL='us.anthropic.claude-opus-4-8'   # pin the version
export ANTHROPIC_DEFAULT_SONNET_MODEL='us.anthropic.claude-sonnet-4-6'

export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=global
export ANTHROPIC_VERTEX_PROJECT_ID=YOUR-PROJECT-ID
export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-5'
export ANTHROPIC_DEFAULT_SONNET_MODEL='claude-sonnet-5'

Bedrock 需要的 IAM 權限是 bedrock:InvokeModel、InvokeModelWithResponseStream、ListInferenceProfiles、GetInferenceProfile，資源指向 inference-profile 和 foundation-model 的 ARN；認證依序看 AWS profile、環境變數、Bedrock API key、IAM Identity Center SSO。Vertex 那邊最小權限是 roles/aiplatform.user，認證走 Application Default Credentials、gcloud 設定或服務帳號金鑰。

把模型版本釘死是刻意的：別名會隨平台換版本，釘住才不會某天早上大家的行為突然不一樣。

前面幾章提過的功能，有些在這兩個平台上不支援，規劃前要先確認：fast mode、Remote Control、Chrome 擴充套件、channels 都不支援 Bedrock、Vertex、Foundry。

資安面的幾個機制

• /security-review：對目前分支跑一次安全檢查，找出不安全的寫法。
• /sandbox：設定 Bash 沙箱的邊界，檔案系統預設限制在工作目錄、網路限制在特定網域；受管來源可以把這些鎖死。
• /permissions：檢視和編輯現在生效的權限規則。
• claude doctor：診斷設定檔問題。
• cleanupPeriodDays：決定本機謄本留幾天。雲端 session 跑在隔離的虛擬機裡，認證走短期的 scoped token。

認證資訊、SOC 2 與 ISO 27001 這類合規文件放在 Anthropic 的 Trust Center（https://trust.anthropic.com），客戶要資料時直接給這個連結比較快。

下一步

如果你是幫公司導入：先在一台機器上放好 managed-settings.json，只寫三件事——permissions.deny 的黑名單、disableBypassPermissionsMode、requiredMinimumVersion，用 /status 確認它有出現在 Setting sources 裡，再推給其他人。如果你是個人使用者，這一章只要記得一件事：公司發的電腦上，有些設定你改了不會生效，先看 /status 再找 IT。

資料來源：Claude Code 官方文件〈Managed settings〉的 Where each mechanism stores the policy、Choose a delivery mechanism、Keys only a managed source can set、How Claude Code combines managed sources 各節，〈Security〉的 Privacy safeguards 各節，〈Amazon Bedrock〉與〈Google Vertex AI〉的 Configure Claude Code 各節（2026-09-18 查詢）