事件
生命週期的觸發點，例如 SessionStart、PreToolUse、PostToolUse、Stop。
Agent 工作流程／掛鉤
讓規則
真的發生。
掛鉤 把反覆提醒 代理 的工作，改成固定時機、固定範圍、固定回應的系統規則。它不取代人，而是把容易忘記的邊界守住。
這份實作採安全預設：不自動刪除、提交、發布或傳送資料；每個阻擋與提醒都能被檢查、停用與修改。
確定性規則被觸發就會執行，不依模型是否剛好記得。
窄範圍用 比對條件 限制時機，避免每個動作都被慢檢查拖住。
可回復先用提醒與阻擋，不做自動修復；有問題可直接停用。
基礎
先懂四個元件，
再裝任何 掛鉤。
一個好 掛鉤 不是「功能很多」，而是只在必要時做一件可預測的事，並且知道什麼時候不該繼續。
比對條件
縮小範圍，例如只匹配 Bash，或只在 Edit／Write 後處理。
處理程序
真正執行的本機命令；讀 JSON、輸出判斷或補充上下文。
停止規則
明確放行、拒絕或交給人工，避免自動化變成無限循環。
平台差異
Claude Code 與 Codex：
概念相同，設定不能照抄。
兩者都把 掛鉤 組成 事件 → 比對條件 → 處理程序，但可用事件與 處理程序 能力不同；設定前要以官方文件為準。
Claude Code
掛鉤 可設在個人、專案或外掛層級。Command、HTTP、MCP tool、Prompt 與 Agent handler 的能力較完整。
- 個人層：
~/.claude/settings.json - 適合：安全攔截、技能載入、深度品質判斷
- 注意：所有符合的 掛鉤 可能平行執行
Codex
目前實際執行的是 Command 處理程序；設定可放在 ~/.codex/hooks.json 或 config。改過的命令 掛鉤 要由使用者在 /hooks 介面信任。
- 適合：本機規則、驗證、記憶與安全邊界
- 注意：非受管 掛鉤 要先審閱，不應繞過信任流程
- 同一事件多個命令可平行啟動
本次採用的做法：共用一支只有本機、無外部網路連線的 處理程序，分別在 Claude Code 與 Codex 的設定中呼叫；既有 掛鉤 一律保留，不用整份設定覆寫。
掛鉤 實戰大全
15 個常用情境，
從守住邊界開始。
公開內容未列出付費資料中的原始 15 項清單。以下是依公開方法、兩個示範案例與官方支援能力整理的可安全落地版本。
啟動與提問
讓每次開始都有共同基準01SessionStart
專案範圍校正
新對話或恢復時，提醒 代理 先讀專案指示、辨認工作區與驗證方式。
邊界：只補充上下文，不掃描或上傳專案內容。
02SessionStart
工作前置檢查
先找既有規則、測試命令與未完成工作，避免一開始就改檔。
邊界：只要求盤點；是否動手仍由任務決定。
03UserPromptSubmit
隱私資料提醒
送出 提示詞 時提醒不要貼 API 金鑰、Cookie、密碼、私鑰或 .env 原文。
邊界：需要值時只請使用者提供遮罩後資訊。
04UserPromptSubmit
技能與討論路由
遇到產品決策、設計選擇或過去決定，提醒先走討論或大腦查詢流程。
邊界：不替使用者做未確認的高影響決策。
工具使用前
在做出不可逆動作前攔一下05PreToolUse
危險 Git 指令攔截
在 Bash 執行前阻擋 git reset --hard、強制 推送、破壞性 清理 等高風險指令。
邊界：不自動改成別的指令；交回人工確認。
06PreToolUse
秘密檔案保護
嘗試讀寫或列印 .env、私鑰、憑證檔時直接拒絕，避免被 代理 帶入輸出。
邊界：不取代金鑰管理；只減少誤觸。
07PreToolUse
全域設定變更提示
修改 Claude、Codex 或共用 掛鉤 設定前，提醒保留原設定、採結構化合併並在後面驗證語法。
邊界：不擅自覆寫整份設定檔。
工具使用後
在小範圍內補一個最小驗收08PostToolUse
程式碼驗證提醒
編輯程式後要求跑最小的 語法檢查、單元測試或 建置，不把「已修改」當成「已完成」。
邊界：不強迫每次改一行就跑昂貴全量測試。
09PostToolUse
UI 與手機可讀性
改 HTML、CSS 或前端檔後，提醒確認對比、文字溢位、圖片 alt 與桌機／手機排版。
邊界：以截圖或瀏覽器檢查為證，不憑感覺宣稱完成。
10PostToolUse
公開內容來源檢查
教材、文章與公開頁改動後，提醒保留來源、區分原始事實與自己的整理。
邊界：不把未驗證的推測寫成事實。
收尾、壓縮與協作
讓 代理 知道何時停、怎麼交接11停止
完成前驗證
每輪準備結束時，要求回報改了什麼、驗證了什麼、還有哪些測試沒跑。
邊界：不把未執行的測試說成通過。
12停止
發布前人工關卡
部署、公開發文、寄信、發訊息與上架都要有當前任務中的明確同意。
邊界：掛鉤 不自動發布，也不取代人工判斷。
13PreCompact
長對話交接摘要
壓縮上下文前保留目標、已同意決策、變動檔案、驗證狀態與未解風險。
邊界：不把原始私密對話、憑證或暫存資料放入摘要。
14SubagentStart
子 代理 工作簡報
任務開始時補上範圍、來源要求、不可碰的檔案與回報格式，避免子任務越界。
邊界：子 代理 沒有額外的發布或刪除權限。
15SubagentStop
子 代理 成果驗收
結束前要求明確列出假設、來源與驗證證據；耐久但非敏感的經驗才可送進大腦待審。
邊界：不把 原始對話、token、cookie 或私有資料存進大腦。
兩個可直接使用的模式
先裝這兩種，
最容易看見價值。
第一種處理不可逆風險；第二種守住公開內容品質。兩者都比「自動幫你修」更適合作為第一個 掛鉤。
模式 01
危險指令先停住
事件選 PreToolUse，比對條件 只指向 Bash；處理程序 只比對少數高風險模式，命中就回傳 deny。
觸發：PreToolUse / Bash
比對：git reset --hard、git push --force、rm -rf / 或 ~
回應：deny + 說明原因
停止：交由人確認，不改寫指令模式 02
公開文章品質閘門
在 Stop 時檢查這輪是否改過教學或文章；若要深度檢查，設定最多重試次數，避免同一輪一直卡住。
觸發：Stop
範圍：本輪修改的公開內容
檢查：來源、隱私、語氣、版面
停止：連續失敗到上限後交回人工安裝與驗證
設定順序比數量重要。
任何新的 command 掛鉤 都是本機程式。先檢查內容、再接設定、再用模擬 JSON 驗證；不使用跳過信任的危險參數。
先用一個窄 比對條件 與無副作用的提醒開始。
用代表性的 JSON payload 模擬「命中」與「不命中」。
驗證 JSON／TOML 語法；Codex 再從 /hooks 審閱並信任命令。
一週後檢視是否真的有幫助；太吵或太慢就縮小 比對條件 或停用。
資料說明與來源
本頁根據公開來源整理；教學內容不含付費頁面或未公開清單。15 個情境是可實作的安全版本，不主張與外部付費資料逐字相同。
- Claude Code 必學設定 掛鉤，完整教學一次搞懂，Gary Chen，2026-08-16。
- Claude Code 掛鉤 官方文件。
- OpenAI Codex 掛鉤 官方文件。
- 本機實作範圍：只使用本機 command 處理程序；不安裝外部套件、不啟動常駐服務、不外傳資料。