Claude Code 必學設定 Hooks，完整教學一次搞懂
三句話摘要
Claude Code 的 Hooks：在特定時機自動執行檢查、防呆和通知的強制機制。 建立 Hook 只需要說清楚「什麼時候啟動」和「啟動後做什麼」，讓 AI 幫你自動化那些重複提醒、固定時機的工作。 Hook 與 Cloud Markdown 的根本差異：Cloud Markdown 是提醒指條，需要 AI 自己判斷要不要遵守；Hook 是由軟體掌控的 Deterministic 機制，只要設定時間點一到就絕對執行，不涉及 AI 的判斷風險。
重點整理
重點- 1
Hook 與 Cloud Markdown 的根本差異：Cloud Markdown 是提醒指條，需要 AI 自己判斷要不要遵守；Hook 是由軟體掌控的 Deterministic 機制，只要設定時間點一到就絕對執行，不涉及 AI 的判斷風險。
- 2
四個工作階段的 Event 分布：系統啟動階段（Session Start、User Prompt Submit）、工具準備執行階段（PreTool Use）、工具執行完成階段（PostTool Use）、工作結束階段（Stop、Notification、SubAgent 相關事件、Precompact）。
- 3
Handler 的選擇取決於檢查是否需要理解：Command 執行本機腳本適合規則明確的檢查（如敏感資料檢查）；Prompt 用現有資料直接判斷；Agent 可先讀檔案、搜尋、執行測試再判斷，適合複雜驗收；HTTP 和 MCP Tool 用來串接外部服務。
- 4
兩個長期穩定運作的關鍵：觸發範圍要精確（用 Matcher 和 Handler 邏輯雙重篩選），必須設定明確的結束條件（否則 Stop Hook 可能一直重複檢查）。
實用技巧與重點
乾貨- Event 四大階段：
- 啟動階段：Session Start（對話開啟/恢復時）、User Prompt Submit（送出提問時）
- 工具執行階段：PreTool Use（工具執行前），PostTool Use（工具執行後）
- 結束階段：Stop（本輪工作結束時）、Notification（通知提醒）、SubAgentStart/Stop、Precompact（上文濃縮前）
- Handler 五種類型：
- Command：執行本機指令或腳本
- HTTP：將資料傳到外部服務
- MCP Tool：呼叫已連線的 MCP 工具
- Prompt：交給另一個 AI 模型回答（無法讀檔案）
- Agent：啟動 SubAgent 可讀檔案、搜尋、執行測試
- 實際案例：
- 敏感資料檢查：Matcher = Bash（只攔截 Git 命令），Handler = GitCommitSecretGuard 腳本（檢查 ENV 檔案、API 密鑰）
- AI 寫作痕跡檢查：Event = Stop（工作結束時），Handler = Humanizer Gate 程式 + Agent 驗收
- 流行專案應用：Super Powers（SessionStart Hook 強制載入 Skill）、Clubman（User Prompt Submit Hook 注入相關記憶）、Impactable（PostTool Use Hook 驗收 UI 品質）
- Codex 與 Cloud Code 的差異：
- Cloud Code：31 種 Event，5 種 Handler
- Codex：11 種 Event，目前只執行 Command Handler（其他需求透過 Command 呼叫 Skill/Agent 完成）
結論
結論“建立 Hook 只需要說清楚「什麼時候啟動」和「啟動後做什麼」，讓 AI 幫你自動化那些重複提醒、固定時機的工作。”
完整解析
詳細Hooks 解決的核心問題是 Cloud Markdown 的可靠性不足。Cloud Markdown 提供的是提醒指條，AI 在每次對話時需要自己判斷要不要遵守，但 AI 常常會遺忘。相反地，Hook 是由 Claude Code 軟體本身掌控的強制機制，只要設定的時間點一到，軟體就會直接介入強制執行，完全不依賴 AI 的判斷。
Hook 的運作基礎是三層架構。Event 決定了觸發時機——Cloud Code 目前支援 31 種 Event，按工作階段分為四類。啟動階段包括 Session Start（對話開啟或恢復時）和 User Prompt Submit（送出提問時）；工具執行階段有 PreTool Use 和 PostTool Use；結束階段則有 Stop 以及 Notification、SubAgent 系列、Precompact 等特殊狀況的 Event。確定了 Event 後，Matcher 負責篩選條件——雖然 Cloud 會調用很多工具，但不能每次都觸發 Hook，所以 Matcher 用來指定要攔截的具體操作（如只鎖定 Bash、只看副檔名是 .ts 的檔案）。最後，Handler 決定觸發後要做什麼，有五種類型：Command 執行本機腳本；HTTP 傳資料到外部服務；MCP Tool 呼叫已連線的工具；Prompt 交給另一個 AI 模型判斷（無法讀檔案）；Agent 啟動 SubAgent 可以先讀檔案、搜尋、執行測試再判斷。
實務上有兩個常見案例。敏感資料檢查用 PreTool Use Event 在 Git commit 執行前攔截，Matcher 設定為只鎖定 Bash 指令，Handler 執行 GitCommitSecretGuard 腳本檢查提交內容是否包含 .env 檔案、API 密鑰等敏感資訊，若發現就擋下提交並告知哪個檔案有問題。另一個案例是內容創作中檢查 AI 寫作痕跡，用 Stop Event 在工作結束時觸發，Handler 先執行 Humanizer Gate 程式找出本次修改過的文章，再要求 Cloud 啟動 SubAgent 呼叫去 AI 味 Skill 審查文章，檢查通過後才允許結束工作。
要讓 Hook 長期穩定運作，需要注意兩件事。第一是觸發範圍要精確——用 Matcher 和 Handler 邏輯做雙重篩選，避免無關操作也被攔截。第二是必須設定明確的結束條件——特別是 Stop Hook，如果沒有通過條件記錄，可能會一直要求 AI 修改再檢查，陷入無限循環。
關鍵時刻
Pipeline v2帶時間戳的重點，會在逐字稿層級分析上線後產生。目前請先透過原始影片觀看。
事實查核
Pipeline v2說法查證是下一次管線升級的一部分。KeyFrame 只會顯示它真正能驗證的內容。
