生活分享

Claude Code|只處理變更檔案的格式化 Hook

限制格式化範圍並避免事件重複執行。格式化 Hook 如果每次都掃描整個專案,可能改到與任務無關的檔案。本篇只處理 Write 或 Edit 剛完成的 JSON 練習檔,檢查路徑、解析內容,再在有必要時寫回。你會用連續重播確認第二次不再產生變更,也會驗證失敗時原始資料仍保留。

閱讀時間約 7 分鐘

LINE 分享
只處理變更檔案的格式化 Hook:文件、螢幕與完成記號的幾何插圖
圖片:Mokaair (© Mokaair)
本篇目錄
  1. 1. 明確限制會改動的檔案
  2. 2. 準備能看出差異的輸入
  3. 3. 重播兩次,驗證冪等性
  4. 4. 接到實際 PostToolUse 事件
  5. 5. 故障一:JSON 損壞
  6. 6. 故障二:路徑或檔案類型不符合
  7. 7. 避免格式工具把無關檔案一起改掉
  8. 8. 停用與完成判準

格式化 Hook 如果每次都掃描整個專案,可能改到與任務無關的檔案。本篇只處理 Write 或 Edit 剛完成的 JSON 練習檔,檢查路徑、解析內容,再在有必要時寫回。你會用連續重播確認第二次不再產生變更,也會驗證失敗時原始資料仍保留。

先讀與。下載第 74 篇材料,在 starter 操作。需要 Node.js 22 以上;離線重播不需 Claude 帳號,真實觸發另需登入。閱讀約 20 分鐘,練習約 45 分鐘。

明確限制會改動的檔案

明確限制會改動的檔案 → 準備能看出差異的輸入 → 重播兩次,驗證冪等性
明確限制會改動的檔案 → 準備能看出差異的輸入 → 重播兩次,驗證冪等性 · 圖片:Mokaair (© Mokaair)
閱讀完整文字說明

只處理變更檔案的格式化 Hook,以流程和文件圖形呈現教學重點。

本篇只接受練習目錄內 fixtures 下、副檔名為 .json 的實際檔案。事件必須是 PostToolUse,表示工具操作已完成。這個 Hook 不掃描其他 JSON,不格式化 JavaScript,也不碰 package-lock.json。範圍越清楚,越容易驗證格式化沒有造成額外變更。

材料的 hooks/format-json.mjs 先讀事件,再用 boundary.mjs 解析真正路徑,最後檢查相對位置。確認條件後才讀檔並 JSON.parse。這與拿到 file_path 就直接拼成一段格式化命令不同;本課不把事件資料當成 shell 程式碼。

JSON 格式化也不能用「把多個空白換成一個」這類文字替換。字串內容可能真的需要連續空白,像是地址、程式片段或使用者文字。必須先解析資料,再序列化成固定縮排,才能保留字串值的意義。此方法可能調整表面排版,但不應改變解析後的資料。

準備能看出差異的輸入

在 fixtures/demo.json 寫入一行壓縮 JSON,字串刻意保留兩個空白,另加一個陣列。先複製這個原始內容到不會被 Hook 處理的筆記,稍後才能比較。材料的 post-edit.json 指向 fixtures/demo.json,請核對事件內容與實際檔案相符。

寫入 fixtures/demo.json · json
{"title":"保留  兩個空白","items":[1,2,3]}
寫入 fixtures/post-edit.json:離線事件材料 · json
{
  "hook_event_name": "PostToolUse",
  "tool_name": "Edit",
  "session_id": "lab-74",
  "tool_input": {"file_path": "fixtures/demo.json"}
}

這份 JSON 是手工建立的事件,不是 Claude 真的執行過 Edit 的紀錄。重播器會補上你目前的工作目錄,再把資料送入腳本。這讓你能先測函式與檔案處理,但不能據此宣稱 Hook 已被 Claude 載入。

重播兩次,驗證冪等性

先執行重播,預期 demo.json 變成兩格縮排、結尾保留換行。第二次再送入相同事件,檔案內容應完全相同。這種重複執行不造成額外效果的性質叫冪等性,對可能收到相同事件的自動化很有用。

專案終端機:兩次處理同一個事件 · text
node hooks/replay.mjs format-json fixtures/post-edit.json
node hooks/replay.mjs format-json fixtures/post-edit.json
node --test tests/hooks.test.mjs

不只看編輯器覺得排版一樣,還要比較內容或雜湊。測試會檢查重複處理後位元組沒有改變,以及 title 裡的兩個空白仍保留。若你的版本每次都改動結尾,或改壞字串內容,即使 JSON 還能解析,也沒有通過本篇判準。

