社群裡有人分享了幾篇關於 Claude Code Hook 的文章，看完第一個反應是：「我低估了 hook 能做的事情。」

我知道 hook 的存在，但一直把它當成「跑幾個簡單檢查」的輔助工具。那幾篇文章讓我意識到，hook 可以是完整的品質控制基礎設施——在每個關鍵時機介入，執行那些「應該要做但忘記做」的檢查。

Hook 的執行時機

Claude Code Hook 有五個觸發點：SessionStart、UserPromptSubmit、PreToolUse、PostToolUse、Stop，涵蓋整個開發互動的生命週期。

有了這個框架，問題就變成：哪些規範應該在哪個時機點執行？

我們建立了哪些 Hook

Session 啟動檢查

每次 session 開始時自動確認：git 遠端是否有需要同步的變更、開發環境依賴是否完整、工作日誌狀態。這些檢查不阻止啟動，只是讓開發者一開始就有完整的情境。

任務逃避偵測

這是我們設計中比較有趣的一個 hook。它在每次 prompt 提交時執行，掃描內容裡是否出現「太複雜先跳過」、「暫時不處理」這類詞彙，同時也會檢查行為模式：程式碼變更了但測試沒有對應變更、技術債務累積超過閾值等。一旦偵測到逃避行為，會建立一個 block 標記檔案，後續所有工具呼叫都會被阻止，直到問題被正視。

程式異味即時偵測

每次檔案編輯後（PostToolUse），我們會即時掃描變更的程式碼。函數超過 30 行、巢狀超過 4 層、參數超過 5 個、依賴數超過 10 個，這些都會觸發記錄並建議重構。這個 hook 採用非阻塞設計——發現問題時記錄，但不中斷開發流程。

版本推進建議

在 Claude 完成回應時（Stop），hook 會分析當前的工作狀態：有沒有未提交的變更、工作日誌有沒有標記完成、TodoList 系列是否達成。根據這些狀態，自動建議接下來應該做小版本推進還是繼續開發。

文件同步提醒

程式碼變更後，hook 根據檔案類型判斷哪些文件需要同步更新。API 異動對應 API 文件，架構異動對應架構文件，這類規則很難靠人記，但 hook 記得。

一個反覆遇到的事故

hook 開發過程中出過同一個事故不只一次。

Claude Code hook 系統的設計是：任何寫入 stderr 的輸出都會被視為 hook error 顯示給使用者。Python 的 logging 模組預設輸出到 stderr，所以即使 hook 正常執行，只要有 logging 輸出，UI 上就會冒出 hook error 警告。

這個問題反覆出現，最後系統性地修復，確立了一條規則：hook 禁止寫入 stderr，所有輸出必須走 stdout。現在這條規則寫進方法論，新 hook 都有對應的驗證：

1grep -r "sys\.stderr" .claude/hooks/ --include="*.py"

這個指令應該永遠返回空結果。

模組化的演進

剛開始每個 hook 腳本都是獨立的，讀取輸入、處理邏輯、輸出結果各自實作。問題很明顯：讀取 hook 輸入、輸出決策結果這些通用邏輯，在每個腳本裡都重複了一遍。

後來重構引入了共用模組。.claude/lib/ 底下現在有幾個核心模組：hook_io.py 負責標準化 I/O，hook_logging.py 負責日誌，config_loader.py 載入配置，git_utils.py 封裝 git 操作。

帶來兩個好處：腳本結構變得簡潔，開發者只需要專注判斷邏輯；共用模組可以寫獨立的單元測試，以前 hook 的正確性很難驗證，現在有了。

幾個設計原則

非阻塞優先。大部分品質檢查不該阻止開發流程，而是記錄、追蹤、提示。只有真正關鍵的違規——任務逃避、阻止狀態——才完全阻斷操作。

漸進式強制。從警告到記錄到追蹤到阻止，給開發者理解和修正的機會，不是一刀切拒絕。

