Hooks 與確定性自動化

19.1　三種機制怎麼分工：CLAUDE.md、Skills、Hooks

在動手寫 hook 之前，先搞清楚一件事：Claude Code 給你三種「教它做事」的機制，各有各的脾氣。用錯機制，是新手最常見的坑——把該硬擋的事寫成軟建議，結果三不五時被忽略。

三者最關鍵的差別，是「會不會每次都生效」✅官方：

一句話記法：希望它記得 → CLAUDE.md；需要時才用的專業知識 → Skills；一定要發生、不容商量 → Hooks。把該硬擋的規則塞進 CLAUDE.md，等於把保全工作交給一張貼在牆上的紙條——這一章後面講的就是怎麼把紙條換成真正的閘門。

19.2　Advisory vs Mandatory：哪些規則該搬進 hook

判準很簡單，問自己一句話：「這條規則，偶爾被破壞我能接受嗎？」👤達人（這套 advisory／mandatory 分流，整理自實踐者 Matthias Herbert 的 hook 心法）

• 能接受偶爾破壞（風格偏好、命名習慣、「盡量寫測試」）→ 留在 CLAUDE.md 當建議就好。
• 絕不能破壞（不准碰金鑰檔、不准 force push、跑完一定要驗證）→ 搬進 hook，變成機械強制。

搬進 hook 之後，你要認識三個最常用的「時機點」，以及 hook 怎麼表達「放行」或「攔下」✅官方：

hook 怎麼跟 Claude 溝通「行不行」？靠 退出碼（exit code）：腳本結束時回 0 代表放行、回 2 代表攔下。沒有模糊地帶——這就是它比「建議」可靠的根本原因。

退出碼的完整表情：不是「非 0 就是失敗」

寫過 shell 腳本的人，直覺都覺得「回傳非 0 就代表失敗、失敗就該被擋下」——這個直覺在 hook 的世界裡是個陷阱✅官方。Claude Code 的退出碼其實是三種語意，不是「0 跟非 0」兩種：

最容易踩的雷就在最後一列。很多人寫驗證腳本習慣用 set -e，或是沿用工具本身預設的失敗碼（很多程式失敗時預設就回 1），以為這樣就等於「攔下了危險指令」——實測卻是照樣放行，只是終端機角落多跳出一行你可能根本沒注意到的錯誤訊息🌐社群。部署任何 PreToolUse 攔阻腳本之前，養成一個習慣：故意讓它踩雷一次，親眼確認退出碼真的是 2、動作真的沒發生，這比事後才發現閘門形同虛設划算太多。

💡 官方範例儲存庫（examples/hooks/bash_command_validator_example.py）示範了怎麼分開這兩種「有錯」

# 解析 stdin 的 JSON 失敗：這只是「腳本自己出錯」，不是「驗證失敗」，
# 用 1，只顯示給你看，不會擋下任何工具呼叫
try:
    input_data = json.load(sys.stdin)
except json.JSONDecodeError as e:
    print(f"JSON 解析失敗：{e}", file=sys.stderr)
    sys.exit(1)

# 抓到真正該擋的問題（例如指令用了 grep，建議改用 rg）：
# 這才是要餵給 Claude 看、逼它改做法的驗證失敗，用 2
if problems:
    for msg in problems:
        print(msg, file=sys.stderr)
    sys.exit(2)

這個骨架值得記住：1 留給「腳本自己壞掉」，2 才是「我要真的擋下這件事」。兩種都算「有錯」，但只有後者會真的攔住 Claude。

不是每個事件都擋得住

官方文件列出的 hook 事件其實遠遠不只 PreToolUse／PostToolUse／Stop 這三種，還有 SessionStart、UserPromptSubmit、PermissionRequest、ConfigChange、PreCompact……等三十餘種✅官方。但不是每一種都能被 exit 2 擋下：像 PreToolUse、PermissionRequest、UserPromptSubmit、Stop、SubagentStop、PreCompact 這類「動作還沒發生」的事件，exit 2 是真的能把它攔住；而 SessionStart、Setup、Notification、SessionEnd 這類事件，就算你 exit 2，也只是把錯誤秀給你看，流程照樣往下走——這幾種事件的性質本來就不是「守門」，是「通知」。

19.3　設定要放在哪裡：作用域、優先序與寫法

前兩節談的是「什麼時候該用 hook」，這節談更實際的問題：hook 的設定實際上寫在哪個檔案、怎麼精準指定要攔哪個工具呼叫。這節資訊量比較大，建議對照你手邊專案的 .claude/settings.json 邊看邊摸。

