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