跳到主要內容
maxstudioNews
AI 自動化DEV Community (Codex)約 8 分鐘

強化 AI 程式碼助手:Hooks 如何強制執行規則

這篇文章探討了如何在 Claude Code、Cursor 和 Codex 等 AI 程式碼助手中,利用「Hooks」來強制執行規則。Hooks 能夠在特定時機(例如執行 Shell 指令前或檔案編輯後)自動觸發,確保 AI 代理遵循關鍵規範。透過 Hooks,開發者可以彌補傳統指令或提示詞的不足,有效阻擋危險操作、自動格式化程式碼,並在檢查失敗時阻止代理完成任務。

強化 AI 程式碼助手:Hooks 如何強制執行規則
圖片來源:DEV Community (Codex)

這篇文章最初發表於 KitQuarry,由 Eliran Kotzero 撰寫。簡而言之,規則是要求 AI 代理執行某項任務,而掛鉤(Hooks)則是讓工具強制執行該任務。Claude Code、Cursor 和 Codex 等工具都會在固定時間點執行你的腳本,例如在 Shell 指令執行前、檔案編輯後,以及當 AI 代理準備停止時。

這正是「絕不強制推送(force-push)」、「自動格式化所有內容」和「在完成前先執行測試」等規範應用的地方。

為何光靠規則還不夠?指令檔案僅提供上下文情境。Claude Code 的權限文件明確指出:「權限規則由 Claude Code 強制執行,而非模型本身。你在提示詞或 CLAUDE.md 中提供的指令,僅影響 Claude 嘗試執行的內容,但不會改變 Claude Code 允許執行的範圍。」過長或內容擁擠的規則檔案只會讓情況更糟。

Hooks 則是另一半的解決方案。Claude Code 的 Hooks 指南將其描述為「確定性控制:某些動作總是會發生,而非依賴大型語言模型(LLM)自行選擇是否執行。」因此,你可以將規則作為說明,並為那些必須每次都發生的關鍵事項添加 Hooks,例如:在指令執行前阻擋它(如強制推送、reset --hard、DROP TABLE 等危險操作);在編輯後進行修正(執行格式化工具,確保程式碼風格在審查中不會成為問題);以及在檢查失敗時拒絕「完成」指令,並讓 AI 代理繼續工作。

這三種工具都支援相同的三種 Hooks:在 Shell 指令執行前、在 AI 代理編輯檔案後,以及在 AI 代理準備停止時。在 Claude Code 和 Codex 中,指令執行前的 Hook 稱為 PreToolUse 並搭配 Bash 匹配器;Cursor 則使用 beforeShellExecution。

檔案編輯後的 Hook 在 Claude Code 中是 PostToolUse 搭配 Edit 或 Write 匹配器,Cursor 是 afterFileEdit,Codex 則是 PostToolUse 搭配 apply_patch。當 AI 代理準備停止時,三者都使用 Stop Hook。

若要阻擋操作,Claude Code 和 Codex 可以透過腳本以 Exit 2 結束並在標準錯誤輸出(stderr)中提供原因,或回傳 JSON 格式的 permissionDecision。Cursor 則需回傳 JSON 格式的 {"permission": "deny"} 或以 exit 2 結束。

若要讓 AI 代理繼續工作,Claude Code 和 Codex 的 Stop Hook 應以 Exit 2 結束(這會成為新的提示詞),而 Cursor 則需回傳 followup_message。

Codex 的 Hook 格式與 Claude Code 相似,兩者都使用相同的核心事件名稱、匹配器(matcher)與 Hooks 的巢狀結構,以及相同的 hookSpecificOutput JSON 格式。Cursor 則採用較扁平的格式,但它也能讀取 Claude Code 的 Hooks 設定。

Hooks 的儲存位置與執行時機:專案層級的 Hooks 檔案在 Claude Code 是 .claude/settings.json(個人使用可為 .claude/settings.local.json),Cursor 是 .cursor/hooks.json,Codex 則是 .codex/hooks.json 或 .codex/config.toml 中的 [hooks] 區塊。個人層級的 Hooks 檔案則通常位於使用者主目錄下。

Hooks 的執行時機也有所不同:互動式會話(interactive sessions)會暫停 Hooks 執行,直到你接受工作區信任對話框。使用 -p 或 SDK 執行的情況會將資料夾視為受信任。專案 Hooks 僅在受信任的工作區中執行,且你需要透過 /hooks 介面審查並信任每個 Hook。

若 Hook 內容有變更,則會被跳過,直到你再次信任它。你可以透過 /hooks(唯讀)或 Cursor 的「Customize」標籤頁中的「Hooks」輸出通道來查看已載入的 Hooks。若要關閉 Hooks,Claude Code 支援 "disableAllHooks": true,Cursor 則需移除相關條目,Codex 則可在 [features] 下設定 hooks = false 或在 /hooks 中單獨停用。

