[心得] Claude Code Hooks：31 種 Event，真正只要 4 個

一、誰負責啟動？

CLAUDE.md：丟給模型自己看，靠 AI 判斷「現在該不該遵守」——判斷就有失守的時候。

Hooks：Claude Code 背後掌控的 deterministic（結果固定）機制。時間點一到，軟體直接介入執行，根本不經過模型判斷這一關。

• 一次性任務 → 對話裡直接講
• 專案通用規則／大方向 → 寫進 CLAUDE.md 當參考
• 時機一到就絕對必須執行、且不想承擔被 AI 忘記的風險 → 做成 Hook

二、官方 31 種，真正會用到的只有 4 個

Hook 像便利商店自動門：走到感應區就開，沒得商量。寫過 git pre-commit hook 的人一看就懂——差別只在於管的是 AI。請 AI 幫你建 Hook 時，講清楚「什麼時候啟動」＋「啟動後做什麼」即可。

三、設定檔三層：Event／Matcher／Handler

寫在 settings.json，搞懂三層就夠（不必手打每一行）：

1. Event — 什麼時候啟動（例：PostToolUse＝剛調完工具的瞬間）
2. Matcher — 篩選條件，避免到處亂跑（例：只鎖「改程式碼」）
3. Handler — 條件符合後真正動手（例：跑語法檢查腳本）

四、四個真正常用的時機

1. SessionStart — 開新對話／接續紀錄／輸入 clear 時觸發。範例：Superpowers 開場整份灌技能說明（約 1,300 token／次，塞太多前幾輪會變差）。
2. UserPromptSubmit — 按 Enter 送出提問時。範例：claude-mem 解決跨對話失憶。
3. PreToolUse — 已決定工具、尚未執行 → 最適合安全防呆（擋 git reset --hard 等）。
4. PostToolUse／Stop — 改完立刻查可算的東西；深度檢查留到 Stop，避免「嘮叨成本」。

關鍵金句：Hook 擋下後輸出的那句話，會直接變成 Claude 收到的訊息——Hook 不只是攔，還能「講話」。腳本說什麼，Claude 就信什麼。

四個開源專案加起來，掛最多的是 claude-mem（6 個），但用到的時機幾乎都落在上述四種。Handler 五種裡先認得 Command；要查證用 Agent，不要只用 Prompt 瞎猜。

五、實戰一：擋含 .env／金鑰的提交

一句話講給 Claude：當準備提交時，先檢查修改裡有沒有 .env 或 API 金鑰；有就擋下。並要求它自測「有敏感資料擋下／沒有則放行」兩種情況。

• Event＝PreToolUse、Matcher＝Bash
• 放在使用者層 settings.json → 所有專案提交都會過這道關
• 平常感覺不到，真要出事才出現

兩個坑：① Matcher 範圍太大導致空轉、體感變慢——範圍儘量窄，細條件放腳本；② Stop Hook 沒有通過條件會無限循環——要有通過狀態＋次數上限兩道保險。

六、實戰二：擋 AI 味（沒標準答案也能做成門）

Event＝Stop。腳本找出尚未通過的文章，要求 Claude 開 Agent 審稿；改完再查，通過才准結束。文章又被改動則通過記錄失效。

前提：Hook 保證檢查一定發生，不保證判斷一定對——判斷仍是模型。從「你得記得去查」變成「一定會被查」，就是這支影片從頭到尾在講的差別。

七、值不值得做成 Hook？三條件

1. 你會重複做
2. 發生在固定時機
3. 漏掉會有實際損失

三條都對得上才跟你有關；對不上別跟風。另可分辨：改完沒跑測試＝忘了（Hook 可解）；讀權限碰不到的檔＝做不到（掛十個也沒用）。

八、五分鐘起手式

打開 CLAUDE.md，找出那條「寫過但最常忘」的規則（多數人第一條是改完跑測試），跟 Claude 說：

五分鐘內它會建好設定與腳本；不要了刪掉 settings.json 那段即可。寫文案、做研究整理一樣能掛，但別掛太多以免嘮叨成本。Codex 使用者也可做，但 Event 較少、handler 基本只跑 command——別直接複製 Claude Code 設定，把需求講給它重建。