1. Orientación sobre tu recorrido de modernización
Este codelab integral es el laboratorio práctico complementario derivado directamente del artículo de análisis detallado de la arquitectura, Cómo automatizar la modernización con Antigravity y la organización de varios agentes. Si bien usamos un intercambio clásico de frameworks de Node.js como nuestro vehículo de demostración tangible, los patrones de diseño principales, las estructuras de directorios y los procesos de organización de agentes que defenderás aquí son completamente independientes del lenguaje y se pueden aplicar universalmente a cualquier proyecto de modernización heredado a gran escala.
A diferencia de los asistentes de programación estándar que solo completan automáticamente líneas en un solo archivo, aprenderás a aprovechar las capacidades de Google Antigravity centradas en el agente para coordinar equipos autónomos de subagentes especializados de IA. Estos agentes pueden realizar ingeniería inversa de bases de código heredadas, escribir conjuntos de pruebas rigurosos, crear arquitecturas modernas y corregir sus propios errores de compilador con bucles de reflexión, todo de forma independiente, mientras tú mantienes el control absoluto como arquitecto de alto nivel.
Qué aprenderás
- Asignación del flujo de trabajo: Cómo clasificar y separar correctamente las tareas de configuración determinísticas de los desafíos complejos de refactorización heurística
- Arquitectura de habilidades: Cómo estructurar un paquete de habilidades de agente extensible con divulgación progresiva y metadatos de enrutamiento de YAML
- Patrones de diseño de orquestación: Cómo impulsar la refactorización a gran escala encadenando los patrones de diseño de Router, Planificar y ejecutar, y Reflexión
- Contratos de entrada y salida rígidos: Cómo aplicar límites claros de entrada, habilidad y salida en las canalizaciones de ingeniería inversa y de estructuración de objetivos de varias fases
- Verificación de paridad: Cómo aprovechar el subagente del navegador de Antigravity para realizar pruebas de paridad comparativas en un navegador web de Chrome
Qué compilarás
Orquestarás una canalización de refactorización Greenfield completamente automatizada que toma el icónico y desactualizado monolito heredado de Express y Mongoose CRUD (la "demostración de madhums") y lo reconstruye de forma autónoma desde cero en una aplicación del enrutador de aplicaciones de Next.js estrictamente tipificada respaldada por MongoDB, validación estricta de Zod y componentes de IU de ShadCN accesibles.
Requisitos
- IDE de Google Antigravity instalado de forma local (disponible en antigravity.google).
- Node.js (v18 o versiones posteriores) instalado de forma local
- Navegador Chrome para la verificación automatizada de la IU
- Es un clon del monorepo de demostración de código abierto modernizing-expressjs.
2. Configura el entorno de modernización
Antes de liberar agentes autónomos en una base de código heredada y envejecida, debemos establecer un entorno de monorepo limpio y altamente estable. Proporcionar una línea de base limpia a un asistente de IA garantiza que se enfoque por completo en generar código moderno de alta calidad en lugar de desperdiciar tokens en combatir vulnerabilidades de paquetes de hace décadas o discrepancias del compilador.
Comparación entre la arquitectura heredada de Express y la moderna de Next.js
Componente | Pila heredada | Modern Replacement | The Rationale |
Arquitectura | Monolito de Express | App Router de Next.js | Desacopla la lógica en componentes del servidor para optimizar la renderización y el rendimiento de los componentes del servidor de React (RSC). |
Lógica de datos | Mongoose (ODM) | MongoDB y Zod | Se intercambiaron los hooks implícitos del ORM por esquemas Zod explícitos y seguros para tipos, y por el rendimiento del controlador sin procesar. |
Idioma | CommonJS / JavaScript | TypeScript (ESM) | Se aplica la seguridad en tiempo de compilación y se migra a estándares de módulos modernos. |
Frontend | Pug/EJS (vista del servidor) | IU de ShadCN + Tailwind | Pasamos de plantillas rígidas a un sistema de diseño componible, accesible y centrado en la utilidad. |
Auth | Passport.js | NextAuth | Modernización de la administración de sesiones con compatibilidad integrada para Edge y proveedores contemporáneos |
Seguridad | Middleware manual | Zod (validación estricta) | Implementamos una "fuente única de información" para la validación de datos en toda la pila. |
Inicializa el centro de modernización
Nuestra primera acción determinística es clonar la estructura aislada del monorepo. Esto separa el código heredado de solo lectura de nuestro nuevo repositorio de destino Greenfield, lo que garantiza que no haya mutaciones accidentales en la aplicación original.
Abre la terminal de Antigravity y ejecuta los siguientes comandos de configuración:
git clone https://github.com/GoogleCloudPlatform/devrel-demos.git cd devrel-demos/other/modernizing-expressjs
Una vez clonado, abre la carpeta modernizing-expressjs directamente en el explorador del IDE de Antigravity. Verás el siguiente diseño aislado:
/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
Mira este breve video explicativo en el que se muestra cómo preparar y aislar tu entorno de monorepo de forma determinista:
3. Diseña paquetes y patrones de habilidades de agentes de IA
Crear una habilidad de agente sólida es fundamentalmente diferente de escribir una instrucción de chat estándar. Cuando creas un Skill Pack, diseñas una pieza modular de software que un LLM subyacente ejecutará de forma autónoma. Para evitar que el agente alucine o experimente la "tasa de ventana de contexto", presentamos el paquete de habilidades de orquestación de Greenfield de código abierto como una plantilla de creación extensible basada en dos principios no negociables: concisión y divulgación progresiva.
Divulgación progresiva con el enrutamiento de metadatos de YAML
En lugar de volcar todas las reglas de destino en una sola instrucción del sistema monolítica, distribuimos las instrucciones en los directorios. Cada directorio de Skill contiene un punto de entrada SKILL.md incluido en un bloque de encabezado YAML de enrutamiento.
Abre .agents/skills/orchestrating-greenfield-migration/SKILL.md y examina los metadatos 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.
---
Codificación del patrón de planificación y ejecución
Para evitar que un agente autónomo se desvíe, se distraiga con middleware heredado interesante o intente intercambios no autorizados de bases de datos, anulamos la planificación estándar de extremo abierto codificando el patrón Planificar y ejecutar directamente en las instrucciones.
Inspecciona la lista de tareas de Markdown literal incorporada en el orquestador principal:
### 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.
Al darle formato al flujo de trabajo como una lista de tareas explícita con referencias a habilidades intercaladas, el agente copia esta hoja de ruta exacta en su plan de tareas, lo que lo bloquea en un modo de "solo ejecución" que marca sistemáticamente las casillas y llama a subagentes altamente especializados exactamente cuando es necesario.
4. Fase 1: Realiza ingeniería inversa de la aplicación monolítica heredada (auditoría)
Ya podemos activar nuestra secuencia de orquestación principal. Nuestra primera fase importante extrae las reglas de negocio, los esquemas de datos y las cargas útiles de la API de la aplicación monolítica heredada, y los almacena como artefactos Markdown limpios, a la vez que deja atrás una década de deuda técnica imperativa.
Cómo activar la secuencia de refactorización autónoma
En el panel de chat del Administrador de agentes de Antigravity, escribe el siguiente comando personalizado con barra y presiona Intro:
/orchestrating-greenfield-migration
Ahora, observa la consola de tu terminal. Verás cómo el agente principal lee su instrucción del sistema, correlaciona tu solicitud con los metadatos del orquestador, genera la lista de verificación de 5 fases y comienza de inmediato a enviar subagentes "auditores" especializados en paralelo.
El contrato de instrucción de entrada, habilidad y salida
Durante la fase 1, el agente ejecuta una canalización de ingeniería inversa estricta vinculada por el siguiente contrato de instrucciones:
Entradas consumidas: Archivos de código fuente heredados de solo lectura ubicados dentro de legacy-app/.
Habilidades invocadas:
Habilidad | Descripción |
| Realiza un seguimiento de las rutas heredadas para documentar los sobres de respuesta JSON exactos. |
| Descompone los esquemas de Mongoose para extraer relaciones, campos obligatorios y valores predeterminados. |
| Documenta los efectos secundarios implícitos, los flujos de autenticación de Passport y las reglas de middleware. |
| Analiza las plantillas Pug heredadas para asignar la "intención de la IU" de alto nivel (barras de navegación, formularios). |
Artefactos producidos: Especificaciones de Markdown altamente estructuradas que se generan directamente en tu carpeta docs/
Artefacto | Descripción |
| En este documento, se detalla el área de la API de ingeniería inversa de la aplicación heredada de Express. Usa este catálogo para garantizar una paridad estricta cuando vuelvas a compilar rutas en la aplicación modernizada de Next.js. |
| En este documento, se registran los comportamientos, las configuraciones y las reglas estrictas verificados de la aplicación heredada de Express en relación con la autenticación (AuthN), la autorización (AuthZ), los middlewares globales, la administración de sesiones y los efectos secundarios. |
| En este documento, se proporciona un análisis integral de los esquemas heredados de Mongoose de |
| En este documento, se proporciona un análisis detallado de la interfaz de usuario heredada basada en Pug en |
Mira esta captura de terminal en vivo que muestra la auditoría autónoma de ingeniería inversa en acción:
5. Fases 2 y 3: Estructura de TDD y estructura de backend nueva
Una vez que se audita y documenta por completo la aplicación heredada, el orquestador principal avanza para crear la estructura del backend de destino moderno. En esta fase, se presenta el patrón de diseño de agente más potente de nuestro kit de herramientas: la Reflexión (autorreflexión) de circuito cerrado impulsada por un estricto desarrollo basado en pruebas (TDD).
Cómo impulsar el código de recuperación automática con bucles de reflexión
Escribir código moderno es sencillo; garantizar que se compile a la perfección y que supere las estrictas restricciones de validación requiere una evaluación de circuito cerrado. El organizador controla esto de forma autónoma canalizando el resultado de la prueba directamente a la ventana de contexto del subagente:
- Fase 2 (configuración de TDD): El orquestador invoca al subagente
generating-api-tests, que leedocs/API_Contracts.mdy escribe conjuntos de pruebas de integración exhaustivos de Vitest que confirman los códigos de estado HTTP y las cargas útiles JSON exactos requeridos. Como se espera en el TDD, estas pruebas fallan inicialmente. - Fase 3 (estructura del backend): Los subagentes de estructura comienzan a escribir controladores de rutas modernos de Next.js y esquemas de validación estrictos de Zod.
- Bucle de autocorrección: Cuando el arnés determinístico de Vitest evalúa el código nuevo y muestra un error (p.ej., un error de validación
422esperado devolvió un500), el agente no falla. Reflexiona sobre el resultado del error objetivo, vuelve a abrir el controlador de rutas de destino, corrige la estructura de la carga útil del esquema de Zod y vuelve a ejecutar las pruebas. Itera de forma autónoma hasta lograr un código de salida de0.
El contrato de instrucción de entrada, habilidad y salida
Entradas consumidas: Artefactos de especificación obtenidos por ingeniería inversa (docs/API_Contracts.md, docs/Data_Models.md).
Habilidades invocadas:
Habilidad | Descripción |
| Genera conjuntos de integración de Vitest que fallan. |
| Inicializa el diseño base del enrutador de la app de Next.js. |
| Configura el entorno local del ejecutor de pruebas de Vitest. |
| Traduce modelos antiguos de Mongoose a esquemas de MongoDB y Zod. |
| Vuelve a compilar las rutas de Express en controladores de rutas de Next.js y protectores de rutas modulares. |
Resultados producidos: Paquetes de Vitest iniciales con errores, esquemas de Zod completamente escritos, controladores de rutas funcionales de Next.js y ejecuciones de paquetes de pruebas limpias y aprobadas.
Observa la generación automatizada del arnés de prueba de TDD:
Observa la ejecución en tiempo real del bucle de Reflexión que se corrige automáticamente y que estructura el backend de destino:
6. Fase 4: Estructura del frontend moderno (componentes de la IU)
Con la capa de validación de backend completamente protegida y superando las pruebas de integración, el orquestador principal cambia el contexto para modernizar la presentación visual. Las plantillas imperativas renderizadas por el servidor se descartan en favor de un sistema de diseño de componentes altamente accesible y centrado en la utilidad.
Cómo traducir la intención de la IU a vistas componibles
En lugar de intentar una traducción de CSS línea por línea, el subagente de frontend lee el inventario de "Intención de la IU" extraído y asigna los elementos estructurales directamente a equivalentes modernos de alta fidelidad.
El contrato de instrucción de entrada, habilidad y salida
Entradas consumidas: Es el artefacto de inventario de frontend obtenido a través de ingeniería inversa (docs/UI_Inventory.md).
Habilidades invocadas:
Habilidad | Descripción |
| Traduce un artefacto |
Resultados producidos: Páginas de frontend de Next.js listas para producción construidas con componentes de IU de ShadCN altamente accesibles y diseños de utilidad de Tailwind CSS.
Observa la generación autónoma de la capa de vista del frontend modernizado:
7. Fase 5: Verificación y auditoría adversaria
Nuestro canal de refactorización concluye con una revisión de calidad rigurosa. El orquestador principal pasa del análisis de código estático a las pruebas activas del entorno de ejecución, y trata de interrumpir la nueva aplicación objetivo para demostrar la paridad funcional absoluta con el modelo heredado.
Ejecución de la prueba de dos pestañas y activación del navegador
La fase de verificación aprovecha las capacidades visuales y del DOM integradas de Antigravity para demostrar el éxito de forma autónoma sin necesidad de que hagas clic en los formularios de forma manual:
- Paridad lado a lado: El subagente
auditing-parityle indica al ejecutor local que inicie la aplicación monolítica heredada de Express y la aplicación modernizada de Next.js de forma simultánea, lo que verifica la presentación visual y la renderización de datos idénticas. - Sondeo de seguridad adversarial: El organizador invoca al subagente
adversarial-verification, que lanza el Subagente del navegador antigravedad. Este agente especializado acciona el navegador directamente: escribe en las entradas, envía formularios y sondea regresiones de seguridad, cookies de sesión dañadas o casos extremos no controlados. - Generación de registros de auditoría: El subagente del navegador registra automáticamente capturas de video WebP de sus acciones de sesión y las adjunta directamente al informe de migración final como "prueba de trabajo" verificable.
El contrato de instrucción de entrada, habilidad y salida
Entradas consumidas: Aplicaciones heredadas y modernas que se ejecutan en paralelo en entornos de ejecución locales.
Habilidades invocadas:
Habilidad | Descripción |
| Ejecuta verificaciones de validación en paralelo durante el tiempo de ejecución. |
| Sondea los defectos lógicos y las regresiones funcionales con la activación automatizada del navegador. |
Resultados producidos: Un registro de auditoría integral de paridad funcional junto con videos grabados de sesiones del navegador que confirman el éxito completo.
Observa cómo el subagente del navegador automatizado verifica activamente la aplicación modernizada:
8. Preparación para la producción posterior a la migración y próximos pasos
¡Felicitaciones! Orquestaste correctamente una canalización de refactorización autónoma y altamente avanzada para modernizar un monolito heredado desde cero, y aprendiste habilidades universales y altamente transferibles, como la divulgación progresiva, las listas de verificación de Planificar y ejecutar, y los bucles de reflexión de recuperación automática.
Preparación para la implementación en producción
Una vez que tu aplicación de Next.js esté completamente verificada y auditada, podrás avanzar con la integración en producción. Considera implementar los siguientes pasos que son estándares de la industria:
- Enrutamiento incremental: Implementa un proxy inverso (p.ej., el patrón de aplicación estranguladora) para enrutar el tráfico de forma incremental desde la app heredada de Express al destino moderno.
- Conservación del SEO: Asigna rutas heredadas de Express a redireccionamientos permanentes de Next.js (
_redirects.yaml) para conservar la autoridad de dominio existente. - Transmisión de datos: Pasa de la inicialización de bases de datos estáticas a la transmisión de datos de producción en vivo validados de forma segura en el tiempo de ejecución con esquemas Zod estrictos.
- Observabilidad: Reemplaza las utilidades de registro imperativas por frameworks estructurados de OpenTelemetry.
Amplía tu experiencia en modernización
Para explorar las bases de código subyacentes completas, las instrucciones de habilidades personalizadas y la justificación teórica exhaustiva que impulsa esta canalización, asegúrate de leer el artículo principal completo:
Únete a la comunidad de Agentic Builder
Espero que estos patrones de refactorización universales y las canalizaciones basadas en agentes te hayan resultado valiosos. Para mantenerte al tanto de los próximos paquetes de habilidades de código abierto, el contenido técnico detallado y las próximas conferencias en las que participaré, sígueme en los siguientes canales profesionales:
- Seguir en LinkedIn: linkedin.com/in/jamesor
- Seguir en X (Twitter): x.com/JamesOR
Envíanos tu opinión
¿Qué es lo que más te entusiasma de la orquestación de agentes?
Gracias por compilar con Google Antigravity.