UltraGX UltraGX manual
ESENPT
Download PDF

Migrating with an AI agent

The UltraGX output is written so that a coding agent (Claude Code, Codex, Cursor, Antigravity or another) can rebuild the application in another technology without opening GeneXus. The agent does not have to interpret GeneXus code from scratch: it reads rules that are already explained, pseudocode per event, the implicit SQL of each For each, the data model with its keys and a rebuild order.

This chapter describes a way of working that works well. It is not the only one, but it avoids the most common mistakes: asking the agent for everything at once, or letting it invent structure that the KB already defines.

1. Preparing the workspace

  1. Generate the documentation with the full edition and, if you can, with the narrative at ok for the business objects. Use the language your team works in.
  2. Create the repository of the new application separate from the UltraGX output.
  3. Make the output available to the agent as read-only material: for example, a sibling folder (../kb-docs/) or a submodule. There is no need to copy viewer/, _pipeline/ or _source_text/.
  4. In the new repository, write the agent's instructions file (CLAUDE.md, AGENTS.md or the Cursor rules) with:
    • the target technology and its conventions (language, framework, database, folder structure);
    • the location of the KB documentation and the instruction to read its README.md first;
    • the rule that table, attribute and rule names come from the documentation and are never invented;
    • that user notes take precedence over inferred statements.

Example block for that file (with documents in English, the sections are called User notes and Limits of this analysis, as below; adjust the names if your documents are in another language):

## 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. Reading order

The output's README.md tells the agent how to go through it. In short:

  1. README.md, kb_summary.md and kb_clusters_summary.md: what there is and how it is grouped.
  2. datamodel/index.md: tables, keys and which transaction defines each table.
  3. global_rebuild_roadmap.md: in what order to rebuild.
  4. For each cluster: clusters/cluster_NNN.knowledge.md, .flow.md and .rebuild.md.
  5. For each object: its document in objects/ (path in kb_index.json → doc_path).
  6. To follow relationships: kb_graph.json or the Cross references section of each document.

3. Working by phase and by cluster

  1. Data model first. Ask the agent for the database schema and the entities based on datamodel/. Check it against the real database before going on: everything else builds on this.
  2. Follow the roadmap. Take the first phase of global_rebuild_roadmap.md and, within it, one cluster at a time.
  3. One cluster, one task. For each cluster, the agent reads its rebuild plan and the documents of its objects, proposes the design, implements it and writes tests based on the business rules.
  4. Close the cluster before moving to the next one: tests green, rules reviewed one by one and user notes with the decisions taken (they remain for the agent's next sessions).

4. Sample prompts

Orientation

Read ../kb-docs/README.md, kb_summary.md and kb_clusters_summary.md. Summarise what the application does, its
functional areas and the 10 most important tables. Do not write any code yet.

Data model

Based on ../kb-docs/datamodel/, generate the database migrations for PostgreSQL and the ORM entities. Keep the
names, types, primary keys and foreign keys. List any table whose
definition is incomplete.

One cluster

Implement cluster cluster_004 according to clusters/cluster_004.rebuild.md. Read the document of each member object
and reproduce its business rules and the implicit SQL of its For each commands. For the screens, use the user
interface section. Write one test per business rule and flag anything you cannot reproduce with certainty.

A single object

Look up the procedure CalcularDescuento in kb_index.json, read its document and reimplement it as a service. Explain
each branch of the pseudocode in a comment in the corresponding test.

Verification

Compare the InvoiceService service with objects/Facturacion/Transaction.Factura.md: list every business rule in
the document and state where it is implemented or whether it is missing.

5. Good practices