生活分享

Claude Code|Hooks 實用案例

建立格式檢查、測試提示及通知流程。Hook 的價值來自可預測的觸發與可辨認的結果。本篇提供三個漸進用途:檔案編輯後檢查 JavaScript 語法、提醒完成前執行測試,以及在需要注意時留下本機通知紀錄。每個用途都有停止方式,並把檢查失敗與程式故障分開處理。

閱讀時間約 5 分鐘

LINE 分享
Hooks 實用案例:文件、螢幕與完成記號的幾何插圖
圖片:Mokaair (© Mokaair)
本篇目錄
  1. 1. 案例一:編輯後檢查語法
  2. 2. 案例二:在結束前提醒驗證
  3. 3. 案例三:保留本機注意事項
  4. 4. 失敗情況要能被看見

Hook 的價值來自可預測的觸發與可辨認的結果。本篇提供三個漸進用途:檔案編輯後檢查 JavaScript 語法、提醒完成前執行測試,以及在需要注意時留下本機通知紀錄。每個用途都有停止方式,並把檢查失敗與程式故障分開處理。

請先完成,確認人工輸入、真實工具事件及停用測試都成功。本篇使用 Node.js,不需要安裝 formatter 或通知套件。若要導入真正的格式化工具,先閱讀專案既有設定,避免新增另一套相互衝突的風格。

案例一:編輯後檢查語法

案例一:編輯後檢查語法 → 案例二:在結束前提醒驗證 → 案例三:保留本機注意事項
案例一:編輯後檢查語法 → 案例二:在結束前提醒驗證 → 案例三:保留本機注意事項 · 圖片:Mokaair (© Mokaair)
閱讀完整文字說明

Hooks 實用案例,以流程和文件圖形呈現教學重點。

語法檢查適合放在 PostToolUse,因為檔案此時已被寫入。它只能指出已完成修改中的問題,不能宣稱阻止了那次寫入。下面程式只檢查練習專案根目錄的 app.js 與 model.js,不會對每個任意路徑執行命令。

寫入 scripts/check-js.mjs · javascript
import { readFileSync } from 'node:fs';
import { resolve } from 'node:path';
import { spawnSync } from 'node:child_process';
try {
  const event = JSON.parse(readFileSync(0, 'utf8'));
  const root = resolve(event.cwd);
  const file = resolve(root, event.tool_input?.file_path ?? '');
  const allowed = ['app.js', 'model.js'].map(name => resolve(root, name));
  if (allowed.includes(file)) {
    const result = spawnSync(process.execPath, ['--check', file], { encoding: 'utf8' });
    if (result.error) throw result.error;
    if (result.status !== 0) {
      console.log(JSON.stringify({
        systemMessage: 'JavaScript 語法檢查失敗,請查看該檔案。',
        hookSpecificOutput: {
          hookEventName: 'PostToolUse',
          additionalContext: '請修正語法錯誤並重新檢查:' + result.stderr.slice(0, 3000)
        }
      }));
    }
  }
} catch (error) {
  console.error(String(error));
  process.exitCode = 1;
}

把前篇 PostToolUse handler 的 args 改為 scripts/check-js.mjs 對應路徑,或新增另一個 handler。command 仍為 node,timeout 可維持十秒。這是檢查而非自動格式化,不會改寫檔案,因此較容易先理解效果。

人工測試時,在練習副本的 app.js 暫時加入一個未閉合括號,輸入事件包含該檔案的 file_path。預期 stdout 是合法 JSON,包含語法錯誤回饋。再修復括號,預期程式正常結束且不輸出警告。最後透過 Claude 的 Edit 或 Write 重做一次,才算完成整合觸發驗證。

寫入 hook-input.json:改成你的專案絕對路徑 · json
{"cwd":"C:/practice/todo","hook_event_name":"PostToolUse","tool_name":"Edit","tool_input":{"file_path":"C:/practice/todo/app.js"}}

案例二:在結束前提醒驗證

Stop 事件發生在 Claude 回應結束時,可能只是完成一次分析,不一定剛好是功能完成。因此這裡只示範一次簡短提醒,不把每個 Stop 都變成完整測試,也不使用會持續要求 Claude 繼續工作的阻擋回應。

寫入 scripts/remind-tests.mjs · javascript
import { readFileSync } from 'node:fs';
try {
  const event = JSON.parse(readFileSync(0, 'utf8'));
  if (!event.stop_hook_active) {
    console.log(JSON.stringify({
      systemMessage: '交付前請核對實際測試結果;本提醒本身沒有執行測試。'
    }));
  }
} catch (error) {
  console.error(String(error));
  process.exitCode = 1;
}
合併至 .claude/settings.local.json 的 hooks 設定 · json
{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "node",
            "args": ["${CLAUDE_PROJECT_DIR}/scripts/remind-tests.mjs"],
            "timeout": 10
          }
        ]
      }
    ]
  }
}

