UltraGX Manual de UltraGX
ESENPT
Descargar PDF

Migrar con un agente de IA

La salida de UltraGX está escrita para que un agente de programación (Claude Code, Codex, Cursor, Antigravity u otro) pueda reconstruir la aplicación en otra tecnología sin abrir GeneXus. El agente no tiene que interpretar código GeneXus desde cero: lee reglas ya explicadas, pseudocódigo por evento, el SQL implícito de cada For each, el modelo de datos con sus claves y un orden de reconstrucción.

Este capítulo describe un método de trabajo que funciona bien. No es la única forma, pero evita los errores más comunes: pedirle todo de una vez al agente, o dejar que invente estructura que la KB ya define.

1. Preparar el espacio de trabajo

  1. Generá la documentación con la edición completa y, si podés, con la narrativa en ok para los objetos de negocio. Usá el idioma en que trabaja tu equipo.
  2. Creá el repositorio de la aplicación nueva separado de la salida de UltraGX.
  3. Dejá la salida accesible para el agente como material de solo lectura: por ejemplo, una carpeta hermana (../kb-docs/) o un submódulo. No hace falta copiar viewer/, _pipeline/ ni _source_text/.
  4. En el repositorio nuevo, escribí el archivo de instrucciones del agente (CLAUDE.md, AGENTS.md o las reglas de Cursor) con:
    • la tecnología de destino y sus convenciones (lenguaje, framework, base de datos, estructura de carpetas);
    • la ubicación de la documentación de la KB y la indicación de leer primero su README.md;
    • la regla de que los nombres de tablas, atributos y reglas salen de la documentación, no se inventan;
    • que las notas del usuario prevalecen sobre lo inferido.

Ejemplo de bloque para ese archivo (si tus documentos están en español, las secciones se llaman Notas del usuario y Límites de este análisis):

## 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. Orden de lectura

El README.md de la salida le indica al agente cómo recorrerla. En resumen:

  1. README.md, kb_summary.md y kb_clusters_summary.md: qué hay y cómo se agrupa.
  2. datamodel/index.md: tablas, claves y qué transacción define cada tabla.
  3. global_rebuild_roadmap.md: en qué orden reconstruir.
  4. Por cada cluster: clusters/cluster_NNN.knowledge.md, .flow.md y .rebuild.md.
  5. Por cada objeto: su documento en objects/ (ruta en kb_index.json → doc_path).
  6. Para seguir relaciones: kb_graph.json o la sección Referencias cruzadas de cada documento.

3. Trabajar por fases y por cluster

  1. Modelo de datos primero. Pedile al agente el esquema de base de datos y las entidades a partir de datamodel/. Revisalo contra la base real antes de seguir: todo lo demás se apoya en esto.
  2. Seguí la hoja de ruta. Tomá la primera fase de global_rebuild_roadmap.md y, dentro de ella, un cluster por vez.
  3. Un cluster, una tarea. Para cada cluster, el agente lee su plan de reconstrucción y los documentos de sus objetos, propone el diseño, lo implementa y escribe pruebas a partir de las reglas de negocio.
  4. Cerrá el cluster antes de pasar al siguiente: pruebas en verde, revisión de las reglas una por una y notas del usuario con las decisiones tomadas (quedan para las próximas sesiones del agente).

4. Pedidos de ejemplo

Orientación

Leé ../kb-docs/README.md, kb_summary.md y kb_clusters_summary.md. Resumime qué hace la aplicación, sus áreas
funcionales y las 10 tablas más importantes. No escribas código todavía.

Modelo de datos

A partir de ../kb-docs/datamodel/, generá las migraciones de base de datos para PostgreSQL y las entidades del
ORM. Respetá nombres, tipos y claves primarias y foráneas. Listá cualquier tabla cuya
definición esté incompleta.

Un cluster

Implementá el cluster cluster_004 según clusters/cluster_004.rebuild.md. Leé el documento de cada objeto miembro
y reproducí sus reglas de negocio y el SQL implícito de sus For each. Para las pantallas, usá la sección de
interfaz de usuario. Escribí una prueba por regla de negocio y marcá lo que no puedas reproducir con certeza.

Un objeto puntual

Buscá en kb_index.json el procedure CalcularDescuento, leé su documento y reimplementalo como servicio. Explicá
cada rama del pseudocódigo en un comentario de la prueba correspondiente.

Verificación

Compará el servicio InvoiceService con objects/Facturacion/Transaction.Factura.md: enumerá cada regla de negocio
del documento e indicá dónde está implementada o si falta.

5. Buenas prácticas