16 萬行代碼4 個月3 個人。這三個數(shù)字放在一起很多人第一時間會問是不是在吹牛。說句實在話如果一年前有人這么跟我講我也不信。但這次項目確實做完了而且不是靠“散裝 AI Coding”碰運氣堆出來的——中途一度被亂七八糟的生成代碼拖到差點延期后來硬是把流程掰成了體系化的 AI Engineering才把 16 萬行代碼從“能跑”變成了“敢上線”。這篇文章就還原一下我們到底是怎么跑出來的哪些坑值得你繞開以及那些真正讓 AI 寫代碼變得可控的約束條件。我默認看這篇文章的讀者分兩種一種是用過 ChatGPT、Copilot 或 Cursor 寫代碼但還沒經歷過大規(guī)模項目的另一種是團隊里已經在推廣 AI Coding但對代碼質量心有余悸的技術管理者。這篇復盤對兩類人都有參考價值因為核心不是“怎么讓 AI 寫出更多代碼”而是“怎么讓 AI 寫出來的代碼能進主干”。1. 項目是怎么定到 16 萬行的規(guī)模盤點與工期測算1.1 這個項目要解決什么我們這次接的是一個供應鏈公司的統(tǒng)一數(shù)據清洗與報表平臺?？蛻糁翱?Excel 加一堆零散腳本活著每個月月底對賬讓三個人整整耗兩周而且數(shù)據口徑經常對不上。我們要做的不是簡單寫幾個報表接口而是一個完整平臺數(shù)據接入、清洗規(guī)則引擎、調度編排、權限審計、前端可視化一條鏈路全打通。一開始做需求拆解的時候每個人心里都沒底。光數(shù)據源就有 20 套異構系統(tǒng)清洗規(guī)則加起來超過 120 個模板調度層要支持 DAG 編排前端報表頁面有 30 多個還帶著權限控制和操作審計。這種體量放在傳統(tǒng)開發(fā)模式下明擺著是一個 20 人月的項目但客戶給的工期只有 4 個月我們團隊只有 3 個人兩個后端一個前端。當時就兩條路要么砍需求跟客戶重新談范圍要么把生產方式整個換掉。我們選了后者正式把 AI Coding 引入開發(fā)流程。1.2 16 萬行是怎么估算出來的很多人聽到“16 萬行”覺得是個虛數(shù)其實這是我們按模塊拆出來加總的結果。拆解的時候順手做了個代碼量預估表現(xiàn)在回看這個表基本就是整個項目的骨架模塊預估行數(shù)純手寫人日AI 輔助人日數(shù)據接入層20 套數(shù)據源適配器4.0 萬行50 人日18 人日清洗規(guī)則引擎規(guī)則模板 編排3.5 萬行45 人日16 人日前端報表與控制臺30 頁面5.0 萬行60 人日22 人日測試套件單元 集成2.5 萬行30 人日12 人日基礎設施與部署腳本、遷移腳本1.0 萬行15 人日6 人日合計16.0 萬行200 人日74 人日傳統(tǒng)估算里一個開發(fā)人員一天寫 60 到 80 行有效代碼是常態(tài)而且這還不算返工和聯(lián)調時間。200 人日意味著 3 個人不吃不喝要干 66 天以上加上需求溝通、測試修改、上線問題4 個月根本不可能。AI 輔助人日那列一開始是我們拍腦袋寫的計劃是比手寫快 2 到 3 倍。實際跑下來前期只快了 1.5 倍后期體系化之后最快到 5 倍。這個數(shù)據變化后面會詳細說。2. 散裝 AI Coding 撐不過 1 萬行三個必須轉型的信號2.1 第一個信號代碼風格割裂到沒法看項目啟動第一周我們用的是最常規(guī)的 AI Coding 方式——“遇到什么問什么生成的代碼直接粘進項目”。單看每一段AI 寫得還算像樣但合在一起就出問題了。同一個用戶實體的字段命名三個文件里出現(xiàn)了三種風格user_name、userName、username。訂單金額的計算邏輯在訂單服務里寫了一遍在報表模塊里又寫了一遍而且兩遍的舍入規(guī)則還不一致。為什么會這樣因為 AI 的每個會話都是獨立的它沒有記憶每次生成都等于“重新發(fā)明輪子”。你要是不把約束前提寫清楚它每次都會隨機決定一種實現(xiàn)方式。我后來管這叫“散裝 AI 代碼綜合癥”。代碼量小的時候感覺不明顯超過 3000 行就開始露餡你查一個字段名可能要全局搜三遍。這種割裂不只是看著不舒服它是隱形的技術債會在重構和排查問題時集中爆發(fā)。2.2 第二個信號接口漂移直接把開發(fā)卡死真正讓我意識到必須轉型的是第二個信號。項目到了第三周代碼量到了一萬多行開始出現(xiàn)跨模塊接口調整。數(shù)據層把某個函數(shù)從updateOrderStatus(orderId, status)改成了updateOrderStatus(orderId, status, operator)以支持審計字段然后服務層調用方就全亂了。AI 生成代碼的時候根本沒有全局視野。它看不到倉庫里其他文件怎么調用這個函數(shù)也不知道接口變更會影響哪些下游。我試過直接把整個目錄丟給 AI 讓它自己改結果它改了第一處調用漏了第二處第三處編譯一跑滿屏報錯。那段時間的日常就是AI 生成 1000 行人修接口引用花 800 行的精力。使用 AI 省下來的時間又被跨文件協(xié)作的返工給吃回去了。折騰了兩三次之后我明白了一件事AI Coding 的問題從來不在生成這一環(huán)而在生成之后如何跟既有倉庫保持一致。2.3 第三個信號質量不可追溯第三個信號出在 review 環(huán)節(jié)。散裝模式下AI 生成的代碼經常沒有理由——不是“沒有原因”而是“它不解釋原因”。你問它為什么這里用線程池而不用協(xié)程它給你一段含糊的“這樣可以提高性能”但具體評估邏輯完全缺失。更要命的是代碼出 bug 的時候沒法定位意圖。傳統(tǒng)代碼有 commit message、有需求單號、有 reviewer 的討論記錄能還原一段邏輯的前因后果。AI 生成的代碼就是憑空出現(xiàn)的沒有上下文沒有討論歷史出問題你只能翻代碼猜猜不出來就刪掉讓 AI 重新生成。這種“黑盒產出”在小項目里可以忍在需要長期維護的業(yè)務系統(tǒng)里就是定時炸彈。后來我們定了一條規(guī)矩AI 生成的代碼必須附帶“為什么這么寫”的說明不然不允許合入。這就是從 AI Coding 往 AI Engineering 走的起點。2.4 引爆點一次跨模塊重構所有問題集中爆發(fā)是在第一次跨模塊重構。我們要把支付狀態(tài)機的狀態(tài)字段從字符串改成枚舉本質是個很小的調整但涉及 10 個文件。當時 AI 改了 7 個漏了 3 個而且漏掉的那 3 個文件在編譯期不報錯運行期才炸——因為字符串可以隨意比較枚舉一旦對不上就直接悄悄走默認分支。這個 bug 在測試環(huán)境里卡了我們整整兩天。最后人工逐個文件排查才發(fā)現(xiàn)問題前端頁面報“支付狀態(tài)異?！焙蠖巳罩纠锟床坏饺魏螆箦e。那一刻我們都清楚靠“提示詞 復制粘貼”的散裝模式已經走到頭了。代碼量超過 1 萬行、涉及跨文件協(xié)作的時候必須給 AI 建流程、建規(guī)范、建上下文、建質檢機制也就是完整地把 AI Coding 升級成 AI Engineering。3. 體系化改造規(guī)范、上下文與多智能體協(xié)作3.1 先立規(guī)矩讓 AI 在約束里發(fā)揮轉型的第一件事不是找更好的模型而是立規(guī)矩。我們在倉庫根部放了一個AGENTS.md文件把所有 AI 生成代碼必須遵守的約束寫進去。這件事聽起來簡單實際操作挺講究內容不是“你要寫好代碼”這種廢話而是精確到“什么能做什么不能做”的硬性約定。我們當時的AGENTS.md核心內容大概是這樣的結構# 技術棧與目錄 - 后端Python 3.11 FastAPI目錄結構參考 src/ 下的 modules 劃分 - 前端React 18 TypeScript頁面組件放在 src/pages 對應路由目錄 # 編碼約束 - 禁止在路由層直接寫 SQL必須通過 repository 層訪問數(shù)據庫 - 禁止在前端組件里嵌套業(yè)務邏輯業(yè)務狀態(tài)統(tǒng)一走 hooks 或 store - 字段命名統(tǒng)一使用 snake_case數(shù)據庫層 / camelCaseAPI 層 # 過程要求 - 新增模塊必須配套單元測試覆蓋率不低于 80% - 修改接口定義必須同步更新 docs/contracts 下的接口文檔 - 生成代碼必須通過 RuffPython和 ESLint前端檢查后才能提交 # 不建議做的事 - 不建議對已有函數(shù)進行“重構式重寫”優(yōu)先復用現(xiàn)有實現(xiàn) - 不建議在代碼注釋里使用含糊描述必須寫明業(yè)務上下文和設計原因這個文件的魔力在于它不是給 AI 當參考的而是給 AI 當“憲法”的。此后每次讓 AI 生成代碼我們都會先喂一份AGENTS.md讓它按約束生成。結果非常明顯代碼風格從“五花八門”收斂到了“基本統(tǒng)一”命名割裂問題大幅緩解。而且因為約束寫清楚了AI 不再自由發(fā)揮它自己生成代碼的時候也更敢放手做因為邊界已經劃好。3.2 上下文池別讓 AI 靠瞎猜規(guī)范之后第二個問題是上下文。散裝模式下 AI 經常“一本正經地胡說八道”讓它寫一個訂單聚合接口它能給你畫出根本不存在的字段讓它對接某個數(shù)據源它給你寫一套沒有對應的適配器接口。問題根子在于AI 對項目的領域知識一無所知它只能靠訓練語料里的通用規(guī)律瞎猜。要解決這個問題就必須把項目的“上下文”主動喂給它而且這個上下文要準確、精煉、易獲取。我們做法是在倉庫里加了一個docs/contracts目錄專門放三類文檔接口契約每個 API 的路徑、入參、出參、錯誤碼定義數(shù)據字典核心實體的字段定義、類型、業(yè)務含義業(yè)務規(guī)則訂單狀態(tài)流轉、權限判定邏輯、金額計算規(guī)則生成代碼前我們會把相關的契約文檔直接塞進上下文。比如要讓 AI 寫一個“創(chuàng)建訂單”的接口就喂給它docs/contracts/order_api.md和docs/contracts/order_domain.md讓它照著這些定義寫不準自由發(fā)揮字段名和規(guī)則。這個改動帶來的效率提升非常直觀。我們把 AI 生成的“一次通過率”定義為“PR 提交后不需要人工修改邏輯、只改微小格式就能合入”的比例這條指標從 30% 直接拉到了 80% 左右。核心原因就一個AI 不再靠猜了它有據可依。3.3 多智能體分工把 AI 當團隊用不把 AI 當打字機規(guī)范和上下文就位之后我們開始玩更進階的東西多智能體協(xié)作。很多人一聽“多智能體”就覺得是噱頭但實際用下來它解決的是“單 Agent 上下文爆掉”的問題。我們的做法不是讓一個 AI 干完所有活而是把 AI 拆成四個角色接口設計器負責根據需求文檔產出 API 定義和數(shù)據結構輸出物是一份契約文檔實現(xiàn)器負責根據契約文檔寫具體實現(xiàn)代碼輸出物是符合規(guī)范的可運行代碼測試器負責為實現(xiàn)代碼補測試用例輸出物是一組可執(zhí)行的測試重構器負責在代碼合入前對質量不過關的部分做定向優(yōu)化每個角色都有明確的輸入和輸出互相之間不直接對話而是通過文件傳遞。比如“接口設計器”產出的契約文檔會放到docs/contracts/下“實現(xiàn)器”讀取這個文檔生成代碼“測試器”讀取實現(xiàn)代碼生成測試“重構器”跑完靜態(tài)檢查再把結果寫回一個報告文件。為了讓這些 AI 角色不“打架”我們還約定了一個超簡單的任務狀態(tài)機todo - in_progress - review - done規(guī)則是同一時刻只有一個角色能操作同一文件。實現(xiàn)器正在寫的文件測試器不會同時往里面塞測試代碼重構器要動的文件必須等前一個角色把狀態(tài)標記成done。這個機制低技術含量但極其有效直接把“AI 之間互相覆蓋代碼”的問題給消滅了。多智能體的另一個價值是上下文專注。單個 AI 一次處理整個 16 萬行項目必然力不從心但讓它只盯著“接口設計”或者“測試補齊”它的上下文窗口就非常充裕生成質量自然更高。這也是我們?yōu)槭裁磸娬{“分工而不是堆人”。3.4 上崗筆試讓 AI 先提交一份可合入的 PR體系化改造進行到一半的時候我們引入了一個很有意思的機制AI 上崗筆試。起因是發(fā)現(xiàn)不同模型的編碼能力差距很大同一個需求有的模型能規(guī)規(guī)矩矩地寫完并通過測試有的模型會給出一堆花活代碼但根本不遵守項目約束。總不能每次都人肉試錯于是我們設計了一套筆試流程。筆試題目的設計很簡單拿一個已經存在的內部項目切一個分支給 AI 一份需求文檔要求它在一個小時內提交一個完整的 PR。評分維度就四個維度評估方式權重規(guī)范性是否遵守 AGENTS.md 中的命名和架構約束30%測試覆蓋新增代碼是否配套測試覆蓋率是否達 80%30%可讀性變量命名、函數(shù)拆分、注釋是否清晰20%正確性編譯、測試通過且不破壞既有邏輯20%四個維度下來有的模型綜合通過率只有 30%有的能到 85%。我們直接采用通過率最高的模型作為主力其他模型留給簡單任務。筆試這件事最大的價值不是“選模型”而是反向暴露了我們的提示詞和規(guī)范文件寫得夠不夠清楚。如果模型筆試時普遍不遵守某個約束說明我們的規(guī)范表述有歧義修文檔比換模型更有效。順帶一提這也回答了一個常見問題——“ai coding 筆試”到底考什么。我的經驗是不考模型記憶力考它能不能在給定約束下交付合格工程產物。4. 質量防線AI 生成代碼憑什么敢合入主干4.1 用數(shù)據說話技術債登記表很多人擔心 AI Coding 會拉低代碼質量這個擔心不算多余。我們在項目里把質量從“拍腦袋感覺”變成“看數(shù)據說話”最核心的工具是一張技術債登記表。每周五下午我們會統(tǒng)計一次代碼倉庫里的技術債標記包含TODO、FIXME、HACK以及“繞過規(guī)范”的注釋。統(tǒng)計方式是簡單的 grep 加人工確認分類把 AI 生成的代碼里遺留的債務單獨列出來。這張表每周都會更新發(fā)布到團隊群里周次AI 代碼預計行數(shù)TODO/FIXME 數(shù)量技術債密度每千行第 3 周散裝模式1.2 萬行87 個7.3第 6 周體系化初期4.5 萬行110 個2.4第 12 周多智能體 質檢12 萬行152 個1.3技術債密度從 7.3 降到 1.3靠的不是讓 AI“別寫 TODO”而是靠 review 階段強制要求AI 生成代碼里的 TODO 必須給出兜底方案。如果是臨時的 mock 數(shù)據要注明替代實現(xiàn)是誰、大概什么時候替換如果是性能問題的妥協(xié)要注明觸發(fā)條件和后續(xù)跟蹤 issue。AI 可以把單子掛出來但必須把上下文寫清楚這樣別人接手不會一臉懵。4.2 測試覆蓋率卡點沒有測試保護的代碼等于沒有保障測試是 AI 代碼最大的軟肋。階段化之后我們定了一個硬性卡點所有新增模塊的測試覆蓋率必須高于 80%低于這個閾值的 PR 不給予合入。這條規(guī)則本身不稀奇稀奇的是執(zhí)行細節(jié)。我們讓“測試器”角色為 AI 實現(xiàn)代碼補齊測試但很快發(fā)現(xiàn)一個問題AI 自動生成的測試特別喜歡覆蓋 happy path——輸入正常數(shù)據、輸出正常結果看起來覆蓋率挺高但邊界條件全沒測。舉個例子一個金額格式化函數(shù)AI 生成的測試只測了“正常金額轉字符串”沒測“負數(shù)”“零”“超大數(shù)”“科學計數(shù)法傳入”這些邊界。覆蓋率統(tǒng)計數(shù)字可能很好看實際防護效果很有限。我們的對策是在每個模塊的測試配套里人工承擔“邊界用例設計”的角色把 AI 生成的測試跑一遍專門挑那些“我要是寫這段業(yè)務邏輯會出什么 bug”的場景補進去。這個步驟沒法完全自動化但可以把 AI 從“能寫測試”提升到“能寫有效測試”。后來又加了一條規(guī)定AI 生成測試用例時必須顯式列出“已覆蓋的邊界條件”和“未覆蓋但應該覆蓋的邊界條件”沒列說明直接打回。4.3 Diff Review 方法不看“寫了什么”看“為什么需要”AI 生成代碼量大逐行 review 不現(xiàn)實我們調整了 review 的視角。以前人肉 review 的習慣是看每一行寫得對不對現(xiàn)在改成按 diff 塊做“為什么審查”。每個 diff 必須回答三個問題這段代碼要解決什么問題為什么要在這里寫而不是在更下層或更上層寫為什么不用已有函數(shù)或已有模塊第一遍讓“重構器”角色自動跑第二遍人肉抽查。抽查比例是 30% 的 diff 塊集中在核心路徑支付、權限、數(shù)據寫操作。剩下 70% 依賴靜態(tài)檢查和測試兜底。這套方法效果很不錯它不要求 review 者逐行讀懂每一行 AI 代碼而是強迫 AI 先自證“這段代碼存在的合理性”。不合理的地方一抓一個準比如曾經發(fā)現(xiàn)一段 AI 在服務層直接用矩陣拼接的方式拼 SQL雖然能跑但完全繞開了 repository 層。按老辦法逐行看很難發(fā)現(xiàn)這種結構性問題但按“為什么”審查一眼就能看出邏輯放錯了層。4.4 人機結對復查關鍵路徑必須人工過一遍最后一道防線最傳統(tǒng)也最有效人機結對復查。AI 可以生成 16 萬行代碼但核心模塊、支付流轉、權限節(jié)點這些關鍵路徑我們還是堅持由人逐行審核并親自動手調整。我們的做法是劃定“禁區(qū)文件”名單。名單內的文件AI 可以提方案但不能直接改碼。比如支付核心、訂單狀態(tài)機、權限判定邏輯這些文件里 AI 生成的代碼全部由人工重寫或逐行確認后才能合入。這不是不信任 AI而是這些模塊一旦出錯影響的是真實業(yè)務的資金和數(shù)據安全人類需要完全掌握這部分代碼的語義和意圖。這種“AI 跑量人守核心”的方式讓我們在保證速度的同時不至于把項目存亡押在 AI 的“平均表現(xiàn)”上。到了后期禁區(qū)文件的命名和范圍逐漸縮小但心理安全感是前期就建立起來的。5. 踩坑復盤與提速數(shù)據幾個值得直接抄走的結論5.1 提速的真實曲線整個項目下來AI 輔助開發(fā)的速度變化不是一條直線而是三個階段階段模式每人力日均有效代碼行數(shù)備注第 1 階段散裝 AI Coding約 30 行含大量返工和接口修復第 2 階段規(guī)范 上下文池約 120 行一次通過率提升返工減少第 3 階段多智能體 質檢體系約 250 行分工協(xié)作各角色各司其職這個“行數(shù)”不是簡單統(tǒng)計新增行數(shù)而是統(tǒng)計“合入主干且通過測試的有效代碼”。所以它才是真實產能。如果只看新增行數(shù)散裝模式其實也不少但那些代碼有一半在返工。體系化改造本質上是把返工率降下來同時把有效產出提上去。5.2 最坑的三個場景及處理辦法第一坑是“重構老代碼”。AI 不懂老代碼背后的歷史原因它只知道“按當前需求生成”所以一旦讓它動歷史代碼經常會“好心辦壞事”。我們的處理辦法是凡是重構歷史模塊先把現(xiàn)有行為用測試固定下來再讓 AI 動刀。測試就是安全網沒有安全網的 AI 重構一律不批。第二坑是“跨模塊重命名”。AI 會漏改引用而且漏得無聲無息編譯期還發(fā)現(xiàn)不了。處理辦法是跨模塊重命名一律不依賴 AI 手動改而是用語言自帶的工具比如 TypeScript 的find-references、Python 的 IDE 重構先做機械替換再用 AI 處理邏輯調整。AI 負責“改邏輯”工具負責“改引用”職責分開。第三坑是“并發(fā)與時序邏輯”。AI 生成的并發(fā)代碼問題最多尤其是狀態(tài)同步、事務邊界、超時重試這些場景。不是 AI 不懂是它缺少運行時的細粒度反饋。我們的處理辦法簡單粗暴并發(fā)相關代碼一律交給核心開發(fā)者親自動手AI 只負責出初稿最后必須有人逐行推演一遍并發(fā)場景。5.3 給想復制這條路的人三條建議如果你正在把 AI Coding 引入團隊或者已經在路上但覺得失控我建議先做這三件事第一先做好單 Agent 的護欄再考慮多 Agent。很多人一上來就想跑多智能體但基礎規(guī)范、上下文文檔都沒建多 Agent 只會放大混亂。單 Agent 跑順、一次通過率穩(wěn)定到 70% 以上再拆角色分工。第二把“可合入”的定義寫得非常具體。不要只說“要保證質量”要寫清楚lint 通過、類型檢查通過、測試覆蓋率達到多少、必須通過哪些靜態(tài)檢查、review 必須回答哪幾個問題。AI 是一個執(zhí)行者你定義不清楚它就會默認“代碼能跑就行”。第三保留一個“不用 AI 的模塊”。我們特意留了一個核心模塊規(guī)定從設計到實現(xiàn)全人工。它的意義不是拖慢進度而是當一個“質量基準線”。 AI 生成代碼的質量到底行不行拿它跟這個基準模塊一比心中就有數(shù)。沒有基準你就只能靠感覺而感覺在工程問題里是最不可靠的東西。5.4 最后的體會做這個項目前我以為 AI Coding 的最大挑戰(zhàn)是“怎么讓 AI 生成更多代碼”。做完了才發(fā)現(xiàn)真正的挑戰(zhàn)是“怎么讓 AI 生成的代碼敢合入主干”。AI Coding 解決的是“從無到有”AI Engineering 解決的是“從有到敢用”。16 萬行這個數(shù)字沒什么值得吹的真正值錢的是后面那套約束、規(guī)范、上下文體和質檢機制。沒有它們這 16 萬行只會變成一個巨大的噩夢有了它們它才真正是一個可以被維護、被迭代、被交付的項目。我個人的習慣是每次讓 AI 動手之前先花五分鐘檢查三件事規(guī)范文檔是不是最新、相關契約文檔喂進去沒有、這次的驗收標準寫清楚了沒有。這五分鐘花得很值它決定了一小時后你是花五分鐘合并代碼還是花半天給 AI 擦屁股。希望這篇復盤能幫你在復制這條路的時候少走我們走過的彎路。