五層作用域，疊加合併不是互相覆蓋

Claude Code 允許好幾層設定同時存在，各自管不同範圍✅官方：

關鍵行為：這幾層設定是合併（merge），不是「後面蓋掉前面」。你在使用者層設一個 PostToolUse hook，專案層又設另一個，兩個都會生效、依序跑。也因為是合併而非覆蓋，官方做了一個貼心的去重：完全相同的 command／URL 只會執行一次，不會因為你不小心在兩層都寫了同一支腳本就跑兩遍。企業層還有一張王牌——管理員可以開啟 allowManagedHooksOnly，直接把使用者層、專案層、外掛層的 hook 全部鎖死，只認企業自己發布的那份。這在自學場景用不太到，但未來進團隊，若發現 hook「怎麼設都沒反應」，這是一個該懷疑的方向。

matcher 怎麼寫：精確字串、｜ 分隔、regex 陷阱

每個 hook 用 matcher 決定「這次工具呼叫，該不該讓我出手」。它的判斷規則比看起來嚴格✅官方：只要字串裡只出現英數字、底線、連字號、空格跟 |（近期版本也開放用逗號），就會被當成精確字串或用 | 分隔的列表比對；但只要出現其他字元——哪怕只是一個小數點——整串 matcher 就會被當成不加錨點的 JavaScript regex 來解讀。空字串、省略不寫、或寫 *，都代表「全部符合」。

另外兩個常被忽略的細節：matcher 對大小寫敏感，"Bash" 跟 "bash" 是兩回事；MCP 工具的命名規則是 mcp__<server>__<tool>，如果是外掛內建的 MCP server，還會多一層變成 mcp__plugin_<plugin>_<server>__<tool>——要攔 MCP 工具呼叫，matcher 要照這個格式寫，少一個底線都比對不上。

想篩更細，用 if 欄位——但它不是安全邊界

matcher 只能篩到「工具名稱」這個層級（例如整個 Bash）。如果你只想攔「git 開頭的指令」，近期版本加了一個 if 欄位，用權限規則的語法（像 Bash(git *)、Edit(*.ts)）在 matcher 之外再篩一層，只在 PreToolUse／PostToolUse／PostToolUseFailure／PermissionRequest／PermissionDenied 這幾種跟工具直接相關的事件上生效——確切支援的版本與語法細節請以 claude --help 或官方頁面為準，這是比較新才加入、還在演進的功能✅官方。

多個 hook 同時匹配：平行執行，deny 優先

如果同一個事件、同一次呼叫，剛好有好幾個 hook 都命中，Claude Code 不會排隊一個一個跑，而是全部平行執行到完成，再合併結果✅官方。這裡有兩個反直覺的地方要注意：

• 一個 hook 說「擋」，不會中止其他 hook 的副作用：假設你同時掛了一個「記錄用」的 hook（永遠 exit 0，只是把事件寫進 log）跟一個「攔阻用」的 hook（符合條件才 exit 2），攔阻的那個回 deny，記錄的那個照樣把這筆記錄寫進去——這其實是官方建議的「log 與 guard 分離」模式，比把記錄跟攔阻邏輯塞進同一支腳本更好維護🌐社群。
• 多個權限決定合併，最嚴格者優先：PreToolUse 若有多個 hook 各自給出不同決定，優先序是 deny > defer > ask > allow——只要有一個說不行，結果就是不行。至於附加說明文字（additionalContext），每個 hook 給的都會保留、一起餵給 Claude 看，不會互相覆蓋。

19.4　Hook 不只是 shell 指令：五種型別與怎麼選

到目前為止，本章所有例子都預設 hook 是「跑一段 shell 指令」。這是最常用的一種，但其實只是五種型別之一✅官方：

怎麼選：延遲跟複雜度是一起漲的

五種型別能處理的「判斷複雜度」不一樣，延遲也跟著遞增👤達人：command 適合純機械檢查（格式、命名、正規比對），沒有模型呼叫，最快；prompt 適合需要一點語意判斷、但不需要看程式碼實際狀態的情境，例如「這段修改有沒有動到認證邏輯」；agent 才用在必須驗證「程式碼實際狀態」的場合，例如「測試是不是真的通過」，因為它能自己跑指令查證，不是純猜測——但也因此延遲最高。正式環境的排序建議：能用 command 解決就別升級，agent 型審慎使用。

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

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

