寫在最前頭,這份文章主要寫起來是給自己看,
同時內容是比較適合開發者,工程師們可以做些自動化處理的簡單筆記。
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 裡面所採取的模式,似乎都可以動了起來。
這樣的流程提供了極高的自動化與自訂彈性,但同時帶來安全風險。建議在安全環境下充分測試,並遵循最佳實踐,才能發揮其最大效益。(畢竟就還是實實在在可以寫檔案,讀檔案,請閣下自行體驗)
參考連結
- https://docs.anthropic.com/en/docs/claude-code/hooks
- https://x.com/alexalbert__/status/1940480961923473610
- https://github.com/anthropics/claude-code/blob/main/examples/hooks/bashcommandvalidator_example
社群活動分享
如果你看完這篇文章,也開始對「怎麼用 AI 幫你加速、放大你的想法」感到興趣,那你絕對不能錯過這場活動👇
🎤 🐻 Coding Bear 台北場|來聊什麼是 Vibe Coding 台北場
我們將深入分享如何結合 AI 與程式、創意、內容製作,
讓你用最自然的方式,讓 AI 成為你的工作室助手。
📅 時間:7/16(三)18:30
👉 報名連結:https://codingbear.kktix.cc/events/ai-vibe-coding-2025-07-taipei
天南地北來亂聊,從設計、內容到自動化,無論你是創作者還是開發者,這場講座也許會有實用又有趣的靈感(吧)。來聊聊 AI 怎麼幫你少做一點雜事、多做一點你真的想做的事吧!
留言
張貼留言