請把 Stop 與既有 PostToolUse 合併在同一 hooks 物件,不要出現兩個重複 hooks 鍵。人工事件可使用 hook_event_name 為 Stop,並比較 stop_hook_active 為 false 與 true 的輸出;後者應不再產生提醒。

如果將來改為阻擋型 Stop Hook,必須處理再次進入時的循環條件。測試失敗也不應無限重跑同一命令;應先保存錯誤、找出原因,再決定能否修復。產品對連續阻擋有保護限制,但不能把該限制當作正常流程設計。

案例三:保留本機注意事項

需要權限或其他注意事項時,可使用 Notification 事件,沿用前篇 log-edit.mjs 記錄事件時間。先不設定 matcher,觀察真正收到哪些事件,再依目前官方事件欄位縮小條件。Notification 的類型與支援情況可能隨版本改變,不能把一般聊天結束當成一定會觸發通知。

這個本機紀錄不等於手機推播。若要接作業系統通知或外部服務,需自行提供接收程式、權限與連線,並測試失敗回報。第一版只保留最少事件資訊,不將完整提示、工具或路徑送到第三方。

語法檢查只能確認 JavaScript 可解析,不會保證資料操作正確。例如把相等判斷改成不相等仍然是合法語法,但可能造成切換錯誤。因此這個 Hook 與 npm test 各自保留:前者提供快速回饋,後者驗證具體行為。

若改成格式化命令,先區分檢查模式與寫入模式。檢查模式只回報不符合規則的檔案,寫入模式會產生新差異;後者應限制在預期路徑,並避免與編輯器自動格式化互相觸發。驗收要包含原始差異是否被意外擴大。

通知也需要避免重複。對同一個未變化的錯誤,先保存最近一次狀態,再決定是否再次提醒;否則高頻通知容易被忽略。第一個範例先採最小本機紀錄,等你清楚事件頻率與內容後,再加入外部接收端。

本篇程式的人工輸入可以驗證 Node 邏輯,但只有在 Claude 工具事件後出現相應回饋,才是整合驗證。請在筆記中分別列出兩種結果,不把人工執行腳本成功當成所有平台的 Hook 都已測過。

失敗情況要能被看見

症狀可能原因下一步
沒有任何效果事件沒發生或 matcher 不符先查看原始事件與偵錯紀錄
JSON 解析失敗stdout 混入其他文字成功回饋只輸出一個 JSON 物件
每次操作都等很久命令耗時或重複測試縮小檔案範圍並設定 timeout
看見提醒卻沒有測試結果提醒程式沒有跑測試另外執行 npm test 並保存輸出

程式退出碼一表示本範例腳本處理失敗;檢查發現問題則用結構化回饋。不要隨意改成退出碼二,因為不同事件對阻擋回應的處理不同。先理解事件語義,再設計是否要讓 Claude 繼續處理。

小練習是只啟用一個案例,完成成功、故意失敗與停用三次驗證,再加入下一個。移除設定中的對應 handler 後,確認事件不再觸發,最後再整理腳本。需要可手動呼叫的完整驗收流程,請搭配,避免讓高頻事件承擔過大的工作。

覺得這篇整理實用嗎?分享給需要的朋友

LINE 分享

回總目錄

  • 生活分享

    Claude Code|建立第一個 mod:在 Claude Code 行程內數工具呼叫

    寫一個三檔案的 mod,用驗證器與測試確認它掛上的事件。文件把 mod 定義成多了入口檔的 plugin:入口檔叫 hooks module,Claude Code 在事件發生時呼叫裡面的函式,函式可以觀察、改寫或接手事件。

  • 生活分享

    Claude Code|Git Worktree 平行工作

    隔離多個任務的檔案與分支。Git Worktree 讓同一儲存庫擁有多個工作目錄,各自使用分支與檔案。本篇會把待辦篩選與文件整理分開,確認兩個 session 不會直接改到彼此的檔案,再把其中一個成果整合回主分支。你也會知道何時可以安全清理工作目錄。

  • 生活分享

    Claude Code|雙 Worktree 實作與衝突整合

    隔離兩項功能,最後完成整合與回歸。兩個 Claude 工作階段同時編輯專案,最容易出現的問題是互相改到同一份檔案,或各自測試通過、整合後卻失敗。本篇用兩個 Worktree 分別處理篩選預設值與介面文字,故意製造一次小衝突,再完成整合、驗證與清理。你不需要先啟用 Agent Teams。

  • 生活分享

    Claude Code|比較流程品質、用量與執行時間

    以同一資料集比較兩種工作方法。比較兩種 Claude 工作方法時,不能只挑成功那一次,也不能只看第一個答案有多快。本篇用固定案例、原始紀錄和一致判準,比較品質、重試、等待與人工整合時間,最後寫出有樣本數與限制的報告,而不是保證某個方法一定省錢。

資料來源

本文依據上方所列參考來源與標示之核對日期整理;票價、時刻、功能規格或服務條款可能變動,出發、預訂或購買前請至相關官方網站確認最新資訊。

生活分享