Claude Code Hooks：自動化策略完整指南

現行原則： Hooks 是選用的自動化，不是必裝的政策層。除非使用者刻意啟用有文件說明的專案整合，Claude World 工具預設不註冊任何 Hook。

Hooks 會把生命週期事件連接到命令或其他支援的 handler。這很強大，但也表示程式碼直接進入互動式 Session 的執行路徑。最好的起點很簡單：先不用 Hook，只有當需求無法在其他地方更清楚表達時，才加入最小的自動化。

Hooks、指引、權限與 CI 各有不同職責

• 指引說明期望的工作方式，同時保留判斷空間。
• Skills 封裝可重用程序，讓 Claude 或使用者在適合時選用。
• 原生權限決定 Runtime 可以使用哪些工具與操作。
• CI 在清楚的交付邊界驗證 Repository 成果。
• Hooks 自動回應生命週期事件。

不要在隱藏的 Hook 腳本裡重做權限或 CI，也不要把每一條建議都變成強制事件處理器。

判斷順序

依序詢問：

1. 簡短的 CLAUDE.md 指引能否表達意圖？
2. 這是不是應該封裝成 Skill 的可重用工作流？
3. 使用者或 CI 能否在明確 checkpoint 執行命令？
4. 動作是否真的必須在生命週期事件發生時自動執行？
5. 每位專案使用者是否都能接受新增的延遲與失敗模式？

只有第四題的答案是肯定時，才應開始考慮 Hook。

預設運作設定

低干擾環境應具備：

• 工具不註冊任何使用者全域 Hook；
• 沒有隱藏的 deny 規則；
• 沒有自動續跑迴圈；
• 不會自動 commit、push、部署或執行破壞性操作；
• 由使用者明確選擇 CLI 原生權限設定；
• 選用型專案 Hooks 與專案文件放在一起。

組織管理政策與既有使用者設定仍可能影響 Session。工具不應宣稱可以覆蓋這些層級。

關於停止事件

停止與 subagent 停止事件可用於生命週期整合，但不應預設作為「繼續工作」開關。持續拒絕完成的 handler 可能困住 Agent、消耗 tokens，也會掩蓋任務真實狀態。

使用者需要再迭代時，請使用可見且自願啟動的工作流或 Skill。達成驗收條件或使用者要求停止時，讓 Session 正常結束。

由專案明確選用

如果確實需要 Hook：

1. 註冊應跟著需要它的專案。
2. 說明它會讀取哪些資料、執行什麼命令。
3. 清楚提供啟用與移除方式。
4. 限制執行時間與輸出。
5. 優先觀察，不要任意修改。
6. 驗證停用後 CLI 仍能正常使用。

工具與共享環境的 Hooks 一律維持在專案範圍。本指南不安裝也不推薦使用者全域 Hooks。既有個人註冊應視為獨立的本機設定：明確稽核，除非仍是你刻意需要的項目，否則移除。

診斷緩慢或卡住的 Session

盤點組織管理、使用者、專案與本機設定中實際生效的 Hooks。檢查重複事件、遺失腳本、網路呼叫、遞迴啟動 CLI，以及可能拒絕完成的 handler。每次停用一項註冊，開啟新 Session，再比較差異。

當另一個相容 CLI 可能重用 Claude 設定時尤其要做這項稽核：請查看「實際生效的設定」，不能只檢查某一個產品的 Hook 目錄。

支援事件與最新設定語法請讀第 15 課：Hooks 系統。需要可攜式 agents、skills 與 Session 接替、但不強制安裝 Hooks，請見 Director Mode Lite。