作者 | Kyle Howard, Christian Johansen, Dana Katzenelson, Brian Rhot

譯者 | 明知山

本文由 InfoQ 認(rèn)證架構(gòu)師在線課程的學(xué)員撰寫，是其學(xué)習(xí)成果的集大成之作，反映了學(xué)員群體在 AI 與現(xiàn)代軟件架構(gòu)交叉領(lǐng)域的集體學(xué)習(xí)心得。

代碼已成商品，對齊仍是難題

生成式 AI 大幅降低了編寫代碼所需的工作量，快速原型設(shè)計也變得越來越普遍。因此，如今軟件開發(fā)生命周期的瓶頸已轉(zhuǎn)變?yōu)榻M織將創(chuàng)意轉(zhuǎn)化為匹配自身能力的成果并在整個系統(tǒng)中保持凝聚力的能力。

圖 1. 來源：Eduardo Da Silva，經(jīng)授權(quán)使用

一直以來，組織一直依賴人工流程與人工監(jiān)督來保障架構(gòu)的一致性。初創(chuàng)企業(yè)依靠核心技術(shù)人員捕捉架構(gòu)設(shè)計與實際落地之間的偏差；大型企業(yè)則試圖通過變更管理委員會、不斷補充的 ADR（架構(gòu)決策記錄）及相關(guān)文檔來維持架構(gòu)凝聚力。但在這兩種模式下，偏差的識別都十分緩慢，因為都需要同步依賴中心化的權(quán)威決策。對初創(chuàng)企業(yè)而言，開發(fā)團(tuán)隊需要等待忙碌的核心專家；對大型企業(yè)而言，則需要等待評審委員會審批，并在大量文檔化規(guī)范中進(jìn)行篩選，還往往面臨內(nèi)容已過時的問題。生成式 AI 進(jìn)一步加劇了這一矛盾：以往開發(fā)者需要數(shù)天甚至數(shù)周才能完成代碼編寫，如今高管與產(chǎn)品經(jīng)理僅需數(shù)分鐘或數(shù)小時內(nèi)氛圍編程出功能原型。這使得開發(fā)團(tuán)隊陷入了兩難困境：要么受制于人工審核速度而犧牲研發(fā)效率，要么在無法確認(rèn)是否與整體架構(gòu)對齊的情況下盲目推進(jìn)進(jìn)度。

隨著時間推移，這些零散的推進(jìn)不斷累積，最終導(dǎo)致架構(gòu)碎片化。組織往往通過增加流程、制定更嚴(yán)格的規(guī)范來應(yīng)對，這反而進(jìn)一步加大了發(fā)布對齊軟件的難度。這一惡性循環(huán)拖慢了交付速度，也削弱了創(chuàng)新能力。

聲明式架構(gòu)，去中心化的對齊

要在生成式 AI 時代提升架構(gòu)對齊能力，組織需要擺脫單純依賴人工監(jiān)督的模式，轉(zhuǎn)向自動化防護(hù)機制，讓團(tuán)隊能夠自主做出合規(guī)且安全的決策。為此，我們提出聲明式架構(gòu)策略來實現(xiàn)架構(gòu)治理的規(guī)?；瘮U展。

聲明式架構(gòu)將架構(gòu)決策與約束提煉為可由機器強制執(zhí)行的設(shè)計意圖聲明，從而支持安全、獨立的研發(fā)行動。每個聲明都管控著一個明確的作用范圍，即在一個清晰界定的上下文內(nèi)擁有執(zhí)行權(quán)限。若缺乏這一邊界約束，聲明就會淪為它們本應(yīng)取代的、臃腫散亂的設(shè)計指引。

聲明式架構(gòu)的目的并不是為了做出更優(yōu)的決策，而是確保決策不會被忽視。相較于查閱解讀架構(gòu)文檔、等待專家或評審委員會的意見，機器可讀的架構(gòu)意圖聲明讓合規(guī)路徑成為阻力最小的選擇。合規(guī)驗證不再依賴人為意識與記憶，而是被集成到開發(fā)者日常使用的工具中，包括編輯器、構(gòu)建管道與代碼審查工具。在這一框架下，機器可讀性并非技術(shù)上的錦上添花，而是核心要求。僅能被人類理解的聲明依然需要人工參與校驗；只有可被機器推理的聲明才能讓治理能力超越個人或評審委員會的處理上限。后續(xù)章節(jié)中，我們將探討從事件模型、OpenAPI 規(guī)范及 ADR 中提煉聲明式架構(gòu)的實際應(yīng)用。

