戰(zhàn)：格式化、安全與測試的6個(gè)配置)
如果你已經(jīng)開始用 Claude Code 處理日常編碼任務(wù)大概率遇到過這樣的局面它寫得很快但改完的代碼格式化風(fēng)格跟項(xiàng)目規(guī)范完全不是一回事它偶爾會提出一個(gè)看起來很合理的 bash 命令但你沒仔細(xì)看就批準(zhǔn)了測試它也提可更多時(shí)候是建議你“自己跑一下試試”。這些問題不是模型能力不夠而是缺少一套強(qiáng)制性的機(jī)制在工具調(diào)用鏈路里卡點(diǎn)。Hooks 就是干這個(gè)的。這篇文章我會用 6 個(gè)可直接抄走的配置把代碼格式化、安全防護(hù)和自動(dòng)測試這三件事焊死在 Claude Code 的工作流里涵蓋 PreToolUse、PostToolUse、Stop、Notification 等觸發(fā)時(shí)機(jī)和完整腳本適合所有用 Claude Code 寫代碼、并且希望少一點(diǎn)失控感的人。先說清楚一件事hook 不是讓你在 prompt 里多寫幾行“請遵守項(xiàng)目規(guī)范”而是在 Claude 調(diào)用工具Bash、Edit、Write、Read的前后掛上外部腳本。腳本不滿足條件工具調(diào)用就直接被攔下。這種“硬約束”和“軟提示”的區(qū)別就是為什么很多人配置完 hooks 之后代碼合入 CI 的一次通過率明顯提升。1. Hooks 到底解決了什么問題先看三個(gè)最常見的失控現(xiàn)場1.1 失控現(xiàn)場一格式化規(guī)則全憑心情我用 Claude Code 做過一個(gè)小型 TypeScript 項(xiàng)目。模型默認(rèn)的代碼風(fēng)格跟項(xiàng)目里 prettier 配置不能說一模一樣只能說是各寫各的。單引號、雙引號混用對象末尾逗號時(shí)有時(shí)無縮進(jìn)偶爾從兩個(gè)空格跳成四個(gè)。最頭疼的是它每次 Edit 只改一小塊格式化問題被分散在十幾個(gè)文件里肉眼根本盯不過來。你可以在系統(tǒng)提示詞里寫“請始終使用項(xiàng)目 prettier 配置”但模型記不住每一條規(guī)則的細(xì)節(jié)更不會在每次寫入前主動(dòng)跑一遍格式化。等 CI 跑完報(bào)錯(cuò)再回頭修一個(gè)下午就沒了。Hooks 的正確姿勢是在文件落盤之后、或者寫入之前由外部腳本強(qiáng)制執(zhí)行 prettier不讓模型的“個(gè)人風(fēng)格”有機(jī)會進(jìn)入代碼庫。1.2 失控現(xiàn)場二危險(xiǎn)命令說跑就跑Claude Code 的 Bash 工具權(quán)限很大。它可能因?yàn)槟愕哪尘洹扒謇硪幌马?xiàng)目”就執(zhí)行rm -rf node_modules這還算可控但它也可能在改依賴時(shí)順手執(zhí)行npm install --unsafe-perm或者在你沒注意的時(shí)候往~/.bashrc里追加內(nèi)容。AI 沒有“這個(gè)操作影響范圍是否超出當(dāng)前項(xiàng)目”的常識它只有“用戶讓我完成目標(biāo)”的指令。我見過有人被 Claude 連續(xù)執(zhí)行了git push --force覆蓋遠(yuǎn)端提交也見過它在排查問題時(shí)把.env里的密鑰cat到了對話上下文里這些事后都很不好收拾。Bash 類的 hook 就是最后一道閘門命令在執(zhí)行前先過一遍規(guī)則命中風(fēng)險(xiǎn)項(xiàng)直接阻止并告訴 Claude 為什么不行。1.3 失控現(xiàn)場三測試永遠(yuǎn)“我建議你跑一下”另一個(gè)讓我比較無語的行為模式是Claude 改完代碼它的收尾往往是“測試已更新建議你運(yùn)行npm test驗(yàn)證”。如果你不追問它就當(dāng)你已經(jīng)跑過了。偶爾它會主動(dòng)跑但改一次跑一次全量測試幾分鐘就浪費(fèi)在等待上。自動(dòng)測試類的 hook 能解決兩個(gè)層面一是強(qiáng)制改完代碼后自動(dòng)觸發(fā)相關(guān)測試沒有通過就繼續(xù)修二是精準(zhǔn)不是所有變更都跑全量測試而是根據(jù)變更文件反推對應(yīng)的測試范圍。后面我會給出具體的實(shí)現(xiàn)思路。2. 開工前必讀settings.json 和 Hook 觸發(fā)機(jī)制的基礎(chǔ)2.1 配置文件放哪項(xiàng)目級與用戶級Claude Code 的 hooks 配置寫在settings.json里。項(xiàng)目級位置是.claude/settings.json用戶級位置是~/.claude/settings.json。項(xiàng)目級配置隨倉庫走適合團(tuán)隊(duì)統(tǒng)一約束用戶級配置只對本機(jī)生效適合放個(gè)人習(xí)慣類的 hook。我建議大部分自動(dòng)化規(guī)則放項(xiàng)目級這樣團(tuán)隊(duì)里任何人用 Claude Code 都會被同一套規(guī)則約束。需要說明的是項(xiàng)目級配置默認(rèn)情況下對協(xié)作者可見你最好在 README 里寫清楚每個(gè) hook 的用途免得別人 clone 項(xiàng)目后第一次跑被攔截腳本嚇一跳。2.2 六類事件與 matcher 匹配規(guī)則Hooks 的配置結(jié)構(gòu)大致是{ hooks: { PreToolUse: [ { matcher: Edit|Write, hooks: [ { type: command, command: node .claude/hooks/check-format.js } ] } ] } }PreToolUse是事件名表示“工具執(zhí)行之前”。官方支持的事件類型主要有這些事件名觸發(fā)時(shí)機(jī)典型用途PreToolUse工具調(diào)用前攔截危險(xiǎn)命令、檢查寫入內(nèi)容PostToolUse工具調(diào)用后格式化、Lint、自動(dòng)測試NotificationClaude 等待用戶確認(rèn)時(shí)桌面通知提醒StopClaude 回復(fù)生成完成運(yùn)行完整校驗(yàn)、輸出摘要SessionStart會話開始環(huán)境檢查、項(xiàng)目信息注入U(xiǎn)serPromptSubmit用戶提交提示詞時(shí)內(nèi)容過濾、追加上下文PreCompact上下文壓縮前保存任務(wù)進(jìn)度摘要matcher是一段正則表達(dá)式用來限定 hook 作用于哪些工具或哪些調(diào)用。比如Edit|Write表示匹配編輯文件和新建文件操作Bash表示匹配所有 bash 命令也可以寫成Bash\\(.*git.*\\)這類更精確的形態(tài)去匹配包含 git 的命令。2.3 退出碼、stdin JSON 與超時(shí)三個(gè)決定成敗的細(xì)節(jié)hook 命令執(zhí)行時(shí)Claude Code 會通過 stdin 傳入一段 JSON里面至少包含{ session_id: xxx, cwd: /home/user/project, hook_event_name: PreToolUse, tool_name: Bash, tool_input: { command: rm -rf node_modules } }腳本要做的就是讀取這段 JSON然后根據(jù)tool_input內(nèi)容決定返回什么退出碼。我這里約定退出碼0放行工具繼續(xù)執(zhí)行。退出碼2阻止工具執(zhí)行stdout 內(nèi)容會返回給 Claude讓它知道被攔的原因。其他非 0 退出碼表示 hook 自身出錯(cuò)Claude Code 會記錄 warning但不會強(qiáng)制阻止工具。所以攔截類邏輯務(wù)必用2。還有一個(gè)容易被忽略的是timeout。hook 命令默認(rèn)超時(shí)時(shí)間是 60 秒超過會被終止。如果你的自動(dòng)測試腳本可能要跑幾分鐘一定要在 hook 配置里顯式調(diào)大{ type: command, command: node .claude/hooks/run-tests.js, timeout: 120 }另外hook 腳本的 stdout 和 stderr 會被 Claude Code 捕獲并放進(jìn)模型上下文。這意味著你可以在腳本里輸出給模型看的提示信息但不要打印一堆無關(guān)日志否則會白白消耗 token還會干擾模型對工具調(diào)用結(jié)果的理解。3. 前兩個(gè)配置用 PreToolUse 和 PostToolUse 把格式化和 Lint 焊死在編輯動(dòng)作上3.1 配置一文件落盤后自動(dòng)格式化不用再跟模型強(qiáng)調(diào)“別用雙引號”這是我在所有項(xiàng)目里第一個(gè)配的 hook。先給結(jié)論用 PostToolUse 而不是 PreToolUse 做格式化。原因在于調(diào)用時(shí)序。PreToolUse 發(fā)生在 Claude 的 Edit/Write 工具真正寫入文件之前這時(shí)你拿到的file_path是目標(biāo)路徑但文件內(nèi)容還沒寫入或者寫入的是舊版本。如果你在這個(gè)時(shí)機(jī)去prettier --write格式化的是舊文件等 Edit 執(zhí)行完新內(nèi)容覆蓋上去格式化又被沖掉了。所以正確做法是 PostToolUse。腳本在 Edit/Write 完成后拿到文件路徑立刻執(zhí)行格式化命令#!/usr/bin/env node // .claude/hooks/format-on-write.js const fs require(fs); const { execSync } require(child_process); let input ; process.stdin.on(data, (chunk) (input chunk)); process.stdin.on(end, () { try { const payload JSON.parse(input); const filePath payload.tool_input?.file_path; if (!filePath) process.exit(0); const ext filePath.split(.).pop(); const supported [ts, tsx, js, jsx, json, css, md]; if (!supported.includes(ext)) process.exit(0); // 跳過 node_modules 和生成目錄 if (filePath.includes(node_modules) || filePath.includes(dist)) process.exit(0); execSync(npx prettier --write ${filePath}, { cwd: payload.cwd, stdio: pipe, }); console.log([format] ${filePath} 已按項(xiàng)目 prettier 配置格式化); process.exit(0); } catch (e) { // 格式化失敗不阻斷工具調(diào)用避免惡性循環(huán) console.error([format] 格式化失敗: ${e.message}); process.exit(0); } });配置代碼里注冊它{ hooks: { PostToolUse: [ { matcher: Edit|Write, hooks: [ { type: command, command: node .claude/hooks/format-on-write.js } ] } ] } }你可能會擔(dān)心一個(gè)問題格式化之后的文件內(nèi)容和 Claude 在上下文里看到的“剛寫入的內(nèi)容”不一致。實(shí)際影響不大因?yàn)?Claude 下次讀取文件時(shí)讀到的是格式化后的內(nèi)容它自然會基于這個(gè)版本繼續(xù)改。還有一個(gè)坑是 Windows 環(huán)境。npx prettier --write里的路徑如果有特殊字符引號轉(zhuǎn)義容易出問題。建議所有 hook 腳本都用 Node.js 寫避免直接依賴 bash 語法。后面所有示例我都用 Node。3.2 配置二Lint 結(jié)果自動(dòng)回流給模型從源頭減少“改完又錯(cuò)”的來回格式化解決的是風(fēng)格Lint 解決的是“代碼有沒有明顯問題”。我在這個(gè) hook 里跑的是 ESLint并且只針對 Claude 改過的文件不做全量掃描。#!/usr/bin/env node // .claude/hooks/lint-on-write.js const { execSync } require(child_process); let input ; process.stdin.on(data, (chunk) (input chunk)); process.stdin.on(end, () { try { const payload JSON.parse(input); const filePath payload.tool_input?.file_path; if (!filePath || filePath.includes(.test.)) process.exit(0); try { const out execSync( npx eslint ${filePath} --max-warnings0 --format compact, { cwd: payload.cwd, stdio: pipe } ).toString(); // 無錯(cuò)誤則靜默退出 process.exit(0); } catch (e) { const output e.stdout?.toString() || ; // 只輸出錯(cuò)誤摘要最多截取 1500 字符避免刷爆上下文 const summary output.split(\n).slice(0, 20).join(\n).slice(0, 1500); console.error([lint] ESLint 檢測到問題請修復(fù)后再繼續(xù): \n${summary}); process.exit(0); } } catch (e) { process.exit(0); } });注意這里我讓 exit code 保持 0沒有用 2 阻止寫入。為什么不攔截因?yàn)橛行?lint 錯(cuò)誤是結(jié)構(gòu)性的Claude 需要先寫入代碼、看到報(bào)錯(cuò)、再修復(fù)這是一個(gè)迭代過程。如果你在寫入時(shí)就把它攔住模型會陷入“不知道代碼哪里有問題”的困境。更好的做法是把錯(cuò)誤信息喂給它讓它自己判斷怎么改。--max-warnings0這參數(shù)很有用。它把 warning 也當(dāng)作 error 處理防止項(xiàng)目里積累一大堆“不痛不癢”的警告。對 Claude 這種大模型來說警告太多會稀釋注意力寧可讓 hook 直接暴露出來。有人會問eslint 的--fix能不能直接放在 PostToolUse 里自動(dòng)修可以但建議單獨(dú)跑。因?yàn)?-fix可能改出模型意料之外的結(jié)果尤其是一些涉及代碼結(jié)構(gòu)的規(guī)則。我的經(jīng)驗(yàn)是格式化可以自動(dòng)lint 修復(fù)盡量讓模型自己來否則它下次可能重復(fù)犯同樣的錯(cuò)。4. 中間兩個(gè)配置給 Bash 命令套上安全圍欄給寫入內(nèi)容加上敏感信息閘門4.1 配置三危險(xiǎn)命令黑名單 項(xiàng)目目錄白名單雙管齊下Bash hook 是整個(gè)安全體系里最重要的一環(huán)因?yàn)?Claude Code 的大多數(shù)破壞性操作都是通過 Bash 完成的。我的攔截腳本分兩層第一層是黑名單直接命中關(guān)鍵詞就阻止。這里列幾個(gè)我實(shí)測下來比較實(shí)用的規(guī)則const BLOCKED_PATTERNS [ /rm\s-rf\s\//, // 刪除根目錄 /rm\s-rf\s~/, // 刪除用戶目錄 /mkfs\./, // 格式化磁盤 /git\spush\s.*--force/, // 強(qiáng)推 /curl.*\|\s*(ba)?sh/, // curl 管道執(zhí)行腳本 /npm\sinstall\s-g\s.*--unsafe/, /chmod\s-R\s777/, /sudo/, ];第二層是白名單思路這個(gè)更重要。對rm、mv、chmod這類具有破壞性的命令我會校驗(yàn)?zāi)繕?biāo)路徑是否在項(xiàng)目目錄內(nèi)。路徑不在項(xiàng)目內(nèi)直接阻止。實(shí)現(xiàn)得并不復(fù)雜關(guān)鍵在于用 Node 的path.resolve把相對路徑轉(zhuǎn)成絕對路徑再做前綴比較。// .claude/hooks/guard-bash.js const path require(path); let input ; process.stdin.on(data, (chunk) (input chunk)); process.stdin.on(end, () { try { const payload JSON.parse(input); const command payload.tool_input?.command || ; const cwd payload.cwd; for (const pattern of BLOCKED_PATTERNS) { if (pattern.test(command)) { console.error([guard] 命令命中危險(xiǎn)規(guī)則: ${pattern}\n已阻止執(zhí)行。如果你確實(shí)需要執(zhí)行請手動(dòng)在終端操作。); process.exit(2); } } // 對 rm/mv 做路徑范圍檢查 if (/^(rm|mv|chmod)\b/.test(command)) { const unsafe command .split(/\s/) .filter((arg) arg.startsWith(/) || arg.startsWith(~) || arg.startsWith(../)) .some((arg) { const abs path.resolve(cwd, arg); return !abs.startsWith(path.resolve(cwd)); }); if (unsafe) { console.error([guard] 檢測到目標(biāo)路徑超出當(dāng)前項(xiàng)目目錄已阻止執(zhí)行。); process.exit(2); } } process.exit(0); } catch (e) { process.exit(0); } });這個(gè)腳本的思路是“默認(rèn)信任但有限制”。Claude 在項(xiàng)目里跑npm install、git diff、ls這類命令基本不受影響一旦碰到影響范圍超出項(xiàng)目的操作就會被攔截。exit 2的關(guān)鍵在于Claude 能看到 stderr 里的提示它會自己調(diào)整方案。我見過一個(gè)有意思的案例Claude 想把日志寫到/tmp/debug.log被這個(gè) hook 攔了。它看到提示后改為寫到項(xiàng)目下的.logs/debug.log還順手把.logs/加進(jìn)了.gitignore。這說明給模型一個(gè)“為什么不行”的反饋比單純阻止更有效。4.2 配置四敏感信息檢測防止密鑰被寫入代碼或進(jìn)入對話上下文Claude 在寫代碼時(shí)偶爾會“好心”把真實(shí)密鑰寫進(jìn).env文件旁邊或者在測試代碼里硬編碼一個(gè) API Key。更隱蔽的是它可能在排查問題時(shí)直接cat .env把密鑰讀進(jìn)上下文然后這些內(nèi)容就可能出現(xiàn)在日志里。敏感信息 hook 我配在 PreToolUse分別攔截兩類場景Edit/Write檢查tool_input.content和file_path如果發(fā)現(xiàn)密鑰特征阻止寫入。Bash檢查命令里是否有讀取敏感文件或把敏感信息寫入文件的操作。// .claude/hooks/guard-secrets.js const SENSITIVE_PATTERNS [ /sk-[A-Za-z0-9]{20,}/, // OpenAI / Anthropic 風(fēng)格 key /AKIA[0-9A-Z]{16}/, // AWS Access Key /ghp_[A-Za-z0-9]{36,}/, // GitHub Token /BEGIN (RSA|EC|OPENSSH) PRIVATE KEY/, // 私鑰塊 ]; const SENSITIVE_FILES [.env, .env.local, .pem, id_rsa, id_ed25519]; let input ; process.stdin.on(data, (chunk) (input chunk)); process.stdin.on(end, () { try { const payload JSON.parse(input); const tool payload.tool_name; const inputData payload.tool_input || {}; if (tool Edit || tool Write) { const content inputData.content || ; const filePath inputData.file_path || ; const fileBasename path.basename(filePath); if (SENSITIVE_FILES.includes(fileBasename) SENSITIVE_PATTERNS.some((p) p.test(content))) { console.error([guard] 檢測到疑似敏感信息被寫入已阻止。請改用環(huán)境變量或 .env.local 維護(hù)密鑰。); process.exit(2); } } if (tool Bash) { const command inputData.command || ; if (SENSITIVE_FILES.some((f) command.includes(cat ${f}) || command.includes(cat ./${f}))) { console.error([guard] 阻止讀取敏感文件避免密鑰進(jìn)入上下文。); process.exit(2); } } process.exit(0); } catch (e) { process.exit(0); } });這個(gè) hook 的難點(diǎn)在于誤報(bào)控制。比如.env里本身可以不寫密鑰只放配置項(xiàng)名稱項(xiàng)目文檔里也可能出現(xiàn)類似sk-xxx的示例占位符。解決方案是只攔截“文件路徑本身很敏感且內(nèi)容命中密鑰特征”的情況。普通代碼文件里出現(xiàn)sk-開頭的測試占位符我選擇放行因?yàn)槟呛芸赡苁?mock 數(shù)據(jù)。配好之后我建議你在測試環(huán)境故意觸發(fā)一次確認(rèn)攔截生效、模型能被正確引導(dǎo)。如果發(fā)現(xiàn)誤報(bào)就調(diào)整正則的嚴(yán)謹(jǐn)度不要因?yàn)椤皩幙刹粩r也不誤判”而把規(guī)則關(guān)掉安全這種事兒寧可多攔幾次。5. 最后兩個(gè)配置文件變更后自動(dòng)跑測試、任務(wù)完成時(shí)主動(dòng)提醒5.1 配置五PostToolUse 精準(zhǔn)觸發(fā)相關(guān)測試而不是傻等全量執(zhí)行自動(dòng)測試最簡單的實(shí)現(xiàn)是監(jiān)聽PostToolUse的Edit|Write事件文件一變就跑npm test。但全量測試在稍大一點(diǎn)的項(xiàng)目里可能要好幾分鐘Claude 每改一次文件就觸發(fā)一次交互體驗(yàn)會非常差。我采用的策略是根據(jù)文件路徑縮小范圍// .claude/hooks/test-on-change.js const { execSync } require(child_process); const path require(path); let input ; process.stdin.on(data, (chunk) (input chunk)); process.stdin.on(end, () { try { const payload JSON.parse(input); const filePath payload.tool_input?.file_path || ; const cwd payload.cwd; // 只對 src 下的業(yè)務(wù)代碼觸發(fā) if (!filePath.startsWith(src/)) process.exit(0); if (filePath.includes(.test.) || filePath.includes(.spec.)) { // 改動(dòng)的是測試文件直接跑這個(gè)測試 execSync(npx vitest run ${filePath} --reporterdot, { cwd, stdio: pipe, timeout: 60000, }); console.error([test] ${path.basename(filePath)} 測試通過); } else { // 改動(dòng)的是業(yè)務(wù)代碼跑相關(guān)測試 execSync(npx vitest run --changed --reporterdot, { cwd, stdio: pipe, timeout: 60000, }); console.error([test] 相關(guān)測試通過); } process.exit(0); } catch (e) { console.error([test] 相關(guān)測試失敗請查看上面的報(bào)錯(cuò)并修復(fù)\n${e.stdout?.toString().slice(0, 1000)}); process.exit(0); } });如果你用的測試框架不是 vitest思路完全一致Jest 可以用jest -o只跑發(fā)生變更的文件相關(guān)的測試其他框架可以通過 git diff 計(jì)算變更文件再傳給測試命令。這里有兩個(gè)細(xì)節(jié)值得說。一是timeout我給的是 60 秒因?yàn)闇y試命令本身要預(yù)留執(zhí)行時(shí)間如果你在 hook 配置里又設(shè)了一個(gè)更小的 timeout頂層的會先生效導(dǎo)致命令被提前 kill。所以建議兩處都設(shè)成一致。二是失敗時(shí)不要 exit 2。為什么因?yàn)闇y試失敗不代表代碼寫入是錯(cuò)誤的Claude 需要先完成這次工具調(diào)用、看到測試失敗的反饋然后進(jìn)行下一輪修復(fù)。如果我們把 exit 2 當(dāng)作“阻止工具執(zhí)行”相當(dāng)于 Claude 寫了一個(gè)代碼但因?yàn)闇y試沒過就不讓它寫這會陷入奇怪的狀態(tài)。測試 hook 的核心價(jià)值是“反饋”不是“阻斷”。每次測試失敗Claude 都會在下一輪嘗試修復(fù)直到通過。5.2 配置六Stop 和 Notification 事件把等待時(shí)間變成可控提醒最后兩個(gè)配置解決的是“人機(jī)協(xié)作時(shí)的通知”問題。用 Claude Code 時(shí)它經(jīng)常會停下來等人批準(zhǔn)一個(gè) bash 命令或者問一個(gè)問題這時(shí)候如果你切到別的窗口可能很久都不知道需要你確認(rèn)。Notification 事件能在這里觸發(fā)一個(gè)桌面通知。// .claude/hooks/notify-done.js let input ; process.stdin.on(data, (chunk) (input chunk)); process.stdin.on(end, () { try { const payload JSON.parse(input); const event payload.hook_event_name; const title event Notification ? Claude Code 需要確認(rèn) : Claude Code 待辦提醒; // macOS const { execSync } require(child_process); try { execSync(osascript -e display notification 請查看 Claude Code with title ${title}); } catch (e) { // Linux try { execSync(notify-send ${title} 請查看 Claude Code); } catch (_) {} } process.exit(0); } catch (e) { process.exit(0); } });注冊到 Notification 事件即可。至于 Stop 事件我把它用作“任務(wù)收尾檢查”。Claude 每次回復(fù)完成后這個(gè) hook 會檢查一下 git 狀態(tài)如果有未格式化的文件直接輸出提醒讓它主動(dòng)處理。// .claude/hooks/stop-check.js const { execSync } require(child_process); let input ; process.stdin.on(data, (chunk) (input chunk)); process.stdin.on(end, () { try { const payload JSON.parse(input); const cwd payload.cwd; const changed execSync(git status --porcelain, { cwd, stdio: pipe }).toString(); const unformatted changed .split(\n) .filter((line) /\.(ts|js|tsx|jsx|json|css|md)$/.test(line) line.startsWith( M )); if (unformatted.length 0) { console.error( [check] 以下文件有修改但可能未格式化如果確認(rèn)已完成所有任務(wù)請運(yùn)行 prettier --write 處理\n${unformatted.slice(0, 5).join(\n)} ); } process.exit(0); } catch (e) { process.exit(0); } });這個(gè) hook 不會阻止任何操作只是提供一個(gè)“事后提醒”。它的價(jià)值在于解決 Claude 的“總覺得自己干完了”問題——每次回復(fù)完它都能看到還有哪些代碼處于臟狀態(tài)從而決定是否繼續(xù)收拾。6. 完整配置匯總與排錯(cuò)實(shí)錄一份可直接抄走的 settings.json6.1 六合一配置示例把上面六個(gè) hook 合并到項(xiàng)目.claude/settings.json里大概長這樣{ hooks: { PostToolUse: [ { matcher: Edit|Write, hooks: [ { type: command, command: node .claude/hooks/format-on-write.js }, { type: command, command: node .claude/hooks/lint-on-write.js }, { type: command, command: node .claude/hooks/test-on-change.js, timeout: 60 } ] } ], PreToolUse: [ { matcher: Bash, hooks: [ { type: command, command: node .claude/hooks/guard-bash.js }, { type: command, command: node .claude/hooks/guard-secrets.js } ] }, { matcher: Edit|Write, hooks: [ { type: command, command: node .claude/hooks/guard-secrets.js } ] } ], Notification: [ { matcher: .*, hooks: [ { type: command, command: node .claude/hooks/notify-done.js } ] } ], Stop: [ { matcher: .*, hooks: [ { type: command, command: node .claude/hooks/stop-check.js } ] } ] } }請把format-on-write.js、lint-on-write.js、guard-bash.js、guard-secrets.js、test-on-change.js、notify-done.js、stop-check.js這幾個(gè)腳本放到.claude/hooks/目錄下。文件路徑按你項(xiàng)目實(shí)際情況調(diào)整。6.2 排錯(cuò)實(shí)錄我踩過的四個(gè)坑第一個(gè)坑是 matcher 寫太寬。我一開始把 PreToolUse 的 matcher 寫成.*結(jié)果 Claude 每次調(diào)用任何工具都要跑一遍 guard 腳本雖然腳本本身很快但大量 JSON 解析和正則匹配拖慢了整體交互。后來改成了Bash才清爽。第二個(gè)坑是 hook 腳本里忘了讀 stdin。Claude Code 通過 stdin 傳入 JSON如果你的腳本不讀 stdin 直接開始執(zhí)行是拿不到tool_input的。最穩(wěn)妥的寫法就是我上面反復(fù)用的那套process.stdin.on(data)累積后在end事件里處理。第三個(gè)坑是 exit code 語義混淆。早期我把攔截函數(shù)寫成process.exit(1)結(jié)果工具并沒有被阻止只是 Claude Code 報(bào)了個(gè) warning。后來查文檔確認(rèn)PreToolUse 場景下必須用exit(2)才會真正攔截。所以攔截類邏輯請務(wù)必記住2。第四個(gè)坑是 Windows 下路徑和 shell 雙引號問題。在 Windows 上用npx prettier --write ${filePath}如果路徑里帶空格Node 的execSync會解析出錯(cuò)。我的解決辦法是統(tǒng)一用spawnSync搭配參數(shù)數(shù)組避免 shell 轉(zhuǎn)義或者把路徑中的空格做轉(zhuǎn)義處理。最簡單的方案是讓所有腳本都用 Node 編寫盡量不依賴 shell 特殊語法。6.3 還能怎么擴(kuò)展這 6 個(gè)配置是我的基礎(chǔ)配置你可以按需升級。比如在SessionStart事件里注入一個(gè)“當(dāng)前項(xiàng)目測試命令”的提示讓 Claude 一開始就知道用什么命令跑測試。在UserPromptSubmit事件里檢查 prompt 里是否包含“忽略所有規(guī)則”這類注入嘗試遇到可疑內(nèi)容直接攔截。在PreCompact事件里把當(dāng)前未完成的任務(wù)摘要保存到文件上下文壓縮后 Claude 還能記得之前做到哪一步。我個(gè)人在實(shí)際操作中的體會是hooks 配置完成后最明顯的變化不是“代碼變好了”而是“規(guī)則沖突變少了”。格式化、安全、測試這三件事從“需要時(shí)刻盯著”變成了“系統(tǒng)自動(dòng)守門”我只需要在 Claude 被 hook 攔住時(shí)看一眼原因然后決定是調(diào)整規(guī)則還是讓它換個(gè)方案。這種“定好規(guī)則再放手”的開發(fā)方式才是 Claude Code 這類工具真正讓人放心的用法。最后再分享一個(gè)小技巧所有 hook 腳本里那兩行process.stdin.on(data)的讀取邏輯是同一個(gè)套路建議你封裝成一個(gè)readPayload()公共函數(shù)放到hooks/util.js里每個(gè)腳本都 require 它。這樣以后新增 hook 時(shí)代碼能少寫一大半也方便統(tǒng)一處理異常。 Claude Code Hooks實(shí)戰(zhàn)：格式化、安全與測試的6個(gè)配置
如果你已經(jīng)開始用 Claude Code 處理日常編碼任務(wù)大概率遇到過這樣的局面它寫得很快但改完的代碼格式化風(fēng)格跟項(xiàng)目規(guī)范完全不是一回事它偶爾會提出一個(gè)看起來很合理的 bash 命令但你沒仔細(xì)看就批準(zhǔn)了測試它也提可更多時(shí)候是建議你“自己跑一下試試”。這些問題不是模型能力不夠而是缺少一套強(qiáng)制性的機(jī)制在工具調(diào)用鏈路里卡點(diǎn)。Hooks 就是干這個(gè)的。這篇文章我會用 6 個(gè)可直接抄走的配置把代碼格式化、安全防護(hù)和自動(dòng)測試這三件事焊死在 Claude Code 的工作流里涵蓋 PreToolUse、PostToolUse、Stop、Notification 等觸發(fā)時(shí)機(jī)和完整腳本適合所有用 Claude Code 寫代碼、并且希望少一點(diǎn)失控感的人。先說清楚一件事hook 不是讓你在 prompt 里多寫幾行“請遵守項(xiàng)目規(guī)范”而是在 Claude 調(diào)用工具Bash、Edit、Write、Read的前后掛上外部腳本。腳本不滿足條件工具調(diào)用就直接被攔下。這種“硬約束”和“軟提示”的區(qū)別就是為什么很多人配置完 hooks 之后代碼合入 CI 的一次通過率明顯提升。1. Hooks 到底解決了什么問題先看三個(gè)最常見的失控現(xiàn)場1.1 失控現(xiàn)場一格式化規(guī)則全憑心情我用 Claude Code 做過一個(gè)小型 TypeScript 項(xiàng)目。模型默認(rèn)的代碼風(fēng)格跟項(xiàng)目里 prettier 配置不能說一模一樣只能說是各寫各的。單引號、雙引號混用對象末尾逗號時(shí)有時(shí)無縮進(jìn)偶爾從兩個(gè)空格跳成四個(gè)。最頭疼的是它每次 Edit 只改一小塊格式化問題被分散在十幾個(gè)文件里肉眼根本盯不過來。你可以在系統(tǒng)提示詞里寫“請始終使用項(xiàng)目 prettier 配置”但模型記不住每一條規(guī)則的細(xì)節(jié)更不會在每次寫入前主動(dòng)跑一遍格式化。等 CI 跑完報(bào)錯(cuò)再回頭修一個(gè)下午就沒了。Hooks 的正確姿勢是在文件落盤之后、或者寫入之前由外部腳本強(qiáng)制執(zhí)行 prettier不讓模型的“個(gè)人風(fēng)格”有機(jī)會進(jìn)入代碼庫。1.2 失控現(xiàn)場二危險(xiǎn)命令說跑就跑Claude Code 的 Bash 工具權(quán)限很大。它可能因?yàn)槟愕哪尘洹扒謇硪幌马?xiàng)目”就執(zhí)行rm -rf node_modules這還算可控但它也可能在改依賴時(shí)順手執(zhí)行npm install --unsafe-perm或者在你沒注意的時(shí)候往~/.bashrc里追加內(nèi)容。AI 沒有“這個(gè)操作影響范圍是否超出當(dāng)前項(xiàng)目”的常識它只有“用戶讓我完成目標(biāo)”的指令。我見過有人被 Claude 連續(xù)執(zhí)行了git push --force覆蓋遠(yuǎn)端提交也見過它在排查問題時(shí)把.env里的密鑰cat到了對話上下文里這些事后都很不好收拾。Bash 類的 hook 就是最后一道閘門命令在執(zhí)行前先過一遍規(guī)則命中風(fēng)險(xiǎn)項(xiàng)直接阻止并告訴 Claude 為什么不行。1.3 失控現(xiàn)場三測試永遠(yuǎn)“我建議你跑一下”另一個(gè)讓我比較無語的行為模式是Claude 改完代碼它的收尾往往是“測試已更新建議你運(yùn)行npm test驗(yàn)證”。如果你不追問它就當(dāng)你已經(jīng)跑過了。偶爾它會主動(dòng)跑但改一次跑一次全量測試幾分鐘就浪費(fèi)在等待上。自動(dòng)測試類的 hook 能解決兩個(gè)層面一是強(qiáng)制改完代碼后自動(dòng)觸發(fā)相關(guān)測試沒有通過就繼續(xù)修二是精準(zhǔn)不是所有變更都跑全量測試而是根據(jù)變更文件反推對應(yīng)的測試范圍。后面我會給出具體的實(shí)現(xiàn)思路。2. 開工前必讀settings.json 和 Hook 觸發(fā)機(jī)制的基礎(chǔ)2.1 配置文件放哪項(xiàng)目級與用戶級Claude Code 的 hooks 配置寫在settings.json里。項(xiàng)目級位置是.claude/settings.json用戶級位置是~/.claude/settings.json。項(xiàng)目級配置隨倉庫走適合團(tuán)隊(duì)統(tǒng)一約束用戶級配置只對本機(jī)生效適合放個(gè)人習(xí)慣類的 hook。我建議大部分自動(dòng)化規(guī)則放項(xiàng)目級這樣團(tuán)隊(duì)里任何人用 Claude Code 都會被同一套規(guī)則約束。需要說明的是項(xiàng)目級配置默認(rèn)情況下對協(xié)作者可見你最好在 README 里寫清楚每個(gè) hook 的用途免得別人 clone 項(xiàng)目后第一次跑被攔截腳本嚇一跳。2.2 六類事件與 matcher 匹配規(guī)則Hooks 的配置結(jié)構(gòu)大致是{ hooks: { PreToolUse: [ { matcher: Edit|Write, hooks: [ { type: command, command: node .claude/hooks/check-format.js } ] } ] } }PreToolUse是事件名表示“工具執(zhí)行之前”。官方支持的事件類型主要有這些事件名觸發(fā)時(shí)機(jī)典型用途PreToolUse工具調(diào)用前攔截危險(xiǎn)命令、檢查寫入內(nèi)容PostToolUse工具調(diào)用后格式化、Lint、自動(dòng)測試NotificationClaude 等待用戶確認(rèn)時(shí)桌面通知提醒StopClaude 回復(fù)生成完成運(yùn)行完整校驗(yàn)、輸出摘要SessionStart會話開始環(huán)境檢查、項(xiàng)目信息注入U(xiǎn)serPromptSubmit用戶提交提示詞時(shí)內(nèi)容過濾、追加上下文PreCompact上下文壓縮前保存任務(wù)進(jìn)度摘要matcher是一段正則表達(dá)式用來限定 hook 作用于哪些工具或哪些調(diào)用。比如Edit|Write表示匹配編輯文件和新建文件操作Bash表示匹配所有 bash 命令也可以寫成Bash\\(.*git.*\\)這類更精確的形態(tài)去匹配包含 git 的命令。2.3 退出碼、stdin JSON 與超時(shí)三個(gè)決定成敗的細(xì)節(jié)hook 命令執(zhí)行時(shí)Claude Code 會通過 stdin 傳入一段 JSON里面至少包含{ session_id: xxx, cwd: /home/user/project, hook_event_name: PreToolUse, tool_name: Bash, tool_input: { command: rm -rf node_modules } }腳本要做的就是讀取這段 JSON然后根據(jù)tool_input內(nèi)容決定返回什么退出碼。我這里約定退出碼0放行工具繼續(xù)執(zhí)行。退出碼2阻止工具執(zhí)行stdout 內(nèi)容會返回給 Claude讓它知道被攔的原因。其他非 0 退出碼表示 hook 自身出錯(cuò)Claude Code 會記錄 warning但不會強(qiáng)制阻止工具。所以攔截類邏輯務(wù)必用2。還有一個(gè)容易被忽略的是timeout。hook 命令默認(rèn)超時(shí)時(shí)間是 60 秒超過會被終止。如果你的自動(dòng)測試腳本可能要跑幾分鐘一定要在 hook 配置里顯式調(diào)大{ type: command, command: node .claude/hooks/run-tests.js, timeout: 120 }另外hook 腳本的 stdout 和 stderr 會被 Claude Code 捕獲并放進(jìn)模型上下文。這意味著你可以在腳本里輸出給模型看的提示信息但不要打印一堆無關(guān)日志否則會白白消耗 token還會干擾模型對工具調(diào)用結(jié)果的理解。3. 前兩個(gè)配置用 PreToolUse 和 PostToolUse 把格式化和 Lint 焊死在編輯動(dòng)作上3.1 配置一文件落盤后自動(dòng)格式化不用再跟模型強(qiáng)調(diào)“別用雙引號”這是我在所有項(xiàng)目里第一個(gè)配的 hook。先給結(jié)論用 PostToolUse 而不是 PreToolUse 做格式化。原因在于調(diào)用時(shí)序。PreToolUse 發(fā)生在 Claude 的 Edit/Write 工具真正寫入文件之前這時(shí)你拿到的file_path是目標(biāo)路徑但文件內(nèi)容還沒寫入或者寫入的是舊版本。如果你在這個(gè)時(shí)機(jī)去prettier --write格式化的是舊文件等 Edit 執(zhí)行完新內(nèi)容覆蓋上去格式化又被沖掉了。所以正確做法是 PostToolUse。腳本在 Edit/Write 完成后拿到文件路徑立刻執(zhí)行格式化命令#!/usr/bin/env node // .claude/hooks/format-on-write.js const fs require(fs); const { execSync } require(child_process); let input ; process.stdin.on(data, (chunk) (input chunk)); process.stdin.on(end, () { try { const payload JSON.parse(input); const filePath payload.tool_input?.file_path; if (!filePath) process.exit(0); const ext filePath.split(.).pop(); const supported [ts, tsx, js, jsx, json, css, md]; if (!supported.includes(ext)) process.exit(0); // 跳過 node_modules 和生成目錄 if (filePath.includes(node_modules) || filePath.includes(dist)) process.exit(0); execSync(npx prettier --write ${filePath}, { cwd: payload.cwd, stdio: pipe, }); console.log([format] ${filePath} 已按項(xiàng)目 prettier 配置格式化); process.exit(0); } catch (e) { // 格式化失敗不阻斷工具調(diào)用避免惡性循環(huán) console.error([format] 格式化失敗: ${e.message}); process.exit(0); } });配置代碼里注冊它{ hooks: { PostToolUse: [ { matcher: Edit|Write, hooks: [ { type: command, command: node .claude/hooks/format-on-write.js } ] } ] } }你可能會擔(dān)心一個(gè)問題格式化之后的文件內(nèi)容和 Claude 在上下文里看到的“剛寫入的內(nèi)容”不一致。實(shí)際影響不大因?yàn)?Claude 下次讀取文件時(shí)讀到的是格式化后的內(nèi)容它自然會基于這個(gè)版本繼續(xù)改。還有一個(gè)坑是 Windows 環(huán)境。npx prettier --write里的路徑如果有特殊字符引號轉(zhuǎn)義容易出問題。建議所有 hook 腳本都用 Node.js 寫避免直接依賴 bash 語法。后面所有示例我都用 Node。3.2 配置二Lint 結(jié)果自動(dòng)回流給模型從源頭減少“改完又錯(cuò)”的來回格式化解決的是風(fēng)格Lint 解決的是“代碼有沒有明顯問題”。我在這個(gè) hook 里跑的是 ESLint并且只針對 Claude 改過的文件不做全量掃描。#!/usr/bin/env node // .claude/hooks/lint-on-write.js const { execSync } require(child_process); let input ; process.stdin.on(data, (chunk) (input chunk)); process.stdin.on(end, () { try { const payload JSON.parse(input); const filePath payload.tool_input?.file_path; if (!filePath || filePath.includes(.test.)) process.exit(0); try { const out execSync( npx eslint ${filePath} --max-warnings0 --format compact, { cwd: payload.cwd, stdio: pipe } ).toString(); // 無錯(cuò)誤則靜默退出 process.exit(0); } catch (e) { const output e.stdout?.toString() || ; // 只輸出錯(cuò)誤摘要最多截取 1500 字符避免刷爆上下文 const summary output.split(\n).slice(0, 20).join(\n).slice(0, 1500); console.error([lint] ESLint 檢測到問題請修復(fù)后再繼續(xù): \n${summary}); process.exit(0); } } catch (e) { process.exit(0); } });注意這里我讓 exit code 保持 0沒有用 2 阻止寫入。為什么不攔截因?yàn)橛行?lint 錯(cuò)誤是結(jié)構(gòu)性的Claude 需要先寫入代碼、看到報(bào)錯(cuò)、再修復(fù)這是一個(gè)迭代過程。如果你在寫入時(shí)就把它攔住模型會陷入“不知道代碼哪里有問題”的困境。更好的做法是把錯(cuò)誤信息喂給它讓它自己判斷怎么改。--max-warnings0這參數(shù)很有用。它把 warning 也當(dāng)作 error 處理防止項(xiàng)目里積累一大堆“不痛不癢”的警告。對 Claude 這種大模型來說警告太多會稀釋注意力寧可讓 hook 直接暴露出來。有人會問eslint 的--fix能不能直接放在 PostToolUse 里自動(dòng)修可以但建議單獨(dú)跑。因?yàn)?-fix可能改出模型意料之外的結(jié)果尤其是一些涉及代碼結(jié)構(gòu)的規(guī)則。我的經(jīng)驗(yàn)是格式化可以自動(dòng)lint 修復(fù)盡量讓模型自己來否則它下次可能重復(fù)犯同樣的錯(cuò)。4. 中間兩個(gè)配置給 Bash 命令套上安全圍欄給寫入內(nèi)容加上敏感信息閘門4.1 配置三危險(xiǎn)命令黑名單 項(xiàng)目目錄白名單雙管齊下Bash hook 是整個(gè)安全體系里最重要的一環(huán)因?yàn)?Claude Code 的大多數(shù)破壞性操作都是通過 Bash 完成的。我的攔截腳本分兩層第一層是黑名單直接命中關(guān)鍵詞就阻止。這里列幾個(gè)我實(shí)測下來比較實(shí)用的規(guī)則const BLOCKED_PATTERNS [ /rm\s-rf\s\//, // 刪除根目錄 /rm\s-rf\s~/, // 刪除用戶目錄 /mkfs\./, // 格式化磁盤 /git\spush\s.*--force/, // 強(qiáng)推 /curl.*\|\s*(ba)?sh/, // curl 管道執(zhí)行腳本 /npm\sinstall\s-g\s.*--unsafe/, /chmod\s-R\s777/, /sudo/, ];第二層是白名單思路這個(gè)更重要。對rm、mv、chmod這類具有破壞性的命令我會校驗(yàn)?zāi)繕?biāo)路徑是否在項(xiàng)目目錄內(nèi)。路徑不在項(xiàng)目內(nèi)直接阻止。實(shí)現(xiàn)得并不復(fù)雜關(guān)鍵在于用 Node 的path.resolve把相對路徑轉(zhuǎn)成絕對路徑再做前綴比較。// .claude/hooks/guard-bash.js const path require(path); let input ; process.stdin.on(data, (chunk) (input chunk)); process.stdin.on(end, () { try { const payload JSON.parse(input); const command payload.tool_input?.command || ; const cwd payload.cwd; for (const pattern of BLOCKED_PATTERNS) { if (pattern.test(command)) { console.error([guard] 命令命中危險(xiǎn)規(guī)則: ${pattern}\n已阻止執(zhí)行。如果你確實(shí)需要執(zhí)行請手動(dòng)在終端操作。); process.exit(2); } } // 對 rm/mv 做路徑范圍檢查 if (/^(rm|mv|chmod)\b/.test(command)) { const unsafe command .split(/\s/) .filter((arg) arg.startsWith(/) || arg.startsWith(~) || arg.startsWith(../)) .some((arg) { const abs path.resolve(cwd, arg); return !abs.startsWith(path.resolve(cwd)); }); if (unsafe) { console.error([guard] 檢測到目標(biāo)路徑超出當(dāng)前項(xiàng)目目錄已阻止執(zhí)行。); process.exit(2); } } process.exit(0); } catch (e) { process.exit(0); } });這個(gè)腳本的思路是“默認(rèn)信任但有限制”。Claude 在項(xiàng)目里跑npm install、git diff、ls這類命令基本不受影響一旦碰到影響范圍超出項(xiàng)目的操作就會被攔截。exit 2的關(guān)鍵在于Claude 能看到 stderr 里的提示它會自己調(diào)整方案。我見過一個(gè)有意思的案例Claude 想把日志寫到/tmp/debug.log被這個(gè) hook 攔了。它看到提示后改為寫到項(xiàng)目下的.logs/debug.log還順手把.logs/加進(jìn)了.gitignore。這說明給模型一個(gè)“為什么不行”的反饋比單純阻止更有效。4.2 配置四敏感信息檢測防止密鑰被寫入代碼或進(jìn)入對話上下文Claude 在寫代碼時(shí)偶爾會“好心”把真實(shí)密鑰寫進(jìn).env文件旁邊或者在測試代碼里硬編碼一個(gè) API Key。更隱蔽的是它可能在排查問題時(shí)直接cat .env把密鑰讀進(jìn)上下文然后這些內(nèi)容就可能出現(xiàn)在日志里。敏感信息 hook 我配在 PreToolUse分別攔截兩類場景Edit/Write檢查tool_input.content和file_path如果發(fā)現(xiàn)密鑰特征阻止寫入。Bash檢查命令里是否有讀取敏感文件或把敏感信息寫入文件的操作。// .claude/hooks/guard-secrets.js const SENSITIVE_PATTERNS [ /sk-[A-Za-z0-9]{20,}/, // OpenAI / Anthropic 風(fēng)格 key /AKIA[0-9A-Z]{16}/, // AWS Access Key /ghp_[A-Za-z0-9]{36,}/, // GitHub Token /BEGIN (RSA|EC|OPENSSH) PRIVATE KEY/, // 私鑰塊 ]; const SENSITIVE_FILES [.env, .env.local, .pem, id_rsa, id_ed25519]; let input ; process.stdin.on(data, (chunk) (input chunk)); process.stdin.on(end, () { try { const payload JSON.parse(input); const tool payload.tool_name; const inputData payload.tool_input || {}; if (tool Edit || tool Write) { const content inputData.content || ; const filePath inputData.file_path || ; const fileBasename path.basename(filePath); if (SENSITIVE_FILES.includes(fileBasename) SENSITIVE_PATTERNS.some((p) p.test(content))) { console.error([guard] 檢測到疑似敏感信息被寫入已阻止。請改用環(huán)境變量或 .env.local 維護(hù)密鑰。); process.exit(2); } } if (tool Bash) { const command inputData.command || ; if (SENSITIVE_FILES.some((f) command.includes(cat ${f}) || command.includes(cat ./${f}))) { console.error([guard] 阻止讀取敏感文件避免密鑰進(jìn)入上下文。); process.exit(2); } } process.exit(0); } catch (e) { process.exit(0); } });這個(gè) hook 的難點(diǎn)在于誤報(bào)控制。比如.env里本身可以不寫密鑰只放配置項(xiàng)名稱項(xiàng)目文檔里也可能出現(xiàn)類似sk-xxx的示例占位符。解決方案是只攔截“文件路徑本身很敏感且內(nèi)容命中密鑰特征”的情況。普通代碼文件里出現(xiàn)sk-開頭的測試占位符我選擇放行因?yàn)槟呛芸赡苁?mock 數(shù)據(jù)。配好之后我建議你在測試環(huán)境故意觸發(fā)一次確認(rèn)攔截生效、模型能被正確引導(dǎo)。如果發(fā)現(xiàn)誤報(bào)就調(diào)整正則的嚴(yán)謹(jǐn)度不要因?yàn)椤皩幙刹粩r也不誤判”而把規(guī)則關(guān)掉安全這種事兒寧可多攔幾次。5. 最后兩個(gè)配置文件變更后自動(dòng)跑測試、任務(wù)完成時(shí)主動(dòng)提醒5.1 配置五PostToolUse 精準(zhǔn)觸發(fā)相關(guān)測試而不是傻等全量執(zhí)行自動(dòng)測試最簡單的實(shí)現(xiàn)是監(jiān)聽PostToolUse的Edit|Write事件文件一變就跑npm test。但全量測試在稍大一點(diǎn)的項(xiàng)目里可能要好幾分鐘Claude 每改一次文件就觸發(fā)一次交互體驗(yàn)會非常差。我采用的策略是根據(jù)文件路徑縮小范圍// .claude/hooks/test-on-change.js const { execSync } require(child_process); const path require(path); let input ; process.stdin.on(data, (chunk) (input chunk)); process.stdin.on(end, () { try { const payload JSON.parse(input); const filePath payload.tool_input?.file_path || ; const cwd payload.cwd; // 只對 src 下的業(yè)務(wù)代碼觸發(fā) if (!filePath.startsWith(src/)) process.exit(0); if (filePath.includes(.test.) || filePath.includes(.spec.)) { // 改動(dòng)的是測試文件直接跑這個(gè)測試 execSync(npx vitest run ${filePath} --reporterdot, { cwd, stdio: pipe, timeout: 60000, }); console.error([test] ${path.basename(filePath)} 測試通過); } else { // 改動(dòng)的是業(yè)務(wù)代碼跑相關(guān)測試 execSync(npx vitest run --changed --reporterdot, { cwd, stdio: pipe, timeout: 60000, }); console.error([test] 相關(guān)測試通過); } process.exit(0); } catch (e) { console.error([test] 相關(guān)測試失敗請查看上面的報(bào)錯(cuò)并修復(fù)\n${e.stdout?.toString().slice(0, 1000)}); process.exit(0); } });如果你用的測試框架不是 vitest思路完全一致Jest 可以用jest -o只跑發(fā)生變更的文件相關(guān)的測試其他框架可以通過 git diff 計(jì)算變更文件再傳給測試命令。這里有兩個(gè)細(xì)節(jié)值得說。一是timeout我給的是 60 秒因?yàn)闇y試命令本身要預(yù)留執(zhí)行時(shí)間如果你在 hook 配置里又設(shè)了一個(gè)更小的 timeout頂層的會先生效導(dǎo)致命令被提前 kill。所以建議兩處都設(shè)成一致。二是失敗時(shí)不要 exit 2。為什么因?yàn)闇y試失敗不代表代碼寫入是錯(cuò)誤的Claude 需要先完成這次工具調(diào)用、看到測試失敗的反饋然后進(jìn)行下一輪修復(fù)。如果我們把 exit 2 當(dāng)作“阻止工具執(zhí)行”相當(dāng)于 Claude 寫了一個(gè)代碼但因?yàn)闇y試沒過就不讓它寫這會陷入奇怪的狀態(tài)。測試 hook 的核心價(jià)值是“反饋”不是“阻斷”。每次測試失敗Claude 都會在下一輪嘗試修復(fù)直到通過。5.2 配置六Stop 和 Notification 事件把等待時(shí)間變成可控提醒最后兩個(gè)配置解決的是“人機(jī)協(xié)作時(shí)的通知”問題。用 Claude Code 時(shí)它經(jīng)常會停下來等人批準(zhǔn)一個(gè) bash 命令或者問一個(gè)問題這時(shí)候如果你切到別的窗口可能很久都不知道需要你確認(rèn)。Notification 事件能在這里觸發(fā)一個(gè)桌面通知。// .claude/hooks/notify-done.js let input ; process.stdin.on(data, (chunk) (input chunk)); process.stdin.on(end, () { try { const payload JSON.parse(input); const event payload.hook_event_name; const title event Notification ? Claude Code 需要確認(rèn) : Claude Code 待辦提醒; // macOS const { execSync } require(child_process); try { execSync(osascript -e display notification 請查看 Claude Code with title ${title}); } catch (e) { // Linux try { execSync(notify-send ${title} 請查看 Claude Code); } catch (_) {} } process.exit(0); } catch (e) { process.exit(0); } });注冊到 Notification 事件即可。至于 Stop 事件我把它用作“任務(wù)收尾檢查”。Claude 每次回復(fù)完成后這個(gè) hook 會檢查一下 git 狀態(tài)如果有未格式化的文件直接輸出提醒讓它主動(dòng)處理。// .claude/hooks/stop-check.js const { execSync } require(child_process); let input ; process.stdin.on(data, (chunk) (input chunk)); process.stdin.on(end, () { try { const payload JSON.parse(input); const cwd payload.cwd; const changed execSync(git status --porcelain, { cwd, stdio: pipe }).toString(); const unformatted changed .split(\n) .filter((line) /\.(ts|js|tsx|jsx|json|css|md)$/.test(line) line.startsWith( M )); if (unformatted.length 0) { console.error( [check] 以下文件有修改但可能未格式化如果確認(rèn)已完成所有任務(wù)請運(yùn)行 prettier --write 處理\n${unformatted.slice(0, 5).join(\n)} ); } process.exit(0); } catch (e) { process.exit(0); } });這個(gè) hook 不會阻止任何操作只是提供一個(gè)“事后提醒”。它的價(jià)值在于解決 Claude 的“總覺得自己干完了”問題——每次回復(fù)完它都能看到還有哪些代碼處于臟狀態(tài)從而決定是否繼續(xù)收拾。6. 完整配置匯總與排錯(cuò)實(shí)錄一份可直接抄走的 settings.json6.1 六合一配置示例把上面六個(gè) hook 合并到項(xiàng)目.claude/settings.json里大概長這樣{ hooks: { PostToolUse: [ { matcher: Edit|Write, hooks: [ { type: command, command: node .claude/hooks/format-on-write.js }, { type: command, command: node .claude/hooks/lint-on-write.js }, { type: command, command: node .claude/hooks/test-on-change.js, timeout: 60 } ] } ], PreToolUse: [ { matcher: Bash, hooks: [ { type: command, command: node .claude/hooks/guard-bash.js }, { type: command, command: node .claude/hooks/guard-secrets.js } ] }, { matcher: Edit|Write, hooks: [ { type: command, command: node .claude/hooks/guard-secrets.js } ] } ], Notification: [ { matcher: .*, hooks: [ { type: command, command: node .claude/hooks/notify-done.js } ] } ], Stop: [ { matcher: .*, hooks: [ { type: command, command: node .claude/hooks/stop-check.js } ] } ] } }請把format-on-write.js、lint-on-write.js、guard-bash.js、guard-secrets.js、test-on-change.js、notify-done.js、stop-check.js這幾個(gè)腳本放到.claude/hooks/目錄下。文件路徑按你項(xiàng)目實(shí)際情況調(diào)整。6.2 排錯(cuò)實(shí)錄我踩過的四個(gè)坑第一個(gè)坑是 matcher 寫太寬。我一開始把 PreToolUse 的 matcher 寫成.*結(jié)果 Claude 每次調(diào)用任何工具都要跑一遍 guard 腳本雖然腳本本身很快但大量 JSON 解析和正則匹配拖慢了整體交互。后來改成了Bash才清爽。第二個(gè)坑是 hook 腳本里忘了讀 stdin。Claude Code 通過 stdin 傳入 JSON如果你的腳本不讀 stdin 直接開始執(zhí)行是拿不到tool_input的。最穩(wěn)妥的寫法就是我上面反復(fù)用的那套process.stdin.on(data)累積后在end事件里處理。第三個(gè)坑是 exit code 語義混淆。早期我把攔截函數(shù)寫成process.exit(1)結(jié)果工具并沒有被阻止只是 Claude Code 報(bào)了個(gè) warning。后來查文檔確認(rèn)PreToolUse 場景下必須用exit(2)才會真正攔截。所以攔截類邏輯請務(wù)必記住2。第四個(gè)坑是 Windows 下路徑和 shell 雙引號問題。在 Windows 上用npx prettier --write ${filePath}如果路徑里帶空格Node 的execSync會解析出錯(cuò)。我的解決辦法是統(tǒng)一用spawnSync搭配參數(shù)數(shù)組避免 shell 轉(zhuǎn)義或者把路徑中的空格做轉(zhuǎn)義處理。最簡單的方案是讓所有腳本都用 Node 編寫盡量不依賴 shell 特殊語法。6.3 還能怎么擴(kuò)展這 6 個(gè)配置是我的基礎(chǔ)配置你可以按需升級。比如在SessionStart事件里注入一個(gè)“當(dāng)前項(xiàng)目測試命令”的提示讓 Claude 一開始就知道用什么命令跑測試。在UserPromptSubmit事件里檢查 prompt 里是否包含“忽略所有規(guī)則”這類注入嘗試遇到可疑內(nèi)容直接攔截。在PreCompact事件里把當(dāng)前未完成的任務(wù)摘要保存到文件上下文壓縮后 Claude 還能記得之前做到哪一步。我個(gè)人在實(shí)際操作中的體會是hooks 配置完成后最明顯的變化不是“代碼變好了”而是“規(guī)則沖突變少了”。格式化、安全、測試這三件事從“需要時(shí)刻盯著”變成了“系統(tǒng)自動(dòng)守門”我只需要在 Claude 被 hook 攔住時(shí)看一眼原因然后決定是調(diào)整規(guī)則還是讓它換個(gè)方案。這種“定好規(guī)則再放手”的開發(fā)方式才是 Claude Code 這類工具真正讓人放心的用法。最后再分享一個(gè)小技巧所有 hook 腳本里那兩行process.stdin.on(data)的讀取邏輯是同一個(gè)套路建議你封裝成一個(gè)readPayload()公共函數(shù)放到hooks/util.js里每個(gè)腳本都 require 它。這樣以后新增 hook 時(shí)代碼能少寫一大半也方便統(tǒng)一處理異常。