高效 AI 駕馭術
AI 不照 CLAUDE.md、AGENTS.md 的規則做怎麼辦?把規則寫成測試和 hooks(2026)
規則檔只是給模型讀的建議。哪些規則該交給測試擋、哪些只列報告讓人判斷、哪些要用 Claude Code 和 Codex 的 hooks、權限規則擋在工具層,附我網站上的實際例子。
Kelvin Wang · · 10 分鐘閱讀
重點整理
- 每條規則先用文字寫清楚;寫得清楚,才分得出它該由誰執行。
- 零例外、程式查得出來的規則寫成測試,失敗就不算完成。
- 需要判斷的規則寫成稽核腳本,只列報告,由人決定改不改。
- AI 的動作本身(刪資料、讀機密檔)用 hooks、權限規則和沙箱擋,不靠模型記得。
把一定要成立的規則從規則檔搬出去,改成程式檢查。CLAUDE.md 和 AGENTS.md 是給模型讀的,它通常會照做,但沒有保證。所以我把規則分成三種:零例外、程式查得出來的寫成測試,跑不過就不算完成;需要判斷的寫成稽核腳本,列出報告由我看;AI 的動作本身,例如刪資料庫的資料,交給工具的 hooks 和權限規則,在動作發生前就擋下。
為什麼 AI 不照 CLAUDE.md、AGENTS.md 的規則做?
因為規則檔只是 context:模型讀了會參考,但不會被它綁住。Claude Code 的官方最佳實務把指令分成兩種:寫在提示、CLAUDE.md 或 skill 裡的,由模型讀了之後自己決定怎麼做,通常會照做,但沒有保證;設定成 hook、deny 規則或受管設定的,由 Claude Code 這個 harness 每次都執行,不管模型怎麼想1。
同一份文件也說,一直替某一行加「IMPORTANT」它還是被忽略,原因通常只有兩個:檔案太長、那一行被淹沒,或者那是一條不能有例外的規則,應該交給 hook1。Codex 也一樣,AGENTS.md 是組進對話裡的指令;要真的擋住,靠的是 hooks、rules 和沙箱,後面會講。
不過搬出去之前,規則要先寫得夠清楚。
把規則寫成測試,其實就是把我希望的限制(constraint)用文字說清楚。
「畫面要一致」沒辦法測。「狀態色只能用四個語意角色,不能直接寫 green-400」可以測。很多規則要寫到第二種程度,才看得出該由誰來執行。
哪些規則寫成測試,哪些只列報告?
我用兩個問題分:這條規則有沒有例外?違反的時候,程式查不查得出來?
| 規則的性質 | 例子 | 誰執行 | 違反時 |
|---|---|---|---|
| 有例外、要看情況 | 新程式不要照 src/legacy/ 的寫法 | 規則檔(AGENTS.md、CLAUDE.md) | 模型自己判斷 |
| 查得出來,但要人判斷 | 第一段不能重複導言、H2 是問句要加「?」 | 稽核腳本 tools/audit-writing.mjs | 列報告,我決定改不改 |
| 零例外、查得出來 | 每個交易所頁剛好一份 BreadcrumbList | 測試 npx vitest run | 測試失敗,不算完成 |
| AI 的動作本身 | 刪表、清空資料表、讀 .env | hooks、權限規則、沙箱 | 動作執行前就擋下或要我確認 |
這個網站的 repo 現在有 81 個測試檔,大部分是一般的功能測試,其中一批專門守 DESIGN.md 和交易所專區規格裡的規則。DESIGN.md 對整個 repo 有約束力,專案的 CLAUDE.md 第一條就要求改畫面前先讀它。規則和測試互相指:規格寫「測試會擋」並寫出檔名,測試檔開頭的註解寫它對應規格的哪一節。
把規則寫成測試長什麼樣子?
最清楚的例子是麵包屑。DESIGN.md 規定:首頁以外的每個公開頁都有一條麵包屑,元件同時輸出看得到的導覽列和 schema.org 的 BreadcrumbList;頁面不要自己再寫一份,每頁剛好一個。
對應的測試是 tests/exchanges-breadcrumbs.test.ts。它不是挑幾頁檢查,而是把 src/pages/zh-hant/exchanges/ 底下每個路由檔都找出來,展開成每個交易所、每個事件的實際網址,一頁一頁渲染,再檢查三件事:
- 剛好一份
BreadcrumbList。多一份、少一份都失敗。 - 第一層是首頁。
- 最後一層是這一頁自己的網址。
新增的交易所頁不用改測試就會被檢查到。如果新頁的網址多了一個新的動態參數,測試會直接失敗,訊息寫明要在哪裡補測試資料。「新頁面忘了麵包屑」這類問題,不用靠 AI 記得規則。
其他守規格的測試也是同一個寫法:
- 狀態色。
tests/status-colors.test.ts掃src底下所有元件,出現text-red-500、bg-green-400這種直接寫色相的 class 就失敗(DESIGN.md§6)。 - 間距。
tests/spacing-scale.test.ts擋公開頁表外的垂直間距,只准用規格表裡的值(§4.10)。 - 交易所文案。
tests/exchanges-copy.test.ts擋禁用字詞;文案裡不准直接寫百分比,費率一律由已核准的資料填進占位符。 - 事件頁長度。事件進行中時文案每小時改寫、只會變長,所以
tests/exchanges-incident-copy.test.ts限制摘要最多 3 句、220 字。
例外也寫在測試裡,而且要寫原因。間距測試有一個 ALLOW 表,每個保留表外數值的檔案旁邊都寫為什麼;文案測試的百分比白名單以「檔案:欄位路徑」為鍵,新出現的百分比一樣會失敗。禁用字詞則沒有白名單。要開例外,就得在 diff 裡留下看得到的一行。
為什麼寫作規則只報告、不擋建置?
因為很多寫作規則要靠判斷。node tools/audit-writing.mjs 掃所有文章,列出 H2 問句沒加「?」、清單沒有粗體開頭、長文沒有重點整理這類問題,最後一律以成功結束,不擋任何東西。2026-11-17 跑的時候,160 多篇 MDX 裡列出 14 篇。
「第一段不能重複導言」是最好的例子。腳本的做法是比較第一段和導言的字詞重疊:中文用兩個字一組,重疊超過六成就列出來。這抓得到大部分照抄的情況,但也會誤判,例如兩句話用了同一組專有名詞,意思卻不同。真的重複了沒,要讀過才知道。
如果把它寫成會失敗的測試,就會有兩種結果:要嘛為了讓測試通過去改一段本來沒問題的文字,要嘛一直加例外,直到測試失去意義。Claude Code 的最佳實務也提到,大部分準則都有例外,模型看著眼前的程式,通常比事先寫好的規則更能判斷這條準則適不適用1。所以這類規則只產生報告,交給人判斷。
我的規則是:腳本負責找,人負責判斷。報告列出來的每一條,改不改由我決定。
Claude Code 的 hooks 和權限規則怎麼擋 AI 的動作?
測試檢查的是做出來的東西;有些規則要擋的是 AI 正在做的事,等測試跑起來已經來不及。Claude Code 有兩層:
- 權限規則。在 settings 檔寫
allow、ask、deny。比對順序固定是 deny、ask、allow,先符合的決定結果,規則寫得多具體都不會改變這個順序2。例如Read(./.env)放進 deny,Claude 的讀檔工具就不能讀它。 - hooks。在固定時間點執行你寫的 shell 指令,例如每次呼叫工具之前的
PreToolUse。hook 以 exit code 2 結束,或回傳permissionDecision: "deny",這次工具呼叫就會取消,原因會回給 Claude3。hook 回傳 deny 時,就算開了bypassPermissions模式也一樣擋3。
兩層都有官方寫明的限制。Read 的 deny 規則管得到 Claude 內建的讀檔工具和 cat、sed 這類它認得的指令,管不到一支自己開檔案的 Python 或 Node 腳本;要從系統層擋住所有程式,文件建議打開沙箱2。用 prompt 或 agent 類型的 hook 是請另一個模型判斷,同樣不是確定性的;真的要擋,用 command 或 http 類型1。
我自己掛的是一個 PreToolUse hook,對象是 AI 透過 Supabase MCP 執行 SQL 的時候:
DROP、TRUNCATE這類破壞性語句:跳出 Claude Code 的確認視窗,顯示完整 SQL,我看過才放行。用 Remote Control 時,確認會送到手機上。- 一次刪太多筆的
DELETE:在資料庫裡報錯並回滾,不會真的刪下去。 - 一般的讀取和寫入:直接放行,不打斷工作。
這條規則如果只寫在 CLAUDE.md,就只是「刪資料前先問我」,模型可能判斷這次不用問。寫成 hook 之後,問不問就不歸模型決定了。
Codex 有一樣的機制嗎?
有,名稱和做法不太一樣。Codex 有三種可以擋的東西:
- hooks。事件名稱和 Claude Code 很像,
PreToolUse一樣可以回傳permissionDecision: "deny"或以 exit code 2 擋下呼叫。它涵蓋 shell 指令、apply_patch(可以用Edit、Write比對)和 MCP 工具,WebSearch這類託管工具不在內。設定寫在hooks.json或config.toml的[hooks],自己加的 hook 要先審核、信任過才會執行4。 - rules。用 Starlark 寫
prefix_rule(),依指令開頭比對,決定allow、prompt或forbidden;多條符合時取最嚴的。可以用codex execpolicy check先測規則檔。官方標示這個功能還在實驗階段5。 - 沙箱和核准。
workspace-write加on-request是有版本控制的資料夾的預設組合:工作區內可以改檔、跑指令,網路預設關閉,.git、.codex、.agents維持唯讀6。我的 Codex 就是這個組合。
Codex 的文件對 hooks 講得很直白:把它當成有用的護欄,不是完整的執行邊界;有些特殊的工具路徑可以不經過 hook;在雲端編排的情境下,hook 出錯、逾時或回傳格式不對,工具呼叫也可能照樣執行4。所以真正不能被跨過的限制,兩邊都要靠沙箱和權限,hook 是多一層。
| 要擋的東西 | Claude Code | Codex |
|---|---|---|
| 規則檔 | CLAUDE.md(模型參考) | AGENTS.md(模型參考) |
| 工具呼叫前的檢查 | PreToolUse hook | PreToolUse hook |
| 指令白名單、黑名單 | 權限規則 allow/ask/deny | rules:allow/prompt/forbidden(實驗中) |
| 系統層隔離 | 沙箱 | 沙箱模式+核准政策 |
| hook 出錯時 | 可設 onFailure: "block" 一起擋 | 雲端編排下可能照樣執行 |
來源:Claude Code 最佳實務 [1]、權限 [2]、hooks [3];Codex hooks [4]、rules [5]、核准與安全 [6]。
一條規則什麼時候該升級成測試?
我的做法依序是:
- 先用文字寫清楚。寫進
DESIGN.md、專案的 AGENTS.md 或 CLAUDE.md,寫到可以檢查的程度:用哪幾個值、哪幾個字不能出現、每頁幾個。 - 零例外、查得出來,就寫成測試。規格那一行旁邊註明「測試會擋」和測試檔名,測試檔的註解寫回規格的章節。
- 查得出來但要判斷,就寫成稽核腳本。只報告,不擋。
- 擋的是 AI 的動作,就交給 hook、權限規則或沙箱。
- 我指出一個問題,就當成一整類處理。先掃過所有同類的地方一起改,能用程式找出來的那一類就寫進測試,下一次就不用再靠我發現。
2026-11-09 我要求過一條「universal design rule」:不管是 Claude 還是 Codex 改這個網站,品牌色、動畫、圓角都要一致。目前還在提案階段、還沒實作;提出的方向是把圓角、動畫時間這些值寫成具名的 token,再用測試擋寫死的數值,而不是在規格裡多寫幾段文字。只寫成文字的規則,換一個代理、開一個新對話,就要重新賭一次它有沒有讀到。
要說明的是,這個網站部署時 Cloudflare 只跑建置(astro build),不跑測試;npx vitest run 是 AI 在 commit 之前自己跑的。所以「commit 前先跑測試」本身也是寫在規則檔裡的一條規則。
常見問題
規則檔還需要寫那些已經有測試的規則嗎?
要,但寫短一點。規則檔告訴 AI 有這條規則、為什麼、測試在哪裡;測試負責在它忘記的時候擋住。只有測試沒有說明,AI 會在測試失敗後才知道規則存在,多繞一圈。規則檔怎麼寫,可以看 CLAUDE.md、AGENTS.md 怎麼寫。
AI 會不會為了讓測試通過去改測試?
測試檔和程式一樣在 diff 裡,改了就看得到。這也是例外一定要寫在白名單、而且附原因的理由:多一行例外,審 diff 的人一眼就能看見。
我自己審的時候,會特別看測試相關的改動,但平常主要看測試結果:全部綠燈就通過。
沒有測試框架的專案要從哪裡開始?
從一支會失敗的腳本開始就好。grep 找禁用字詞、找寫死的色碼,找到就以非 0 結束,接在 commit 前或 CI 裡跑。規則多了再換成正式的測試框架。設計規則要先寫成文字的部分,可以參考 先寫設計規格再動手。
資料來源