1. Orientamento del percorso di modernizzazione
Questo codelab completo è il laboratorio pratico complementare derivato direttamente dall'articolo di approfondimento sull'architettura Come automatizzare la modernizzazione con Antigravity e l'orchestrazione multi-agente. Sebbene utilizziamo un classico scambio di framework Node.js come veicolo di dimostrazione tangibile, i pattern di progettazione principali, le strutture di directory e i processi di orchestrazione degli agenti che promuoverai qui sono completamente indipendenti dal linguaggio e universalmente applicabili a qualsiasi progetto di modernizzazione legacy su larga scala.
A differenza degli assistenti alla programmazione standard che completano automaticamente le righe in un singolo file, imparerai a sfruttare le funzionalità di Google Antigravity basate sugli agenti per orchestrare team autonomi di subagenti AI specializzati. Questi agenti possono eseguire il reverse engineering di codebase legacy, scrivere rigorose suite di test, creare architetture moderne e correggere autonomamente gli errori del compilatore utilizzando i loop di riflessione, il tutto mantenendo il controllo assoluto in qualità di architetto di alto livello.
Obiettivi didattici
- Mappatura del flusso di lavoro: come classificare e separare correttamente le attività di configurazione deterministiche dalle sfide di refactoring euristiche complesse.
- Architettura delle competenze: come strutturare un pacchetto di competenze dell'agente estensibile utilizzando la divulgazione progressiva e i metadati di routing YAML.
- Orchestrazione dei pattern di progettazione: come eseguire il refactoring su larga scala concatenando i pattern di progettazione Router, Plan-and-Execute e Reflexion.
- Contratti di input/output rigidi: come applicare limiti chiari per input/abilità/output in pipeline di reverse engineering e scaffolding target in più fasi.
- Verifica della parità: come utilizzare il browser secondario di Antigravity per eseguire test di parità affiancati nel browser web Chrome.
Cosa creerai
Orchestrerai una pipeline di refactoring Greenfield completamente automatizzata che prende il monolite CRUD Express e Mongoose legacy iconico e obsoleto (la "demo di madhums") e lo ricostruisce autonomamente da zero in un'applicazione Next.js App Router con tipizzazione rigida supportata da MongoDB, convalida Zod rigorosa e componenti UI ShadCN accessibili.
Che cosa ti serve
- Google Antigravity IDE installato localmente (disponibile all'indirizzo antigravity.google).
- Node.js (v18+) installato localmente.
- Browser Chrome per la verifica automatica della UI.
- Un clone del monorepo dimostrativo open source modernizing-expressjs.
2. Configura l'ambiente di modernizzazione
Prima di lasciare che gli agenti autonomi si occupino di un codebase legacy obsoleto, dobbiamo creare un ambiente monorepo pulito e altamente stabile. Fornire a un assistente AI una base di riferimento pulita garantisce che si concentri interamente sulla generazione di codice moderno di alta qualità, anziché sprecare token per risolvere vulnerabilità di pacchetti decennali o incompatibilità del compilatore.
Mappatura dell'architettura legacy Express e moderna Next.js
Componente | Stack legacy | Sostituzione moderna | La motivazione |
Architettura | Express Monolith | Router delle app Next.js | Separazione della logica in componenti server per il rendering ottimizzato e le prestazioni dei componenti server React (RSC). |
Data Logic | Mongoose (ODM) | MongoDB + Zod | Scambio di hook ORM impliciti con schemi Zod espliciti e type-safe e prestazioni del driver non elaborate. |
Lingua | CommonJS / JavaScript | TypeScript (ESM) | Applicazione della sicurezza in fase di compilazione e passaggio a standard di moduli moderni. |
Frontend | Pug/EJS (visualizzazione server) | ShadCN UI + Tailwind | Passaggio da modelli rigidi a un sistema di progettazione componibile, accessibile e orientato all'utilità. |
Auth | Passport.js | NextAuth | Modernizzazione della gestione delle sessioni con supporto integrato per Edge e provider contemporanei. |
Sicurezza | Middleware manuale | Zod (convalida rigorosa) | Implementazione di un'unica fonte attendibile per la convalida dei dati nell'intero stack. |
Inizializza l'hub di modernizzazione
La prima azione deterministica consiste nel clonare la struttura del monorepo isolato. In questo modo, il codice legacy di sola lettura viene separato dal nuovo repository di destinazione greenfield, garantendo zero mutazioni accidentali all'applicazione originale.
Apri il terminale Antigravity ed esegui i seguenti comandi di configurazione:
git clone https://github.com/GoogleCloudPlatform/devrel-demos.git cd devrel-demos/other/modernizing-expressjs
Una volta clonato, apri la cartella modernizing-expressjs direttamente nell'esploratore dell'IDE Antigravity. Vedrai il seguente layout isolato:
/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
Guarda questo breve video tutorial che mostra come preparare e isolare in modo deterministico l'ambiente monorepo:
3. Pacchetti e pattern di competenze dell'agente AI Architect
La creazione di una skill dell'agente solida è fondamentalmente diversa dalla scrittura di un prompt di chat standard. Quando crei un pacchetto di skill, progetti un modulo software che un LLM sottostante eseguirà in modo autonomo. Per evitare che l'agente abbia allucinazioni o subisca una "tassa sulla finestra contestuale", introduciamo il pacchetto di skill di orchestrazione Greenfield open source come modello di creazione estensibile basato su due principi non negoziabili: concisione e divulgazione progressiva.
Divulgazione progressiva utilizzando il routing dei metadati YAML
Anziché inserire tutte le regole di targeting in un unico prompt di sistema monolitico, distribuiamo le istruzioni tra le directory. Ogni directory delle competenze contiene un punto di ingresso SKILL.md racchiuso in un blocco frontmatter di routing YAML.
Apri .agents/skills/orchestrating-greenfield-migration/SKILL.md e controlla i metadati del router:
---
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.
---
Codifica hardcoded del pattern Plan-and-Execute
Per impedire a un agente autonomo di andare fuori tema, di farsi distrarre da middleware legacy interessanti o di tentare scambi di database non autorizzati, eseguiamo l'override della pianificazione standard open-ended codificando il pattern Plan-and-Execute direttamente nelle istruzioni.
Ispeziona l'elenco di controllo Markdown letterale incorporato nell'orchestratore principale:
### 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.
Se formatti il flusso di lavoro come un elenco di controllo esplicito con riferimenti alle competenze in linea, l'agente copia questa roadmap esatta nel suo piano di attività, bloccandola in una modalità "solo esecuzione" che seleziona sistematicamente le caselle e richiama i subagenti altamente specializzati esattamente quando necessario.
4. Fase 1: esegui il reverse engineering del monolite legacy (controllo)
Siamo pronti ad attivare la nostra sequenza di orchestrazione principale. La prima fase principale estrae le regole aziendali, gli schemi dei dati e i payload API dal monolite legacy, memorizzandoli come artefatti Markdown puliti, lasciandosi alle spalle un decennio di debito tecnico imperativo.
Attiva la sequenza di refactoring autonomo
Nel riquadro della chat di Antigravity Agent Manager, digita il seguente comando slash personalizzato e premi Invio:
/orchestrating-greenfield-migration
Ora osserva la console del terminale. Vedrai l'agente principale leggere il prompt di sistema, abbinare la tua richiesta ai metadati dell'orchestratore, generare l'elenco di controllo in 5 fasi e iniziare immediatamente a inviare in parallelo i subagenti "Auditor" specializzati.
Il contratto didattico di input/abilità/output
Durante la fase 1, l'agente esegue una pipeline di reverse engineering rigorosa vincolata dal seguente contratto di istruzioni:
Input utilizzati: file di codice sorgente legacy di sola lettura che si trovano all'interno di legacy-app/.
Competenze invocate:
Competenza | Descrizione |
| Traccia le route legacy per documentare le buste di risposta JSON esatte. |
| Decostruisce gli schemi Mongoose per estrarre relazioni, campi obbligatori e valori predefiniti. |
| Documenti sugli effetti collaterali impliciti, flussi di autenticazione del passaporto e regole del middleware. |
| Esegue la scansione dei modelli Pug legacy per mappare l'"intent UI" di alto livello (barre di navigazione, moduli). |
Artefatti prodotti: specifiche Markdown altamente strutturate generate direttamente nella cartella docs/
Artefatto | Descrizione |
| Questo documento descrive in dettaglio l'area della superficie dell'API di reverse engineering dell'applicazione Express legacy. Utilizza questo catalogo per garantire una parità rigorosa durante la ricostruzione delle route nell'applicazione Next.js modernizzata. |
| Questo documento registra i comportamenti, le configurazioni e le regole rigorose verificate dell'applicazione Express legacy in merito ad autenticazione (AuthN), autorizzazione (AuthZ), middleware globali, gestione delle sessioni ed effetti collaterali. |
| Questo documento fornisce un'analisi completa degli schemi Mongoose legacy di |
| Questo documento fornisce un'analisi dettagliata dell'interfaccia utente legacy basata su Pug in |
Guarda questo video di acquisizione del terminale in tempo reale che mostra l'audit di reverse engineering autonomo in azione:
5. Fasi 2 e 3: harness TDD e scaffolding del backend greenfield
Con l'applicazione legacy completamente controllata e documentata, l'orchestratore principale passa alla creazione della struttura del backend di destinazione moderno. Questa fase introduce il pattern di progettazione agentico più potente del nostro toolkit: Reflexion (auto-riflessione) a ciclo chiuso basato su un rigoroso Test-Driven Development (TDD).
Scrivere codice auto-riparante utilizzando i loop di riflessione
Scrivere codice moderno è semplice; garantire che venga compilato perfettamente e superi rigorosi vincoli di convalida richiede una valutazione a circuito chiuso. L'orchestratore gestisce questa operazione in modo autonomo reindirizzando l'output del test direttamente nella finestra contestuale del subagent:
- Fase 2 (configurazione TDD): l'orchestratore richiama il subagent
generating-api-tests, che leggedocs/API_Contracts.mde scrive suite di test di integrazione Vitest esaustive che asseriscono i codici di stato HTTP e i payload JSON richiesti esatti. Come previsto in TDD, questi test inizialmente non riescono. - Fase 3 (struttura di base del backend): gli agenti secondari di scaffolding iniziano a scrivere moderni gestori di route Next.js e schemi di convalida Zod rigorosi.
- Ciclo di autocorrezione: quando l'imbracatura deterministica Vitest valuta il nuovo codice e restituisce un errore (ad esempio, un errore di convalida
422previsto ha restituito un500), l'agente non si arresta in modo anomalo. Riflette sull'output di errore dell'obiettivo, riapre il gestore di route di destinazione, corregge la struttura del payload dello schema Zod ed esegue nuovamente i test. Esegue iterazioni in modo autonomo fino a ottenere un codice di uscita0.
Il contratto didattico di input/abilità/output
Input consumati: artefatti delle specifiche di reverse engineering (docs/API_Contracts.md, docs/Data_Models.md).
Competenze invocate:
Competenza | Descrizione |
| Genera suite di integrazione Vitest non riuscite. |
| Inizializza il layout di base del router delle app Next.js. |
| Configura l'ambiente di esecuzione dei test Vitest locale. |
| Converte i vecchi modelli Mongoose in schemi MongoDB + Zod. |
| Ricrea le route Express in Route Handler Next.js e Route Guard modulari. |
Output prodotti: suite Vitest iniziali non riuscite, schemi Zod completamente digitati, gestori di route Next.js funzionali ed esecuzioni di suite di test pulite e riuscite.
Osserva la generazione automatica dell'ambiente di test TDD:
Osserva l'esecuzione in tempo reale dell'impalcatura del ciclo di auto-correzione di Reflexion del backend di destinazione:
6. Fase 4: crea la struttura del frontend moderno (componenti UI)
Con il livello di convalida del backend completamente protetto e superati i test di integrazione, l'orchestratore principale sposta il contesto per modernizzare la presentazione visiva. I modelli imperativi sottoposti a rendering lato server vengono eliminati a favore di un sistema di progettazione di componenti altamente accessibile e basato sulle utilità.
Traduzione dell'intent dell'UI in visualizzazioni componibili
Anziché tentare una traduzione CSS riga per riga, il subagente frontend legge l'inventario "UI Intent" estratto e mappa gli elementi strutturali direttamente con equivalenti moderni ad alta fedeltà.
Il contratto didattico di input/abilità/output
Input utilizzati: l'artefatto di inventario frontend di reverse engineering (docs/UI_Inventory.md).
Competenze invocate:
Competenza | Descrizione |
| Traduce un artefatto |
Output prodotti: pagine frontend Next.js pronte per la produzione create utilizzando componenti UI ShadCN altamente accessibili e layout di utilità Tailwind CSS.
Guarda la generazione autonoma del livello di visualizzazione del frontend modernizzato:
7. Fase 5: verifica e controllo contraddittorio
La nostra pipeline di refactoring si conclude con un rigoroso controllo della qualità. L'orchestratore principale passa dall'analisi statica del codice al test attivo dell'ambiente di runtime, tentando attivamente di interrompere la nuova applicazione di destinazione per dimostrare la parità funzionale assoluta con la baseline legacy.
Esecuzione del test a due schede e attivazione del browser
La fase di verifica sfrutta le funzionalità visive e DOM integrate di Antigravity per dimostrare autonomamente la riuscita senza richiedere di fare clic manualmente sui moduli:
- Parità affiancata: il subagent
auditing-parityindica al runner locale di avviare contemporaneamente sia il monolite Express legacy sia l'applicazione Next.js modernizzata, verificando la visualizzazione e il rendering dei dati identici. - Sondaggio di sicurezza avversario: l'orchestratore richiama il subagent
adversarial-verification, che avvia il subagent del browser Antigravity. Questo agente specializzato attiva direttamente il browser digitando negli input, inviando moduli e verificando la presenza di regressioni della sicurezza, cookie di sessione danneggiati o casi limite non gestiti. - Generazione di audit trail: il subagente del browser registra automaticamente le acquisizioni video WebP delle attivazioni della sessione, allegandole direttamente al report di migrazione finale come "prova di lavoro" verificabile.
Il contratto didattico di input/abilità/output
Input utilizzati: applicazioni legacy e moderne eseguite in parallelo in ambienti di runtime locali.
Competenze invocate:
Competenza | Descrizione |
| Esegue controlli di verifica affiancati in fase di runtime. |
| Esegue il probing per rilevare difetti logici e regressioni funzionali utilizzando l'attivazione automatica del browser. |
Output prodotti: una traccia di controllo completa della parità funzionale abbinata a video di sessioni del browser registrate che confermano il successo completo.
Osserva il subagente del browser automatizzato che verifica attivamente l'applicazione modernizzata:
8. Preparazione per la produzione post-migrazione e passaggi successivi
Complimenti! Hai orchestrato correttamente una pipeline di refactoring agentica autonoma e altamente avanzata per modernizzare un monolite legacy da zero, apprendendo competenze universali e altamente trasferibili come la divulgazione progressiva, le liste di controllo Pianifica ed esegui e i loop di riflessione auto-riparativi.
Preparazione al deployment in produzione
Con l'applicazione Next.js completamente verificata e controllata, puoi procedere all'integrazione in produzione. Prendi in considerazione l'implementazione di questi passaggi successivi standard del settore:
- Routing incrementale: esegui il deployment di un proxy inverso (ad es. il pattern Strangler Fig) per instradare il traffico in modo incrementale dall'app Express legacy alla destinazione moderna.
- Conservazione della SEO: mappa le route Express legacy ai reindirizzamenti permanenti di Next.js (
_redirects.yaml) per mantenere l'autorità di dominio esistente. - Streaming dei dati: passa dall'inserimento statico del database allo streaming dei dati di produzione in tempo reale con convalida sicura in fase di runtime utilizzando schemi Zod rigorosi.
- Osservabilità: sostituisci le utilità di logging imperative con framework OpenTelemetry strutturati.
Approfondisci le tue competenze di modernizzazione
Per esplorare le codebase sottostanti complete, le istruzioni per le skill personalizzate e la logica teorica esaustiva alla base di questa pipeline, assicurati di leggere l'articolo principale completo:
Entra a far parte della community di Agentic Builder
Spero che questi pattern di refactoring universali e pipeline agentiche ti siano stati utili. Per rimanere aggiornato sui futuri pacchetti di competenze open source, sui contenuti tecnici approfonditi e sui prossimi interventi nelle conferenze, seguimi sui canali professionali:
- Segui su LinkedIn: linkedin.com/in/jamesor
- Segui su X (Twitter): x.com/JamesOR
Facci sapere la tua opinione
Cosa ti entusiasma di più dell'orchestration agentica?
Grazie per creare con Google Antigravity.