事件模型作為聲明式架構(gòu)

事件模型描述了信息在系統(tǒng)中的流轉(zhuǎn)方式，通常通過協(xié)作建模來生成。

圖 2. 帶有高亮垂直切片（綠色矩形）的事件模型。每個切片是一個自包含的行為單元，擁有自己的命令、事件和讀取模型。來源：Adam Dymitruk，Adaptech Group

畫布上的可視化便簽內(nèi)容被一一對應(yīng)轉(zhuǎn)錄為具備形式化 Schema 支持的 eventmodel.json 文件中。該 eventmodel.json 構(gòu)成了系統(tǒng)的聲明式架構(gòu)：它是一份機器可讀的架構(gòu)意圖藍(lán)圖，可據(jù)此生成符合規(guī)范的實現(xiàn)，也可讓智能體對照著對實現(xiàn)進(jìn)行評估。

圖 3. 從事件模型到生成代碼

1. 為自動化提供支撐

垂直切片具有明確的邊界范圍，包含描述單個行為單元所需的聲明。這種最小化范圍是在各個層面實現(xiàn)自動化的關(guān)鍵。代碼工件可使用代碼模板從事件模型確定性地生成，無需依賴 AI。同時，由于每個切片都是自包含的，代碼工件也按切片進(jìn)行組織（參見垂直切片架構(gòu)）；一旦出現(xiàn)問題，只需替換單個切片，而無需拆解復(fù)雜的依賴網(wǎng)絡(luò)（仍需遵守對外部依賴的相關(guān)契約）。對于模板無法覆蓋的場景，形式化 Schema 可讓 AI 發(fā)揮更大作用。Nebulit 的 Martin Dilger 定義了一套 Claude 規(guī)則文件文件，用于分析代碼庫并從中生成事件模型。領(lǐng)域?qū)＜译S后可以通過 AI 智能體審查和優(yōu)化模型，實現(xiàn)比代碼更高抽象層次的對話式編程。由于范圍被最小化，人與 AI 均可聚焦于獨立切片，大幅降低認(rèn)知負(fù)荷。正是這種最小化范圍使得 Ralph Loop（下文詳述）得以實現(xiàn)，讓每個切片成為 AI 智能體的獨立迭代目標(biāo)。

2. 大規(guī)模去中心化架構(gòu)對齊

事件模型能夠?qū)崿F(xiàn)去中心化，但其前提是建模過程必須跨團(tuán)隊協(xié)作進(jìn)行。如果各團(tuán)隊在孤立環(huán)境中獨立建模，每個團(tuán)隊的事件模型或許會在內(nèi)部保持一致，但可能導(dǎo)致整個產(chǎn)品出現(xiàn)架構(gòu)碎片化。Adaptech Group、Nebulit 等機構(gòu)已實踐了覆蓋多個團(tuán)隊的多領(lǐng)域協(xié)作建模，驗證了該模式可以拓展到單一團(tuán)隊邊界之外。諸如 architecture.md、OpenAPI 校驗工具（下文會提到）這類技術(shù)對齊機制能強制規(guī)范系統(tǒng)的構(gòu)建方式，但無法保證團(tuán)隊協(xié)同構(gòu)建出正確的產(chǎn)品。這就需要覆蓋范圍更廣的共享建模，例如事件建?；蚱渌麉f(xié)作式設(shè)計方法。好消息是：技術(shù)治理將人類的注意力從監(jiān)督實現(xiàn)細(xì)節(jié)中解放出來，為實現(xiàn)產(chǎn)品級的架構(gòu)對齊創(chuàng)造了空間。

3.Ralph Loop：從切片到交付