若要使用真正格式化工具處理 JavaScript,先另外確認工具及專案設定,不要把這個 JSON 範例直接套到所有檔案。不同語言的註解、尾逗號與語法規則不同。JSON.parse 不支援的 JSONC,也不能當成一般 JSON 無聲覆寫。

接到實際 PostToolUse 事件

先保存既有 .claude/settings.json,再合併下方 hooks 欄位。matcher 只匹配 Write 與 Edit,腳本本身仍會檢查路徑與副檔名。設定外層條件和程式內層條件都要存在,因為離線重播或未來調整設定時,不能只靠其中一層假設輸入永遠正確。

寫入 .claude/settings.json:合併而非覆蓋其他設定 · json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [{"type": "command", "command": "node hooks/format-json.mjs", "timeout": 10}]
      }
    ]
  }
}

另開 Claude,要求只把 fixtures/demo.json 改成另一份壓縮 JSON。觀察原工具完成後的 Hook 紀錄,再讀檔確認排版。記錄實際事件、腳本退出狀態及最後檔案差異,不要只看模型說「已自動格式化」。

Hook 內的檔案寫入不是同一次 Claude Write 工具呼叫的原始內容。審查差異時應把工具修改與格式化造成的排版都算進最終結果。若需要復原,要另外檢查 Git 差異;不能把 PostToolUse 想成能撤回之前已完成的操作。

故障一:JSON 損壞

把 demo.json 最後的大括號刪掉,先保存這個故障版本的內容,再重播事件。預期腳本回報 JSON formatting failed,原始檔案維持不變。因為解析在寫入前完成,失敗不應把檔案清空或寫成部分結果。

本課把錯誤放進 PostToolUse 的 additionalContext,讓 Claude 知道格式化沒有完成;這不是 PreToolUse 的拒絕決定。主工具已經改過檔案,因此你還需要修復 JSON、重跑驗證,再確認結果。若只忽略訊息,下一步讀取仍會遇到壞資料。

不要自動「修好」任意不合法 JSON 再覆蓋原檔。缺括號可能容易猜,但缺少字串內容或數值時沒有唯一答案。讓錯誤可見並保留原始輸入,比產生一份看似能解析卻改變意思的資料更容易追查。

故障二:路徑或檔案類型不符合

把事件改成指向 model.js,重播後應不修改該檔;改成練習目錄外的專用假路徑,應得到邊界錯誤。用檔案雜湊比較前後結果,不能只因腳本沒有印東西就推定一切正常。沒有匹配目標與執行失敗是兩種不同結果。

案例預期檔案結果預期說明
合法 fixtures JSON固定排版且資料不變完成處理
第二次相同事件位元組不再改變冪等
損壞 JSON保留原始故障內容回報解析錯誤
JavaScript 檔案不修改不在處理範圍
界外路徑不讀寫界外檔案回報範圍錯誤

若資料夾或檔名包含中文與空格,先用重播器驗證,再做真實 Hook 觸發。程式能處理路徑不代表 shell 設定一定正確;可接續比較各環境。這份程式也不承諾能防止其他程序同時改動同一檔案,併發寫入需要另外設計。

避免格式工具把無關檔案一起改掉

格式化前後比較目標檔案的內容和修改清單。漂亮的 JSON 縮排只證明格式轉換成功,若其他檔案也被修改,仍不符合本課範圍。把處理目標限制在事件提供的單一檔案,並在執行前核對目錄與副檔名。

遇到無效 JSON 時保留原檔,回報解析失敗的位置,由使用者或後續修正流程處理。不要為了讓格式工具成功而自動刪除無法解析的片段,這可能改變資料意義。

停用與完成判準

停止本次 Hook 時,只移除自己加入的 PostToolUse 項目或恢復先前備份,再建立新工作階段確認沒有新的格式化觸發。保留 demo.json 與兩輪比較結果作為證據,不必刪除整個 .claude 目錄。若其他 Hook 仍在工作,確認來源再處理。

完成應有合法、重複、損壞、錯類型與界外路徑五種案例,以及至少一次實際 Claude 觸發紀錄。未登入時可以完成離線部分,但真實事件欄位要保持待測。小練習是加入一個陣列頂層 JSON,確認程式依資料格式處理,而不是只接受你第一次示範的物件形狀。

下一步可把格式化與分開:格式化整理已改檔案,品質檢查判斷測試結果,各自保存證據與失敗處理,避免一個事件腳本同時承擔所有任務。

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

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

資料來源

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

生活分享