跳到主要內容

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 怎麼幫你少做一點雜事、多做一點你真的想做的事吧！

標籤：

留言

張貼留言

這個網誌中的熱門文章

[CSS] z-index 在不同瀏覽器繼承問題

今天會討論到這個課題，是因為要實做一個Popup dialog，所以我們希望的結果如下圖。 可是在IE7 卻發生了這樣的情況。 Popup不論怎麼設定z-index都無法浮在最上層，我們看一下html架構發生什麼事情。
27 則留言
繼續閱讀>>

[教學] 快快樂樂刪除CodeIgniter index.php

預設的CI網址預設都設定為index.php同一層級，因此所有的程式都必須指定index.php導向才能開始，例如 http://localhost/ci/index.php/welcome/test http://localhost/ci/welcome/test 本文將說明如何將惱人的index.php消除，還你一個漂亮的URL。 設定開始： 接下來說明如何使用rewrite方式將惱人的index.php去除。 rewrite不清楚的人，煩請先自行google 首先要先確定Apache的 mod_rewrite 有 開啟 ，如果沒有開啟請設定好之後重新啟動apache。 接著，在根目錄底下建立一個新檔案，檔名為 .htaccess ，裡面程式碼如下： <IfModule mod_rewrite.c> RewriteEngine On RewriteBase / RewriteCond %{REQUEST_FILENAME} !-f RewriteCond %{REQUEST_FILENAME} !-d RewriteRule ^(.*)$ index.php/$1 [L] </IfModule> 接著到 application/config/config.php ，開啟檔案修改 $config['index_page'] = ""; 注意： /index.php/$1 要根據你目錄，例如 http://localhost/index.php ，網站根目錄為 /ci/index.php 則要寫成 /ci/index.php/$1 接著至CI目錄下，尋找 config\config.php ， 修改一下裡面的檔案，修改如下： $config['index_page'] = ""; 存檔後，如此一來大功告成。 參考資料 官方網站說明
21 則留言
繼續閱讀>>

[教學] Mojito 安裝與入門，install mojito for beginner.

mojito ，最近終於從 YDN 對外公開此專案，這個套件主要用於解決前端多重裝置及瀏覽器端的問題，後端服務採取 node.js ，因此使用上必定要先準備以下幾個元素 準備素材 c++ complier git Node.js > 0.4.x NPM > 1.0.x 安裝方式 git clone git://github.com/yahoo/mojito.git cd mojito/source sudo npm install -g . npm install . 以上四個簡單的步驟，就可以把 mojito module 完整安裝到服務器上，接著就可以開始進入 mojito 的世界 使用方式 mojito 提供了完整的 command line 給開發者使用，接著先建立一個基本 hello world 專案，跟著以下步驟完成第一個專案。首先建立一個 mojito application， mojito create app hello cd hello 切換到目錄之後，再接著建立自己的 mojit，這邊的 mojit 就像是一個應用（application）可能會包含許多個獨立網站體，擁有獨立架構的 MVC ，包含內部設定等，詳細資料可以參考官方的 說明 ，建立 mojit mojito create mojit HelloMojit 輸入指令後，會看到顯示結果如下， creating mojit called 'HelloMojit' (using "default" archetype) ✔ mojit: HelloMojit created! ✔ mojito done. 接著修改 application.json 這個 mojit 設定檔案，讓剛才新建立的 hellp application 指定底下有一個 mojit -> HelloMojit ，讓應用可以去執行 mojit controller ，修改如下， [ { "settings": [ "master" ], "appPort": 8666, "specs": { ...
11 則留言
繼續閱讀>>