Claude Code Hooks 與自動化指南：事件驅動的 AI 工作流完全教學

1. 什麼是 Hooks？跟 Skills 有什麼不同？

• Skills：使用者主動觸發（輸入 /指令 或自然語言）→ Claude 執行預設流程
• Hooks：事件自動觸發（工具被呼叫、訊息送出、指令完成等）→ 系統自動執行 Shell 指令
• 組合威力：/Deploy Skill 執行部署 → 部署完成 → Hook 自動跑 Smoke Test → Smoke Test 通過 → Hook 發 Slack 通知

2. Hook 事件類型

3. 設定方式：settings.json

• 設定檔位置：~/.Claude/Settings.Json（全域）或 .Claude/Settings.Json（專案層級）
• 基本結構：Hooks 物件下按事件類型分組，每個事件可綁定多個 Hook
• 每個 Hook 包含：Type（Command）、Command（要執行的 Shell 指令）、Description（說明）
• 可選欄位：Matcher（只對特定工具名稱觸發）、Timeout（超時設定）
• 優先順序：專案層級的設定會覆蓋全域設定

4. 範例 1-3：開發流程自動化

• 範例 1 — 檔案修改後自動 Lint：Posttooluse + Matcher: Write/Edit → 執行 Eslint --Fix 或 Black 自動格式化剛修改的檔案
• 範例 2 — 對話開始時載入專案狀態：Sessionstart → 執行 Git Status 和 Docker Ps，把結果帶入對話上下文
• 範例 3 — 危險操作前攔截：Pretooluse + Matcher: Bash → 檢查指令是否包含 Rm -Rf、Git Push --Force 等危險操作，有的話阻止執行

5. 範例 4-6：品質保證自動化

• 範例 4 — 提交前自動跑測試：Pretooluse + Matcher: Bash（當指令包含 Git Commit）→ 先跑 Pytest，測試通過才允許提交
• 範例 5 — 翻譯安全檢查：Posttooluse + Matcher: Write（當修改 .Po 或 Locale 檔案）→ 自動執行 Python3 Scripts/Check_Translations.Py --Js-Safety
• 範例 6 — Json 修改後自動驗證：Posttooluse + Matcher: Write（當修改 Data/Guides/ 下的檔案）→ 自動執行 ./Scripts/Validate_Json.Sh

6. 範例 7-8：通知與記錄

• 範例 7 — 完成後自動通知：Stop → 把 Claude 的最後回應摘要發到 Slack 或 Telegram，讓團隊成員知道任務完成
• 範例 8 — 操作記錄：Posttooluse → 把每次工具呼叫的類型和參數記錄到 Log 檔案，方便事後追蹤「Claude 做了什麼」

7. Hooks + Skills 組合模式

• 模式 1 — 前置檢查：Hook（Pretooluse）確認環境正常 → Skill 執行主要工作。例如部署前 Hook 檢查 Ci 是否通過
• 模式 2 — 後處理鏈：Skill 完成主要工作 → Hook（Stop）自動執行後處理。例如 /Content-Pipeline 建立內容後，Hook 自動 Commit 並通知
• 模式 3 — 品質門禁：Skill 修改程式碼 → Hook（Posttooluse）自動跑 Lint 和測試 → 全部通過才繼續。確保 Ai 產出的程式碼符合品質標準

8. 除錯與最佳實踐

• Hook 沒觸發：確認事件類型和 Matcher 是否正確。用 Echo 指令測試 Hook 是否被呼叫
• Hook 阻擋了操作：檢查 Hook 的 Exit Code。非零的 Exit Code 會阻止操作
• Hook 太慢：加入 Timeout 設定，避免 Hook 卡住整個工作流。預設超時 60 秒
• 最佳實踐 1：Hook 指令保持簡單——一個 Hook 做一件事
• 最佳實踐 2：用 Description 清楚說明 Hook 的用途，方便團隊成員理解
• 最佳實踐 3：先在個人設定中測試，確認無誤後再推到專案設定
• 最佳實踐 4：敏感操作（如自動 Push、自動部署）的 Hook 要特別謹慎，建議加入確認步驟