Claude Code Hooks 實用範例：七個即用腳本，提升自動化效率

原文最初發佈於 Unattended。Claude Code 掛鉤是在會話中固定時間點執行的 shell 指令。常見的掛鉤會在工具呼叫之前（PreToolUse）、之後（PostToolUse）、當 Claude 嘗試結束時（Stop）以及會話結束時（SessionEnd）執行。

本指南提供七個可直接複製貼上的腳本：其中兩個是防護措施，用於阻擋危險指令和受保護的檔案；三個是防止停滯的掛鉤（測試閘門、「等待您的輸入」通知、啟動時提供情境）；另外兩個是日誌記錄掛鉤，用於記錄每次工具呼叫和會話。每個腳本都是一個位於 .claude/hooks/ 中的小型 bash 檔案，並在 .claude/settings.json 中進行配置（參考掛鉤指南）。

哪種選項適合您？請從解決您當前問題的掛鉤開始，然後根據需要添加其他掛鉤。對於初學者，首次使用掛鉤，建議選擇腳本 4（Claude 等待時的通知），它不會改變任何功能，且易於檢查。

對於日常工作，讓 Claude 自動執行指令，建議選擇腳本 1 和 2（防護措施）。對於夜間或排程執行卻提早停止的情況，建議選擇腳本 3（停止測試閘門）和腳本 5（工具日誌）。若要監控預算或用量，建議選擇腳本 5 和 6（日誌記錄）。

這些建議的原因是：初學者的通知掛鉤不會阻擋任何操作，即使出錯也不會造成破壞。日常使用時，防護措施是確定性的，它們總是會執行，因此您不必依賴模型記住規則。監控預算時，日誌會顯示代理實際執行了什麼，這有助於您在更改計畫或提示詞之前做出決策。

掛鉤的配置方式：每個掛鉤都是設定檔中事件名稱下的 JSON 條目。Claude Code 會將事件資料透過標準輸入（stdin）發送給腳本，而腳本的結束代碼或 JSON 輸出則控制接下來的行為。

官方參考資料的重點：掛鉤設定檔可位於 ~/.claude/settings.json（適用於所有專案）、.claude/settings.json（專案級別，可提交到版本控制）或 .claude/settings.local.json（專案級別，被 Git 忽略）。

標準輸入包含 session_id、transcript_path、cwd、permission_mode、hook_event_name，以及 tool_name 和 tool_input 等事件欄位。

結束代碼 0 表示成功，任何 JSON 輸出都會被應用；2 表示在支援阻擋的事件上發生阻擋錯誤；任何其他代碼表示非阻擋錯誤，操作仍會繼續。指令掛鉤的預設超時時間為 600 秒，可透過 "timeout" 更改。匹配器可以是 "Bash"、"Edit|Write" 或正規表達式，留空或使用 "*" 則匹配所有內容。

路徑請使用 ${CLAUDE_PROJECT_DIR}，以便腳本在任何工作目錄中都能執行。以下所有腳本都需要 jq 來解析標準輸入中的 JSON。

