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