Ralph Wiggum Loop 是多種 AI 循環(huán)機制之一，智能體會反復(fù)執(zhí)行任務(wù)，直至滿足完成標(biāo)準(zhǔn)；每次迭代都會以全新上下文重新啟動，避免推理能力退化。在早期迭代階段，通常會由架構(gòu)師參與其中，對配置進(jìn)行調(diào)整與驗證。這張圖展示了 AI 輔助 ADDR 流程在第二次迭代中的輸出結(jié)果示例。

事件模型中的每個垂直切片都對應(yīng)一個迭代目標(biāo)：智能體讀取切片規(guī)范、完成實現(xiàn)，并對照 Given-When-Then 規(guī)范進(jìn)行驗證，循環(huán)執(zhí)行直至驗證通過。由于每個切片都采用最小化范圍，能夠適配單個上下文窗口，即便使用輕量化模型，在這種條件下也能產(chǎn)出可靠的結(jié)果。

規(guī)范 + 垂直切片 = AI 的糖果（來源：Martin Dilger）

圖 4. Ralph Loop 文件結(jié)構(gòu)

這個結(jié)構(gòu)清晰地展現(xiàn)了整個流程：plan 文件夾相互獨立，支持并行執(zhí)行。每個文件夾都包含獨立的進(jìn)度標(biāo)記、實現(xiàn)復(fù)選框與日志記錄。反饋循環(huán)中產(chǎn)生的決策與經(jīng)驗會在各 plan 之間累積。當(dāng)這些內(nèi)容足夠重要時，由開發(fā)人員進(jìn)行審核，并更新 AGENTS.md。智能體的行為基于整理后的經(jīng)驗進(jìn)行演進(jìn)，而非自動自我修改。每次迭代都會產(chǎn)生組織知識，作為工作產(chǎn)出的副產(chǎn)品。[代碼庫鏈接]

4. 事件建模的前景

圖 5. Wardley 地圖：事件模型工具演進(jìn)

上面的 Wardley 地圖展示了 AI 的工業(yè)化應(yīng)用路徑：將成熟的事件模型工具與新興的模式標(biāo)準(zhǔn)相結(jié)合，催生出一種全新模式——對話式 AI 事件建模。這個過程將領(lǐng)域?qū)＜遗c生成式 AI 相結(jié)合，通過對話而非編寫代碼來完成系統(tǒng)建模。在上述事件建模工作流中，代碼成為可丟棄的產(chǎn)物。切片具備最小范圍且定義完整，受模板與架構(gòu)的約束治理，無需人工維護(hù)，可直接從規(guī)范重新生成。這重新定義了遺留系統(tǒng)現(xiàn)代化的路徑：不必重寫數(shù)百萬行代碼，只需對領(lǐng)域建模并據(jù)此生成全新代碼即可保證系統(tǒng)持續(xù)保持架構(gòu)對齊。

事件建模在領(lǐng)域行為層面開展，將業(yè)務(wù)意圖提煉為可由機器執(zhí)行的切片。而這套聲明式模式同樣適用于領(lǐng)域邊界之外。當(dāng)行為完成建模并在內(nèi)部實現(xiàn)后，外部接口也必須保持一致。聲明式架構(gòu)并非只局限于內(nèi)部切片，還可延伸至維系系統(tǒng)協(xié)同的各類契約。

OpenAPI 驗證器作為聲明式架構(gòu)

以一家中型企業(yè)為例，該企業(yè)運營著高度分布式的 SaaS 平臺，包含數(shù)十個由自治團(tuán)隊負(fù)責(zé)的數(shù)百個組件，主要通過 HTTP API 進(jìn)行交互。以往，該組織高度依賴隱性的個人架構(gòu)負(fù)責(zé)制與“標(biāo)準(zhǔn)與實踐”文檔。所謂“正確”的做法，很大程度上取決于團(tuán)隊咨詢了哪些人、最先查到哪些文檔。團(tuán)隊往往難以找到最優(yōu)方案，進(jìn)而在項目初期就埋下架構(gòu)偏離的風(fēng)險。而在執(zhí)行過程中，各類臨時決策會進(jìn)一步加劇這種偏離，導(dǎo)致架構(gòu)設(shè)計意圖與實際落地之間的差距不斷擴大。