exec form vs shell form：一次解決 Windows 路徑與注入風險

command 型 hook 還有一個藏在設定寫法裡的細節，會決定它穩不穩、安不安全✅官方：設定裡有沒有寫 args 陣列。

路徑替身變數：讓同一支腳本到哪個專案都能用

寫 hook 腳本時，與其把路徑寫死，Claude Code 提供幾個替身變數，在 command／args／headers／input 各種型別裡都能用，也會同步匯出成環境變數✅官方：${CLAUDE_PROJECT_DIR}（目前專案的根目錄）、${CLAUDE_PLUGIN_ROOT}（外掛安裝目錄，注意外掛更新後這個路徑會變）、${CLAUDE_PLUGIN_DATA}（外掛可以長期寫入的資料目錄）。

SessionStart 事件還有一個專屬變數 CLAUDE_ENV_FILE：hook 把環境變數寫進這個檔案，之後每次 Bash 工具呼叫前都會自動把它當成前導腳本執行。這個機制搭配 CwdChanged（目錄切換）事件一起用，可以做出類似 direnv 的效果——每次 cd 進不同的子專案，環境變數自動跟著換，因為 Claude 的 Bash 工具不會自動繼承你 shell 裡裝的 direnv 掛鉤。

💡 SessionStart 與 CwdChanged 都掛同一行，模擬 direnv 自動載入

# 兩個事件都掛這支指令：每次開新對話、或每次切換工作目錄，
# 都把 direnv 該載入的環境變數寫進 CLAUDE_ENV_FILE
direnv export bash > "$CLAUDE_ENV_FILE"

19.5　達人在用的六種生產級閘門

理論講完，來看真實世界。下面六種模式整理自實踐者 Lloyd Pilapil 的生產環境經驗🌐社群——都是社群驗證有效、但非官方明文的做法，你可以挑需要的套用。

1. 1
   🛡️防線

   擋住關鍵檔案（PreToolUse）

   寫一個 hook，看到 Claude 要改 .env、middleware、或 API route 就回 exit 2 攔下。這是最該優先架的一道。

2. 2
   🛡️防線

   擋住敏感邏輯（PreToolUse）

   要動到登入授權（auth）、金流（payments）、資料庫這類高風險區域時，先攔下來要你親自確認，別讓它自動改下去。

3. 3
   🛡️防線

   擋住危險指令（PreToolUse）

   在正式環境裡跑 npm install / pip install 之類會動到依賴的指令，除非明確是裝開發用套件（--save-dev），否則攔下。

4. 4
   🧹善後

   改完自動格式化（PostToolUse）

   每次 Claude 改完檔，自動跑一次 Prettier／格式化工具，省得程式碼風格亂掉。這是「事後善後」，所以用 PostToolUse。

5. 5
   🧹善後

   改完自動型別檢查（PostToolUse）

   改完跑一次 tsc --noEmit（只檢查型別、不產出檔案），第一時間抓出型別錯誤，不用等到 build 才發現。

6. 6
   🔔通知

   收尾時叮一聲（Stop）

   Claude 收尾時，用 Stop hook 發一個系統通知（macOS 桌面通知）提醒你「跑完了，來看一下」。長任務尤其好用。

注意這六種的分工：前三種「絕對不能做」的防線全在 PreToolUse（呼應上一節），後三種「善後與通知」用 PostToolUse 或 Stop。你看出規律了——要擋，就架在動作之前；要善後，就掛在動作之後。

第一種怎麼寫：擋住關鍵檔案的完整範例

六種模式裡最該優先架的是第一種，這裡給一個可以直接改著用的完整範例🌐社群。先是攔阻腳本本身：

💡 .claude/hooks/protect-files.sh：命中保護清單就攔下

#!/bin/bash
# 讀 Claude Code 從 stdin 餵進來的事件 JSON，取出這次要動的檔案路徑
FILE_PATH=$(cat | jq -r '.tool_input.file_path')

# 不准碰的檔案清單，自己按專案需要增減
PROTECTED_PATTERNS=(".env" "package-lock.json" ".git/")

for pattern in "${PROTECTED_PATTERNS[@]}"; do
  if [[ "$FILE_PATH" == *"$pattern"* ]]; then
    # 寫給 Claude 看的理由要印到 stderr，不是 stdout
    echo "Blocked: $FILE_PATH matches protected pattern '$pattern'" >&2
    exit 2
  fi