設定步驟（只需執行一次）：在您的專案根目錄中，執行 mkdir -p .claude/hooks .claude/logs。將下面的每個腳本儲存到 .claude/hooks/ 中，並使其可執行：chmod +x .claude/hooks/*.sh。

將匹配的 JSON 區塊添加到 .claude/settings.json 的頂層 "hooks" 鍵下。如果您使用多個掛鉤，請將它們合併到一個 "hooks" 物件中。在 Claude Code 中，輸入 /hooks，此選單是一個唯讀瀏覽器，會顯示每個掛鉤、其事件以及來源檔案。請故意觸發事件（例如，要求 Claude 執行 rm -rf /tmp/x），並檢查掛鉤是否被觸發。

防護措施腳本（1-2）：在損害發生前阻止。防護措施使用 PreToolUse，它會在工具呼叫之前執行，並可以允許、拒絕、詢問或延遲該呼叫。

腳本 1：阻擋破壞性 shell 指令。block-dangerous.sh 是一個範例防護措施，用於在執行危險的 Bash 指令之前拒絕它們。如果指令包含 rm -rf、git push --force、git reset --hard 或 DROP TABLE 等模式，它將輸出一個 JSON，其中 permissionDecision: "deny" 會阻擋該呼叫。

如果腳本沒有輸出任何內容並以 0 結束代碼退出，則會應用正常的權限流程。請注意，模式匹配很容易被規避（例如，使用 rm -r -f），因此應將其視為安全帶而非沙盒，並同時保留您原有的權限規則。

腳本 2：保護機密和鎖定檔案。protect-files.sh 是一個範例，用於拒絕編輯敏感路徑。如果檔案路徑包含 ".env"、"package-lock.json"、".git/" 或 "secrets/" 等模式，腳本將以結束代碼 2 退出，並將錯誤訊息輸出到標準錯誤（stderr）。

在 PreToolUse 事件上，結束代碼 2 會阻擋呼叫，並且您的標準錯誤訊息會作為原因傳達給 Claude，這樣它就可以改變方向，而不是盲目重試。

防止停滯腳本（3-5）：保持自動化流程順暢。這些掛鉤處理三種常見的停滯情況：Claude 過早宣布「完成」、Claude 在您不在時停在提示詞處，以及 Claude 在沒有情境的情況下啟動。

腳本 3：在測試失敗時阻止 Claude 停止。stop-gate.sh 是一個範例停止閘門，如果測試失敗，它會阻擋 Claude 宣布「完成」一次。腳本包含一個迴圈防護，如果 Claude 已經因為停止掛鉤而繼續，則允許其停止。

在 Stop 事件上，帶有原因的 decision: "block" 會讓 Claude 繼續工作，並且該原因會成為其下一個指令。stop_hook_active 欄位在 Claude 已經因為 Stop 掛鉤而繼續時為 true，請務必檢查它，否則可能會創建一個永不結束的迴圈。請注意，此腳本不適用於測試套件執行時間超過超時限制的專案，此時應替換為更快的檢查，例如 lint 或型別檢查。

腳本 4：當 Claude 等待您的輸入時收到通知。notify.sh 是一個範例，當 Claude 需要輸入時，它會記錄日誌並發送桌面通知。它會將訊息寫入 waiting.log，並嘗試使用 osascript 或 notify-send 發送桌面通知。

將其配置在 Notification 事件下，匹配器為 "permission_prompt|idle_prompt"。這兩種都是文件記載的通知類型。在無頭伺服器上，桌面通知不會起作用，但 waiting.log 仍然會顯示夜間執行在哪裡卡住了。

腳本 5（額外情境）：在會話開始時向 Claude 提供簡報。session-context.sh 是一個範例，用於在啟動時向 Claude 提供當前儲存庫的狀態。它會輸出當前分支、未提交的檔案列表以及 TODO.md 中的待辦事項。

在 SessionStart 事件上，腳本的標準輸出（stdout）會被添加到 Claude 的情境中。這與大多數事件不同，在大多數事件中，輸出會進入偵錯日誌。請務必保持輸出簡短，因為標準輸出欄位上限為 10,000 個字元，超過此長度的內容將被保存到檔案中，只顯示預覽。

用量日誌記錄腳本（6-7）：了解代理實際執行了什麼。日誌記錄掛鉤會為每個事件向檔案添加一行 JSON，這樣您就可以在事後審查執行情況，而無需閱讀整個對話紀錄。

腳本 6：記錄每次工具呼叫。log-tools.sh 是一個範例，為每次工具呼叫生成一行 JSON 日誌。它會記錄時間戳、會話 ID、工具名稱以及目標（指令、檔案路徑或網址）。

將其配置在 PostToolUse 事件下，並將 async: true 設定為處理程式選項，這樣日誌記錄就不會減慢每次工具呼叫的速度。

腳本 7：結束時的會話摘要。session-summary.sh 是一個範例，用於在會話結束時生成摘要。它會從 tools.jsonl 中統計該會話的工具呼叫次數，並列出最常使用的前三個工具，然後將摘要寫入 sessions.log。

將其註冊在 SessionEnd 事件下。文件記載的結束原因包括 clear、logout、prompt_input_exit 等。此腳本的限制是它只計算工具呼叫次數，而非 token 或成本。要獲取 token 數量，請使用相關工具。

常見錯誤與修正：大多數掛鉤問題歸結為五個原因之一。

如果掛鉤從未觸發，可能是事件名稱或匹配器錯誤（名稱區分大小寫，例如 Bash、Edit|Write）。如果出現「hook error」通知，可能是腳本不可執行或缺少 jq。請執行 chmod +x，安裝 jq，並使用 echo '{}' | your_script.sh 進行測試。

如果 JSON 輸出被忽略，可能是腳本以非 0 結束代碼退出，或者在 JSON 之前列印了額外文字。請確保只列印 JSON，然後以 exit 0 結束。如果 Claude 從未完成，可能是 Stop 掛鉤忽略了 stop_hook_active。

請添加腳本 3 中的迴圈防護。如果掛鉤在一個資料夾中有效，但在另一個資料夾中無效，可能是使用了相對路徑。請使用 ${CLAUDE_PROJECT_DIR}。

對於其他任何問題，請開啟偵錯日誌，它會顯示掛鉤執行情況、完整的標準錯誤輸出和 JSON 解析失敗。如果掛鉤出錯導致 Claude 編輯了不應編輯的檔案，相關文章解釋了如何回溯。

下一步：最快的成功是今天先設定一個防護措施和一個日誌記錄，然後在兩者都正常運作後再添加測試閘門。

您可以自行操作：將腳本 1 和腳本 6 添加到一個專案中，然後使用 /hooks 檢查兩者是否已註冊。執行一個正常任務，然後閱讀 .claude/logs/tools.jsonl。當一切看起來正常時，再添加腳本 3，並使用您最快的測試指令。

如果您不想自己建置這些：Claude Academy 的「Claude Code in Action」是一個約一小時、包含 9 節課程的免費課程，其中包括使用掛鉤來執行規則。這適合想要結構化基礎知識的人，但不適合需要特定設定幫助的人，因為它是通用培訓。

Claude Team 方案：每月每席 25 美元，或按年計費每月 20 美元（截至 2026 年 10 月；請查看官方頁面）。這對於小型團隊想要共享專案設定很有用，管理員可以透過 allowManagedHooksOnly 等受控設定來限制掛鉤。

對於個人開發者來說不值得：Pro 方案（每月 20 美元，或按年計費每月 17 美元，截至 2026 年 10 月；請參閱 Claude 定價）已經包含 Claude Code。限制：沒有任何方案會為您編寫掛鉤。