Agent 規則檔案怎麼寫：讓 AI 生成可治理應用

先給結論：在一個 AI 寫絕大部分程式碼的世界裡，你的 agent 規則檔案（AGENTS.md、.cursor/rules、CLAUDE.md）就是你真正在生效的架構文件。只拿它管縮排和元件庫，管的是”好不好看”，不是”敢不敢上線”。把許可權、審批、審計和目標格式寫進去，才是在生成那一刻控制風險。

一個真實的小事故。某團隊的 AGENTS.md 寫得很認真：兩空格縮排、用內部 UI 庫、提交資訊用祈使句。agent 一條不落地照做，生成的程式碼”非常規範”。然後有人發現，它順手生成的 GET /api/refunds 把所有人的退款記錄都返回了。

程式碼評審時沒人攔下——因為它確實符合規則檔案裡的每一條。agent 沒違反任何規則，它只是沒被告知許可權這回事。那份規則裡，沒有一條是關於”誰能看哪些資料”的。它被教會了怎麼寫得好看，沒被教會怎麼寫得可治理。

你的規則檔案，管錯了東西

幾乎每個用 AI 寫程式碼的團隊，現在都有一份給 agent 的規則檔案。這是個好習慣。問題是它被用在了最不值錢的地方。

盤一下大多數規則檔案裡寫了什麼：程式碼風格、目錄結構、用哪個庫、命名約定、提交規範。挑不出錯，但它們有一個共同點——全是關於”程式碼長什麼樣”，沒有一條關於”這個應用被允許做什麼”。它們讓多個 agent、多次生成的產出保持一致，解決的是”長得像一家人”；完全沒碰那些決定一個企業應用能不能上線的事：誰能看哪些資料、哪些動作要審批、出了事查不查得到。

換句話說，當寫程式碼這件事交給了 AI，規則檔案就從”程式碼規範”升級成了”架構與治理的約束”——因為它是少數幾個能在生成的那一刻就把約束注入進去的地方。一旦程式碼被生成出來，再去補許可權、補審計，就是事後返工；而規則檔案是最早能把治理前置到生成階段的槓桿。

把”可治理性”寫進規則，而不是事後補

事後補治理，是當下最常見、也最貴的錯法：先讓 agent 生成，再回頭審許可權、補審計、加審批——也就是 AI Agent 試點進不了生產那篇裡說的治理返工。每生成一個應用就返工一次，規模化之後這筆賬會越來越難付。

更省的做法，是讓規則把 agent 指向一個本身就可治理的目標。一份這樣的規則，核心不是風格，是約束產出的形態：

# AGENTS.md —— 生成業務應用時
- 把領域建模為 ObjectStack 物件（ObjectSchema），不要手寫表和遷移
- 所有訪問許可權走 PermissionSet 宣告，絕不在接口裡手寫 if 判斷鑑權
- 不要手寫 SQL 拼接或鑑權中介軟體——這些由執行時承擔
- 有審批需求的動作，宣告為掛在物件上的 flow，而不是寫在程式碼裡
- 產出必須是可審查的後設資料 diff，而不是大段實現

逐條看，每一行都在把一類”事後才會爆的風險”提前關掉：第二行讓越權從”接口裡漏寫一個判斷”變成”許可權被顯式宣告、執行時強制”；第四行讓審批從”某段程式碼裡的硬邏輯”變成”掛在物件上、可被審計的流程”。在這種規則下，開頭那個 GET /api/refunds 不會再發生：agent 生成的是一個聲明瞭”按呼叫者許可權讀取”的 support_refund 物件，越權那條路從源頭就被關上了——而不是指望 agent 在某次生成裡”恰好記得”加判斷。

為什麼”讓 agent 生成 ObjectStack”是現實的：開放的飛輪

這裡有個繞不過去的問題：憑什麼 agent 能把一個特定的目標格式寫對？規則寫得再好，模型不會寫也白搭。

答案正是開放語義層那篇論證過的飛輪——agent 更容易生成它見過、能檢索到、能被規則約束的東西。一個封閉平臺的私有格式，如果公開材料少、示例少、校驗反饋弱，再怎麼寫規則也很難穩定生成。而 ObjectStack 是 Apache 2.0 的開放協議，這讓”讓 agent 寫對它”具備了三個現實前提：

可被學到：開放 + 公開 + 被討論 → 更容易被模型和檢索系統學到；
可被約束：一份規則檔案把 agent 的產出錨定到這個宣告式目標；
可在生成時校驗：執行時會校驗生成的後設資料——非法的定義直接被拒，agent 當場拿到糾錯訊號。這是自由格式程式碼給不了的關鍵差別：一段錯的 SQL 可能照樣跑、上線才爆，而一份錯的後設資料進不了門、當場就被打回重寫。

正是第 3 點，把”讓 agent 寫對”變成了有反饋的收斂過程——agent 寫錯、被拒、改對，像編譯錯誤一樣即時。更進一步，你還可以把執行時的受治理工具通過 MCP 暴露出來，讓 agent 在生成時就調取權威定義、在執行時又能在邊界內操作它——寫和用，同一套治理。（受治理工具層這件事，MCP 那篇單獨講過。）

落地：今天就能加的三條

不必一步到位重寫整份規則。如果你現在只往 agent 的規則檔案里加三條治理約束，按收益排序，應該是這三條：

“許可權必須顯式宣告，不準在程式碼裡手寫鑑權。” 這一條直接消滅開頭那種”漏寫一個判斷就洩露全表”的事故——把鑑權從”agent 是否記得”變成”聲明裡是否寫了”。
“高風險動作（動錢、發合同、刪資料）必須宣告為帶審批的流程。” 讓”該不該停下來等人”不再取決於 agent 的臨場判斷，而是一條可審計的規則。
“產出可審查的宣告，而不是大段實現；改動要能在一屏 diff 裡看完。” 這一條守住的是你自己的 Merge 按鈕——它強制 agent 交付你審得動的東西。

這三條的共同點：它們約束的都不是”程式碼怎麼寫”，而是”產出能不能被治理、被審查”。這正是規則檔案該幹、卻很少有人讓它乾的事。

先潑一盆冷水

兩點必須說清，否則就把規則檔案神化了。

第一，規則檔案管的是產出的形態，不是 agent 的判斷力。它能保證 agent 生成的是受治理的後設資料，保證不了它理解對了業務意圖。“該給客服多大的退款許可權”這種判斷，仍然要人來定、來 review——規則只是確保這個判斷有地方落、且會被強制執行，而不是散落在八千行裡。它把”該不該做”這個問題擺到你面前，但不替你回答。

第二，別把它當成”官方 SDK”。我這裡給的是一種打法、一份示例規則，不是某個一鍵安裝的官方檔案——你需要按自己的棧把它寫實、維護好。它的價值在思路：把治理前置到生成那一刻，而不是等程式碼長出來再補。

結語

AI 寫程式碼的時代，團隊之間拉開差距的，不再是誰的工程師寫得快——是誰的 agent 生成的東西敢上線。而這件事的開關，很大程度上就在那份常被拿來管縮排的規則檔案裡。

把它從”程式碼規範”升級成”可治理性約束”，再給 agent 指一個開放、宣告式、執行時能託底的目標——你生成的每一個應用，就從第一行起就是可審、可治、可擔責的。

npm i -g @objectstack/cli && os start

給你的 agent 寫上”建模為 ObjectStack 物件、許可權走宣告”，讓它生成一個退款應用——然後試著讓它越權返回全部資料，看執行時怎麼從源頭拒絕它。