AI專家楊夕凱現(xiàn)任職高德地圖擔任智能應用與基建平臺負責人先后負責動態(tài)數(shù)據(jù)、AI 導航、智能應用及基建平臺等業(yè)務方向。其長期深耕地圖數(shù)字孿生、空間智能、AR/數(shù)字人及 AI 導航算法模型等領(lǐng)域并參與建設(shè)支撐千億級數(shù)據(jù)的端云一體化基礎(chǔ)設(shè)施與工業(yè)級 AI 研發(fā)體系。以下內(nèi)容梳理自高德技術(shù)團隊發(fā)布的超級應用 AI 原生研發(fā)模式工程實踐系列。透過這些技術(shù)分享可以清晰看到當 AI 深度參與代碼生成并由人工進行關(guān)鍵兜底時多 Agent 并行場景下的統(tǒng)一規(guī)范與倉庫級真源控制是應對 AI 代碼熵增的核心路徑。一、AI 代碼熵增多 Agent 并行生成的核心風險在 Agentic Coding 場景中AI 生成代碼的速度顯著提升但如果沒有統(tǒng)一規(guī)范約束系統(tǒng)復雜度也會同步上升。命名風格不一致、架構(gòu)模式混用、隱式依賴蔓延、重復代碼堆積都會隨著生成次數(shù)增加而累積。這類現(xiàn)象可以概括為 AI 代碼熵增代碼產(chǎn)出變快但系統(tǒng)的可維護性、可理解性和可測試性下降。對于超級應用而言這一問題更明顯。超級應用通常具備數(shù)億用戶、數(shù)百萬行代碼、數(shù)十個團隊協(xié)同的特征。單個 Agent 生成一段代碼可能沒有問題但多個 Agent 在不同時間、不同會話、不同任務中并行生成時如果缺少統(tǒng)一執(zhí)行標準產(chǎn)出物很容易偏離既有架構(gòu)約束。從工程落地的客觀規(guī)律來看控制 AI 代碼熵增的關(guān)鍵不是限制 AI 生成能力而是讓 AI 在明確的規(guī)則邊界內(nèi)生成。規(guī)范需要從寫給人看的文檔轉(zhuǎn)變?yōu)?AI 可讀取、可執(zhí)行、可驗證的工程約束。二、倉庫唯一真源把隱式知識轉(zhuǎn)化為 AI 可讀事實控制 AI 代碼熵增的第一步是建立倉庫唯一真源。傳統(tǒng)研發(fā)中架構(gòu)設(shè)計可能存在于設(shè)計文檔中業(yè)務規(guī)則可能散落在 Wiki、注釋或工程師經(jīng)驗里接口約定也可能依賴口頭溝通。這些信息對人類工程師尚且需要反復確認對 AI 則更難穩(wěn)定獲取。在楊夕凱的推動下高德技術(shù)團隊在 AI-Native 研發(fā)模式中將代碼倉庫作為系統(tǒng)事實的唯一來源。其核心思路包括三點結(jié)構(gòu)即架構(gòu)系統(tǒng)架構(gòu)通過目錄結(jié)構(gòu)、模塊劃分和依賴關(guān)系顯式表達。AI 可以通過閱讀倉庫結(jié)構(gòu)理解系統(tǒng)層級而不是依賴外部設(shè)計文檔。代碼即規(guī)則業(yè)務規(guī)則、校驗邏輯和狀態(tài)流轉(zhuǎn)盡量通過類型系統(tǒng)、接口契約和代碼實現(xiàn)表達減少散落在注釋或外部文檔中的隱式約定。文檔即約束AGENTS.md、README.md、API 契約等文檔與代碼共存于同一倉庫并作為 AI 的補充說明書。文檔不是孤立說明而是與代碼實現(xiàn)共同接受校驗。這種設(shè)計的價值在于減少 AI 的信息缺口。AI 不再需要在多個來源之間拼接上下文而是以倉庫為基準獲取事實。當答案始終存在于倉庫中時AI 生成結(jié)果的一致性才有基礎(chǔ)。三、Spec-Driven Development從修改代碼到演進規(guī)范倉庫唯一真源解決的是事實從哪里來Spec-Driven Development 解決的是 AI 如何基于事實執(zhí)行。規(guī)范驅(qū)動開發(fā)的核心是把軟件維護的重點從直接修改代碼轉(zhuǎn)向維護產(chǎn)生代碼的規(guī)范。在楊夕凱及其團隊的實踐中規(guī)范被拆成三層遞進結(jié)構(gòu)Spec定義做什么Spec 層描述需求目標、接口契約和數(shù)據(jù)模型。它是 AI 理解任務的起點。對于服務端接口Spec 需要明確字段語義、參數(shù)約束、錯誤碼和狀態(tài)流轉(zhuǎn)對于端側(cè)能力Spec 需要說明組件職責、調(diào)用前提和平臺差異。Plan定義怎么做Plan 層描述技術(shù)方案包括架構(gòu)決策、技術(shù)選型和模塊拆分。它讓 AI 在生成代碼前知道應該遵循哪條實現(xiàn)路徑而不是自由發(fā)揮。Task定義做到什么程度Task 層描述驗收標準、測試要求和輸出格式。它讓 AI 的交付結(jié)果可檢查、可驗證而不是停留在看起來完成了的狀態(tài)。這種三層結(jié)構(gòu)使 AI 生成過程具備可追溯性。當結(jié)果不符合預期時修正對象不只是代碼本身而是產(chǎn)生錯誤代碼的 Spec、Plan 或 Task。規(guī)范因此成為可持續(xù)演進的工程資產(chǎn)。四、三級分層規(guī)范全局一致與局部靈活兼顧統(tǒng)一規(guī)范并不意味著所有項目使用同一套細則。為了兼顧全局一致性和局部靈活性楊夕凱團隊采用三級分層規(guī)范模型全局規(guī)范層、項目規(guī)范層和模塊規(guī)范層。4.1 全局規(guī)范層跨項目基線標準全局規(guī)范層定義跨項目、跨團隊的基線標準是所有 AI Agent 的公共知識。其物理載體包括全局 Skills 和公用配置主要內(nèi)容包括編碼風格規(guī)范統(tǒng)一命名約定、格式化規(guī)則和目錄規(guī)范。架構(gòu)約束規(guī)范明確分層依賴規(guī)則、模塊邊界和跨模塊通信協(xié)議。安全基線規(guī)范約束密鑰管理、輸入校驗和權(quán)限檢查等最低安全要求。API 設(shè)計規(guī)范要求接口遵循 RESTful 標準并統(tǒng)一錯誤碼、版本策略和請求響應格式。全局規(guī)范的作用是讓不同 Agent、不同項目、不同任務共享同一套基礎(chǔ)標準避免每個團隊重復定義基礎(chǔ)規(guī)則。4.2 項目規(guī)范層倉庫級操作手冊項目規(guī)范層繼承全局規(guī)范并針對具體項目做定制。其物理載體是倉庫根目錄下的規(guī)范文件集合核心文件包括AGENTS.md項目全景地圖作為 AI 的導航入口。內(nèi)容控制在較短篇幅內(nèi)包含項目說明、工作規(guī)則、模塊索引和輸出格式要求。README.md面向人類的項目說明同時為 AI 提供項目背景。docs/architecture/存放架構(gòu)總覽、層級依賴規(guī)則、核心數(shù)據(jù)模型和接口契約。.agents/存放 AI 歷史決策、錯誤修復記憶和自進化信息。項目規(guī)范層的關(guān)鍵設(shè)計是AGENTS.md是地圖而不是手冊。它只做索引和指路詳細內(nèi)容通過鏈接按需加載避免一次性塞入過多上下文。4.3 模塊規(guī)范層就近參考的局部上下文模塊規(guī)范層聚焦單一模塊負責提供局部上下文。典型文件包括模塊級AGENTS.md描述模塊職責邊界、內(nèi)部依賴和特殊約束。模塊README.md說明模塊公共 API、使用示例和配置參數(shù)。AI 在執(zhí)行任務時按照從近到遠的優(yōu)先級參考規(guī)范先看模塊規(guī)范再看項目規(guī)范最后參考全局規(guī)范。這樣既能保證整體一致性也能保留模塊級靈活性。五、AGENTS.mdAI 的項目入口文件在多 Agent 協(xié)同場景中AGENTS.md承擔 AI 入口文件的角色。它可以理解為面向 AI Agent 的 README用于告訴 AI 當前倉庫是什么、有哪些模塊、應該遵循哪些規(guī)則、輸出格式是什么。在楊夕凱主導的實踐中AGENTS.md有幾個明確設(shè)計原則短小清晰項目級AGENTS.md控制在約 100 行以內(nèi)避免占用過多上下文窗口。導航優(yōu)先不堆疊全部細節(jié)而是提供模塊導航索引和關(guān)鍵規(guī)則入口。按需加載詳細架構(gòu)、接口契約和測試要求通過鏈接指向具體文檔AI 根據(jù)任務需要讀取。與代碼同倉維護AGENTS.md與代碼一起演進避免文檔長期落后于實現(xiàn)。這種設(shè)計讓 AI 進入倉庫后能夠快速建立項目認知。對于多 Agent 并行生成場景統(tǒng)一入口文件還能減少不同 Agent 因理解路徑不同而產(chǎn)生的輸出差異。六、端云同倉讓 AI 具備全棧上下文端云一體是楊夕凱團隊規(guī)范體系中的另一個關(guān)鍵設(shè)計。傳統(tǒng)研發(fā)中客戶端與服務端往往分屬不同倉庫、不同技術(shù)棧和不同團隊。對人類工程師而言這種拆分可以通過溝通和文檔彌補但對 AI Agent 而言跨倉庫上下文缺失會直接影響生成質(zhì)量。端云同倉的目標是將客戶端能力、云端服務、共享類型定義和基礎(chǔ)設(shè)施配置納入同一個工程體系中。這樣 AI 可以在一次上下文中理解完整鏈路而不是只看到局部代碼。端云同倉帶來的工程收益主要包括AI 可以跨越端云邊界追蹤類型定義和接口契約。AI 在修改服務端接口時可以同步感知客戶端調(diào)用邏輯。AI 可以發(fā)現(xiàn)并消除端云之間的冗余定義和不一致性。AI 能夠基于全局視角進行接口設(shè)計和影響面分析。對于超級應用來說端云同倉不是簡單地把代碼放進一個目錄而是要求統(tǒng)一構(gòu)建工具鏈、依賴管理、測試框架和發(fā)布流程。只有工程治理也統(tǒng)一AI 才能用一套規(guī)則操作整個系統(tǒng)。七、自文檔化代碼降低 AI 的理解成本規(guī)范最終要落到代碼層面。為了讓 AI 生成結(jié)果穩(wěn)定代碼本身需要具備自文檔化能力即通過命名、類型、接口和依賴表達清晰語義。該團隊在代碼級規(guī)范中強調(diào)幾個要點7.1 語義化命名變量、函數(shù)和類型名稱需要完整表達意圖避免縮寫和模糊命名。例如calculateOrderTotalPrice()優(yōu)于calcOTP()PaymentTransaction優(yōu)于DataObj。AI 依賴名稱理解語義命名越清晰生成和修改的確定性越高。7.2 類型安全優(yōu)先強類型系統(tǒng)是 AI 的重要約束工具。該實踐要求公共 API 具備完整類型簽名避免使用寬泛類型并通過聯(lián)合類型和字面量類型約束取值范圍。類型系統(tǒng)可以在 AI 生成階段提前暴露錯誤減少運行時不確定性。7.3 接口契約標準化接口需要遵循統(tǒng)一規(guī)范包括明確的 HTTP 方法語義、標準化錯誤響應格式、版本化策略和完整的接口定義。接口契約越標準AI 越容易生成正確的調(diào)用代碼和測試用例。7.4 零隱式依賴模塊依賴必須顯式聲明不依賴全局狀態(tài)、環(huán)境變量魔法或運行時注入。AI 應能通過閱讀模塊聲明和配置文件理解依賴關(guān)系。這一要求是組件可獨立測試、可復用的基礎(chǔ)。7.5 函數(shù)職責單一長函數(shù)會增加 AI 定位問題和理解邏輯的難度。職責單一的小函數(shù)更容易被 AI 正確理解、修改和測試。對于長時程 Agent 任務清晰的函數(shù)邊界也有助于降低上下文消耗。八、自動化門禁讓規(guī)范可驗證規(guī)范如果只依賴人工審查很難匹配 AI 高速生成的節(jié)奏。因此團隊將規(guī)范約束接入自動化門禁讓不符合規(guī)則的產(chǎn)出在進入倉庫前被攔截。自動化門禁主要覆蓋幾類檢查架構(gòu)合規(guī)性檢查驗證代碼變更是否突破模塊邊界、是否違反依賴方向、是否兼容既有接口契約。格式化與結(jié)構(gòu)校驗檢查目錄結(jié)構(gòu)、文件命名、模板字段和文檔引用是否符合標準。安全掃描對新增代碼進行安全漏洞掃描并識別潛在風險。性能回歸檢測對關(guān)鍵路徑變更執(zhí)行性能基準測試防止性能劣化。文檔一致性檢查驗證文檔引用鏈接、接口索引和示例代碼是否完整存在。這些門禁讓規(guī)范從建議變成約束。AI 生成的代碼不僅要寫出來還要通過統(tǒng)一標準檢查后才能進入主倉庫。這有助于在源頭控制熵增而不是等問題積累后再治理。九、自進化機制規(guī)范不是靜態(tài)文檔統(tǒng)一規(guī)范還需要持續(xù)演進。AI Agent 在執(zhí)行過程中會遇到新的錯誤模式、新的架構(gòu)決策和新的工程約束這些信息如果只停留在單次任務日志中價值有限。團隊通過.agents/memory-session/等目錄沉淀執(zhí)行經(jīng)驗其中包含兩類典型內(nèi)容ERRORS.md記錄 AI 執(zhí)行中的典型錯誤和解決方案避免同類錯誤重復發(fā)生。LEARNINGS.md記錄關(guān)鍵架構(gòu)決策包括背景、取舍和最終選擇幫助 AI 理解為什么這樣設(shè)計。這些經(jīng)驗會反饋到規(guī)范體系中。當某類問題反復出現(xiàn)時團隊可以將其轉(zhuǎn)化為新的規(guī)則、模板或門禁檢查。規(guī)范因此從靜態(tài)文檔變成動態(tài)工程系統(tǒng)能夠隨著 AI 生成規(guī)模和頻率的提升持續(xù)優(yōu)化。十、抗熵架構(gòu)的工程價值從工程治理角度看Spec as AIOS 的核心價值不是增加文檔而是把規(guī)范變成 AI 可執(zhí)行的操作系統(tǒng)。倉庫唯一真源提供事實基礎(chǔ)Spec-Driven Development 提供執(zhí)行路徑三級分層規(guī)范提供治理結(jié)構(gòu)AGENTS.md 提供入口導航端云同倉提供全棧上下文自動化門禁提供質(zhì)量約束自進化機制提供持續(xù)改進能力。這套體系解決的是多 Agent 并行生成下的一致性問題。不同 Agent 可以在同一套規(guī)范下工作不同任務可以在同一套倉庫事實中追溯不同生成結(jié)果可以通過同一套門禁驗證。AI 生成速度越快規(guī)范體系的重要性越高因為速度本身不會自動帶來工程效率只有可控的速度才能轉(zhuǎn)化為穩(wěn)定交付能力。需要明確的是從工程落地的客觀規(guī)律來看這一方案在標準化、新建模塊的場景下效果顯著但對于高度定制化、缺乏標準化的歷史遺留復雜代碼AI 重構(gòu)成本依然較高“先治理基建、再釋放 AI”是使其生效的必要前提。同時當前的 AI 研發(fā)模式并非完全無人化工程師仍需基于完整的 PR 與測試報告進行最終審查人機協(xié)同仍是核心邊界。十一、未來方向從規(guī)范約束到深度托管隨著 AI Agent 能力增強軟件研發(fā)正在從人機協(xié)作走向 AI 深度參與、人工關(guān)鍵兜底的深度托管模式。統(tǒng)一規(guī)范是這一過程中的基礎(chǔ)設(shè)施它讓人類定義規(guī)則和邊界讓 AI 在規(guī)則內(nèi)執(zhí)行編碼、構(gòu)建、測試和修復。未來規(guī)范體系還可能進一步與生產(chǎn)線、評測系統(tǒng)和經(jīng)驗記憶深度結(jié)合。規(guī)范不再只是項目文檔而是持續(xù)學習的工程治理系統(tǒng)。它會根據(jù)真實任務反饋調(diào)整約束會根據(jù)不同場景驗證適用范圍也會根據(jù) Agent 執(zhí)行數(shù)據(jù)優(yōu)化生成質(zhì)量。對于超級應用而言控制 AI 代碼熵增不是一次性工程而是長期演進過程。只有當規(guī)范、倉庫、門禁和生產(chǎn)線形成閉環(huán)AI 原生研發(fā)才能從快速生成走向穩(wěn)定交付。