UltraGX Manual do UltraGX
ESENPT
Baixar PDF

Migrar com um agente de IA

A saída do UltraGX foi escrita para que um agente de programação (Claude Code, Codex, Cursor, Antigravity ou outro) possa reconstruir o aplicativo em outra tecnologia sem abrir o GeneXus. O agente não precisa interpretar código GeneXus do zero: ele lê regras já explicadas, pseudocódigo por evento, o SQL implícito de cada For each, o modelo de dados com suas chaves e uma ordem de reconstrução.

Este capítulo descreve um método de trabalho que funciona bem. Não é a única forma, mas evita os erros mais comuns: pedir tudo de uma vez ao agente, ou deixar que ele invente estrutura que a KB já define.

1. Preparar o espaço de trabalho

  1. Gere a documentação com a edição completa e, se possível, com a narrativa em ok para os objetos de negócio. Use o idioma em que a sua equipe trabalha.
  2. Crie o repositório do novo aplicativo separado da saída do UltraGX.
  3. Deixe a saída acessível ao agente como material somente leitura: por exemplo, uma pasta irmã (../kb-docs/) ou um submódulo. Não é preciso copiar viewer/, _pipeline/ nem _source_text/.
  4. No novo repositório, escreva o arquivo de instruções do agente (CLAUDE.md, AGENTS.md ou as regras do Cursor) com:
    • a tecnologia de destino e suas convenções (linguagem, framework, banco de dados, estrutura de pastas);
    • a localização da documentação da KB e a indicação de ler primeiro o seu README.md;
    • a regra de que os nomes de tabelas, atributos e regras vêm da documentação, não são inventados;
    • que as notas do usuário prevalecem sobre o que foi inferido.

Exemplo de bloco para esse arquivo (se os seus documentos estiverem em português, as seções se chamam Notas do usuário e Limites desta análise):

## Legacy system knowledge

The GeneXus application being migrated is documented in ../kb-docs (UltraGX output, read-only).
Start with ../kb-docs/README.md. Locate objects through kb_index.json (doc_path column).
Table and column names, keys and business rules come from those documents; never invent them.
"User notes" sections override inferred statements. When a document lists something under
"Limits of this analysis", ask before assuming.

2. Ordem de leitura

O README.md da saída indica ao agente como percorrê-la. Em resumo:

  1. README.md, kb_summary.md e kb_clusters_summary.md: o que existe e como está agrupado.
  2. datamodel/index.md: tabelas, chaves e qual transação define cada tabela.
  3. global_rebuild_roadmap.md: em que ordem reconstruir.
  4. Para cada cluster: clusters/cluster_NNN.knowledge.md, .flow.md e .rebuild.md.
  5. Para cada objeto: o seu documento em objects/ (caminho em kb_index.json → doc_path).
  6. Para seguir relações: kb_graph.json ou a seção Referências cruzadas de cada documento.

3. Trabalhar por fases e por cluster

  1. Modelo de dados primeiro. Peça ao agente o esquema do banco de dados e as entidades a partir de datamodel/. Revise-o contra o banco real antes de seguir: todo o resto se apoia nisso.
  2. Siga o roteiro. Pegue a primeira fase de global_rebuild_roadmap.md e, dentro dela, um cluster por vez.
  3. Um cluster, uma tarefa. Para cada cluster, o agente lê o seu plano de reconstrução e os documentos dos seus objetos, propõe o design, implementa e escreve testes a partir das regras de negócio.
  4. Feche o cluster antes de passar ao próximo: testes passando, revisão das regras uma a uma e notas do usuário com as decisões tomadas (elas ficam para as próximas sessões do agente).

4. Pedidos de exemplo

Orientação

Leia ../kb-docs/README.md, kb_summary.md e kb_clusters_summary.md. Resuma o que o aplicativo faz, suas áreas
funcionais e as 10 tabelas mais importantes. Não escreva código ainda.

Modelo de dados

A partir de ../kb-docs/datamodel/, gere as migrations do banco de dados para PostgreSQL e as entidades do
ORM. Respeite nomes, tipos e chaves primárias e estrangeiras. Liste qualquer tabela cuja
definição esteja incompleta.

Um cluster

Implemente o cluster cluster_004 conforme clusters/cluster_004.rebuild.md. Leia o documento de cada objeto membro
e reproduza suas regras de negócio e o SQL implícito dos seus For each. Para as telas, use a seção de
interface do usuário. Escreva um teste por regra de negócio e marque o que você não conseguir reproduzir com certeza.

Um objeto específico

Procure em kb_index.json o procedure CalcularDescuento, leia o seu documento e reimplemente-o como serviço. Explique
cada ramo do pseudocódigo em um comentário do teste correspondente.

Verificação

Compare o serviço InvoiceService com objects/Facturacion/Transaction.Factura.md: enumere cada regra de negócio
do documento e indique onde ela está implementada ou se está faltando.

5. Boas práticas