可觀測性。hook 系統自己也需要被監控。有一個 performance monitor hook 專門追蹤其他 hook 的執行時間，超過 5 秒視為需要立即優化。

配置外部化。品質規則的閾值、代理人分派規則，全部放在 YAML 配置檔，不硬編碼在腳本裡。需要調整只改配置。

現在的感受

把規範寫進文件和寫進 hook，是完全不同的感受。

寫進文件的規範靠人記。寫進 hook 的規範，在每個關鍵時機自動執行，開發者甚至可以不知道它存在——但規範確實在發生效用。品質基線從依賴個人紀律，變成由系統保證。

在開發 Book Overview App 的過程中，我設計了一套完整的 Hook 系統防護體系，目的是防止開發過程中的逃避行為和確保AI的工作品質。

🔸 Hook 防護體系設計起因

AI會有逃避行為，以完成任務指標為優先而捨棄程式品質或者直接修改測試。

我設計了以下幾種防止停止和強制繼續的 Hook 機制：

🔹 check-todos.py - TodoWrite 完成度檢查

1# 防止未完成工作的會話結束
2if todos_pending or todos_in_progress:
3    output = {"continue": True, "stopReason": "Incomplete todos detected"}

• 🔹 目的: 防止有未完成 TodoWrite 任務時意外停止
• 🔹 機制: 檢查 transcript 中的 TodoWrite 工具狀態
• 🔹 效果: 強制繼續工作直到所有對話任務完成

🔹 check-work-log.sh - 工作日誌完成度檢查

1# 當工作狀態為進行中時，exit 2 阻止停止
2exit 2  # 阻止會話結束，要求繼續工作

• 🔹 目的: 確保當前版本的工作確實完成才允許停止
• 🔹 機制: 分析工作日誌的完成指標和技術債務狀況
• 🔹 效果: 避免「假性完成」，確保工作品質

🔹 check-next-objectives.sh - 版本系列目標檢查

1# 當版本系列仍在進行中時，exit 2 阻止停止
2exit 2  # 防止版本系列中途放棄

• 🔹 目的: 防止版本系列開發中途放棄
• 🔹 機制: 檢查 todolist.md 中的版本系列完成度
• 🔹 效果: 確保版本系列目標達成才允許推進

🔹 check-5w1h-compliance.py - 決策品質檢查

1# 當 5W1H 分析不合規時，阻止 TodoWrite
2{"decision": "block", "reason": "5W1H analysis required"}

• 🔹 目的: 防止逃避性思考和粗糙決策
• 🔹 機制: PreToolUse 階段攔截並檢查 5W1H 完整性
• 🔹 效果: 強制深度思考，杜絕逃避行為

🔸 遇到的邏輯衝突問題

在開發過程中，發現了奇怪的狀況：

原問題:

• check-todos.py 顯示 “All todos completed successfully.”
• 同時系統又顯示 “Stop hook prevented continuation” 訊息
• 我的問題是：已完成所有 todos 為何還阻止停止？這訊息是誰吐出來的？

根本原因:

• 不同 Hook 腳本檢查不同的 todo 來源（會話 vs 專案）
• 會話的任務已結束，但是有其他hook觸發了避免停止的機制

設計思路

防護體系的核心理念：

• 多層防護：從對話層、工作層、版本層、決策層建立完整防護
• 零逃避容忍：任何逃避行為都會被自動檢測和阻止
• 品質強制：不符合品質標準的工作不允許繼續
• 使用者指引：被阻止時提供明確的修正指引和下一步行動

Exit Code 官方定義

根據 Claude Code 官方文件，Hook 腳本的 Exit Code 具有特定含義：

Exit 0 - 成功執行

1exit 0

• 🔸 正常成功執行
• 🔸 允許 Claude Code 繼續操作
• 🔸 不會產生任何阻止行為
• 🔸 用途: 檢查通過、條件滿足、正常完成

