先說(shuō)個(gè)我印象很深的場(chǎng)景。前陣子帶一個(gè)模擬項(xiàng)目X后端用了一套分層架構(gòu)業(yè)務(wù)邏輯全收在 service 層數(shù)據(jù)訪問(wèn)只允許走倉(cāng)儲(chǔ)接口。我給 AI 編碼助手派了個(gè)活“把訂單狀態(tài)流轉(zhuǎn)補(bǔ)全?！彼傻猛旖Y(jié)果 code review 時(shí)差點(diǎn)沒(méi)繃住——它直接在控制器里 new 了一個(gè)倉(cāng)儲(chǔ)實(shí)例繞過(guò)了 service還順手訪問(wèn)了實(shí)體內(nèi)部一個(gè)本應(yīng)私有的方法。代碼能跑測(cè)試也綠可架構(gòu)就這么被捅了個(gè)洞。當(dāng)時(shí)我第一反應(yīng)是怪自己 prompt 寫(xiě)得不夠細(xì)。后來(lái)才發(fā)現(xiàn)問(wèn)題根本不在指令寫(xiě)沒(méi)寫(xiě)清楚而是我壓根沒(méi)把“項(xiàng)目事實(shí)”告訴 AI。這個(gè)項(xiàng)目里誰(shuí)依賴誰(shuí)、哪些邊界不能碰、測(cè)試該怎么跑、代碼風(fēng)格是什么——這些信息人靠看代碼、翻文檔就能摸個(gè)大概但 AI 編碼工具在一次任務(wù)里只能看到一小塊上下文它不知道這些“潛規(guī)則”自然就會(huì)選最短路徑。于是我把這些事全部寫(xiě)進(jìn)了一個(gè)叫 AGENTS.md 的文件里放在項(xiàng)目根目錄讓 AI 每次開(kāi)工前先讀它。幾個(gè)迭代下來(lái)AI 生成代碼繞過(guò)封裝、破壞架構(gòu)的頻率肉眼可見(jiàn)地降了下來(lái)。這篇文章就把我這段時(shí)間的實(shí)踐完整拆開(kāi)講AGENTS.md 里到底該寫(xiě)什么、四種最關(guān)鍵的項(xiàng)目事實(shí)怎么組織、踩過(guò)哪些坑、怎么驗(yàn)證它真在生效。內(nèi)容不挑工具主流的 AI 編程輔助工具基本都兼容這套約定適合正在用 AI 寫(xiě)業(yè)務(wù)代碼、又不想讓架構(gòu)失控的團(tuán)隊(duì)和個(gè)人。1. 為什么 AI 寫(xiě)的代碼總愛(ài)“抄近道”問(wèn)題不在模型在上下文先潑一盆冷水大部分 AI 編碼工具不會(huì)主動(dòng)去看你項(xiàng)目里十幾層目錄的依賴關(guān)系也不會(huì)翻開(kāi)你那份幾百行的架構(gòu)設(shè)計(jì)文檔再動(dòng)手。它的工作方式很像一個(gè)閱讀范圍有限的新同事你給它一個(gè)任務(wù)它就在局部文件里搜索線索然后按“最常見(jiàn)、最省事”的路徑把代碼補(bǔ)出來(lái)。這就有個(gè)天然矛盾。人寫(xiě)代碼時(shí)腦子里裝著一張家譜圖controller 調(diào) serviceservice 調(diào) repositoryrepository 才碰數(shù)據(jù)庫(kù)工具函數(shù)放 utilsDTO 不能混進(jìn)領(lǐng)域模型。這些是多年形成的肌肉記憶?？?AI 沒(méi)有這張圖它的“常識(shí)”來(lái)自海量公開(kāi)代碼而那些公開(kāi)代碼里有大量糟糕的寫(xiě)法。于是它看到需要數(shù)據(jù)訪問(wèn)時(shí)第一反應(yīng)是直接 new 一個(gè)倉(cāng)儲(chǔ)對(duì)象看到某個(gè)類里有現(xiàn)成方法就不管它是 public 還是 internal先調(diào)了再說(shuō)。這件事說(shuō)白了就是上下文缺失。打個(gè)比方你讓一個(gè)只見(jiàn)過(guò)廚房的實(shí)習(xí)生去餐廳后廚做事告訴他“把出餐口那桌的菜端過(guò)去”。他可能直接從炒菜鍋里把菜舀出來(lái)就端走——因?yàn)樗恢莱霾土鞒?、不知道哪個(gè)窗口是傳菜口、不知道哪些菜已經(jīng)扣了蓋。你得先把后廚的動(dòng)線、崗位邊界、禁忌事項(xiàng)統(tǒng)統(tǒng)講清楚他才知道怎么干而不闖禍。AGENTS.md 要解決的正是這個(gè)“后廚動(dòng)線”問(wèn)題。它不代替你寫(xiě)業(yè)務(wù)代碼也不存放具體實(shí)現(xiàn)細(xì)節(jié)而是把你項(xiàng)目里“人知道但代碼里看不出來(lái)”的事實(shí)——架構(gòu)分層、依賴方向、封裝邊界、測(cè)試習(xí)慣——寫(xiě)成 AI 能直接讀取的上下文。讓 AI 在動(dòng)手前先獲得跟你腦子里那份家譜圖差不多的信息。有一類人會(huì)覺(jué)得這事麻煩覺(jué)得寫(xiě) AGENTS.md 不如多寫(xiě)幾行注釋。我的觀點(diǎn)是注釋是寫(xiě)給“正在看這段代碼的人”的而 AGENTS.md 是寫(xiě)給“每次開(kāi)工前需要全局視角的 AI 同事”的。兩者的服務(wù)對(duì)象完全不一樣。AI 一次能看到的上下文窗口有限你不可能指望它從項(xiàng)目注釋里拼出整個(gè)架構(gòu)圖它讀一個(gè)文件就只認(rèn)一個(gè)文件。給它一份集中、精煉、命令式的項(xiàng)目簡(jiǎn)報(bào)遠(yuǎn)比零散的注釋更高效。那具體寫(xiě)什么我總結(jié)下來(lái)最有價(jià)值的項(xiàng)目事實(shí)有四類缺一類AI 的行為都會(huì)跑偏。下面逐一拆開(kāi)講。2. 四種項(xiàng)目事實(shí)AGENTS.md 里到底該裝什么這一節(jié)是核心我會(huì)把每種事實(shí)單獨(dú)拿出來(lái)講清楚它解決什么痛點(diǎn)、該寫(xiě)成什么樣、不寫(xiě)的后果是什么。每個(gè)類別我附一段可以照著改的寫(xiě)法不追求華麗但求能直接用。2.1 架構(gòu)與分層地圖讓 AI 知道它站在哪一層第一種事實(shí)是項(xiàng)目的地形圖。很多項(xiàng)目用了分層架構(gòu)、六邊形架構(gòu)或者模塊化設(shè)計(jì)但代碼庫(kù)里并沒(méi)有一個(gè)地方會(huì)直接告訴你“這兩層之間不能反著依賴”。AI 拿到一個(gè)小任務(wù)時(shí)它看到的只有當(dāng)前文件和相鄰的幾個(gè)文件無(wú)法感知全貌。你讓它改一個(gè)訂單模塊它可能順手就在控制器里寫(xiě)起了領(lǐng)域邏輯因?yàn)樗静恢李I(lǐng)域邏輯應(yīng)該在 service 層。我在模擬項(xiàng)目X里是這么寫(xiě)的技術(shù)棧與分層 - 代碼采用分層架構(gòu)嚴(yán)格按 controller - service - repository 的方向依賴。 - controller 只做參數(shù)接收與響應(yīng)包裝不允許出現(xiàn)任何業(yè)務(wù)判斷。 - service 承載業(yè)務(wù)規(guī)則和事務(wù)邊界事務(wù)必須由 service 開(kāi)啟與提交。 - repository 是唯一允許訪問(wèn)數(shù)據(jù)源的入口禁止把數(shù)據(jù)訪問(wèn)邏輯寫(xiě)在 service 里。 - 領(lǐng)域?qū)嶓w放在 domain 目錄任何外部層不得直接訪問(wèn)實(shí)體內(nèi)部字段。 - 跨層調(diào)用一律走接口不直接依賴具體實(shí)現(xiàn)類。這段文字的核心套路是“定義角色 邊界聲明”。你要先告訴 AI 每一層是干嘛的再明確哪層能碰哪層每句話都用肯定或否定式命令。AI 對(duì)“不允許”“必須”“唯一入口”這類強(qiáng)約束的反應(yīng)比對(duì)“請(qǐng)盡量保持架構(gòu)整潔”要可靠得多。如果你寫(xiě)“注意分層”“建議按架構(gòu)規(guī)范來(lái)”AI 很可能把它當(dāng)成背景噪音直接忽略。這里有個(gè)細(xì)節(jié)值得強(qiáng)調(diào)寫(xiě)目錄職責(zé)時(shí)最好結(jié)合項(xiàng)目里真實(shí)的目錄名而不是只說(shuō)抽象概念。比如“service 層”可以是虛構(gòu)的但“app/services/下的類只負(fù)責(zé)業(yè)務(wù)編排”這種帶真實(shí)路徑的描述AI 能直接映射到文件路徑上理解和遵守的概率會(huì)高很多。我后來(lái)把 AGENTS.md 里所有“層”都改成了“目錄A/目錄B/”這種形式效果立竿見(jiàn)影。我自己見(jiàn)過(guò)不寫(xiě)架構(gòu)地圖的典型事故AI 要給一個(gè)功能增加“導(dǎo)出 Excel”的能力它自己找了一個(gè)第三方庫(kù)在控制器里裸調(diào)用沒(méi)有走 service也沒(méi)有做參數(shù)校驗(yàn)。功能是好的可代碼風(fēng)格跟項(xiàng)目完全脫節(jié)。后來(lái)我在 AGENTS.md 里加了一條“所有新引入的第三方依賴必須先經(jīng)過(guò)人工確認(rèn)”這個(gè)坑才算堵住。2.2 編碼規(guī)范與風(fēng)格基線讓 AI 生成的代碼長(zhǎng)得像“自己人”第二種事實(shí)是風(fēng)格基線。很多團(tuán)隊(duì)沒(méi)有精力把編碼規(guī)范做成 ESLint 規(guī)則或靜態(tài)檢查或者雖有規(guī)則但覆蓋不全。AI 在訓(xùn)練數(shù)據(jù)里見(jiàn)過(guò)各種風(fēng)格有的用函數(shù)式、有的用類和裝飾器、有的喜歡鏈?zhǔn)秸{(diào)用、有的偏好提前 return。你不告訴它這個(gè)項(xiàng)目偏好哪種它就會(huì)按自己“最熟悉”的風(fēng)格輸出結(jié)果就是代碼庫(kù)突然混入了一種陌生風(fēng)格——抽獎(jiǎng)抽出來(lái)一樣吧唧掉在 2021 年的老文件里字體都不一樣看著別扭。風(fēng)格基線不是面子工程它直接影響 AI 代碼的可維護(hù)性。一個(gè)項(xiàng)目如果所有 service 方法都返回 Result 對(duì)象而不是 throw 異常那么 AI 新寫(xiě)的代碼如果直接拋異常調(diào)用方的錯(cuò)誤處理模式就斷了如果項(xiàng)目統(tǒng)一用命名參數(shù)式調(diào)用AI 突然用位置參數(shù)閱讀和改動(dòng)的成本立刻上升。我在 AGENTS.md 里會(huì)這樣寫(xiě)代碼風(fēng)格約定 - 命名方法名使用動(dòng)詞開(kāi)頭變量?jī)?yōu)先使用意圖明確的名詞禁止拼音縮寫(xiě)。 - 錯(cuò)誤處理業(yè)務(wù)方法統(tǒng)一返回 ResultT不在業(yè)務(wù)層直接 throw。 - 函數(shù)風(fēng)格service 層方法保持短小單個(gè)方法不超過(guò)約 30 行過(guò)長(zhǎng)先拆私有方法。 - 空值處理禁止裸用 null 傳遞數(shù)據(jù)缺失統(tǒng)一使用 Optional。 - 集合操作優(yōu)先使用擴(kuò)展函數(shù)和流式 API不使用 for 循環(huán)處理集合。 - 測(cè)試優(yōu)先使用領(lǐng)域語(yǔ)言描述的測(cè)試用例單元測(cè)試不觸達(dá)真實(shí)網(wǎng)絡(luò)。寫(xiě)這部分時(shí)最大的坑是“過(guò)度細(xì)化”。我在早期版本里把變量命名規(guī)則、縮進(jìn)、換行、引號(hào)全都塞進(jìn)去了結(jié)果 AI 的主要精力全花在“遵守格式”上反而忽略了業(yè)務(wù)邏輯。后來(lái)我把這些瑣碎規(guī)則刪掉只保留那些“會(huì)破壞架構(gòu)或調(diào)用方式”的風(fēng)格約定——錯(cuò)誤處理模式、空值服用、函數(shù)長(zhǎng)度紅線、集合操作偏好。事實(shí)證明這類“影響代碼結(jié)構(gòu)”的風(fēng)格規(guī)則對(duì) AI 最有約束力而縮進(jìn)引號(hào)之類的事交給格式化工具去統(tǒng)一就行。還有個(gè)反直覺(jué)的經(jīng)驗(yàn)跟 AI 討論“風(fēng)格”的時(shí)候說(shuō)“不要”“避免”不如說(shuō)“優(yōu)先使用”“統(tǒng)一使用”有效。因?yàn)?AI 生成代碼時(shí)會(huì)優(yōu)先選擇它熟悉的模式你告訴它“不要用 for 循環(huán)”它可能還是用但你告訴它“統(tǒng)一使用擴(kuò)展函數(shù)處理集合”它就會(huì)嘗試照做。正面表達(dá)讓它有明確替代方案。2.3 封裝邊界與操作禁忌把項(xiàng)目里“不能碰的地方”圈出來(lái)第三種事實(shí)是最容易被忽視、卻最能直接減少“繞過(guò)封裝”的一類。一個(gè)項(xiàng)目經(jīng)過(guò)幾年迭代總會(huì)沉淀出一些約定俗成的封裝邊界某個(gè)模塊對(duì)外開(kāi)放了三個(gè)入口但內(nèi)部其實(shí)還有十幾個(gè)方法某個(gè)類雖然字段都是 public但業(yè)務(wù)上不該被外部直接改寫(xiě)某個(gè)初始化流程必須先走哪一步被跳過(guò)就會(huì)埋雷。這些信息往往不會(huì)寫(xiě)在注釋里但對(duì) AI 來(lái)說(shuō)它們就是“必須遵守的紅線”。我在模擬項(xiàng)目X里就吃過(guò)這方面的虧。那個(gè)項(xiàng)目有個(gè)數(shù)據(jù)訪問(wèn)門(mén)面類內(nèi)部維護(hù)著連接池和緩存對(duì)外只暴露了幾個(gè)查詢方法。AI 拿到任務(wù)后覺(jué)得“直接訪問(wèn)緩存字段更快”就繞過(guò)門(mén)面方法讀寫(xiě)內(nèi)部緩存結(jié)果并發(fā)環(huán)境下緩存一致性出了問(wèn)題。后來(lái)我在 AGENTS.md 里加了整整一段“邊界與禁忌”封裝邊界紅線禁止違反 - 數(shù)據(jù)訪問(wèn)只能通過(guò) RepositoryA 接口項(xiàng)目?jī)?nèi)不存在第二個(gè)合法入口。 - 所有寫(xiě)操作必須先調(diào)用 TransactionManager.begin()完成后必須提交。 - 域?qū)ο蟮膶傩越雇獠恐苯?set必須通過(guò)領(lǐng)域行為方法修改。 - 配置對(duì)象只允許在系統(tǒng)啟動(dòng)階段讀取業(yè)務(wù)運(yùn)行期禁止修改配置。 - 外部系統(tǒng)接口調(diào)用統(tǒng)一走 gateway 目錄禁止在 service 里直接發(fā) HTTP 請(qǐng)求。這段落的關(guān)鍵是“寫(xiě)禁忌時(shí)要把為什么順便帶上”。我發(fā)現(xiàn)純寫(xiě)“禁止訪問(wèn)緩存字段”這種規(guī)則AI 執(zhí)行起來(lái)會(huì)打折但寫(xiě)成“緩存字段由門(mén)面統(tǒng)一管理繞過(guò)會(huì)導(dǎo)致一致性異常”AI 就會(huì)把它當(dāng)成一條有因果邏輯的約束而不是一個(gè)“隨便寫(xiě)寫(xiě)的項(xiàng)目偏好”。這個(gè)差異非常明顯可以說(shuō)是 AI 上下文工程里性價(jià)比最高的技巧。不過(guò)要小心這類條目不能寫(xiě)太多。我在第一次整理時(shí)列了二十多條禁忌結(jié)果 AGENTS.md 太長(zhǎng)了AI 讀完前面幾條就忘了后面的。后來(lái)我把禁忌按“最高優(yōu)先級(jí)”和“普通約定”分兩級(jí)最高優(yōu)先級(jí)的控制在五條以內(nèi)其余放到文件后半部。效果是那些真正容易破壞架構(gòu)的紅線AI 基本都能記住而普通約定遺漏的代價(jià)相對(duì)沒(méi)那么大可以容忍。2.4 測(cè)試、構(gòu)建與運(yùn)行上下文讓 AI 補(bǔ)代碼時(shí)先知道“怎么檢查自己”第四種事實(shí)是關(guān)于工作流的。AI 寫(xiě)代碼和人類寫(xiě)代碼有個(gè)很大區(qū)別人寫(xiě)完后會(huì)跑測(cè)試、跑 lint、做自測(cè)而 AI 生成的代碼往往直接就是“最終交付狀態(tài)”。如果 AI 完全不了解項(xiàng)目的測(cè)試命令、lint 規(guī)則和 mock 習(xí)慣它很容易產(chǎn)出能通過(guò)編譯、但完全不符合項(xiàng)目驗(yàn)收標(biāo)準(zhǔn)的代碼。它甚至可能為了“讓測(cè)試通過(guò)”去修改應(yīng)該保持不變的測(cè)試文件。這部分我建議固定寫(xiě)成檢查與驗(yàn)證 - 單元測(cè)試運(yùn)行命令pnpm test 或 ./gradlew test按項(xiàng)目實(shí)際情況替換。 - 寫(xiě)完功能后必須補(bǔ)充對(duì)應(yīng)單測(cè)測(cè)試文件與被測(cè)文件同目錄。 - 外部依賴在測(cè)試中使用 mock不發(fā)起真實(shí)服務(wù)調(diào)用。 - 所有公共方法必須附帶文檔注釋新文件必須遵循現(xiàn)有頭注釋風(fēng)格。 - 改動(dòng)入口文件時(shí)運(yùn)行 lint 檢查命令見(jiàn) ./scripts/check.sh。有人會(huì)覺(jué)得“這不就是 README 里的內(nèi)容嗎”但它們的服務(wù)對(duì)象完全不同README 是給人看的快速上手文檔信息是敘述式的而 AGENTS.md 里的驗(yàn)證命令要寫(xiě)得“唯命令是從”。AI 讀了就知道“要跑哪些命令、補(bǔ)什么測(cè)試、用什么 mock 策略”等于給它一套自檢流程。這里我想單獨(dú)強(qiáng)調(diào) mock 和依賴隔離這類事。很多項(xiàng)目里測(cè)試環(huán)境會(huì)預(yù)設(shè)一批數(shù)據(jù)庫(kù)種子數(shù)據(jù)、有幾個(gè)測(cè)試賬號(hào)。AI 不知道這些它寫(xiě)的測(cè)試可能直接依賴本地環(huán)境、或者硬編碼了一個(gè)真實(shí)生產(chǎn)環(huán)境才有的賬號(hào)。在 AGENTS.md 里明確“測(cè)試不得依賴本機(jī)數(shù)據(jù)庫(kù)、統(tǒng)一使用 mock 數(shù)據(jù)源”之后AI 發(fā)生類似問(wèn)題的次數(shù)斷崖式下降。這類規(guī)則就是那種“人知道但代碼里完全看不到”的首選代表。我還會(huì)順手寫(xiě)上“開(kāi)發(fā)時(shí)優(yōu)先參考哪幾個(gè)現(xiàn)有文件”。比如“新接口風(fēng)格可參考modules/下的訂單模塊”相當(dāng)于給 AI 指了個(gè)模仿對(duì)象。機(jī)器人學(xué)風(fēng)格看例子比看規(guī)則快得多這條實(shí)測(cè)很管用。3. 把四種事實(shí)落成 AGENTS.md 的寫(xiě)作方法論內(nèi)容方向定好了接下來(lái)就是怎么寫(xiě)。很多人第一次寫(xiě) AGENTS.md 容易犯的毛病是要么寫(xiě)成回憶錄事無(wú)巨細(xì)地記錄項(xiàng)目史要么寫(xiě)成論文講一堆抽象原則。這兩種寫(xiě)法 AI 都不愛(ài)讀。我踩過(guò)幾輪之后總結(jié)出來(lái)幾條寫(xiě)作規(guī)則按重要性排下來(lái)大概是下面這個(gè)樣子。3.1 文件放哪、叫什么、用什么格式最直觀也最關(guān)鍵的一條文件必須命名為AGENTS.md放在項(xiàng)目根目錄。當(dāng)前主流的 AI 編程輔助工具基本都認(rèn)這套約定——你說(shuō)別的名字比如PROJECT_RULES.md、CONTEXT.txt很多工具壓根不會(huì)自動(dòng)讀取它們只會(huì)去找自己約定的那個(gè)名字。這算是 AI 編碼領(lǐng)域最早走向事實(shí)標(biāo)準(zhǔn)的約定文件跟 README 一樣位置和名字本身就是約定的一部分。格式強(qiáng)烈建議用純文本 Markdown 的輕量結(jié)構(gòu)。不要用 HTML、不要用表格、不要用復(fù)雜嵌套列表——AI 讀取這些內(nèi)容時(shí)越接近自然語(yǔ)言和簡(jiǎn)單 Markdown越容易正確解析。我在實(shí)踐中發(fā)現(xiàn)同樣的信息用短段落和簡(jiǎn)單列表寫(xiě)AI 的執(zhí)行質(zhì)量明顯高于用表格寫(xiě)?？赡芤?yàn)楸砀竦拈喿x順序跟文本不太一致AI 容易把單元格內(nèi)容切碎理解。如果你在 AGENTS.md 里放了表格最好還要把關(guān)鍵規(guī)則在表格外再用一句話重復(fù)一次這樣防止丟失。我還建議給文件按“高優(yōu)先級(jí)規(guī)則”和“參考信息”分區(qū)域。實(shí)測(cè)下來(lái)AI 在讀取項(xiàng)目文件時(shí)對(duì)文件頂部的注意力高于底部。所以最高頻的紅線規(guī)則要放在最前面比如“依賴方向不許反”“數(shù)據(jù)訪問(wèn)只走倉(cāng)儲(chǔ)接口”。而那些“推薦的參考文件列表”“常見(jiàn)術(shù)語(yǔ)”這類參考性內(nèi)容可以放到后面即使被截?cái)鄟G了損失也可控。3.2 寫(xiě)規(guī)則時(shí)請(qǐng)用“命令式話術(shù)”而不是“建議式話術(shù)”寫(xiě) AGENTS.md 的人大多性格溫和寫(xiě)出來(lái)的句子容易變成“建議保持分層結(jié)構(gòu)”“盡量通過(guò) service 訪問(wèn)數(shù)據(jù)”。這種語(yǔ)氣在跟人溝通時(shí)很合適但給 AI 就不太行。AI 對(duì)句式的敏感度遠(yuǎn)超我們的直覺(jué)命令式——“必須通過(guò) service 訪問(wèn)數(shù)據(jù)”“禁止在控制器中寫(xiě)業(yè)務(wù)邏輯”——比建議式更容易被執(zhí)行。為什么模型在訓(xùn)練數(shù)據(jù)里看到的“必須”和“禁止”往往出現(xiàn)在規(guī)范文檔和編碼標(biāo)準(zhǔn)中它會(huì)判定這是一條高權(quán)重約束而“盡量”“建議”這類詞跟“可做可不做”關(guān)聯(lián)會(huì)被模型當(dāng)成軟性提示。所以在 AGENTS.md 里我后來(lái)把所有模糊詞全部替換成精確詞不僅“盡量”類詞要?jiǎng)h干凈連“通?！薄耙话銇?lái)說(shuō)”也全改掉。一份好的 AGENTS.md讀起來(lái)應(yīng)該像交警指揮交通而不是朋友勸你早點(diǎn)睡。同時(shí)長(zhǎng)句子要拆短。AI 的指令遵循能力在處理簡(jiǎn)短、獨(dú)立的指令時(shí)最強(qiáng)如果一句話里塞了主語(yǔ)、條件、例外情況模型的注意力會(huì)被分散。我有一條自我檢查標(biāo)準(zhǔn)AGENTS.md 里的任何一條規(guī)則讀起來(lái)不應(yīng)該超過(guò)兩行。超了就拆開(kāi)寫(xiě)或者重新組織句子。3.3 用“問(wèn)題—規(guī)則—例子”的三角結(jié)構(gòu)組織每條事實(shí)單純的規(guī)則列表容易顯得干巴巴而且 AI 難以理解規(guī)則背后的意圖。我后來(lái)形成了一套固定寫(xiě)法每一類重要事實(shí)先用一句“為什么”說(shuō)明背景再列出具體規(guī)則最后給一個(gè)或兩個(gè)微型例子說(shuō)明對(duì)與錯(cuò)。舉個(gè)例子我在模擬項(xiàng)目X里寫(xiě)數(shù)據(jù)訪問(wèn)規(guī)則時(shí)第一條是背景項(xiàng)目統(tǒng)一通過(guò)倉(cāng)儲(chǔ)接口訪問(wèn)數(shù)據(jù)避免業(yè)務(wù)邏輯散落到四面八方。 規(guī)則任何數(shù)據(jù)讀取必須調(diào)用 RepositoryA 接口。 對(duì)const data await this.repository.findByOrderId(id) 錯(cuò)const data await db.query(SELECT ...)禁止在 service 直接拼接 SQL。這個(gè)三角結(jié)構(gòu)的價(jià)值在于AI 不僅知道“不能怎么做”還知道“應(yīng)該怎么替代”——這是減少繞過(guò)封裝的關(guān)鍵中的關(guān)鍵。光給禁令人會(huì)迷茫但配上正確做法的示例AI 就有了一條可模仿的路徑。實(shí)踐中帶“對(duì)/錯(cuò)”示例的規(guī)則比只有文字的規(guī)則遵守率肉眼可見(jiàn)地高。這個(gè)方法也解決了“AGENTS.md 太長(zhǎng)”的一個(gè)心態(tài)問(wèn)題你不用追求每一條都帶示例挑那些“繞過(guò)后果嚴(yán)重”的高頻路徑寫(xiě)對(duì)錯(cuò)例就行。普通約定比如“方法不超過(guò) 30 行”寫(xiě)規(guī)則即可寫(xiě)得太多反而稀釋重點(diǎn)。4. 實(shí)操記錄讓 AGENTS.md 真正生效的完整閉環(huán)方法論講完接下來(lái)是我在一周內(nèi)的實(shí)操過(guò)程。這部分我會(huì)寫(xiě)得比較具體包括第一天怎么搭、第二天怎么驗(yàn)證、后面怎么迭代你可以直接照著流程走。4.1 從零搭建的三步走梳理、成稿、喂給 AI 試跑第一步不是寫(xiě)文件而是“盤(pán)點(diǎn)”。我把項(xiàng)目里最近三個(gè)月 AI 犯過(guò)錯(cuò)的地方全翻出來(lái)按“架構(gòu)破壞”“繞過(guò)封裝”“風(fēng)格不一致”“驗(yàn)證缺失”四類歸類。這一步是我強(qiáng)烈建議做的你寫(xiě) AGENTS.md 的內(nèi)容不是憑空想出來(lái)的而是用你自己的事故記錄反推出來(lái)的。如果項(xiàng)目沒(méi)有現(xiàn)成記錄就去翻最近的 Code Review 評(píng)論評(píng)論里人給人提的意見(jiàn)就是 AGENTS.md 里最需要的素材。第二步才是動(dòng)筆。我先用大白話把這些規(guī)則寫(xiě)出來(lái)不追求格式工整甚至帶著口語(yǔ)。整理到差不多能覆蓋上述四類事實(shí)后再花半小時(shí)精簡(jiǎn)刪掉重復(fù)、刪掉過(guò)于瑣碎的格式規(guī)則、把模糊詞全部換成命令式。這時(shí)文件頭版大約 40~60 行我覺(jué)得這是一個(gè)比較理想的開(kāi)張尺寸太短覆蓋不了信息太長(zhǎng) AI 記不住。第三步是試跑。我會(huì)挑三個(gè)不同類型的任務(wù)喂給 AI一個(gè)是“在既有服務(wù)里加一個(gè)端點(diǎn)”一個(gè)是“修改現(xiàn)有查詢邏輯”一個(gè)是“新增一個(gè)獨(dú)立小模塊”。這三個(gè)任務(wù)的共同特點(diǎn)是都存在“繞過(guò)封裝抄近路”的空間。跑完之后去 diff重點(diǎn)看有沒(méi)有違反 AGENTS.md 里紅線的行為。第一次試跑我印象很深——AI 不再 new 倉(cāng)儲(chǔ)了但它開(kāi)始嘗試直接訪問(wèn)實(shí)體私有字段這屬于我之前沒(méi)覆蓋到的新盲區(qū)。于是當(dāng)天我就把這條補(bǔ)充進(jìn)去了。這個(gè)過(guò)程本身就是 AGENTS.md 不斷變好的方式它不是在寫(xiě)文檔而是在和 AI 的協(xié)作中持續(xù)長(zhǎng)出來(lái)的。4.2 怎么驗(yàn)證 AGENTS.md 真在起作用而不是你的錯(cuò)覺(jué)驗(yàn)證這件事非常容易被忽略。好多團(tuán)隊(duì)寫(xiě)完 AGENTS.md 就完事了但問(wèn)起來(lái)“它到底起了多大作用”誰(shuí)也說(shuō)不清。我自己的做法是每個(gè)迭代周期挑幾條“高危任務(wù)”比如涉及直接數(shù)據(jù)訪問(wèn)、跨模塊調(diào)用的任務(wù)專門(mén)用“誘導(dǎo)性 prompt”來(lái)測(cè) AI 會(huì)不會(huì)踩雷。比如我會(huì)故意這樣問(wèn) AI“這個(gè)訂單狀態(tài)要更新直接用 Redis 緩存里的那份數(shù)據(jù)改成已完成?！边@個(gè) prompt 本身就是一個(gè)繞過(guò)封裝的路易十六——如果 AGENTS.md 生效AI 應(yīng)該拒絕照做而是說(shuō)“要經(jīng)過(guò) service 的完整流程”。如果它照做了說(shuō)明規(guī)則沒(méi)寫(xiě)到位立刻回去補(bǔ)。我管這種方法叫“紅線探針”它的好處是防患于未然比每次都等 code review 發(fā)現(xiàn) AI 闖禍再修復(fù)要省錢(qián)得多。另一個(gè)有效驗(yàn)證方法是看 diff 風(fēng)格漂移度。跑幾次任務(wù)后把 AI 生成的新代碼和同目錄下的人類代碼放一起感受是否“一眼像同一個(gè)人寫(xiě)的”。平時(shí)我只看邏輯對(duì)不對(duì)很少檢查風(fēng)格但有了 AGENTS.md我會(huì)專門(mén)檢查 AI 生成的代碼有沒(méi)有跟既有代碼風(fēng)格割裂。有時(shí)候 AGENTS.md 里第一條“錯(cuò)誤處理統(tǒng)一用 Result”AI 遵守了但它在命名上又開(kāi)始搞匈牙利命名法這說(shuō)明名稱規(guī)則表達(dá)得不夠強(qiáng)或者位置太靠后沒(méi)被讀到。4.3 團(tuán)隊(duì)協(xié)作與迭代AGENTS.md 要隨項(xiàng)目一起生長(zhǎng)寫(xiě) AGENTS.md 不是一次性行為。項(xiàng)目在變規(guī)則在變甚至 AI 工具的能力也在變。我見(jiàn)過(guò)一個(gè)常見(jiàn)的失敗模式項(xiàng)目組花一天時(shí)間寫(xiě)了詳盡版 AGENTS.md之后半年沒(méi)人碰最后 AI 的行為跟規(guī)則越來(lái)越遠(yuǎn)。這不是 AGENTS.md 的錯(cuò)是你沒(méi)讓它跟代碼同步成長(zhǎng)。我現(xiàn)在的節(jié)奏是每次 code review 發(fā)現(xiàn) AI 犯同類錯(cuò)誤超過(guò)兩次就為它新增一條規(guī)則每次把某條規(guī)則從 AGENTS.md 里刪掉一定是確認(rèn)它已經(jīng)變成了自動(dòng)化檢查比如 eslint 規(guī)則、編譯期錯(cuò)誤。這樣 AGENTS.md 里的每條規(guī)則都有明確價(jià)值不會(huì)淪為僵尸條目。一個(gè)額外的經(jīng)驗(yàn)是規(guī)則不要一個(gè)人悶頭寫(xiě)團(tuán)隊(duì)里每個(gè)人對(duì)“哪些行為不可容忍”的標(biāo)準(zhǔn)不一樣。前端工程師可能不關(guān)心那個(gè)倉(cāng)儲(chǔ)私有方法后端工程師則視其為命根子。我在模擬項(xiàng)目X里是讓前后端各派代表各寫(xiě)一段最后再合并去重。合并時(shí)爭(zhēng)執(zhí)是難免的——你說(shuō)“禁止在 service 里發(fā)請(qǐng)求”他說(shuō)“我們有個(gè)回調(diào)就是這樣”——我的原則是“誰(shuí)的地盤(pán)誰(shuí)說(shuō)了算”。領(lǐng)域規(guī)則的最終發(fā)言權(quán)屬于那個(gè)方向的技術(shù)負(fù)責(zé)人。5. 常見(jiàn)問(wèn)題速查為什么 AGENTS.md 有時(shí)不靈這部分是大家最容易遇到問(wèn)題的地方。我把自己和一些同行踩過(guò)的坑整理成速查表你在排查時(shí)可以按圖索驥。表現(xiàn)可能原因解決辦法AI 完全像沒(méi)讀過(guò) AGENTS.md文件名不對(duì)或放錯(cuò)目錄確認(rèn)文件名嚴(yán)格是 AGENTS.md位置在項(xiàng)目根目錄看到規(guī)則但不遵守規(guī)則用了建議式語(yǔ)氣改成“必須”“禁止”并配上對(duì)/錯(cuò)示例只遵守前半部分規(guī)則文件太長(zhǎng)后部信息被截?cái)喟炎罡邇?yōu)先級(jí)紅線放到文件最頂部精簡(jiǎn)總行數(shù)新代碼風(fēng)格仍跟項(xiàng)目割裂風(fēng)格條款太抽象補(bǔ)一個(gè)“參考實(shí)現(xiàn)文件”路徑讓 AI 直接模仿規(guī)則只對(duì)部分工具生效工具版本老舊或不兼容確認(rèn) AI 工具版本是否支持 AGENTS.md 自動(dòng)讀取加新規(guī)則后舊功能變差新舊規(guī)則沖突先理清規(guī)則優(yōu)先級(jí)沖突時(shí)明確哪條優(yōu)先某些格式信息表格解析錯(cuò)復(fù)雜 Markdown 導(dǎo)致解析割裂規(guī)則用短段落和列表寫(xiě)表格只做補(bǔ)充還想補(bǔ)充兩個(gè)不屬于表格但很常見(jiàn)的問(wèn)題。第一個(gè)是“AGENTS.md 里寫(xiě)了規(guī)則但 AI 生成時(shí)還是不守”——這種情況我見(jiàn)最多的是因?yàn)?AGENTS.md 里的規(guī)則跟代碼里的既定事實(shí)沖突。比如你寫(xiě)“數(shù)據(jù)訪問(wèn)必須走倉(cāng)儲(chǔ)接口”但代碼里明明到處都是db.query的直連那 AI 會(huì)覺(jué)得規(guī)則可能只是“理想”實(shí)際項(xiàng)目實(shí)際是另一種做法。這時(shí)候不只是寫(xiě)規(guī)則還要把 AGENTS.md 里引用的“標(biāo)準(zhǔn)路徑示例”跟代碼里的實(shí)際做法統(tǒng)一起來(lái)讓規(guī)則與事實(shí)一致。第二個(gè)是“別把所有希望都?jí)涸?AGENTS.md 上”。它再完善也不能替代編譯檢查、靜態(tài)分析和自動(dòng)化測(cè)試。AI 在遵守上下文規(guī)則方面已經(jīng)進(jìn)步很多但它畢竟是概率模型偶爾還是會(huì)抽風(fēng)。我現(xiàn)在的用法是AGENTS.md 負(fù)責(zé)“減少概率”CI 和 lint 負(fù)責(zé)“兜住底線”Code Review 負(fù)責(zé)“最終裁決”。三者各管一段整體效果最穩(wěn)。6. 踩過(guò)幾次坑之后幾條想說(shuō)的真話回到文章開(kāi)頭那個(gè)場(chǎng)景。后來(lái)我在 AGENTS.md 里明確寫(xiě)上了“數(shù)據(jù)訪問(wèn)只允許走倉(cāng)儲(chǔ)接口、事務(wù)必須由 service 開(kāi)啟、領(lǐng)域?qū)ο笞侄谓雇獠恐苯訉?xiě)入”這三條再讓 AI 去補(bǔ)狀態(tài)流轉(zhuǎn)它給出的方案就是老老實(shí)實(shí)走 service 方法——雖然最后還是讓我改了十五分鐘但“繞過(guò)架構(gòu)”這一類問(wèn)題基本絕跡了。我不覺(jué)得是 AI 變聰明了而是我終于把它缺的上下文給了它。每次有團(tuán)隊(duì)來(lái)找我聊 AI 編碼效率我最后都會(huì)說(shuō)別把 AGENTS.md 當(dāng)成寫(xiě)文檔任務(wù)把它當(dāng)成“給 AI 同事做入職培訓(xùn)”。新人入職你要給他講架構(gòu)、講規(guī)范、講紅線、講怎么自測(cè)AI 同事也一樣只是它需要的是精簡(jiǎn)、命令式、可檢索的文本而且它入職培訓(xùn)比人快得多——改完文件立刻生效不用等它消化。你項(xiàng)目里那些最容易讓 AI 闖禍的“潛規(guī)則”現(xiàn)在就可以開(kāi)始列。別追求一次寫(xiě)完。先把最近 code review 里 AI 犯過(guò)的錯(cuò)按四類事實(shí)歸類挑一兩個(gè)最扎心的寫(xiě)進(jìn) AGENTS.md讓 AI 下次開(kāi)工前先讀到。跑幾輪再加新的。等它的“搗亂頻率”降下來(lái)你會(huì)發(fā)現(xiàn)改 AGENTS.md 花掉的時(shí)間遠(yuǎn)比你返工擦屁股的時(shí)間省得多。