HOOK FIELD MANUAL
返回學習歷程
LOCAL FIRST

CLAUDE CODE · PRACTICAL SETUP

把重複提醒，換成會準時出現的規則。

這份手冊不會替你寫入任何設定，也不會執行任何命令。它只把 Hook 的判斷、設定與驗證流程拆開，讓你能看懂後再安全地套用到自己的工作環境。

STEP 00 / CHOOSE THE RIGHT TOOL

先把三種情況分清楚。

Hook 適合固定時機、必須重複執行的規則。它不是拿來取代每一段提示文字，也不是把每一個習慣都自動化。

目前焦點：Hook。 當一個動作必須在固定時機執行，而且不能靠模型自己記得，就適合做成 Hook。

下一步： 先選擇這條規則的設定範圍，再從情境模板開始調整。

STEP 01 / SETTINGS SCOPE

決定這條規則要留在哪裡。

設定位置決定誰會讀到它，以及它是否應該被提交到版本控制。先選範圍，再複製 JSON，避免把個人路徑帶進團隊專案。

目前建議位置.claude/settings.json：適合希望團隊共同維護的 Hook。

CONCEPT MAP / LIFECYCLE

Hook 的四段式流程。

設定不是一段魔法文字。每一次觸發都有清楚的順序：先決定時間點，再過濾目標，最後交給適合的 handler 處理。

點選任一節點可查看它在設定器裡對應的欄位與實務提醒。

目前焦點：Event。 Event 對應下方設定器的 Event 欄，先決定觸發時機。

STEP 02 TO 04 / CONFIGURATOR

從工作情境產生最小設定。

選擇一個範例，再依你的工具與環境調整。

選擇工作情境

`matcher` 是單一、大小寫敏感的字串。例如 `Bash` 或 `Edit|Write`，不是 JSON 陣列。

command 必填欄位

使用可重複執行的指令碼。Hook 事件 JSON 會透過 stdin 傳入。

使用 `args` 時會採 exec form；在 Windows 上請讓 `command` 指向真正可執行檔，例如 `node`，再把指令碼路徑放進 `args`。

目前產生的設定 JSON

這段 JSON 只定義「何時呼叫哪一種 handler」。它不會替你建立指令碼、不會檢查秘密，也不會在這台電腦上安裝任何規則。Handler 是教學上的名稱；正式 JSON 會將它寫入內層 `hooks` 陣列，並以 `type` 表示。

REFERENCE / HANDLER FIELDS

每一種 handler 都有自己的必要欄位。

Hook 的觸發時機是固定的，但 handler 的工作方式不同。不要把 `command` 複製到所有類型，也不要假設每個 Event 都支援全部類型。

command

使用 `command`。可加 `args` 或 `shell`。適合可測試、可重複執行的規則。

http

使用 `url`。事件 JSON 會以 POST 傳送。需先確認 allowlist 與安全邊界。

mcp_tool

使用 `server`、`tool`，可加 `input`。server 必須已連線。

prompt

使用 `prompt`。觸發是固定的，判斷仍由模型完成。

agent

使用 `prompt`，可加 `timeout`。功能為實驗性，適合需要讀檔或跑測試的驗證。

CONCEPT MAP / SAFETY GATE

安全規則要能說清楚「過」或「不過」。

最適合做成 Hook 的防呆，通常有一個可測試的條件。下面是提交前敏感資料檢查的安全分流示意。

這裡只展示決策方式。正式的防護腳本仍需要你在本機建立、測試並納入對應設定。

SIMULATION OUTPUT 等待選擇結果

選擇 Block 或 Allow，查看 Hook 會回報什麼。此頁不讀取專案、不掃描檔案，也不執行提交。

模擬結果，不代表已在電腦上安裝或驗證任何 Hook。

CONCEPT MAP / VERIFICATION LOOP

規則寫完，還要走過一次驗證迴圈。

不要直接相信設定檔看起來合理。從低風險範例開始，確認 Hook 被載入、條件有命中、放行與攔截都符合預期，再擴大範圍。

檢查設定位置： 用 `/hooks` 確認設定已被載入。常見錯誤是把檔案放在不符合預期範圍的位置。

  1. 01
  2. 02
  3. 03
  4. 04

本頁驗收清單：0 / 4 已勾選。重新整理後會清空。

Stop Hook 的界線：先定義可驗證的放行條件，例如測試通過或檢查清單完成。若連續幾次都無法通過，應回報未完成項目與檢查輸出，交由人決定下一步；不要讓阻擋機制變成無限循環。

BOUNDARY / PORTABILITY

不要把格式相像，當成機制相同。

這份設定器只產生 Claude Code 範例。Cursor 與 Codex 的 Hook 機制、設定位置與事件名稱可能不同，不要直接複製 Claude Code 的設定。先依你正在使用的版本查官方文件，再建立實際規則。