done

exit 0

💡 註冊進 .claude/settings.json

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

除了退出碼，還可以直接回結構化 JSON

PreToolUse 表達「攔下」不是只有 exit 2 一種寫法，也可以維持 exit 0，改成印一段結構化 JSON，把決定寫在 hookSpecificOutput.permissionDecision 欄位裡✅官方：

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "請改用 rg 取代 grep，效能比較好"
  }
}

兩種寫法最後都是攔下，效果一樣；差別是結構化 JSON 能把「攔下的理由」寫得更完整、格式更明確，也能表達 ask（轉人工確認）而不只是「行」或「不行」二選一。純 exit 2 寫起來比較快，結構化 JSON 資訊量比較大——看腳本需求挑一種，不用兩種都做。

19.6　閘門放對位置：寫一半 vs 收尾時

架 hook 還有一個容易踩的細節：閘門卡在哪個時間點。同樣是「測試要過」，卡錯地方會把 Claude 搞得綁手綁腳。

達人的共識是分兩層處理👤達人（整理自 Shrivu Shankar 與 Boris Cherny 的實踐）：

💡 範例：PostToolUse 自動格式化，加 || true 確保不中斷流程

# 改完檔自動格式化；就算 format 出錯也回成功（|| true），
# 不打斷 Claude 正在進行的工作
bun run format || true

💡 範例：收尾時的硬閘門，測試沒過就不准停

#!/bin/bash
INPUT=$(cat)

# 防無窮迴圈：如果這已經是被同一個 Stop hook 擋過一次的「被迫延續」，
# 直接放行，不要再擋一次
STOP_ACTIVE=$(echo "$INPUT" | jq -r '.stop_hook_active')
if [ "$STOP_ACTIVE" = "true" ]; then
  exit 0
fi

# 真正的驗證：測試套件有沒有過
if npm test --silent >/dev/null 2>&1; then
  exit 0
fi

# 沒過：印一段 JSON，把「還沒做完」的理由塞進 reason 欄位
echo '{"decision": "block", "reason": "測試套件未通過，請先修正再結束"}'
exit 2

另外，SessionStart（每次開新對話時）和壓縮記憶之後這兩個時機，也可以用 hook 把關鍵 context「重新注入」一次，確保 Claude 不會因為記憶被壓縮而忘了重要前提。

背景執行：async 與 asyncRewake

有些 hook 天生就跑得慢（例如掃一次完整的安全性檢查），你不會希望 Claude 乾等它跑完才能繼續工作。這時候可以加 "async": true，讓這個 hook 變成非阻塞——Claude 不等它，逕自往下做✅官方。如果你還想要這支背景腳本「跑完之後有辦法叫醒 Claude」（例如背景掃描真的抓到問題，想事後回報），再加一個 "asyncRewake": true：它結束時如果 exit 2，stderr／stdout 的內容會用「系統提醒」的形式送回對話——很適合「先放行、等真的有問題才打斷」的場景。

19.7　給多代理用的閘門：逼它做到達標才放手

如果你用到第 16 章講的 Agent Teams（多個 Claude 平行協作），hook 還有一招進階用法：把品質閘門架在「隊友」身上，逼它持續工作到達標，不准提早收工。

機制是這樣✅官方🧪實驗性：Agent Teams 提供 TeammateIdle（隊友閒置時）、TaskCreated（任務建立時）、TaskCompleted（任務完成時）這幾個時機。你在這些 hook 裡回 exit 2 + 一句回饋，就能把「準備閒置／準備收工」的隊友擋回去，附上「還沒達標，繼續做」的訊息，逼它接著做下去。

這招的價值，是結構性地對抗「假裝做完」——不靠提醒它「要認真」，而是用機械閘門卡住「沒達標就不放行」。這跟本章一開始的核心精神一致：與其拜託它，不如架一道它繞不過去的閘門。

寫法上跟 Stop hook 是同一套邏輯，只是換了觸發的事件：腳本讀進 stdin 的事件 JSON，判斷「這個任務、這個隊友，真的達標了嗎」，沒有就 exit 2 並把還缺什麼寫進理由，逼它接著做；真的達標了就 exit 0 放行。跟第 15 章提過的「驗證閉迴圈」是同一個核心精神，只是這裡守的不是「Claude 想收工」，而是「隊友想閒置或想結案」。

19.8　進階：把 hook 事件變成可觀測的儀表板

