本文整理自 Anthropic Academy
Claude Code 提供了一套 可自動化執行的 Hooks 機制，幫助我們在大型專案中避免常見錯誤、保持程式碼品質穩定。這篇文章將分享幾個實用的 Claude Code Hooks 範例與進階技巧，讓你打造更聰明、更可靠的開發流程。
Claude Code 之所以會幫忙寫程式，我簡單理解：有點像是一個中繼站把使用者跟 Claude 拉起來，而 Hooks 會插在 Claude code 跟 Claude 之間去介入，你可以再去做一些你想指定的任務。
截圖自Anthropic Academy
Hooks 常用種類如下：
- PreToolUse：function call 之前執行
- PostToolUser：function call 之後執行
- Notification：當 Claude Code 傳送通知時觸發
- Stop：Claude 回覆結束時觸發
- 還有一些... e.g. SubagentStop, PreCompact, ...
工具列表（Tool Names）如下：
- Read：讀取檔案內容（如讀取原始碼、設定檔等）
- Edit / MultiEdit：編輯現有檔案（可用於小幅度或多段編輯）
- Write：建立新檔案並寫入內容
- Bash：執行 Shell 指令或腳本
- Glob：依樣式條件（如
*.ts）尋找檔案或資料夾 - Grep：在檔案中搜尋特定字串內容
- Task：產生 Claude 子代理任務，處理更複雜目標
- WebFetch / WebSearch：存取或搜尋網頁資源
- 還有：NotebookRead, NotebookEdit, TodoWrite, ...
講白了 Claude Code 作為中介，使用「工具」作為溝通邏輯，分派工作給 Claude。
Hooks 設定位置
使用 Claude Code 時，所有設定都會藏在專案（或家目錄）底下的「.claude」資料夾當中。Hooks 也會在此設定。
截圖自Anthropic Academy
常用設定
設定 PreToolUse
PreToolUse Hook 會在 Claude 執行某個工具之前觸發，並允許你審查其即將執行的操作。你可以根據工具名稱與參數做判斷：
"PreToolUse": [
{
"matcher": "Read",
"hooks": [
{
"type": "command",
"command": "node /home/hooks/read_hook.ts"
}
]
}
]
在這個例子中：
- 每當 Claude 嘗試使用
Read工具時，就會先執行指定的指令read_hook.ts - 你的命令會從標準輸入（stdin）接收到工具調用的 JSON 詳細資料
- 然後你可以根據這些資訊做出兩種決策：
- 允許：回傳 exit code 0，Claude 將正常繼續執行工具
- 阻擋：回傳 exit code 2，Claude 將中止該操作，並顯示 stderr 作為錯誤提示
設定 PostToolUse
PostToolUse Hook 會在 Claude 執行工具 之後 觸發，因此無法阻擋操作。但你可以用來進行：
- 檔案格式化（例如剛寫入或編輯的檔案）
- 對 Claude 回傳附加訊息或後處理結果
"PostToolUse": [
{
"matcher": "Write|Edit|MultiEdit",
"hooks": [
{
"type": "command",
"command": "node /home/hooks/edit_hook.ts"
}
]
}
]
在這段設定中：
- 當 Claude 執行檔案寫入或編輯後
- 就會自動執行
edit_hook.ts - 這個腳本可以讀取 Claude 剛剛操作的內容，例如格式、檔名、變更差異等等，並進行額外後處理
實際可能應用場景
以下是 Claude Code hooks 官方認為在實務上常見的幾種應用方式：
- 程式碼格式化：在 Claude 編輯完檔案後自動執行 formatter
- 自動化測試：當檔案變動時觸發單元測試或整合測試
- 存取控制：阻擋 Claude 讀取或編輯特定敏感檔案
- 程式品質檢查：執行 linter 或 type checker，並將錯誤回饋給 Claude
- 存取記錄與稽核：記錄 Claude 操作過的檔案或內容
- 命名規則 / 結構驗證：自動檢查變數命名、檔案路徑、模組歸屬等規範
最常用的兩個 Hooks：
PreToolUse給你預防與限制 Claude 行為的能力PostToolUse則提供擴充、審查、強化 Claude 行為的機會
官方範例
1. 防止 Claude 閱讀敏感檔 .env
假設使用者輸入 "read a .env file"，但我們不想要 Claude 去讀取。
因此或許我們可以：
使用 PreToolUse Hook 監控 Claude 使用 Read 和 Grep 工具時讀取資料，如果 Claude 試圖閱讀 .env、secrets/ 等敏感目錄，則跳出 Exit Code 2 以阻擋操作。
以下是範例 settings.local.json <- Claude Code 設定檔
{
"hooks": {
"PreToolUse": [
{
"matcher": "Read|Grep",
"hooks": [
{
"type": "command",
"command": "node ./hooks/read_hook.js"
}
]
},
]
}
...
}
read_hook.js
async function main() {
const chunks = [];
for await (const chunk of process.stdin) {
chunks.push(chunk);
}
const toolArgs = JSON.parse(Buffer.concat(chunks).toString());
// readPath is the path to the file that Claude is trying to read
const readPath = toolArgs.tool_input?.file_path || toolArgs.tool_input?.path || "";
// TODO: ensure Claude isn't trying to read the .env file
if (readPath.includes(".env")) {
console.error("you cannot read .env files");
process.exit(2);
}
}
main();
2. TypeScript 類型檢查自動修復
問題情境：當你要求 Claude 新增一個函式參數，Claude 常常會只修改函式定義，卻漏改其他呼叫處，造成類型錯誤。
解法：使用 PostToolUse Hook 在 Claude 修改任何檔案後，立即執行 tsc --noEmit，擱取類型錯誤，並將錯誤回饋給 Claude，讓 Claude 自動修正確保程式碼無類型錯誤。
3. 強者大大分享製作「語音通知系統」
有強者大大分享的範例是，在任務結束時執行預先設計好的 chatgptsay.sh ，這個功能是把你給定message 用 gpt-4o-mini-tts 讀出來。
也就是說，看起來是在 Notification Hook 上做設計，加入這個機制。所以在每次任務完以後，就會有聲音告訴你 Claude 做了啥XDD
使用 Hooks 安全建議
截圖自Anthropic Academy
- 驗證並清淨輸入：不能直接信任 stdin JSON 中的資料
- 總是加上引號：對 shell 變數用
"$VAR"而非$VAR - 防禦路徑繞迴：檢查 file_path 是否包含
.. - 使用絕對路徑：避免相對路徑被抽離環境用錯（重要）
- 跳過敏感檔案：如
.env、.git/、ssh keys 等
