八個令 AI Agent 穩定運行嘅 Hook

CLAUDE.md 本質上係一份建議。你寫「提交前跑 Prettier」，Agent 大概有三成機率唔跟。指令寫得更精確都冇用。八成服從率唔係模型質素問題，而係將規則放入 context window 然後靠模型自律呢個結構本身嘅限制。

Hook 係另一個層次嘅東西。Hook 係腳本，會喺特定生命週期點自動執行，唔管模型決定點做。PreToolUse 係喺 Agent 修改檔案或者執行指令之前觸發。PostToolUse 係之後觸發。模型唔可以選擇要唔要跑，Hook 就係會跑。

實際效果係即刻見到嘅。喺 CLAUDE.md 加十行規則，同喺 .claude/settings.json 加一個 Hook，係完全唔同性質嘅介入。Exit code 2 會即時攔截 Agent 動作。Exit code 0 放行。其他 exit code 會記錄警告但唔阻擋。因為 Hook 係放喺 settings.json 入面，commit 一次之後整個團隊透過 git 就拿到同一套設定。

執行前嘅四道守衞

我跑 Hook 超過六個月，以下四個 PreToolUse Hook 喺每個項目都冇被刪過。

攔截危險指令 透過正則表達式比對 rm -rf、git reset --hard、DROP TABLE 等破壞性模式，然後回傳 exit code 2，喺動作發生之前直接殺掉。試過親眼見到 Agent 嘗試對唔應該碰嘅目錄跑 rm -rf。冇呢個 Hook，後果係真實嘅。

保護敏感檔案 攔截任何對 .env、package-lock.json、*.pem 同類檔案嘅修改嘗試。Agent 根本冇機會覆蓋你嘅 lock file 或者將憑證洩露進 commit 入面。

PR 前要求測試通過 將拉取請求嘅建立鎖定喺測試通過之後。matcher 設定到 mcp__github__create_pull_request，Agent 就真係冇辦法喺測試未過之前開 PR。「後補修測試」呢個說法從此消失。

記錄每一條指令 將 Agent 執行嘅每一條 bash 指令連時間戳一齊寫入 .claude/command-log.txt。三日後發現咩地方唔妥，可以逐步追返發生過咩事。

執行後嘅三個審查員

PostToolUse Hook 係喺 Agent 修改完檔案之後即刻跑。我將三個串聯起嚟按順序執行。

自動格式化 喺每個改過嘅檔案跑 Prettier。Python 項目換成 Black，Go 項目換 gofmt。不管 Agent 有冇記得格式化，格式化工具都會跑。

自動 Lint 格式化完之後即刻跑 ESLint。如果 ESLint 發現錯誤，Agent 喺同一個 turn 入面就會見到並修正。到人類代碼審查嗰陣，lint 問題數量趨近於零。

自動測試 每次檔案有改動之後跑對應嘅測試套件。測試失敗嘅話，Agent 幾秒之內就知道並嘗試修正。我將輸出用 tail -5 過濾，只保留摘要，避免測試輸出塞滿 context window。

順序係有意義嘅。先 Prettier，然後 ESLint，然後測試。到人類睇到代碼嗰陣，格式化同 lint 已經通過咗。Code review 裡面嘅風格評論基本上消失。

Agent 停下時保住工作成果

一個 Stop Hook 處理呢件事：自動 Commit 每次 Agent 完成一個回應就跑 git add -A && git commit。每個工作單元有自己嘅 commit。兩個任務唔會混進同一個 commit 入面。

配合 git worktree 用，就可以喺功能分支上得到自動嘅 per-branch commit。Agent 崩潰或者你中途打斷佢，上一段工作成果唔會丟失。

冇咁順滑嘅地方

Hook 串聯聽起嚟好優雅，但係調試一條出問題嘅鏈比調試單一腳本難得多。有一次自動測試 Hook 靜靜地失敗，原因係新項目入面冇裝測試運行器，我花咗一個鐘追查點解 Agent 一直在生成未經測試嘅代碼。呢個 Hook 回傳 exit code 0（通過），因為測試腳本本身搵唔到，shell 將「command not found」當作非阻塞狀況處理。之後我加咗一個顯式檢查，確認測試運行器存在先至執行。

效能係另一個限制。通常嘅擔憂係 Hook 多咗會拖慢速度，但問題唔係咁簡單。真正嘅問題係每個獨立 Hook 係咪可以喺 200 毫秒以內完成。Prettier 喺單個檔案上大概跑 50ms。ESLint 大概 80ms。測試因項目而異，但範圍縮到受影響嘅檔案就可以保持快速。如果任何一個 Hook 超過一秒，Agent 嘅反饋迴圈就會開始感覺遲頓。

點解呢套做法成立

OpenAI 嘅 Harness 工程博客提過一點：Agent 喺嚴格邊界同可預測結構入面工作得最好。React 嘅設計哲學對組件講嘅嘢係一樣嘅：有定義好生命週期階段同狀態嘅可組合單元。

Claude Code 嘅 Hook 跟從相同嘅抽象。State 對應 session 同 memory。Hook 係喺生命週期邊界介入嘅函數。PreToolUse 劃定邊界。PostToolUse 令結構可預測。Stop 保住結果。

之前喺 CLAUDE.md 入面嘅「跑 Prettier」呢行，我已經刪咗。Hook 每次都會跑，唔使叫佢。