當你的 hook 越架越多、又跑多代理時，會想知道「到底發生了什麼、誰在什麼時候做了什麼」。社群有人把這件事做成了一個即時儀表板，值得認識——但這是社群專案，不是 Claude Code 內建，當作開眼界、需要時自己搭。

19.9　卡住怎麼辦：除錯與常見錯誤排除法

hook 寫錯很難一眼看出來——它不像網頁排版跑掉那樣有畫面可比對，出錯常常就是「安靜地什麼都沒發生」，或反過來「安靜地照樣執行了」。這節整理三種偵錯管道，加上幾個新手（甚至老手）最常踩的坑。

三種偵錯管道

常見錯誤與排除法

19.10　小結

這一章的核心只有一句：絕不能退讓的規則，別寫成建議，要架成閘門。CLAUDE.md 是「希望它記得」（約七成遵循），Hooks 是「每次一定發生」（確定性強制）。判準是問自己「偶爾破壞我能接受嗎」——能接受就留 CLAUDE.md，不能就搬進 hook。

三個時機要分清楚：PreToolUse 是唯一能真正擋住動作的事件，所有安全防線都架在這；PostToolUse 用來事後善後（自動格式化、型別檢查）；Stop 用來收尾把關（測試沒過不准收，記得檢查 stop_hook_active 防無窮迴圈）。退出碼只有 2 才是真攔阻，0 放行，其他非零碼（尤其容易誤用的 1）一律放行、只顯示提示——這是整章最容易誤踩的陷阱，部署前務必刻意測過失敗路徑。達人的六種生產級閘門你不用一次到位，先架「擋關鍵檔」和「自動格式化」就很有感。hook 不是只能寫 shell 指令，設定也不是只有一個地方放，但這些都是「需要時再查」的細節，不是動手前非背不可的知識；真的卡住時，先查 /hooks 有沒有設定對，再用 --debug-file 追執行過程。至於 teammate 閘門和可觀測儀表板，分別是實驗性功能與社群專案，理解概念、需要時再深入。也別忘了 .claude/settings.json 屬於 repo 的一部分——clone 陌生專案前，養成先看一眼 hook 設定的習慣。下一章我們把場景拉到無人值守：用 claude -p 在 CI 流水線裡跑 Claude，並把安全鎖死。

19.11　動手試試

1. 1
   ✋動手做

   盤點你的「絕不退讓」清單

   拿你手上的專案，列出 2～3 條「偶爾被破壞無法接受」的規則（例如：不准改某個設定檔、提交前測試一定要過）。對每一條問一次「這該用 PreToolUse 擋、還是 Stop 收尾把關？」——光是分清這兩類，你就抓到 hook 設計的精髓了。

2. 2
   ✋動手做

   把一條 CLAUDE.md 規則「升級」成 hook

   回去翻你的 CLAUDE.md，找一條其實「不能被忽略、卻只寫成建議」的規則（最常見的是「不要改 .env」）。回到第 8 章的 hook 設定，把它改成一個 PreToolUse 閘門：偵測到要改該檔就回 exit 2 攔下。設好後故意叫 Claude 改那個檔，確認它真的被擋下來。

   ✅ 預期會看到

   Claude 嘗試改該檔時被 hook 攔截、動作沒有發生——你親手把一條「軟建議」變成了「鐵閘門」。

3. 3
   ✋動手做

   加一個「改完自動格式化」的善後 hook

   設一個 PostToolUse hook，在 Claude 改完檔後自動跑你的格式化工具，記得指令後面加 || true（例如 bun run format || true），確保格式化萬一失敗也不會中斷流程。比較看看：擋的 hook 架在動作「之前」，善後的 hook 掛在動作「之後」——這個前後之分，就是整章的關鍵直覺。

4. 4
   ✋動手做

   親手踩一次退出碼的陷阱，再修正它

   寫一支超簡單的 PreToolUse 腳本，故意先用 exit 1 表達「我要攔下」，實際測一次：echo '{"tool_name":"Bash","tool_input":{"command":"ls"}}' | ./你的腳本.sh; echo $?，觀察退出碼、也觀察 Claude 是否真的被擋下。接著把 exit 1 改成 exit 2，重新測一次，比較兩次的差異。

   ✅ 預期會看到

   exit 1 時動作照樣放行，只在畫面角落多一行不起眼的錯誤提示；exit 2 時動作才真的被擋下。親眼看過這個落差一次，你就再也不會忘記這個陷阱。