claude-code-hooks-mastery 是一個圍繞 Claude Code Hooks 的學習專案。
它不是只給幾個零散腳本，而是把 Claude Code 的 hooks 生命週期、配置方式、腳本寫法和常見自動化場景放在一起講清楚。對想讓 Claude Code 更可控、更像工程化助手的人來說，這類資料很值得看。
Claude Code 預設已經能讀程式碼、改檔案、跑命令。但如果你想讓它在特定時機自動檢查權限、攔截危險操作、注入專案規範、執行測試、提醒團隊規則，單靠聊天指令就不夠穩定。Hooks 的價值就在這裡：把「每次都要提醒 AI 的規則」變成可執行的流程。
Hooks 解決什麼問題
使用 Claude Code 一段時間後，常見痛點大概有這些：
- 每次新會話都要重複告訴它專案規則
- 擔心它執行不該執行的命令
- 希望檔案修改前後自動做檢查
- 想在提交前自動跑格式化、測試或安全掃描
- 想把團隊規範寫成固定流程，而不是靠口頭提醒
- 想在工具呼叫前後拿到上下文，做記錄或攔截
- 希望複雜任務可以觸發子代理或專門腳本處理
Hooks 就是為這些「固定時機的自動動作」準備的。
你可以把它理解成 Claude Code 工作流裡的事件鉤子：當會話開始、使用者提交提示詞、模型準備呼叫工具、工具呼叫完成、代理即將結束等節點發生時，Claude Code 可以執行你配置的腳本。
13 個 Hooks 生命週期
專案 README 的重點之一，是系統整理了 Claude Code 的 13 個 hook 事件。
這些事件覆蓋了從會話開始到工具呼叫、從使用者輸入到代理結束的多個節點。按用途可以粗略分成幾類：
- 會話啟動相關：用於初始化環境、注入專案上下文
- 使用者輸入相關：用於檢查提示詞、補充規則、做稽核
- 工具呼叫前相關：用於權限判斷、命令攔截、安全檢查
- 工具呼叫後相關：用於記錄結果、觸發格式化、執行驗證
- 任務結束相關：用於總結、清理、通知或保存狀態
這種生命週期設計讓你不必把所有規則都寫進一個超長提示詞裡。
比如，權限控制應該發生在工具呼叫前；格式化檢查更適合發生在檔案修改後；專案規範注入適合發生在會話開始或使用者輸入後。把規則放到正確的 hook 節點，通常比把所有內容塞進 system prompt 更可靠。
配置檔案在哪裡
Claude Code 的 hooks 通常透過設定檔配置。
常見位置包括：
- 使用者級配置：
~/.claude/settings.json - 專案級配置：
.claude/settings.json
使用者級配置適合放個人偏好，比如通用安全規則、命令攔截、日誌路徑。
專案級配置適合放倉庫相關規則，比如這個專案必須跑什麼測試、哪些目錄不能改、生成檔案怎麼處理、提交前要做哪些檢查。
如果你在團隊裡使用 Claude Code，更推薦把專案級配置放進倉庫。這樣每個人打開專案時，拿到的是同一套 AI 協作約束，而不是各自憑記憶提醒。
單檔案腳本為什麼重要
專案裡強調了 UV 單檔案腳本的寫法。
這類腳本的好處是部署簡單。一個 Python 檔案就可以宣告依賴並執行，不必為了一個 hook 單獨維護複雜環境。對 hooks 來說，這很合適，因為很多 hook 只是做一件小事：
- 檢查命令是否允許執行
- 判斷檔案路徑是否安全
- 讀取專案規範並返回給 Claude
- 掃描輸出中是否包含敏感資訊
- 在修改後執行格式化或測試
- 把事件寫入日誌
Hook 腳本越小，越容易維護，也越不容易變成新的複雜系統。
可以做哪些自動化
claude-code-hooks-mastery 展示的方向比較多，實際工作中最常見的是下面幾類。
1. 權限和安全控制
這是 hooks 最直接的用途。
比如在 Claude Code 準備執行命令之前，先檢查命令內容。如果命令包含刪除、重置、清空、覆蓋等高風險動作，就阻止執行或要求人工確認。
類似規則還可以用於檔案路徑：
- 不允許修改生產配置
- 不允許寫入金鑰檔案
- 不允許刪除遷移腳本
- 不允許觸碰指定目錄
- 不允許執行未批准的網路命令
這類保護放在工具呼叫前，比寫一句「不要做危險操作」更可靠。
2. 上下文注入
很多專案都有固定背景：
- 技術棧
- 編碼規範
- 測試命令
- 分支策略
- 目錄結構
- 禁止事項
- 生成檔案處理規則
這些內容每次手動告訴 Claude Code 很麻煩，也容易漏。Hooks 可以在會話開始或使用者提交提示詞後，把必要上下文自動注入進去。
這相當於給 Claude Code 配一個專案級的工作說明書。它不會替代 README 或開發文件，但能讓 AI 在執行任務前更快進入正確狀態。
3. 修改後的驗證
當 Claude Code 修改檔案後，可以透過 hook 自動觸發檢查。
常見動作包括：
- 執行格式化
- 執行 lint
- 執行單元測試
- 檢查型別錯誤
- 掃描生成檔案
- 校驗 Markdown 或 JSON 格式
這對減少低級錯誤很有幫助。尤其是 AI 改動多個檔案時，修改後自動跑一輪輕量驗證，可以更早發現問題。
不過也要注意，hook 裡不適合預設塞太重的任務。每次檔案改動都跑完整測試套件，可能會讓體驗變得很慢。更實用的做法是按檔案類型、目錄和任務風險選擇檢查範圍。
4. 團隊規則驗證
如果團隊已經有明確約定，可以把一部分約定放進 hooks。
比如：
- 提交訊息格式
- 程式碼風格規則
- 禁止直接修改某些生成檔案
- 文件必須同步更新
- API 變更必須改測試
- 某些目錄只能用指定工具生成
這會讓 Claude Code 更像團隊流程的一部分，而不是一個不受約束的外部助手。
當然，hooks 不應該替代 CI。它更適合做本地快速提醒和前置攔截，真正的最終驗證仍然應該交給 CI、review 和測試系統。
5. 子代理和專門任務
README 裡還提到子代理相關內容。
這類用法適合把複雜任務拆給更專門的流程處理。比如主會話負責理解需求，hook 或配置觸發專門的檢查、稽核、總結、文件整理任務。
對個人使用者來說，最先值得做的不是複雜代理編排，而是把重複、明確、低風險的動作交給 hooks。等規則穩定後，再考慮更複雜的自動化。
Statusline 和輸出樣式
專案還覆蓋了狀態列和輸出樣式。
這部分看起來像體驗細節，但對長期使用 Claude Code 很有意義。狀態列可以展示當前上下文、任務狀態、環境資訊或提示資訊；輸出樣式則可以讓 Claude Code 的回答更符合你的工作習慣。
如果你每天都在同一個終端裡和 AI 協作，這些細節會影響效率。好的狀態提示能減少誤操作，也能讓你更快判斷當前會話是否處在正確專案、正確分支、正確環境裡。
不要把 hooks 寫得過重
Hooks 很強，但不適合什麼都往裡面塞。
比較好的規則是：
- 高頻動作要快
- 安全攔截要明確
- 輸出要短
- 失敗原因要可讀
- 腳本盡量單一職責
- 重型檢查交給顯式命令或 CI
如果一個 hook 每次都執行十幾秒，使用者很快就會想關掉它。如果一個 hook 攔截規則含糊不清，Claude Code 和使用者都會難以理解下一步該怎麼做。
Hooks 最適合處理那些邊界清楚的事情：允許或拒絕、補充上下文、記錄日誌、執行輕量檢查、提示下一步。
適合怎樣的使用者
如果你只是偶爾讓 Claude Code 改一小段程式碼，可能暫時不需要深入 hooks。
但如果你符合下面幾種情況，就很適合研究這個專案：
- 高頻使用 Claude Code
- 經常讓 AI 修改真實專案程式碼
- 擔心 AI 執行危險命令
- 想把團隊規範自動注入 AI 工作流
- 希望修改後自動跑檢查
- 想把重複提醒變成配置
- 正在搭建更穩定的 AI 編程流程
尤其是多人協作專案，hooks 的意義會更明顯。它可以把一部分團隊經驗沉澱成腳本，而不是靠每個人臨時提醒 AI。
使用時要注意
第一，先從安全類 hook 開始。
相比複雜自動化，命令攔截、路徑保護、敏感檔案檢查更容易落地，也更能立刻降低風險。
第二，專案級規則要謹慎提交。
.claude/settings.json 會影響所有使用這個倉庫的人。把規則提交前，最好確認它不會過度限制正常開發，也不會依賴只有你本機才存在的路徑。
第三，hook 輸出要簡潔。
Claude Code 會消費這些輸出。輸出太長，會污染上下文；輸出太模糊，又起不到指導作用。最好只返回必要判斷和下一步建議。
第四，保持可除錯。
Hooks 一旦變多，問題可能出在配置、腳本、權限、路徑、依賴或 Claude Code 本身。給腳本留下清楚日誌，會讓後續排查輕鬆很多。
參考
最後一句
Claude Code Hooks 的價值，是把「希望 AI 每次都記住的規矩」變成真正會執行的流程。
如果你已經開始把 Claude Code 用在真實專案裡，hooks 會是從「會聊天的編程助手」走向「可約束的工程協作者」的關鍵一步。