Claude Code Hooks 開發指南：完整實戰手冊

2026 編輯更新： 舊版文章曾包含使用者全域的攔截規則與強迫續跑做法，這些範例已退役。目前建議是指引優先、預設零 hooks，而且只能由專案明確選擇啟用。

Claude Code Hooks 是事件驅動的自動化機制。當某個小型、確定性的動作必須在特定生命週期事件發生時執行，它會很有用；但若目的是教 Agent 如何工作，Hook 通常不是第一選擇。

先選最輕量的機制

需求	優先選擇
說明專案慣例與意圖	CLAUDE.md 指引
封裝可重用程序	在適當時機使用 Skill
在明確邊界執行檢查	一般命令、task 或 CI
自動觀察生命週期事件	小型、選用型 Hook
控制工具權限	CLI 原生權限與組織政策

預設安裝可以維持 零個啟用中的 hooks，同時完整提供 agents、skills 與 session 工作流。自動攔截器越少，延遲與意外拒絕越少，除錯也更直接。

Guidance-first Hook 契約

新增 Hook 前，先寫清楚五件事：

1. 事件： 哪個確切事件需要自動化。
2. 效果： Hook 只執行哪一個有界限的副作用。
3. 範圍： 哪個專案主動啟用並擁有設定。
4. 失敗行為： 選用型便利功能失敗時不能卡住 Session。
5. 移除方式： 不必解除安裝整套工具也能停用。

如果需求只是「優先跑精準測試」、「摘要差異」或「發佈前先詢問」，請保留成指引。把建議改造成攔截通常只增加干擾，不會增加能力。

適合選用的 Hooks

好的候選項目應確定、快速、可見，而且容易移除：

• 完成操作後追加簡短的本機稽核紀錄。
• 在明確的專案事件後刷新產生式 metadata。
• Session 開始時顯示簡短的專案提示。
• 長時間工作完成後發出通知。

每個 Hook 只做一件事，限制輸出，盡量不依賴網路，並在專案設定中清楚呈現是否啟用。

不再預設安裝的模式

• 複製到所有專案的使用者全域 Hook 套件。
• 廣泛拒絕 Shell 或檔案操作的前置攔截。
• 強迫 Claude 或 subagent 持續執行的停止事件邏輯。
• 使用者看不到的自動測試、lint、commit 或部署關卡。
• 長時間執行且會擷取 prompt、原始碼或憑證的腳本。

這些模式可能讓功能完整的 CLI 看起來像卡住，也會重複原生權限、CI 與明確工作流 Skills 的職責。

稽核實際生效的設定

專案 Hook 目錄為空，不代表沒有 Hook 在運作。請檢查環境中每一層有效設定：

• 組織管理的設定；
• 使用者設定；
• 專案設定；
• 未提交的本機專案設定；
• 可能載入 Claude 資產的擴充功能或相容 CLI 整合。

逐一記錄事件、命令、範圍、timeout、資料存取，以及是否能變更或拒絕操作。移除找不到腳本的孤兒註冊與用途不明的自動化，只保留專案使用者都能說明其價值的項目。

不干擾工作的驗證方式

每次只在可拋棄的專案測試一個選用 Hook，確認：

• Hook 停用時一般 Session 仍正常；
• 失敗可見而且可恢復；
• 延遲有明確上限；
• 輸出不會洩漏秘密或私有原始碼；
• 不會意外形成續跑迴圈。

最新事件 schema 與生命週期參考請讀第 15 課：Hooks 系統。需要預設零 hooks 的多 CLI 環境，請見 Director Mode Lite。