外觀

語言

高效 AI 駕馭術

AI 不照 CLAUDE.md、AGENTS.md 的規則做怎麼辦?把規則寫成測試和 hooks(2026)

規則檔只是給模型讀的建議。哪些規則該交給測試擋、哪些只列報告讓人判斷、哪些要用 Claude Code 和 Codex 的 hooks、權限規則擋在工具層,附我網站上的實際例子。

Kelvin Wang · · 10 分鐘閱讀

重點整理

  1. 每條規則先用文字寫清楚;寫得清楚,才分得出它該由誰執行。
  2. 零例外、程式查得出來的規則寫成測試,失敗就不算完成。
  3. 需要判斷的規則寫成稽核腳本,只列報告,由人決定改不改。
  4. 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 的動作本身刪表、清空資料表、讀 .envhooks、權限規則、沙箱動作執行前就擋下或要我確認

這個網站的 repo 現在有 81 個測試檔,大部分是一般的功能測試,其中一批專門守 DESIGN.md 和交易所專區規格裡的規則。DESIGN.md 對整個 repo 有約束力,專案的 CLAUDE.md 第一條就要求改畫面前先讀它。規則和測試互相指:規格寫「測試會擋」並寫出檔名,測試檔開頭的註解寫它對應規格的哪一節。

把規則寫成測試長什麼樣子?

最清楚的例子是麵包屑。DESIGN.md 規定:首頁以外的每個公開頁都有一條麵包屑,元件同時輸出看得到的導覽列和 schema.org 的 BreadcrumbList;頁面不要自己再寫一份,每頁剛好一個。

對應的測試是 tests/exchanges-breadcrumbs.test.ts。它不是挑幾頁檢查,而是把 src/pages/zh-hant/exchanges/ 底下每個路由檔都找出來,展開成每個交易所、每個事件的實際網址,一頁一頁渲染,再檢查三件事:

  1. 剛好一份 BreadcrumbList。多一份、少一份都失敗。
  2. 第一層是首頁。
  3. 最後一層是這一頁自己的網址。

新增的交易所頁不用改測試就會被檢查到。如果新頁的網址多了一個新的動態參數,測試會直接失敗,訊息寫明要在哪裡補測試資料。「新頁面忘了麵包屑」這類問題,不用靠 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 CodeCodex
規則檔CLAUDE.md(模型參考)AGENTS.md(模型參考)
工具呼叫前的檢查PreToolUse hookPreToolUse hook
指令白名單、黑名單權限規則 allow/ask/denyrules:allow/prompt/forbidden(實驗中)
系統層隔離沙箱沙箱模式+核准政策
hook 出錯時可設 onFailure: "block" 一起擋雲端編排下可能照樣執行

來源:Claude Code 最佳實務 [1]、權限 [2]、hooks [3];Codex hooks [4]、rules [5]、核准與安全 [6]。

一條規則什麼時候該升級成測試?

我的做法依序是:

  1. 先用文字寫清楚。寫進 DESIGN.md、專案的 AGENTS.md 或 CLAUDE.md,寫到可以檢查的程度:用哪幾個值、哪幾個字不能出現、每頁幾個。
  2. 零例外、查得出來,就寫成測試。規格那一行旁邊註明「測試會擋」和測試檔名,測試檔的註解寫回規格的章節。
  3. 查得出來但要判斷,就寫成稽核腳本。只報告,不擋。
  4. 擋的是 AI 的動作,就交給 hook、權限規則或沙箱。
  5. 我指出一個問題,就當成一整類處理。先掃過所有同類的地方一起改,能用程式找出來的那一類就寫進測試,下一次就不用再靠我發現。

2026-11-09 我要求過一條「universal design rule」:不管是 Claude 還是 Codex 改這個網站,品牌色、動畫、圓角都要一致。目前還在提案階段、還沒實作;提出的方向是把圓角、動畫時間這些值寫成具名的 token,再用測試擋寫死的數值,而不是在規格裡多寫幾段文字。只寫成文字的規則,換一個代理、開一個新對話,就要重新賭一次它有沒有讀到。

要說明的是,這個網站部署時 Cloudflare 只跑建置(astro build),不跑測試;npx vitest run 是 AI 在 commit 之前自己跑的。所以「commit 前先跑測試」本身也是寫在規則檔裡的一條規則。

想深入 Harness Engineering 是什麼?AI Harness 讓 AI agent 穩定做事的 7 個部分(2026) 規則變測試是 harness 的第二部分,另外還有規則檔、skill、MCP、記憶、子代理和驗收。

常見問題

規則檔還需要寫那些已經有測試的規則嗎?

要,但寫短一點。規則檔告訴 AI 有這條規則、為什麼、測試在哪裡;測試負責在它忘記的時候擋住。只有測試沒有說明,AI 會在測試失敗後才知道規則存在,多繞一圈。規則檔怎麼寫,可以看 CLAUDE.md、AGENTS.md 怎麼寫。

AI 會不會為了讓測試通過去改測試?

測試檔和程式一樣在 diff 裡,改了就看得到。這也是例外一定要寫在白名單、而且附原因的理由:多一行例外,審 diff 的人一眼就能看見。

我自己審的時候,會特別看測試相關的改動,但平常主要看測試結果:全部綠燈就通過。

沒有測試框架的專案要從哪裡開始?

從一支會失敗的腳本開始就好。grep 找禁用字詞、找寫死的色碼,找到就以非 0 結束,接在 commit 前或 CI 裡跑。規則多了再換成正式的測試框架。設計規則要先寫成文字的部分,可以參考 先寫設計規格再動手。

資料來源

  1. 1. Best practices for Claude Code · Claude Code Docs · 2026-11-17 查詢
  2. 2. Configure permissions · Claude Code Docs · 2026-11-17 查詢
  3. 3. Automate actions with hooks · Claude Code Docs · 2026-11-17 查詢
  4. 4. Hooks · OpenAI Codex Docs · 2026-11-17 查詢
  5. 5. Rules · OpenAI Codex Docs · 2026-11-17 查詢
  6. 6. Agent approvals & security · OpenAI Codex Docs · 2026-11-17 查詢

關於作者

Kelvin Wang

電機工程師,和 AI Agent 做工具,分享工程與投資的實作筆記。

更多關於我