Claude Code Hooks：自動化與安全的最佳實踐

寫在最前頭，這份文章主要寫起來是給自己看，

同時內容是比較適合開發者，工程師們可以做些自動化處理的簡單筆記。

Claude Code hooks

Claude Code hooks 是一種強大的自動化機制，允許用戶在 Claude Code 的不同生命週期階段，自定義執行 shell 指令。這種設計讓開發者能夠將規則和自動化行為嵌入到應用層級，確保每次都能可靠執行，而不必依賴 LLM（大型語言模型）是否會選擇執行某項操作。

Hooks 的核心用途

通知：自訂收到 Claude Code 等待用戶輸入或執行權限時的提醒方式。
自動格式化：如在每次檔案編輯後自動執行 prettier（針對 .ts 檔）、gofmt（針對 .go 檔）等。
日誌記錄：追蹤所有執行過的命令，便於合規或除錯。
自動反饋：當 Claude Code 產生不符合團隊規範的程式碼時，自動給出反饋。
自訂權限：阻擋對生產環境檔案或敏感目錄的修改[^1]。

配置與結構

Hooks 透過設定檔進行配置，分為全域（~/.claude/settings.json）、專案（.claude/settings.json）、本地專案（.claude/settings.local.json）以及企業級策略設定。每個 hook 由「事件名稱」和「匹配器」組成：

"hooks": {
  "PreToolUse": [
    {
      "matcher": "Bash",
      "hooks": [
        {
          "type": "command",
          "command": "jq -r '...'"
        }
      ]
    }
  ]
}

matcher：用於匹配工具名稱（支援正則表達式），如 Write、Edit|Write、Notebook.*。
hooks：當匹配時要執行的命令陣列。
type：目前僅支援 "command"。
command：要執行的 bash 指令。
timeout：可選，命令執行的最大秒數。

Hook Event 事件

事件類型	觸發時機與用途
PreToolUse	工具呼叫前，可阻擋執行並提供反饋
PostToolUse	工具執行完畢後
Notification	Claude Code 發送通知時
Stop	主代理回應結束時
SubagentStop	子代理回應結束時

Hook 輸入與輸出

輸入：所有 hooks 透過 stdin 接收 JSON，包含 sessionid、transcriptpath 及事件相關資料。
輸出：可用 exit code 或 JSON 控制 Claude 行為。
- exit code 0：成功。
- exit code 2：阻擋行為，stderr 會回饋給 Claude。
- 進階可回傳 JSON，細緻控制是否繼續、阻擋原因、是否隱藏輸出等[^1]。

範例

自動格式化程式碼

"hooks": {
  "PostToolUse": [
    {
      "matcher": "Write|Edit|MultiEdit",
      "hooks": [
        {
          "type": "command",
          "command": "/home/user/scripts/format-code.sh"
        }
      ]
    }
  ]
}

自訂通知

"hooks": {
  "Notification": [
    {
      "matcher": "",
      "hooks": [
        {
          "type": "command",
          "command": "python3 ~/my_custom_notifier.py"
        }
      ]
    }
  ]
}

安全性考量

風險警告：Hooks 會以用戶權限自動執行 shell 指令，可能造成資料遺失或系統損壞，Anthropic 不負任何責任。
最佳實踐：
- 驗證與清理輸入資料。
- 始終引用變數（"$VAR" 而非 $VAR）。
- 防止路徑穿越（檢查 ..）。
- 使用絕對路徑。
- 避免處理敏感檔案（如 .env、.git/、金鑰等）。

官方範例

Claude Code hooks 官方提供的 bashcommandvalidator_example.py 範例，是一個用於「Bash 指令安全驗證」的 hook 腳本。這個範例展示了如何在 Claude Code 執行 shell 指令前，自動檢查指令內容是否符合安全規範，並攔截潛在的危險操作。其核心原理是：

解析傳入的 Bash 指令，檢查是否包含多重命令串接（如 &&、||、; 等），以防止命令注入攻擊。
根據預設的允許清單判斷指令前綴，僅允許特定安全命令執行，否則要求用戶審核。
若發現可疑結構或注入風險，會直接阻擋執行，並將原因回饋給 Claude Code 進行提示。

這個範例腳本可作為自訂 hooks 的基礎，協助團隊在自動化流程中提升 Bash 指令的安全性。

https://github.com/anthropics/claude-code/blob/main/examples/hooks/bashcommandvalidator_example

除錯與維護

使用 /hooks 檢查設定。
確認設定檔為有效 JSON。
手動測試命令與檢查 exit code。
使用 claude --debug 追蹤 hooks 執行情況。

總結

Claude Code hooks 這樣的更新，至少讓我可以接上完成提醒事件，讓我的小腦袋瓜可以被 notify，當然也可以想到許多不同的應用情境，之前在 slack hook 裡面所採取的模式，似乎都可以動了起來。

這樣的流程提供了極高的自動化與自訂彈性，但同時帶來安全風險。建議在安全環境下充分測試，並遵循最佳實踐，才能發揮其最大效益。（畢竟就還是實實在在可以寫檔案，讀檔案，請閣下自行體驗）

參考連結

社群活動分享

如果你看完這篇文章，也開始對「怎麼用 AI 幫你加速、放大你的想法」感到興趣，那你絕對不能錯過這場活動👇

🎤 🐻 Coding Bear 台北場｜來聊什麼是 Vibe Coding 台北場

我們將深入分享如何結合 AI 與程式、創意、內容製作，

讓你用最自然的方式，讓 AI 成為你的工作室助手。

📅 時間：7/16（三）18:30

👉 報名連結：https://codingbear.kktix.cc/events/ai-vibe-coding-2025-07-taipei

天南地北來亂聊，從設計、內容到自動化，無論你是創作者還是開發者，這場講座也許會有實用又有趣的靈感（吧）。來聊聊 AI 怎麼幫你少做一點雜事、多做一點你真的想做的事吧！

熱血漢誌 - 技術新鮮人到技術經理人，必懂的事

搜尋此網誌