自主人工智慧代理如何在你做伏地挺身的同時產生你的微服務平台的完整架構快照，以及為什麼該文件會成為你的人工智慧驅動的品質管道中最強大的輸入。
太長不看
架構文件並非苦差事。當它與原始程式碼放在一起，並被導入到人工智慧驅動的品質管線中時，靜態分析便從「查找拼字錯誤」轉變為「尋找系統性安全漏洞和代價高昂的基礎設施洩漏」。本文記錄了一個真實的實驗：在Google雲端平台上，一個自主人工智慧代理產生了跨多服務的架構文件——而人類工程師幾乎完全不在場——並記錄了這些文件如何為我們的人工智慧品質門控系統帶來全新的視角。
-
“自文件化程式碼”問題
軟體工程中一直存在著一種根深蒂固的假設，即結構良好的程式碼本身就具有自解釋性。簡潔的函數、良好的變數名，以及 Pylint 10.0/10 的高分——這還不夠嗎？
它不是。
程式碼描述了系統的執行方式。架構文件則描述了系統存在的意義以及它如何與周圍環境互動。如果沒有這個上下文層，所有自動化分析工具都如同在黑暗中摸索。它們只能看到一個函數，卻看不到它在更廣泛的服務網格中扮演的角色；它們只能看到一個 API 呼叫，卻看不到它應該執行的安全邊界。
在工程工作流程中引入人工智慧工具時，這種區別至關重要。讓低階工程師在缺乏架構上下文的情況下分析原始程式碼，就好比讓資深工程師在無法存取系統設計的情況下進行安全審查。
-
做伏地挺身的同時產生架構
我的平台執行在 Google Cloud 上。它由數十個部署在Cloud Run上的微服務組成，這些微服務透過 REST API 進行交互，將資源持久化到Google Cloud Storage ，並將所有 AI 操作路由到集中式的Vertex AI網關。這是一個功能豐富、連接良好的系統——但唯一的文件卻分散在各個 README 文件中。
我決心改變這種現狀。目標是：為每個服務建立一個標準化的、機器可讀的架構快照，並直接提交到程式碼倉庫。
方法：引導式自主代理執行。
工程師設定了方向，並制定了文件標準，然後便退居幕後。人工智慧代理程式——由Gemini 3 Flash和執行在Antigravity （一款智慧編碼助理）中的Claude Sonnet 4.6驅動——接管了工作。它自主檢查了每個服務，讀取了原始程式碼，追蹤了服務間的依賴關係，將現有實作與文件標準進行交叉比對，並迭代地產生了結構化的ARCHITECTURE.md檔案。在這個過程中，工程師的主要活動幾乎都變成了體力勞動。
最終成果並非非正式筆記，而是一套嚴謹的、多層次的文件體系：
📦 platform-root
┣ 📜 ARCHITECTURE.md ← Level 0: Global service mesh, topology, lifecycle status
┗ 📂 services
┣ 📂 core-ai-gateway
┃ ┗ 📜 ARCHITECTURE.md ← Level 1: Security policy engine, FinOps guardrails
┣ 📂 orchestration-bot
┃ ┗ 📜 ARCHITECTURE.md ← Level 1: Async task flow, Telegram webhook handling
┣ 📂 media-transcriber
┃ ┗ 📜 ARCHITECTURE.md ← Level 1: Speech-to-Text pipeline, GCS asset management
┗ 📂 translation-engine
┗ 📜 ARCHITECTURE.md ← Level 1: Structured output, multilingual routing每份文件都遵循嚴格的範本：
-
目的：這項服務存在的具體業務和技術原因。
-
設計原則：關鍵權衡－無狀態、延遲目標、回退策略。
-
交互圖：服務間流程、安全邊界和 AI 提供者整合的Mermaid圖。它可以由代理程式產生並在 GitLab 中自動繪製。
-
LLM 上下文區塊：針對自動化代理和 AI 審閱者最佳化的精確摘要。
整個操作最終產生了一張可導航、相互關聯的架構圖——建構過程僅需極少的人類認知努力（而且還運用了視覺化技術！）
-
質量門覺醒
文件與原始程式碼一起提交後，我使用我們基於 AI 的Quality Gate執行了標準的 CI 品質審查——該服務基於Gemini 透過 Vertex AI建置，旨在對每個合併請求執行自動化的架構和安全審查。
💡 質量門究竟是什麼？
它並非價值 10 萬美元的企業級 SaaS 平台，而是一個輕量級的、專用的微服務——與它所審查的平台屬於同一平台——部署在Google Cloud Run上。它公開一個端點，接收來自 CI 管線的合併請求差異，建立一個包含程式碼庫架構文件的 LLM 提示，呼叫Vertex AI（Gemini） ，並傳回一個結構化的 JSON 審查報告。
>
由於它執行在 Cloud Run 上，因此僅在觸發程式碼審查時啟動，並在審查結束後立即關閉。我的每月總成本僅為幾美元——僅相當於人工程式碼審查一小時成本的一小部分。這正是 Google Cloud 無伺服器模式的實際應用：只需為實際使用的運算資源付費，並且僅在 AI 能夠創造價值時才使用它。
差異顯而易見。
先前，由於缺乏架構背景，品質閘僅限於程式碼層面的分析：風格一致性、常見安全反模式、相依性版本。雖然有用，但不夠深入。
由於有了ARCHITECTURE.md檔案作為上下文訊息，模型可以同時查看架構和程式碼。這帶來了質的飛躍：品質閘從靜態分析工具轉變為在系統設計層面運作的推理系統。
它在幾分鐘內就發現了兩個關鍵問題——這兩個問題在程式碼庫中已經存在數月而未被發現。
發現1：分散式追蹤中斷
我們的一項路由服務包含一個中間件，該中間件會明確地剝離傳入的追蹤標頭。表面上看，這似乎是一項合理的安全措施，可以防止外部客戶端將追蹤標識符注入內部系統。
品質門將其辨識為嚴重的觀測性違規。
由於架構文件描述了網格中的分散式追蹤標準（包括與Google Cloud Trace相容的端到端X-Trace-ID傳播要求），因此該模型理解，在邊界處剝離這些標頭並不能隔離威脅，而是會完全切斷追蹤鏈。在任何生產環境中，工程師將無法在Cloud Logging中關聯跨服務的日誌，從而將例行除錯變成耗時數小時的取證調查，且無法依賴任何Cloud Audit Logs關聯資訊。
安全意圖✓。系統性後果✗。文件揭示了這一矛盾。
發現二：無聲的儲存洩漏
有記錄顯示，某媒體處理服務在每次處理作業後，會故意跳過 Google Cloud Storage 中臨時資源的清理。其理由顯而易見──為了簡化操作，避免因刪除錯誤而導致的故障。
品質門將此與已記錄的資料最小化和最小權限存取架構原則進行了交叉比對，並將其標記為安全違規和財務營運違規。
影響：使用者音訊檔案（可能包含敏感個人資訊）會無限期地累積在雲端儲存。沒有生命週期策略，也沒有刪除觸發機制。成本悄無聲息地累積成長。每次新的處理請求都會擴大攻擊面。
單獨使用程式碼檢查工具或程式碼審查工具都無法發現這些問題。這兩個問題都源自於程式碼行為與架構意圖的交會點——而這只有在文件存在的情況下才能被發現。
-
投資報酬率案例
這項實驗在三方面都產生了可衡量的投資回報：
| 維度 | 無文件 | 有文件 + AI 代理 |
|---|---|---|
|架構圖繪製| 高階架構師工時 | 代理週期，幾乎無需人工幹預 |
|審查品質| 程式碼層面發現的問題 | 系統層面和政策層面發現的問題 |
|問題發現成本| 事後或審計 | CI/CD 管線（分鐘、分） |
|品質門| 通用、固定的企業級工具 | 可自訂的微服務，可依團隊或開發人員進行調整 |
在Google雲端平台的背景下，還有三個因素值得特別注意：
-
Vertex AI 代幣效率：當質量門由 Gemini 模型支援時，提供結構化的
ARCHITECTURE.md檔案可以減少模型從原始程式碼重建系統意圖所消耗的代幣。更完善的上下文意味著更便宜、更快速、更準確的生成，從而直接影響您的 AI 運算成本。 -
Cloud Run 可觀測性：上述分散式追蹤發現對於基於 Cloud Run 的架構特別重要，因為這類架構中的服務是無狀態且短暫的。如果沒有持續的追蹤傳播，除錯 Cloud Run 上的服務間故障將變得異常困難。文件明確指出了這一風險，並使其可被發現。
-
無伺服器成本模型：由於品質閘是一項僅在 CI/CD 執行期間呼叫的 Cloud Run 服務，因此不存在任何空閒成本。對於一個每天提交多個合併請求的典型團隊而言，整個 AI 驅動的審核流程每月成本僅需幾美元——甚至低於一個工時。這正是 Google Cloud 無伺服器模式的預期運作方式：按需提供高智慧運算，且成本極低。
-
給平台工程師的啟示
這項實驗的關鍵發現並非人工智慧代理編寫文件的速度比人類快，這在意料之中。關鍵發現在於，架構文件儲存在程式碼庫中，能夠大幅提升所有讀取該文件的自動化工具的效能。
無論您的自動化工具是人工智慧程式碼審查器、合規性掃描器、入職助理或基礎設施規劃代理，這項原則都適用。文件越完善，在其上執行的每個工具的訊號品質就越高。
實用建議：
-
將文件與程式碼放在一起。一個單獨的、與程式碼不同步的 wiki 頁面是無用的。而服務目錄中的
ARCHITECTURE.md文件，如果與程式碼在同一提交中更新，則是重要的訊號。 -
建立文件標準。統一的模板（意圖、原則、互動圖）能使文件不僅人可讀，而且機器也能讀。
-
定義生命週期狀態。明確標記已棄用或停用的服務。自動化代理不應將舊程式碼作為當前標準的參考。
-
使用智能體產生初始草稿。從一張白紙開始寫文件確實會帶來認知負擔。智能體非常擅長產生結構化的初稿，工程師可以對其進行驗證和完善。
-
將文件匯入到您的持續整合 (CI) 管線中。具備架構情境的 AI 品質審查工具與不具備架構情境的 AI 品質審查工具截然不同。
-
建造您自己的品質門，並使其完全符合您的需求。這是企業級 SaaS 無法比擬的關鍵優勢：靈活性。由 Gemini 提供支援、並由您的合規規則、架構標準和團隊慣例驅動的客製化 Cloud Run 服務，意味著每位開發人員都可以擁有一個了解專案具體情況的專屬審核員，而不是一套適用於所有程式碼庫的通用規則集。
-
結論
架構文件歷來被視為可有可無的額外工作——理論上很有價值，但實務上卻常被忽略。這項實驗表明，當文件與原始碼位於同一位置，遵循一致的機器可讀標準，並藉助自主代理保持更新時，它就成為了關鍵的基礎設施元件。
它使自動化系統能夠從平台設計層面進行推理，而不僅僅是程式碼語法。它將人工智慧驅動的品質門從昂貴的程式碼檢查工具轉變為真正的架構顧問。而且，它可以在你做其他事情的同時，為整個平台產生相應的品質門。
這份價值 1 萬美元的ARCHITECTURE.md文件並非比喻。它指的是在 5 分鐘的持續整合 (CI) 審查中發現關鍵架構缺陷與在生產事故、合規性審計或意料之外的雲端儲存帳單中發現該缺陷之間的成本差額。
將您的架構文件化，並將其保存在程式碼庫中。讓代理商負責維護。
保持標準化，確保安全。
原文出處：https://dev.to/gdg/architecture-documentation-as-a-first-class-engineering-asset-4a1j
1) --- 會變成分隔線（上一行必須是空白）
2) # 會變成一級標題
3) ## 會變成二級標題
4) ### 會變成三級標題
5) **粗體文字**會顯示粗體文字
6) ```當第一行與最後一行會顯示程式碼
7) 請搜尋 Markdown 語法，了解各種格式
