1. Orientando sua jornada de modernização
Este codelab abrangente é o laboratório prático complementar derivado diretamente do artigo de análise detalhada da arquitetura, Como automatizar a modernização com o Antigravity e a orquestração multiagente. Embora usemos uma troca de framework Node.js clássico como nosso veículo de demonstração tangível, os principais padrões de design, estruturas de diretório e processos de orquestração agêntica que você vai defender aqui são totalmente independentes de linguagem e universalmente aplicáveis a qualquer projeto de modernização legado em escala.
Ao contrário dos assistentes de programação padrão que apenas preenchem automaticamente linhas em um único arquivo, você vai aprender a aproveitar os recursos de agente do Google Antigravity para orquestrar equipes autônomas de subagentes de IA especializados. Esses agentes podem fazer engenharia reversa de bases de código legadas de forma independente, escrever conjuntos de testes rigorosos, criar arquiteturas modernas e corrigir automaticamente os próprios erros do compilador usando loops de reflexão, tudo isso enquanto você mantém o controle absoluto como arquiteto de alto nível.
O que você vai aprender
- Mapeamento do fluxo de trabalho: como classificar e separar corretamente as tarefas de configuração determinísticas dos desafios complexos de refatoração heurística.
- Arquitetura de habilidades: como estruturar um pacote de habilidades de agente extensível usando divulgação progressiva e metadados de roteamento YAML.
- Orquestração de padrões de design: como impulsionar a refatoração em grande escala encadeando os padrões de design do roteador, de planejamento e execução e de reflexão.
- Contratos de entrada/saída rígidos: como aplicar limites claros de entrada/habilidade/saída em pipelines de engenharia reversa e de scaffolding de destino de várias fases.
- Verificação de paridade: como aproveitar o subagente do navegador do Antigravity para realizar testes de paridade lado a lado no navegador da Web Chrome.
O que você vai criar
Você vai orquestrar um pipeline de refatoração Greenfield totalmente automatizado que usa o monólito CRUD do Express e do Mongoose legados e desatualizados (a "demonstração do madhums") e o recria de forma autônoma em um aplicativo do roteador de apps Next.js com digitação estrita, com suporte do MongoDB, validação Zod estrita e componentes de interface do ShadCN acessíveis.
O que é necessário
- IDE do Google Antigravity instalado localmente (disponível em antigravity.google).
- Node.js (v18 ou mais recente) instalado localmente.
- Navegador Chrome para verificação automatizada da interface.
- Um clone do monorepo de demonstração de modernização do Express.js de código aberto modernizing-expressjs.
2. Configurar o ambiente de modernização
Antes de liberar agentes autônomos em uma base de código legada, precisamos estabelecer um ambiente de monorepo limpo e altamente estável. Dar uma linha de base limpa a um assistente de IA garante que ele se concentre totalmente na geração de código moderno de alta qualidade, em vez de desperdiçar tokens lutando contra vulnerabilidades de pacotes de décadas ou incompatibilidades de compiladores.
Mapeamento da arquitetura do Express legado em comparação com o Next.js moderno
Componente | Pilha legada | Substituição moderna | A justificativa |
Arquitetura | Monolítico do Express | Roteador de apps Next.js | Desacoplar a lógica em componentes de servidor para renderização otimizada e desempenho de componentes de servidor React (RSC). |
Lógica de dados | Mongoose (ODM) | MongoDB + Zod | Trocar hooks ORM implícitos por esquemas Zod explícitos e seguros e desempenho de driver bruto. |
Idioma | CommonJS / JavaScript | TypeScript (ESM) | Aplicar segurança no momento da compilação e migrar para padrões de módulos modernos. |
Front-end | Pug/EJS (visualização do servidor) | Interface do ShadCN + Tailwind | Mudar de modelos rígidos para um sistema de design combinável, acessível e utilitário. |
Auth | Passport.js | NextAuth | Modernizar o gerenciamento de sessões com suporte integrado para Edge e provedores contemporâneos. |
Segurança | Middleware manual | Zod (validação estrita) | Implementar uma "única fonte de verdade" para validação de dados em toda a pilha. |
Inicializar o hub de modernização
Nossa primeira ação determinística é clonar a estrutura isolada do monorepo. Isso separa o código legado somente leitura do nosso novo repositório de destino Greenfield, garantindo que não haja mutações acidentais no aplicativo original.
Abra o terminal do Antigravity e execute os seguintes comandos de configuração:
git clone https://github.com/GoogleCloudPlatform/devrel-demos.git cd devrel-demos/other/modernizing-expressjs
Depois de clonado, abra a pasta modernizing-expressjs diretamente no explorador do IDE do Antigravity. Você vai observar o seguinte layout isolado:
/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
Assista a este breve tutorial em vídeo que demonstra como preparar e isolar seu ambiente de monorepo de forma determinística:
3. Arquitetar pacotes e padrões de habilidades de agentes de IA
A criação de uma habilidade de agente robusta é fundamentalmente diferente da escrita de um comando de chat padrão. Ao criar um pacote de habilidades, você está projetando um software modular que um LLM subjacente vai executar de forma autônoma. Para evitar que o agente tenha alucinações ou sofra "imposto de janela de contexto", apresentamos o pacote de habilidades de orquestração Greenfield de código aberto como um modelo de criação extensível impulsionado por dois princípios não negociáveis: concisão e divulgação progressiva.
Divulgação progressiva usando o roteamento de metadados YAML
Em vez de despejar todas as regras de destino em um único comando de sistema monolítico, distribuímos instruções em diretórios. Cada diretório de habilidades contém um ponto de entrada SKILL.md encapsulado em um bloco de frontmatter de roteamento YAML.
Abra .agents/skills/orchestrating-greenfield-migration/SKILL.md e inspecione os metadados do roteador:
---
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ção fixa do padrão de planejamento e execução
Para evitar que um agente autônomo se desvie, se distraia com um middleware legado interessante ou tente trocas de banco de dados não autorizadas, substituímos o planejamento aberto padrão codificando o padrão Planejamento e execução diretamente nas instruções.
Inspecione a lista de verificação literal do Markdown incorporada no orquestrador 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.
Ao formatar o fluxo de trabalho como uma lista de verificação explícita com referências de habilidades inline, o agente copia esse mapa de caminho exato para o plano de tarefas, bloqueando-o em um modo "somente execução" que marca sistematicamente as caixas e invoca subagentes altamente especializados exatamente quando necessário.
4. Fase 1: fazer engenharia reversa do monólito legado (auditoria)
Estamos prontos para acionar nossa sequência de orquestração principal. Nossa primeira fase principal extrai as regras de negócios, os esquemas de dados e os payloads de API do monólito legado, armazenando-os como artefatos Markdown limpos, deixando para trás uma década de dívida técnica imperativa.
Acionar a sequência de refatoração autônoma
No painel de chat do Gerenciador de agentes do Antigravity, digite o seguinte comando de barra personalizado e pressione Enter:
/orchestrating-greenfield-migration
Agora, observe o console do terminal. Você vai ver o agente principal ler o comando do sistema, corresponder sua solicitação aos metadados do orquestrador, gerar a lista de verificação de cinco fases e começar imediatamente a enviar subagentes "Auditores" especializados em paralelo.
O contrato de instrução de entrada/habilidade/saída
Durante a Fase 1, o agente executa um pipeline de engenharia reversa estrito vinculado ao seguinte contrato de instrução:
Entradas consumidas: arquivos de código-fonte legados somente leitura localizados em legacy-app/.
Habilidades invocadas:
Habilidade | Descrição |
| Rastreia rotas legadas para documentar envelopes de resposta JSON exatos. |
| Desconstrói esquemas do Mongoose para extrair relações, campos obrigatórios e padrões. |
| Documenta efeitos colaterais implícitos, fluxos de autenticação do Passport e regras de middleware. |
| Verifica modelos Pug legados para mapear a "intenção da interface" de alto nível (barras de navegação, formulários). |
Artefatos produzidos: especificações Markdown altamente estruturadas geradas diretamente na pasta docs/
Artefato | Descrição |
| Este documento detalha a área de superfície da API de engenharia reversa do aplicativo Express legado. Use esse catálogo para garantir a paridade estrita ao recriar rotas no aplicativo Next.js modernizado. |
| Este documento registra os comportamentos, configurações e regras estritas verificados do aplicativo Express legado em relação à autenticação (AuthN), autorização (AuthZ), middlewares globais, gerenciamento de sessões e efeitos colaterais. |
| Este documento fornece uma análise abrangente dos esquemas legados do Mongoose de |
| Este documento fornece uma análise detalhada da interface do usuário legada baseada em Pug em |
Assista a esta captura de terminal ao vivo demonstrando a auditoria autônoma de engenharia reversa em ação:
5. Fases 2 e 3: harness de TDD e scaffolding de back-end Greenfield
Com o aplicativo legado totalmente auditado e documentado, o orquestrador principal avança para o scaffolding do back-end de destino moderno. Essa fase apresenta o padrão de design agêntico mais poderoso do nosso kit de ferramentas: Reflexion (autorreflexão) de circuito fechado, impulsionado pelo desenvolvimento orientado a testes (TDD) estrito.
Como gerar código de autocura usando loops de reflexão
Escrever código moderno é simples. No entanto, garantir que ele seja compilado perfeitamente e aprove restrições de validação estritas exige uma avaliação de circuito fechado. O orquestrador processa isso de forma autônoma, transmitindo a saída do teste diretamente para a janela de contexto do subagente:
- Fase 2 (configuração do TDD): o orquestrador invoca o subagente
generating-api-tests, que lêdocs/API_Contracts.mde grava conjuntos de testes de integração Vitest exaustivos, afirmando os códigos de status HTTP e payloads JSON exatos necessários. Como esperado no TDD, esses testes falham inicialmente. - Fase 3 (scaffolding de back-end): os subagentes de scaffolding começam a escrever gerenciadores de rotas Next.js modernos e esquemas de validação Zod estritos.
- Loop de autocorreção: quando o harness determinístico do Vitest avalia o novo código e retorna uma falha (por exemplo, um erro de validação
422esperado retornou um500), o agente não falha. Ele reflete sobre a saída de erro objetiva, reabre o gerenciador de rotas de destino, corrige a estrutura de payload do esquema Zod e executa os testes novamente. Ele itera de forma autônoma até atingir um código de saída de0.
O contrato de instrução de entrada/habilidade/saída
Entradas consumidas: artefatos de especificação de engenharia reversa (docs/API_Contracts.md, docs/Data_Models.md).
Habilidades invocadas:
Habilidade | Descrição |
| Gera conjuntos de integração do Vitest com falha. |
| Inicializa o layout básico do roteador de apps Next.js. |
| Configura o ambiente do executor de testes local do Vitest. |
| Traduz modelos antigos do Mongoose em esquemas do MongoDB + Zod. |
| Recria rotas do Express em gerenciadores de rotas Next.js e guardas de rotas modulares. |
Saídas produzidas: conjuntos iniciais do Vitest com falha, esquemas Zod totalmente digitados, gerenciadores de rotas Next.js funcionais e execuções de conjuntos de testes limpas e aprovadas.
Observe a geração automatizada do harness de teste TDD:
Observe a execução em tempo real do loop de reflexão de autocorreção que cria o back-end de destino:
6. Fase 4: criar o front-end moderno (componentes da interface)
Com a camada de validação de back-end totalmente reforçada e os testes de integração aprovados, o orquestrador principal muda o contexto para modernizar a apresentação visual. Os modelos imperativos renderizados pelo servidor são descartados em favor de um sistema de design de componentes altamente acessível e utilitário.
Como traduzir a intenção da interface em visualizações combináveis
Em vez de tentar uma tradução CSS linha por linha, o subagente de front-end lê o inventário extraído de "intenção da interface" e mapeia elementos estruturais diretamente para equivalentes modernos de alta fidelidade.
O contrato de instrução de entrada/habilidade/saída
Entradas consumidas: o artefato de inventário de front-end de engenharia reversa (docs/UI_Inventory.md).
Habilidades invocadas:
Habilidade | Descrição |
| Traduz um artefato |
Saídas produzidas: páginas de front-end Next.js prontas para produção construídas usando componentes de interface do ShadCN altamente acessíveis e layouts de utilitários CSS do Tailwind.
Assista à geração autônoma da camada de visualização de front-end modernizada:
7. Fase 5: verificação e auditoria adversária
Nosso pipeline de refatoração conclui com uma verificação de qualidade rigorosa. O orquestrador principal faz a transição da análise estática de código para o teste ativo do ambiente de execução, tentando ativamente quebrar o novo aplicativo de destino para comprovar a paridade funcional absoluta com a linha de base legada.
Executar o teste de duas guias e a ativação do navegador
A fase de verificação aproveita os recursos visuais e de DOM integrados do Antigravity para comprovar o sucesso de forma autônoma, sem exigir que você clique manualmente nos formulários:
- Paridade lado a lado: o subagente
auditing-parityinstrui o executor local a iniciar o monólito do Express legado e o aplicativo Next.js modernizado simultaneamente, verificando a apresentação visual e a renderização de dados idênticas. - Sondagem de segurança adversária: o orquestrador invoca o subagente
adversarial-verification, que inicia o subagente do navegador do Antigravity. Esse agente especializado ativa o navegador diretamente, digitando entradas, enviando formulários e investigando regressões de segurança, cookies de sessão corrompidos ou casos extremos não tratados. - Geração de trilha de auditoria: o subagente do navegador grava automaticamente capturas de vídeo WebP das ativações de sessão, anexando-as diretamente ao relatório de migração final como "prova de trabalho" verificável.
O contrato de instrução de entrada/habilidade/saída
Entradas consumidas: aplicativos legados e modernos executados lado a lado em ambientes de execução locais.
Habilidades invocadas:
Habilidade | Descrição |
| Executa verificações de paridade lado a lado no ambiente de execução. |
| Investiga falhas lógicas e regressões funcionais usando a ativação automatizada do navegador. |
Saídas produzidas: uma trilha de auditoria de paridade funcional abrangente combinada com vídeos de sessão do navegador gravados confirmando o sucesso completo.
Observe o subagente do navegador automatizado verificando ativamente o aplicativo modernizado:
8. Preparação para produção pós-migração e próximas etapas
Parabéns! Você orquestrou um pipeline de refatoração agêntica autônomo e altamente avançado para modernizar um monólito legado do zero, aprendendo habilidades universais e altamente transferíveis, como divulgação progressiva, listas de verificação de planejamento e execução e loops de reflexão de autocura.
Preparação para a implantação de produção
Com o aplicativo Next.js totalmente verificado e auditado, você está pronto para avançar para a integração de produção. Considere implementar estas próximas etapas padrão do setor:
- Roteamento incremental: implante um proxy reverso (por exemplo, o padrão Strangler Fig) para rotear o tráfego de forma incremental do aplicativo Express legado para o destino moderno.
- Preservação de SEO: mapeie rotas legadas do Express para redirecionamentos permanentes do Next.js (
_redirects.yaml) para manter a autoridade de domínio atual. - Transmissão de dados: passe da propagação estática do banco de dados para a transmissão de dados de produção ao vivo validados com segurança no ambiente de execução usando esquemas Zod estritos.
- Observabilidade: substitua os utilitários de geração de registros imperativos por frameworks OpenTelemetry estruturados.
Aprofunde seu conhecimento de modernização
Para explorar as bases de código subjacentes completas, instruções de habilidades personalizadas e justificativa teórica exaustiva que impulsionam esse pipeline, leia o artigo principal completo:
Participe da comunidade de criadores de agentes
Espero que você tenha achado esses padrões de refatoração universais e pipelines agênticos valiosos. Fique por dentro dos futuros pacotes de habilidades de código aberto, conteúdo técnico detalhado e palestras em conferências futuras seguindo-me nos canais profissionais:
- Siga no LinkedIn: linkedin.com/in/jamesor
- Siga no X (Twitter): x.com/JamesOR
Envie sua opinião
O que mais te anima na orquestração agêntica?
Agradecemos por criar com o Google Antigravity!