該組織正處于增長的關(guān)鍵節(jié)點，計劃推出面向客戶的 API 層。組織優(yōu)先保障兼容性與易用性，以最大化這一新接口的使用率。同時，它也希望保留高度自治團(tuán)隊所帶來的高效交付優(yōu)勢，并意識到當(dāng)前臨時化的架構(gòu)治理方式已形成瓶頸。此外，該組織還希望確保架構(gòu)能夠持續(xù)適配不斷變化的業(yè)務(wù)需求。

為了調(diào)和這種緊張關(guān)系，該組織采用了基于 OpenAPI 規(guī)范的聲明式架構(gòu)方案：由中央平臺團(tuán)隊制定標(biāo)準(zhǔn)并提供校驗工具（代碼檢查工具）。這些校驗工具將平臺團(tuán)隊的架構(gòu)意圖進(jìn)行編碼，向開發(fā)團(tuán)隊提供合規(guī)性自動反饋，并集成至 CI/CD 流程中，避免生產(chǎn)環(huán)境出現(xiàn)架構(gòu)偏離。同時，這類工具也被整合進(jìn)開發(fā)者工作流（如 IDE 插件、GitHub 狀態(tài)檢查），實現(xiàn)快速反饋并將偏差檢測左移。這種集中決策、分散執(zhí)行的模式保障了跨領(lǐng)域 API 在路徑規(guī)范、版本控制與向后兼容、分頁設(shè)計、錯誤結(jié)構(gòu)等方面的一致性，最終為內(nèi)部產(chǎn)品團(tuán)隊與外部 API 使用者提供流暢的開發(fā)者體驗。

這種方法可以自然地融入到組織現(xiàn)有的軟件生命周期中，而該生命周期本身就高度依賴聲明式基礎(chǔ)設(shè)施與獨立可部署能力。每個團(tuán)隊的 OpenAPI 規(guī)范均作為 API 的部署配置來使用，平臺會將 OpenAPI 文檔轉(zhuǎn)換為 API 網(wǎng)關(guān)配置、授權(quán)策略及面向用戶的文檔。由于所有開發(fā)團(tuán)隊共用一套標(biāo)準(zhǔn)化的構(gòu)建、測試、部署流水線，平臺團(tuán)隊只需通過一個統(tǒng)一且可預(yù)期的節(jié)點即可強制執(zhí)行架構(gòu)意圖，無需逐一對各團(tuán)隊進(jìn)行協(xié)調(diào)。各團(tuán)隊可繼續(xù)沿用他們熟悉的現(xiàn)有流程，部署時的校驗機制從根本上杜絕了架構(gòu)偏離的可能性。只有驗證通過部署才能成功，因此存在偏差的內(nèi)容永遠(yuǎn)不會進(jìn)入生產(chǎn)環(huán)境。

圖 6. 包含構(gòu)建時與部署時校驗的 API 生命周期

這種模式旨在為開發(fā)團(tuán)隊降低認(rèn)知負(fù)擔(dān)、提升自治度，同時在生產(chǎn)環(huán)境中實現(xiàn)嚴(yán)格的架構(gòu)一致性，最終為客戶提供統(tǒng)一且直觀的 API 體驗。前期反饋表明，該方案正按預(yù)期落地：如今 API 團(tuán)隊可以直接將通過的驗證結(jié)果作為客觀依據(jù)，而這些治理需求以往需要數(shù)天甚至數(shù)周的人工審核。

由于架構(gòu)意圖已被編碼為機器可驗證的規(guī)則，架構(gòu)對齊變得可觀測。平臺團(tuán)隊通過校驗工具收集各類遙測數(shù)據(jù)，包括校驗錯誤率、變更前置時間、產(chǎn)品團(tuán)隊反饋等，以此識別系統(tǒng)性的流程阻塞。重復(fù)出現(xiàn)的違規(guī)通常意味著標(biāo)準(zhǔn)不夠清晰或不切實際；較長的前置時間可能表明約束過多；而持續(xù)較低的違規(guī)率則說明相關(guān)約定穩(wěn)定可行。

