便條擋不住：用 hook 把金鑰攔在提交之前

常駐檔是便條，不是保險，談 CLAUDE.md 時講過這句話。這一篇講保險長什麼樣。

場景是這樣的。你在 CLAUDE.md 裡用粗體寫了「絕對不要把 API 金鑰或密碼提交上去」。AI 讀了，也記得。然後某天它處理一個複雜的錯誤，對話裡塞滿了程式碼和錯誤訊息，那條規則被推到視線之外，它把含金鑰的 .env 檔跟其他修改一起 commit 了。推上 GitHub，金鑰公開，接下來是別人拿你的額度刷爆帳單。

這種事不能靠 AI 的自律。絕對不能發生的事，要靠一段不管 AI 怎麼想都會執行的程式。在 Git 裡這叫 hook：在特定時機（例如 commit 之前）自動跑的腳本。

三行設定，金鑰進不了 git

不用自己寫掃描規則。有一個專門的開源工具叫 gitleaks，它的工作就是在 git 內容裡找密碼、API 金鑰、token（各種服務發給你的通行證字串）。裝法有兩種。

用 pre-commit 框架。在專案根目錄建 .pre-commit-config.yaml，內容照 gitleaks README 的三行（repo 位址、版本、hook id 為 gitleaks），然後執行 pre-commit install。之後每次 commit，它會自動跑，抓到就顯示「Detect hardcoded secrets … Failed」並拒絕提交。

或者直接叫 AI 幫你裝。在代理工具裡說：「幫我在這個專案裝 gitleaks 的 pre-commit hook，每次 commit 前掃描金鑰與密碼，抓到就擋下。」它會幫你建設定檔、裝工具、測試一次。這是少數我會直接讓 AI 動的環境設定，因為它做的是加一道鎖，不是開一道門。

兩件事要先講清楚。第一，這是本機的防線，同事 clone 專案之後要各自跑一次 pre-commit install，否則他們的機器上沒有這道鎖；團隊要全面防，還要在 CI（程式碼推上去之後自動跑的檢查流程）上再掃一次。第二，hook 可以被 --no-verify 跳過，所以常駐檔裡要多一條：「不准使用 --no-verify」。這一條是便條，但它防的是「AI 想繞過鎖」這件事，而繞過鎖的動作本身可以再用 Claude Code 的 hook 擋（見下面）。

Claude Code 自己也有一套 hook 機制，跟 git hook 不同層：它在 AI 要執行某個工具（例如跑一條指令）之前觸發，可以直接擋下。官方文件對「便條 vs 強制」的區分就是這樣寫的：要在特定時間點一定執行的事，寫成 hook；要不管 AI 怎麼想都擋下的事，用 hook 或權限設定。

架構也有「便條擋不住」的問題，但解法不是 linter

很多人以為 Pocock 有一個「架構掃描的 linter」。我讀了原始碼，它不是 linter，這裡照實講它是什麼。

那支 Skill 叫 improve-codebase-architecture，只有你手動啟動才會跑。它做三件事。掃描：派子代理走一遍程式庫（優先看最近常改的地方），找出「理解一個概念要在很多小模組之間跳來跳去」「模組的介面跟實作一樣複雜」這類摩擦。報告：產一份 HTML，每個候選點附問題、解法、好處、改前改後的圖，和建議強度。拷問：你挑一個候選點，它用 grilling（動工前先被拷問那篇的拷問法）跟你一題一題走過決策樹，最後才動手。

它要解決的問題叫淺模組（shallow module）：介面跟實作差不多複雜的模組。外表分工很細，實際上每個小房間都要主程式記住獨立的參數，AI 一進去修 bug 就迷路。目標是深模組：一扇簡單的門（例如只暴露一個 processCheckout）藏著幾百行複雜邏輯。判斷方法叫刪除測試：如果把這個模組拔掉，複雜度是「集中到別處」還是「只是搬個位置」？前者代表它是有在藏細節的深模組。

這個概念來自 John Ousterhout 的《A Philosophy of Software Design》。跟 hook 的關係是同一個道理：你在常駐檔寫「請保持模組乾淨」沒有用，要有一個定期跑的流程去找出來、攤在你面前、逼你決定。

動手做

專案裡有任何 API 金鑰或密碼的，今天就裝 gitleaks。交給 AI，貼這段：

請在這個專案裝 gitleaks 的 pre-commit hook：
1. 照 gitleaks 官方 README 建 .pre-commit-config.yaml（repo 指向 gitleaks，hook id 為 gitleaks，版本用 README 目前列的）。
2. 安裝 pre-commit 並執行 pre-commit install。
3. 做一次測試：建一個含假金鑰（例如 AKIA 開頭的假 AWS key）的暫存檔，嘗試 commit，確認被擋下；然後刪掉那個檔。
4. 在 .gitignore 確認 .env 與所有 *.key、*.pem 都被排除。
5. 回報：hook 有沒有擋下測試、.gitignore 加了什麼。不要用 --no-verify。

用 Claude Code、想擋「AI 自己繞過鎖」的，在 .claude/settings.json 加一條 PreToolUse hook，matcher 設 Bash，腳本檢查指令字串裡有沒有 --no-verify 或 git push --force，有就回傳拒絕。寫法照官方 hooks 文件；不確定的話叫 AI 照文件幫你寫，然後你自己試一次 git commit --no-verify 確認真的被擋。

專案越改越亂、想做一次架構盤點的，裝了 Pocock 的 skills 之後打 /improve-codebase-architecture，等它開 HTML 報告。只看「Top recommendation」那一段，其他先不管。

裝對了的樣子：你親手試過一次假金鑰 commit，看到它被擋；同事的機器上也裝了（問過，不是假設）；常駐檔裡有「不准 --no-verify」，而且 Claude Code hook 真的擋得住；架構報告你至少做過一個 Top recommendation。

還有一件事現在就能做：在專案裡搜尋 sk-、AKIA、password=、token=。搜到任何一個真的值，先去把它換掉，再裝 hook。已經進過 git 歷史的金鑰，刪檔不夠，要視為已外洩。

便條擋不住恍神，絕對不能發生的事用 hook。gitleaks 三行設定今天就裝，已經進過 git 的金鑰視為外洩，先換掉。hook 是本機防線，同事要各自裝、CI 要再掃一次、--no-verify 要另外擋。架構也一樣：寫「請保持乾淨」沒用，要有一個定期跑的流程把問題攤出來。

站內延伸

• 為什麼便條不是保險 → 常駐檔是便條不是憲法
• 迴圈裡不准改測試的邊界 → 迴圈的停損
• 「鎖」的完整清單、外洩後的處理 → 找方法AI Agent 權限最小化、AI 資安事件紀錄

來源： gitleaks（用途、pre-commit 設定、安裝）；Claude Code：Hooks guide（PreToolUse 與「hook 不管 AI 怎麼想都會執行」）；mattpocock/skills：improve-codebase-architecture（掃描、HTML 報告、grilling 三步；刪除測試）。深模組概念出自 John Ousterhout《A Philosophy of Software Design》。