想讓 Claude Code「改完一定跑測試」、「碰到敏感檔案一定停下來」？把規則只寫在 CLAUDE.md 還不夠。它提供的是模型可參考的指示；Hooks 則是在固定時機由 Claude Code 執行的自動化關卡。當你不想承擔 AI 漏做一步的風險，Hooks 才是適合的工具。
先講結論：什麼規則該用 Hooks？
用三個問題判斷即可：
- 它是否會重複發生？
- 它是否有明確的觸發時機？
- 漏掉時，是否會造成真實成本？例如覆寫程式、提交機密或交付未驗證的功能。
三題都是「是」，就很適合做成 Hook。一次性的需求直接在對話裡交代；專案原則與背景脈絡可留在 CLAUDE.md；需要保證執行的步驟，再交給 Hooks。
Hooks 與 CLAUDE.md：差別在「誰負責啟動」
| 工具 | 適合處理 | 限制 |
|---|---|---|
CLAUDE.md |
專案背景、架構原則、長期慣例 | 仍要由模型在當下理解並遵守，不能當成強制閘門 |
| Hooks | 固定時機的檢查、阻擋、格式化、驗收或通知 | 需要控制觸發範圍與通過條件，否則會拖慢或卡住流程 |
影片把 Hook 比喻為便利商店自動門：感應到條件就開，不需要再問「現在要不要照做」。這是理解 Hooks 最實用的角度。
設定檔只要理解三層：Event、Matcher、Handler
- Event（事件）：什麼時候啟動，例如工具執行前或任務準備結束時。
- Matcher（匹配條件）：要攔哪種工具、檔案或操作，避免每個動作都執行。
- Handler（處理方式）：條件符合後真正要做什麼，例如跑本機指令、送出提示、呼叫 Agent 或 HTTP 服務。
官方文件也列出用 Matcher 篩選 Hooks，以及 command、prompt、agent、HTTP 等自動化方式。不要先背完所有事件：先從工作流中真正會造成損失的一個動作開始即可。
最值得先掌握的 4 個時機
1. SessionStart：在新對話或恢復工作時準備環境
適合重新載入工作環境、帶回必要上下文或提醒當前狀態。要特別小心：每次開對話都注入大量內容，會占用上下文與成本；只放「這次一定需要」的資訊。
2. PreToolUse：在操作真正執行前做安全防呆
這是保護程式碼庫最有價值的關卡。例如只在終端機命令相關操作觸發，檢查是否含危險的 Git 操作、機密檔案或不允許的部署指令。若不合格，回傳原因讓 Claude Code 停下來處理，而不是事後補救。
3. PostToolUse：操作完成後立即驗收可計算的事情
適合在修改後跑格式化、語法檢查、測試，或檢查 HTML 圖片連結與基本可近用性。原則是：改完立刻查，但只查能可靠判定的項目。過度昂貴或主觀的審查不該在每個小修改後都觸發。
4. Stop：任務準備結束前做最後一道總檢
Stop 適合把比較深、比較慢的驗收集中到最後：例如彙整變更後跑完整測試、跨模型程式碼審查，或讓另一個 Agent 檢查文章是否仍有明顯 AI 腔。影片的重點很精準：Hook 能保證「檢查會發生」，但不能神奇保證模型的判斷永遠正確。
兩個實戰模板：安全提交與自動測試
提交前擋住敏感資料
將 Event 放在 PreToolUse，Matcher 限縮為終端機命令，Handler 再檢查是否為提交操作，以及本次變更是否包含 .env、金鑰或其他敏感內容。關鍵不是把 Matcher 寫得無所不包，而是讓它先縮小範圍，再由腳本做精準判斷。
改完 TypeScript 就跑測試
可從一句清楚的需求開始：「每次修改 TypeScript 檔案後，執行測試；失敗時指出錯誤並阻擋交付。」讓 Claude Code 協助產生設定與腳本後，務必親自確認兩種結果：有錯時確實阻擋、沒錯時能正常放行。
最常見的兩個坑
坑 1：Matcher 範圍太大，Claude Code 突然變慢
如果每個終端機指令、每次檔案讀取都觸發重量級檢查，體感會像 AI 無故卡頓。做法是先把 Matcher 縮到最小可行範圍，進一步的條件交給 Handler 快速判斷；不相關時應安靜退出。
坑 2：Stop Hook 沒有出口，陷入無限修正
Stop Hook 每次阻止任務結束，都可能促使 Agent 再修改並再次觸發自己。一定要加入兩道保險：通過狀態（已驗收就不要重複攔）與次數上限（連續失敗幾次就交還人類決策）。這比一味要求「做到完美」可靠得多。
Prompt 與 Agent Handler 怎麼選？
| 類型 | 適用情境 | 例子 |
|---|---|---|
| command | 有清楚、可程式化規則 | 檢查金鑰、跑測試、格式化 |
| prompt | 給定資料就能判斷 | 根據一段輸入檢查需求是否齊全 |
| agent | 必須查檔案、跑測試或蒐集證據 | 確認功能是否真的完成、進行跨模型審查 |
簡單說：能用程式穩定判斷的，優先用 command；需要查證才有答案的，不要假裝 prompt 看得出來，應交給 agent。
開始前的極簡檢查表
- 從
CLAUDE.md找一條 Claude Code 最常漏掉、但它其實做得到的規則。 - 明確寫出「何時觸發」與「觸發後做什麼」。
- 先用小範圍 Matcher，驗證失敗會擋、成功會放。
- 若是 Stop Hook，加上通過記錄與重試上限。
- 把每次會注入上下文、或會叫用模型的 Hook 視為成本，避免無節制堆疊。
結語
Hooks 不該取代思考，也不是把所有規則都自動化。它最有價值的地方，是把那些「固定時機、重複發生、漏掉代價很高」的工作，從提醒變成真正的流程關卡。先做一個安全、可驗證且有退出條件的 Hook，通常比一次塞進十個複雜自動化更有效。