正如 ADDR 流程中的 R 環(huán)節(jié)用于優(yōu)化 API 設(shè)計，這類校驗工具的反饋也能讓架構(gòu)意圖本身持續(xù)迭代。平臺團(tuán)隊基于實際觀測到的行為優(yōu)化規(guī)則，而非依靠定期修訂標(biāo)準(zhǔn)或臨時討論。架構(gòu)隨業(yè)務(wù)同步演進(jìn)，團(tuán)隊也能順勢做出調(diào)整。

確定性驗證守護(hù)著系統(tǒng)邊界，但架構(gòu)遠(yuǎn)不止語法與結(jié)構(gòu)。它是長期積累的判斷力，而這種判斷力無法被規(guī)整地寫進(jìn)檢查規(guī)則里。

關(guān)于架構(gòu)決策記錄

“在項目生命周期中，各項決策背后的核心動機是最難追溯的內(nèi)容之一?！?——Michael Nygard，2011 年

架構(gòu)決策記錄（ADR）是軟件開發(fā)項目中各項重大變更背后的推理依據(jù)。它能夠?qū)⑾嚓P(guān)背景從決策者傳遞給后續(xù)負(fù)責(zé)維護(hù)系統(tǒng)的人員，而這類背景信息往往會因敏捷開發(fā)動態(tài)迭代的特性而丟失。

ADR 提供了一套聚焦于識別權(quán)衡方案與替代選項的決策框架，同時補充了各類上下文信息——這些信息對最終決策的影響往往甚于單純挑選“更優(yōu)方案”本身。ADR 也成為了驅(qū)動軟件系統(tǒng)持續(xù)演進(jìn)的集體決策歷程記錄。

然而，隨著生成式 AI 的出現(xiàn)，研究時間大幅縮短，生產(chǎn)力預(yù)期也在不斷提升，ADR 很可能難以有效地達(dá)成目標(biāo)。人反而成了瓶頸，這在那些要求決策記錄在實施前必須審批通過的組織中，問題會尤為突出。Michael Nygard 在 2011 年的博文中就曾提到，“沒人會閱讀長篇大論的文檔”，這也是他設(shè)計 ADR 的初衷之一?？扇缃裎臋n可以輕松批量生成，即便短小的文檔也沒人看時，又會發(fā)生什么？智能體會是解決方案嗎？

architecture.md 作為聲明式架構(gòu)

利用架構(gòu)適應(yīng)度函數(shù)對 OpenAPI 規(guī)范進(jìn)行靜態(tài)分析只是第一步，而在規(guī)范驅(qū)動開發(fā)的當(dāng)下，我們需要更進(jìn)一步。確定性驗證器固然可以校驗語法、風(fēng)格與結(jié)構(gòu)，但應(yīng)用程序本身的設(shè)計意圖該如何保障？

確定性工具只知曉你明確告知它們的內(nèi)容，它們無法指出一個完全有效的 REST 端點違反了要求內(nèi)部通信使用異步事件的核心架構(gòu)決策，除非依賴脆弱的白名單和例外。以往，我們試圖通過“左移”和引導(dǎo)開發(fā)者查閱大量架構(gòu)決策記錄（ADR）維基文檔來彌補這一差距，但這會給團(tuán)隊帶來沉重的認(rèn)知負(fù)擔(dān)。我們并非真正做到左移，而是將負(fù)擔(dān)直接轉(zhuǎn)嫁給了開發(fā)側(cè)，這必然會導(dǎo)致架構(gòu)隨著系統(tǒng)擴展逐漸偏離設(shè)計初衷。

我們需要一種既能理解指導(dǎo)方針的字面含義又能領(lǐng)會其核心精神的機制。我們需要將架構(gòu)提煉為智能體模型可執(zhí)行的格式，在開發(fā)過程中實時為開發(fā)者提供指導(dǎo)，而不只是對代碼進(jìn)行把關(guān)校驗。

引入 architecture.md

這份文件是將我們的架構(gòu)指南精簡提煉為智能體友好型指令的成果，可在每次執(zhí)行時靈活且一致地應(yīng)用。將海量陳舊的維基文檔直接交給智能體只會引發(fā)混亂與幻覺，甚至導(dǎo)致流水線停滯。因此，每份 ADR 都必須提煉成人類與智能體均可理解、并能應(yīng)用到代碼中的簡潔指令：