Exit 1 - 一般錯誤

1exit 1

• 🔸 非阻塞性錯誤
• 🔸 操作仍可繼續
• 🔸 表示: 有問題但不嚴重
• 🔸 用途: 輕微問題、建議性警告

Exit 2 - 阻止停止 (關鍵!)

1exit 2

• 🔸 阻止 Claude Code 停止會話
• 🔸 顯示 stderr 內容給 Claude
• 🔸 強制要求繼續工作
• 🔸 用途: 工作未完成、需要繼續開發
• 🔸 注意: 這是「阻止停止」而非「阻止繼續」

Exit 3+ - 嚴重錯誤

1exit 3

• 🔸 嚴重錯誤狀態
• 🔸 通常阻止繼續
• 🔸 自定義錯誤類型
• 🔸 用途: 需要立即處理的問題

Exit 2 的真正定義

語意澄清

🔸 錯誤理解:

• “Stop hook prevented continuation” = 阻止繼續工作

🔸 正確理解:

• “Stop hook prevented continuation” = 阻止了「停止會話」這個行為
• 實際效果在我腳本觸發的原因：當前會話還有todo清單未完成，強制繼續工作，不允許停止會話

實際應用場景

專案中的 Exit 2 使用案例：

check-work-log.sh

 1# 當工作狀態為 "IN_PROGRESS" 時
 2if [[ $WORK_STATUS == "IN_PROGRESS" ]]; then
 3    echo "工作進行中，建議完成後再推進"
 4
 5    # 輸出詳細說明到 stderr
 6    cat >&2 <<EOF
 7🔸 版本推進暫停 - 當前工作尚未完成
 8
 9🔸 停止原因：
10• 工作日誌顯示工作仍在進行中
11• 完成度指標不足
12• todolist.md 中有待辦任務
13
14🔸 建議的 TodoWrite 任務：
15請執行以下工作項目...
16EOF
17
18    exit 2  # 阻止停止，要求繼續工作
19fi

check-next-objectives.sh

 1# 當版本系列狀態為 "IN_PROGRESS" 時
 2case "$SERIES_STATUS" in
 3    "IN_PROGRESS")
 4        echo "版本系列仍在進行中"
 5
 6        # 提供具體的待辦任務資訊
 7        cat >&2 <<EOF
 8🔸 版本推進暫停 - 當前版本系列仍在進行中
 9
10🔸 部分待完成任務範例：
11• 修復UI測試中的類型問題
12• 更新ViewModel層錯誤處理適配
13
14🔸 建議的 TodoWrite 任務：
15繼續版本系列開發...
16EOF
17
18        exit 2  # 阻止停止，要求繼續版本開發
19        ;;
20esac

🔸 Hook 系統邏輯衝突解決方案

問題診斷

衝突場景:

• check-todos.py 檢查 TodoWrite 工具（會話級別）
• 其他 Hook 腳本檢查 todolist.md（專案級別）
• 結果：TodoWrite 完成但 todolist.md 仍有待辦事項

解決策略

方案一：Hook 腳本提供 TodoWrite 建議

在返回 exit 2 的 Hook 腳本中：

 1# 檢查 todolist.md 中的未完成任務
 2PENDING_TODOS=$(grep -c "\[ \]" "$PROJECT_ROOT/docs/todolist.md" 2>/dev/null || echo "0")
 3
 4# 在 stderr 中提供 TodoWrite 建議
 5cat >&2 <<EOF
 6🔸 建議的 TodoWrite 任務：
 7請執行以下 TodoWrite 來管理具體工作項目：
 8
 9TodoWrite([
10  {"content": "完成當前版本核心開發工作", "status": "pending", "activeForm": "完成當前版本核心開發工作"},
11  {"content": "執行完整測試確保100%通過率", "status": "pending", "activeForm": "執行完整測試確保100%通過率"}
12])
13EOF

