1. 瞭解現代化歷程
這項完整的程式碼研究室是實用練習，直接衍生自「如何運用 Antigravity 和多代理程式自動化調度管理機制，自動執行現代化作業」這篇深入探討架構的文章。雖然我們使用經典的 Node.js 框架交換做為具體示範工具，但您在此處學到的核心設計模式、目錄結構和代理程式自動化調度管理程序完全與語言無關，適用於任何大規模的舊版現代化專案。
與僅在單一檔案中自動完成程式碼行的標準程式設計助理不同，您將瞭解如何運用 Google Antigravity 的代理優先功能，協調自主團隊的專業 AI 子代理。這些代理可以獨立進行舊版程式碼庫的逆向工程、編寫嚴格的測試套件、搭建現代架構，並使用 Reflexion 迴圈自我修正編譯器錯誤，而您則可做為高階架構師，維持絕對控制權。
課程內容
- 對應工作流程：如何正確分類及區分決定性設定工作，以及複雜的啟發式重構挑戰。
- 技能架構：如何使用漸進式揭露和 YAML 路由中繼資料，建構可擴充的代理技能套件。
- 協調設計模式：如何透過串連 Router、Plan-and-Execute 和 Reflexion 設計模式，推動大規模重構。
- 嚴格的輸入/輸出合約：如何在多階段反向工程和目標支架管道中，強制執行明確的輸入/技能/輸出界線。
- 同位檢查：瞭解如何運用 Antigravity 的瀏覽器子代理程式，在 Chrome 網路瀏覽器中並排執行同位測試。
建構項目
您將協調全自動的 Greenfield 重構管道，該管道會採用過時的舊版 Express 和 Mongoose CRUD 單體 (「madhums 示範」)，並從頭自主重建為嚴格型別的 Next.js 應用程式路由器應用程式，後者以 MongoDB、嚴格的 Zod 驗證和可存取的 ShadCN UI 元件為基礎。
軟硬體需求
- 在電腦上安裝 Google Antigravity IDE (網址為 antigravity.google)。
- 在本機安裝 Node.js (v18 以上版本)。
- Chrome 瀏覽器，用於自動化 UI 驗證。
- 開放原始碼 modernizing-expressjs 示範單一存放區的副本。
2. 設定現代化環境
在讓自主代理程式處理老舊的舊版程式碼之前，我們必須先建立乾淨且高度穩定的單一存放區環境。為 AI 助理提供乾淨的基準，可確保 AI 助理完全專注於生成高品質的現代程式碼，而不是浪費權杖來解決數十年前的套件漏洞或編譯器不符問題。
舊版 Express 與新版 Next.js 架構的對應關係
構成要素 | 舊版堆疊 | 現代化替代方案 | The Rationale |
架構 | Express Monolith | Next.js 應用程式路由器 | 將邏輯解耦至伺服器元件，以最佳化算繪和 React 伺服器元件 (RSC) 效能。 |
資料邏輯 | Mongoose (ODM) | MongoDB + Zod | 將隱含 ORM 勾點換成顯式、型別安全的 Zod 結構定義，以及原始驅動程式效能。 |
語言 | CommonJS / JavaScript | TypeScript (ESM) | 強制執行編譯時間安全，並改用現代模組標準。 |
前端 | Pug/EJS (伺服器檢視畫面) | ShadCN UI + Tailwind | 從僵硬的範本轉移至可組合、無障礙且實用優先的設計系統。 |
Auth | Passport.js | NextAuth | 內建 Edge 和現代供應商的支援功能，可簡化工作階段管理。 |
安全 | 手動中介軟體 | Zod (嚴格驗證) | 在整個堆疊中，為資料驗證實作「單一資料來源」。 |
初始化現代化中心
第一個確定性動作是複製隔離的單一存放區結構。這會將唯讀的舊版程式碼與新的綠地目標存放區分開，確保原始應用程式不會發生任何意外突變。
開啟 Antigravity 終端機，然後執行下列設定指令：
git clone https://github.com/GoogleCloudPlatform/devrel-demos.git cd devrel-demos/other/modernizing-expressjs
複製完成後，請直接在 Antigravity IDE 檔案總管中開啟 modernizing-expressjs 資料夾。您會看到以下獨立版面配置：
/modernizing-expressjs/ ├── .agents/ # Skills metadata and checklists │ └── skills/ ├── docs/ # Target directory for reverse-engineered markdown artifacts ├── legacy-app/ # Read-only root of the legacy Express monolith ├── modern-app/ # Greenfield target repository for the Next.js rewrite ├── GEMINI.md # Project-wide agent constitution └── README.md # Companion documentation
請觀看這部簡短的逐步解說影片，瞭解如何準備及隔離單一存放區環境，確保結果具有確定性：
3. 設計 AI 代理技能包和模式
撰寫強大的代理程式技能與編寫標準即時通訊提示有本質上的差異。撰寫技能包時，您設計的是模組化軟體，可由基礎大型語言模型自主執行。為避免代理程式產生幻覺或發生「內容視窗稅」，我們推出開放原始碼的 Greenfield Orchestration 技能包，做為可擴充的撰寫範本，並以兩項不可協商的原則為基礎：簡潔和漸進式揭露。
使用 YAML 中繼資料路徑進行漸進式揭露
我們不會將所有目標規則都匯入單一的單體式系統提示，而是將指令分散到各個目錄。每個 Skill 目錄都包含以 YAML 路由 frontmatter 區塊包裝的 SKILL.md 進入點。
開啟 .agents/skills/orchestrating-greenfield-migration/SKILL.md 並檢查路由器中繼資料：
---
name: orchestrating-greenfield-migration
description: >
Manages the end-to-end modernization of legacy Express
monoliths into Next.js architectures. Orchestrates subagents
for auditing, scaffolding, and verification. Use when starting
or managing a greenfield rewrite project.
---
硬式編碼規劃與執行模式
為防止自主代理程式偏離主題、因有趣的舊版中介軟體而分心，或嘗試未經授權的資料庫交換作業，我們直接在指令中硬式編碼 Plan-and-Execute 模式，覆寫標準的開放式規劃。
檢查主協調器內嵌的 Markdown 檢查清單：
### Phase 1: The AI audit (reverse engineering)
Dispatch subagents to produce specifications while identifying project-specific test scenarios.
* [ ] Init `docs/verification/Verification_Plan.md` to create baseline template.
* [ ] Run `auditing-data-models` -> Append Data Integrity Stress-Tests.
* [ ] Run `auditing-api-contracts` -> Append API Parity & Edge Case Probes.
* [ ] Run `auditing-business-logic` -> Append Logic & Authorization Stress-Tests.
* [ ] Run `auditing-ui-archeology` -> Append Interaction & Layout Targets.
將工作流程格式化為明確的檢查清單，並內含技能參照，代理程式就會將這份確切的藍圖複製到工作計畫中，鎖定為「僅執行」模式，有系統地勾選方塊，並在需要時呼叫高度專業的子代理程式。
4. 第 1 階段：對舊版單體式架構進行逆向工程 (稽核)
我們準備好觸發主要協調順序了！第一階段的主要工作是從舊版單體式架構中擷取業務規則、資料結構定義和 API 酬載，並以乾淨的 Markdown 構件形式儲存，同時擺脫長達十年的必要技術債。
觸發自主重構序列
在 Antigravity Agent Manager 聊天面板中，輸入下列自訂斜線指令，然後按下 Enter 鍵：
/orchestrating-greenfield-migration
現在，請觀察終端機控制台。您會看到主要代理程式讀取系統提示詞、將要求與 Orchestrator 的中繼資料相符、輸出 5 階段檢查清單，並立即開始平行調度專門的「稽核員」子代理程式。
輸入/技能/輸出教學合約
在第 1 階段，代理程式會執行嚴格的逆向工程管道，並受下列指令合約約束：
耗用的輸入內容：位於 legacy-app/ 內的唯讀舊版原始碼檔案。
叫用的技能：
技能 | 說明 |
| 追蹤舊版路徑，記錄確切的 JSON 回應封包。 |
| 解構 Mongoose 結構定義，擷取關係、必填欄位和預設值。 |
| 文件隱含的副作用、Passport 驗證流程和中介軟體規則。 |
| 掃描舊版 Pug 範本，對應高階「UI 意圖」(導覽列、表單)。 |
產生的構件：直接在 docs/ 資料夾中生成高度結構化的 Markdown 規格
構件 | 說明 |
| 本文詳細說明舊版 Express 應用程式的逆向工程 API 介面區域。重建新版 Next.js 應用程式中的路徑時，請使用這個目錄確保嚴格一致。 |
| 本文記錄舊版 Express 應用程式中，與驗證 (AuthN)、授權 (AuthZ)、全域中介軟體、工作階段管理和副作用相關的已驗證行為、設定和嚴格規則。 |
| 本文將全面分析 |
| 本文詳細分析 |
觀看這段終端機即時擷取畫面，瞭解自主反向工程稽核的實際運作情形：
5. 第 2 和第 3 階段 - TDD 測試架構和全新後端架構
完成舊版應用程式的全面稽核和記錄後，主要自動調度管理工具會繼續搭建現代目標後端。這個階段會導入工具包中最強大的代理設計模式：嚴格的測試驅動開發 (TDD) 驅動的封閉迴路反思 (自我反思)。
使用 Reflexion 迴圈驅動自我修復程式碼
編寫現代程式碼很簡單，但要確保程式碼能完美編譯，並通過嚴格的驗證限制，則需要閉迴路評估。協調器會自主處理這項作業，直接將測試輸出內容傳回子代理程式的內容視窗：
- 第 2 階段 (TDD 設定)：協調器會叫用
generating-api-tests子代理程式，該程式會讀取docs/API_Contracts.md並編寫詳盡的 Vitest 整合測試套件，斷言確切的必要 HTTP 狀態碼和 JSON 酬載。如 TDD 中預期，這些測試一開始會失敗。 - 階段 3 (後端架構)：架構子代理程式開始編寫新式 Next.js 路由處理常式和嚴格的 Zod 驗證結構定義。
- 自我修正迴圈：確定性 Vitest 測試架構評估新程式碼並傳回失敗結果 (例如預期的
422驗證錯誤傳回500) 時，代理程式不會當機。代理程式會反思目標錯誤輸出內容、重新開啟目標路徑處理常式、修正 Zod 結構定義酬載結構，然後再次執行測試。代理程式會自主迭代，直到達到0的結束代碼為止。
輸入/技能/輸出教學合約
消耗的輸入內容：反向工程規格構件 (docs/API_Contracts.md、docs/Data_Models.md)。
叫用的技能：
技能 | 說明 |
| 產生失敗的 Vitest 整合套件。 |
| 初始化基本 Next.js 應用程式路由器版面配置。 |
| 設定本機 Vitest 測試執行器環境。 |
| 將舊的 Mongoose 模型轉換為 MongoDB + Zod 結構定義。 |
| 將 Express 路由重建為 Next.js 路由處理常式和模組化路由防護措施。 |
產生的輸出內容：初始失敗的 Vitest 套件、完整輸入的 Zod 結構定義、功能正常的 Next.js 路由處理常式，以及通過測試的乾淨測試套件執行作業。
觀察自動生成的 TDD 測試架構：
觀察目標後端自我修正 Reflexion 迴圈的即時執行情況：
6. 第 4 階段 - 搭建現代化前端 (UI 元件) 的架構
後端驗證層完全強化並通過整合測試後，主要自動化調度程式會轉移環境，以更新視覺呈現方式。捨棄命令式伺服器端算繪範本，改用無障礙優先的實用元件設計系統。
將 UI 意圖轉換為可組合檢視區塊
前端子代理程式不會嘗試逐行翻譯 CSS，而是讀取擷取的「UI 意圖」目錄，並直接將結構元素對應至高保真度的現代對等項目。
輸入/技能/輸出教學合約
耗用的輸入內容：經過逆向工程的前端廣告空間構件 (docs/UI_Inventory.md)。
叫用的技能：
技能 | 說明 |
| 將 |
產生的輸出內容：使用高度無障礙的 ShadCN UI 元件和 Tailwind CSS 公用程式版面配置建構的 Next.js 前端網頁，可用於正式環境。
觀看自動生成的新式前端檢視層：
7. 第 5 階段：驗證與對抗稽核
重構管道的最後階段是嚴格的品質掃描。主要協調器會從靜態程式碼分析轉換為主動執行階段環境測試，積極嘗試破壞新的目標應用程式，以證明其功能與舊版基準完全相同。
執行雙分頁測試和瀏覽器啟動
驗證階段會運用 Antigravity 的整合式視覺和 DOM 功能，自動證明成功，您不必手動點選表單：
- 並行同位：
auditing-parity子代理程式會指示本機執行器同時啟動舊版 Express 單體和新版 Next.js 應用程式，驗證視覺呈現和資料算繪是否相同。 - 對抗性安全探查：協調器會叫用
adversarial-verification子代理，啟動 Antigravity 瀏覽器子代理。這個專用代理會直接啟動瀏覽器，在輸入欄位中輸入內容、提交表單，並探查安全性回歸、損毀的工作階段 Cookie 或未處理的極端情況。 - 稽核記錄產生：瀏覽器子代理程式會自動記錄工作階段啟動的 WebP 影片擷取畫面，並直接附加至最終遷移報告，做為可驗證的「工作證明」。
輸入/技能/輸出教學合約
耗用的輸入內容：在本地執行階段環境中並行執行的舊版和現代化應用程式。
叫用的技能：
技能 | 說明 |
| 執行執行階段比對驗證檢查。 |
| 使用自動瀏覽器啟動功能，探查邏輯瑕疵和功能迴歸。 |
產生的輸出內容：完整的同等功能稽核追蹤記錄，以及記錄的瀏覽器工作階段影片，確認完全成功。
觀察自動瀏覽器子代理程式，主動驗證現代化應用程式：
8. 遷移後準備好投入生產環境及後續步驟
恭喜！您已成功調度高度先進的自主代理重構管道，從頭開始翻新舊版單體式架構，並學習可普遍轉移的技能，例如逐步揭露、計畫與執行檢查清單，以及自我修復的 Reflexion 迴圈。
準備部署至正式環境
Next.js 應用程式通過完整驗證和稽核後，即可進行正式版整合。建議您採取下列業界標準的後續步驟：
- 漸進式路由：部署反向 Proxy (例如 Strangler Fig 模式)，將流量從舊版 Express 應用程式漸進式地導向至新式目標。
- 保留搜尋引擎最佳化 (SEO) 設定：將舊版 Express 路徑對應至 Next.js 永久重新導向 (
_redirects.yaml)，保留現有網域權威度。 - 資料串流：從靜態資料庫播種移至即時生產資料串流，並在執行階段使用嚴格的 Zod 結構定義安全地驗證。
- 可觀測性：以結構化的 OpenTelemetry 架構取代命令式記錄公用程式。
加深現代化專業知識
如要瞭解完整的基礎程式碼集、自訂技能指令，以及推動這個管道的詳盡理論基礎，請務必閱讀完整的主文章：
加入 Agentic Builder 社群
希望這些通用重構模式和代理管道對您有所幫助。如要掌握未來的開放原始碼技能包、深入技術內容和即將舉行的會議演講，請透過專業管道追蹤我：
- 在 LinkedIn 上追蹤：linkedin.com/in/jamesor
- 在 X (Twitter) 上追蹤：x.com/JamesOR
請告訴我們您的想法
您最期待代理程式協調功能帶來哪些好處？
感謝您使用 Google Antigravity 建構內容！