我們做 X 而不是 Y。

當(dāng) C 為真時，我們優(yōu)先選擇 A 而不是 B。

每個 ADR 和技術(shù)要求都有獨立的適用范圍與處理方式，被封裝為意圖的原子單元。

* [ADR-073] [警告] 禁止記錄包含個人可識別信息（PII）的請求體。日志記錄前需通過 `Redact()` 工具對載荷進(jìn)行脫敏處理。

圖 7. architecture.md 示例

閉環(huán)：自動化治理

如果我們放任靜態(tài)文件過時，它們就變得毫無用處。為了避免 architecture.md 變成又一個陳舊的維基頁面，我們將它作為代碼進(jìn)行管理。治理智能體可在每日夜間運行，將倉庫清單與中央 ADR 語料庫進(jìn)行比對，若檢測到新增或已被替代的決策，便會自動發(fā)起拉取請求更新規(guī)范，確保倉庫始終不會偏離企業(yè)基準(zhǔn)架構(gòu)。

隨著實現(xiàn)逐步成熟，你可能會遇到 architecture.md 變得臃腫的情況，但這個問題可以通過使用目錄結(jié)構(gòu)輕松解決（如 這個提案，加上 agents.md，將限定范圍的片段放在單獨文件中）。

有了經(jīng)過驗證的清單，運行時執(zhí)行就變得簡單。無論是以 GitHub Action 還是本地 IDE Copilot 的形式運行，智能體只需獲取相關(guān)條款（例如僅在涉及 Schema 文件時加載數(shù)據(jù)規(guī)則），評估代碼的語義意圖，并提供就地修復(fù)方案。

如果你的架構(gòu)是一份可執(zhí)行清單，你的工具就不再是批評者，而是協(xié)作者。用于指導(dǎo)智能體進(jìn)行代碼審查的同一份文件既可以作為生成適應(yīng)度函數(shù)的依據(jù)，也可以作為基礎(chǔ)設(shè)施身份的驗證依據(jù)。我們不只是在左移，而是為“左側(cè)”提供了清晰的指引。

結(jié) 論

在生成式 AI 時代，代碼與文檔的編寫已趨于通用化，因此保障整個組織內(nèi)的一致性與標(biāo)準(zhǔn)變得比以往更為關(guān)鍵。通過采用聲明式架構(gòu)與反饋循環(huán)，組織能夠持續(xù)演進(jìn)，并自動化地落實架構(gòu)意圖。運用事件建模、OpenAPI 校驗、架構(gòu)決策記錄等行業(yè)標(biāo)準(zhǔn)實踐，并將成果提煉為機器可執(zhí)行的架構(gòu)意圖聲明，組織可以讓團(tuán)隊高效推進(jìn)工作，同時保持高度一致且可靠的協(xié)同。這種模式可擴展至智能體流程，覆蓋以往僅能由人工驗證工作意圖的場景。

為消除集中式治理帶來的瓶頸，架構(gòu)決策必須直接編碼到用于生成和驗證實現(xiàn)的工具中。合規(guī)路徑應(yīng)當(dāng)是最簡便的路徑。生成器應(yīng)在項目啟動階段及開發(fā)者工作流內(nèi)部發(fā)揮作用。驗證器則應(yīng)集成到 IDE、拉取請求和部署環(huán)節(jié)中。交付管道之外的治理機制很容易被繞過，而嵌入到流程中的治理機制變得隱形且自動化。這些機制必須配備能夠持續(xù)演進(jìn)聲明式架構(gòu)的反饋循環(huán)。

代碼如今已十分充足，但對齊一致性卻并非如此。架構(gòu)治理的未來不在于更多審查委員會或更完善的文檔，而在于持續(xù)執(zhí)行與優(yōu)化聲明式意圖，使其與所治理的系統(tǒng)保持同速演進(jìn)。

查看英文原文：

https://www.infoq.com/articles/architectural-governance-ai-speed/

聲明：本文由 InfoQ 翻譯，未經(jīng)許可禁止轉(zhuǎn)載。