方案二：統一狀態檢查邏輯

確保所有 Hook 腳本檢查相同的狀態來源，或者建立狀態同步機制。

實際演練

Exit Code 選擇原則

• 🔸 Exit 0: 一切正常，可以繼續
• 🔸 Exit 1: 有小問題，但可以繼續
• 🔸 Exit 2: 工作未完成，禁止停止，必須繼續
• 🔸 Exit 3+: 嚴重問題，需要立即處理

Hook 腳本設計模式

 1#!/bin/bash
 2
 3# 🔸 檢查狀態
 4check_work_status() {
 5    # 實作狀態檢查邏輯
 6}
 7
 8# 🔸 根據狀態決定 exit code
 9case "$WORK_STATUS" in
10    "COMPLETED")
11        echo "工作已完成，可推進版本"
12        exit 0
13        ;;
14    "MOSTLY_COMPLETED")
15        echo "基本完成，建議檢查後推進"
16        exit 1
17        ;;
18    "IN_PROGRESS")
19        echo "工作進行中，建議完成後再推進"
20
21        # 🔸 提供詳細的使用者指引
22        cat >&2 <<EOF
23🔸 停止原因說明
24🔸 需要採取的行動
25🔸 建議的 TodoWrite 任務
26EOF
27
28        exit 2  # 阻止停止
29        ;;
30    *)
31        echo "工作未完成，需要繼續開發"
32        exit 3
33        ;;
34esac

使用者體驗優化

• 清楚的錯誤訊息: 使用 stderr 輸出詳細說明
• 具體的行動指引: 告訴使用者需要做什麼
• TodoWrite 整合: 提供可執行的任務建議
• 狀態一致性: 確保不同檢查機制的邏輯一致

🔸 實際測試結果

測試案例 : check-work-log.sh

1$ ./.claude/scripts/check-work-log.sh
2# 返回 exit 3，stderr 顯示：
3🔸 版本推進暫停 - 工作未開始或缺乏完成指標
4🔸 停止原因：
5• 工作日誌缺乏完成指標 (0 = 0)
6• todolist.md 中有 240 個待辦任務
7
8🔸 建議的 TodoWrite 任務：
9請執行以下 TodoWrite 開始系統化工作...

測試案例 🔸: check-next-objectives.sh

1$ ./.claude/scripts/check-next-objectives.sh
2# 返回 exit 2，stderr 顯示：
3🔸 版本推進暫停 - 當前版本系列仍在進行中
4🔸 部分待完成任務範例：
5• 修復UI測試中的類型問題
6• 更新ViewModel層錯誤處理適配
7
8🔸 建議的 TodoWrite 任務：
9請執行以下 TodoWrite 繼續版本系列開發...

🔸 效果評估

問題解決成果

• 🔸 邏輯一致性: Hook 系統不再產生矛盾訊息
• 🔸 使用者體驗: 清楚知道為什麼被阻止和需要做什麼
• 🔸 工作流程: TodoWrite 與 todolist.md 狀態同步

關鍵學習

🔸 Exit 2 的真實含義: 阻止停止，要求繼續工作 🔸 stderr 的重要性: Claude Code 會顯示 stderr 給使用者 🔸 狀態檢查一致性: 不同檢查機制需要協調 🔸 使用者指引: 提供可執行的具體建議比抽象說明更有效

後續改善方向

• Hook 腳本標準化: 建立統一的錯誤處理和訊息格式
• 狀態同步機制: 建立 TodoWrite 與 todolist.md 的雙向同步
• 使用者體驗測試: 收集真實使用場景的反饋
• 文件完善: 將這些經驗整理成團隊開發規範

🔸 參考資源

• Claude Code Hooks Guide
• Claude Code Hook Events
• reddit網友分享 在有todo未完成的情況下用hook偵測會話轉階段，強迫AI繼續工作不要停下來