這三種工具都會合併來自所有層級的 Hooks,而非讓一個檔案取代另一個,因此個人設定的 Hook 和專案 Hook 若針對同一事件,將會同時執行。Hooks 會以你的使用者權限執行,所以在使用你未編寫的儲存庫時,務必在信任前仔細閱讀其中的 Hooks。Claude Code 的文件也警告,使用 claude -p 指令會直接執行儲存庫中已提交的 Hooks,而不會徵求你的同意。

設定:一個腳本資料夾,三個小型設定檔。將腳本放在儲存庫中,但不要放在任何單一工具的專屬資料夾內,這樣所有三種工具和你的團隊成員都能使用相同的程式碼:scripts/agent-hooks/guard_commands.py 用於 Shell 指令前、scripts/agent-hooks/format_edited.py 用於檔案編輯後,以及 scripts/agent-hooks/require_checks.py 用於 AI 代理準備停止時。

每個腳本都會從標準輸入(stdin)讀取事件 JSON,並判斷是哪個工具呼叫了它。Cursor 會在每個 Hook 中傳送 cursor_version 欄位並預期回傳 JSON;Claude Code 和 Codex 則接受 exit code 2 並在標準錯誤輸出(stderr)中提供原因。這些腳本僅需要 Python 3 和 Git。

Hook 1:阻擋危險指令 (guard_commands.py)

這個腳本會在 &&、||、; 和管道符號處分割命令列,因此像 cd src && rm -rf ../.. 這樣的指令也會被攔截。它會阻擋強制推送(但不包含 --force-with-lease)、reset --hard、clean -f、--no-verify、SQL 中的 DROP 或 TRUNCATE、將下載內容直接導向 Shell 執行,以及遞迴刪除根目錄 /、家目錄 ~、變數 $VAR、上層目錄 ..、當前目錄 . 或所有檔案 * 等危險操作。

然而,rm -rf node_modules dist 這樣的指令仍可執行。當指令被阻擋時,訊息會指示 AI 代理停止並詢問使用者,而非僅僅顯示「已阻擋」而讓代理嘗試其他方法。你可以編輯 PATTERNS 變數來匹配你自己的禁止清單。

在 Claude Code 的設定中,一個以 exit 2 結束的 Hook 會在權限規則檢查之前就阻擋該呼叫,因此即使你全面允許 Bash 指令,這個防護措施依然有效。反之則不然:Hook 無法批准被拒絕(deny)或詢問(ask)規則攔截的呼叫。

Claude Code 也提供 if 欄位(例如 "Bash(git *)")來跳過與不相關指令的腳本生成,但其文件指出該過濾器僅為「盡力而為」,因此上述腳本會自行檢查每個指令。

在 Cursor 的設定中,failClosed: true 會在腳本崩潰或逾時時阻擋指令。若沒有此設定,Cursor 將會放行該指令。對於未被阻擋的指令,腳本會回傳 allow,如同 Cursor 官方的 block-git.sh 範例所示。

然而,這並不會自動批准任何操作:Cursor 團隊成員已在 2026 年 3 月的論壇中證實,目前這些 Hooks 只會強制執行 deny,而 allow 和 ask 則會被忽略,因此你正常的批准設定仍然適用。務必只依賴 deny 規則。

Codex 的文件建議從 Git 根目錄解析儲存庫本地的 Hook 路徑,因為 Codex 可能會從子資料夾啟動。^Bash$ 匹配器涵蓋了 Shell 指令與統一執行會話(unified exec sessions)。在添加檔案後,請務必開啟 /hooks 並信任這些 Hooks,否則它們將不會執行。

Hook 2:格式化 AI 代理編輯的內容 (format_edited.py)

scripts/agent-hooks/format_edited.py 腳本會對編輯過的檔案執行 Prettier(從儲存庫的 node_modules 中取得)、ruff format 或 gofmt,並跳過任何未安裝的格式化工具。

你可以修改 FORMATTERS 變數以符合你的技術棧。這個腳本會從事件資料中取得檔案路徑。對於 Claude Code 的 Edit/Write 和 Cursor 的 afterFileEdit 事件,它會直接取得檔案名稱;而對於 Codex 的 apply_patch 事件,由於它不提供檔案名稱,腳本會改為格式化所有已修改或新增的檔案。

Share

覺得值得一看?分享給朋友。

以上為 AI 自動翻譯導讀。原文版權歸 DEV Community (Codex) 所有, 建議透過「閱讀原文」前往原始網站,以取得最完整資訊並支持原作者。

Newsletter

不用每天追,AI 重點每週寄給你

43 個來源、每 2 小時更新,太多看不完。電子報每週挑最值得看的幾則,附上 Max 的看法。

每週一封。Email 只用來寄電子報,每封信都能一鍵退訂。