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