Todas las guías técnicas
Modernización con IA

Migración de sistemas con agentes de IA

Cómo inventariar las reglas de negocio, migrar por partes y comprobar que el sistema nuevo se comporta igual que el anterior, mientras adoptas una arquitectura más moderna.

01

Cuándo usar esta guía

Úsala cuando tu equipo transforma un sistema existente y necesita conservar sus reglas de negocio mientras cambia la tecnología, la arquitectura o la plataforma.

La meta no es copiar el sistema anterior línea por línea. Es conservar el comportamiento de negocio que debe seguir igual, decidir de forma explícita qué no se lleva y aprovechar lo que ofrece la tecnología nueva, con cada decisión documentada. A lo largo de la guía, la marca DEV señala lo que sólo hace o decide alguien del equipo.
  • Inventario antes de implementar

    Se documentan las reglas de cada módulo, pantalla o porción del sistema (lo que en inglés llaman slice), y nadie empieza a construir hasta que se aprueban.

  • Un rol más en el ciclo de agentes

    Entre el Implementador y el Auditor entra la Fuente de verdad, que comprueba las reglas de negocio y el uso de la arquitectura nueva. El Auditor sigue revisando la calidad y la definición de terminado.

  • Requerimientos y patrones del sistema nuevo

    Se fijan en la plantilla nueva. El sistema anterior aporta evidencia de negocio, pero no dicta la arquitectura.

  • Seguridad para ambos sistemas

    El gateway y la DLP cubren el código y los datos del sistema anterior, y los secretos de producción quedan fuera del alcance del agente.

  • Terminado, con evidencia

    Las pruebas y la trazabilidad demuestran que las reglas se conservaron y que se siguió el diseño nuevo.

02

Flujo de migración

Son seis fases y van en orden. El inventario aprobado es lo que abre la puerta al ciclo de agentes.

Arquitectura nueva · DEV

Plantilla y requerimientos del sistema nuevo

Los requerimientos no funcionales y los patrones de la tecnología nueva se fijan en la plantilla. El sistema anterior aporta el inventario de reglas de negocio; no decide cómo se construye lo nuevo.
  • Seguridad: prácticas de OWASP, autenticación, autorización y cifrado de la tecnología nueva.
  • Desempeño: objetivos de servicio (SLO) del sistema migrado.
  • Arquitectura nueva: capas, límites entre dominios y registros de decisiones (ADR) de la migración.
  • Observabilidad: logs, trazas y métricas del entorno nuevo.
Entorno de desarrollo

Infraestructura en contenedores

  • Crear: la estructura inicial del sistema nuevo con Compose o Devcontainer, según la plantilla.
  • Ejecutar: servicios aislados y, cuando el inventario lo necesite, acceso de sólo lectura al sistema anterior.
  • Probar y cerrar: las pruebas de la porción migrada corren en el entorno nuevo hasta cumplir la definición de terminado.
Controles de seguridad

Gateway · DLP · Escaneo local · Secretos

  • Gateway hacia los modelos: aplica la prevención de fuga de datos (DLP) al código y a los datos de negocio del sistema anterior que entran en un prompt.
  • Gitleaks o equivalente: bloquea los secretos de ambos sistemas.
  • Secretos por ambiente: sólo en desarrollo, QA y pruebas; producción queda fuera del alcance del agente.
Antes del ciclo · DEV

Inventario de reglas de negocio

Un agente documenta las reglas del módulo, la pantalla o la porción elegida. Ese inventario es la referencia del negocio y tiene que existir antes de que arranque el ciclo Orquestador–Implementador–Fuente de verdad–Auditor.
Ciclo de ejecución

Orquestador → Implementador → Fuente de verdad → Auditor

Con el inventario aprobado, el ciclo comprueba dos cosas a la vez: que se respeten las reglas de negocio y que se aprovechen los patrones de la arquitectura nueva.
Puertas de control

Commit · Push · Solicitud de cambios (PR) · Merge

Además de la seguridad y la definición de terminado, la solicitud de cambios (pull request o PR) adjunta el inventario de la porción y el veredicto de la Fuente de verdad, con su evidencia.
03

Inventario de reglas de negocio

El inventario tiene que ser tan concreto que otra persona pueda revisar la evidencia y escribir pruebas a partir de él. Primero documentas cinco aspectos del sistema anterior y luego compruebas lo necesario para aprobarlo. No son etapas en secuencia; se trabajan en paralelo.

Qué documentar del sistema anterior

Interfaz y experiencia

Pantallas y flujos

De cada campo registra el tipo, si es obligatorio, su valor inicial y sus validaciones en cliente y servidor. Documenta estados, errores, flujos, mensajes, cuándo se muestra o habilita cada elemento, los servicios externos que se llaman, y los permisos y roles.
API y servicios

Contratos y efectos

Registra endpoints, contratos y códigos de respuesta; reglas de negocio y de orquestación; persistencia, transacciones e idempotencia; integraciones y efectos secundarios; autorización, auditoría, límites, procesos programados, eventos y dependencias de tiempo.
Datos y autorización

Condiciones de operación

Documenta roles, autorización, auditoría, límites, dependencias de tiempo y cualquier condición que cambie el resultado.
Evidencia de origen

Trazabilidad al sistema anterior

Relaciona cada regla con la fuente donde se puede comprobar (código, configuración, documentación, datos de prueba o la validación de una persona experta) e indica qué tan crítica es y qué dudas quedan.
Criterios de aceptación

Casos normales y casos límite

Anota los resultados de negocio esperados, los caminos principales, los límites y los errores que deben seguir funcionando igual. Una regla sin fuente ni validación de un experto queda como duda, no como hecho.

Qué debe quedar aprobado antes de implementar

  • Catálogo de reglas de la porción

    Se delimita el módulo, la pantalla o el conjunto de endpoints, y cada regla tiene identificador, descripción, evidencia del sistema anterior y nivel de criticidad.

  • Casos de prueba de negocio

    El camino normal, los límites y los casos raros que deben sobrevivir a la migración, cada uno con su resultado esperado.

  • Exclusiones explícitas

    Cualquier comportamiento o deuda que no se replica tiene una decisión documentada y una persona responsable.

  • Aprobación antes de implementar

    Una persona experta del negocio o del área técnica revisa la lista y resuelve las ambigüedades antes de que arranque el ciclo.

04

Infraestructura del sistema nuevo

Usa los mismos criterios de entorno, aislamiento y pruebas de la base común, con dos diferencias. El acceso al sistema anterior es de sólo lectura, y las pruebas de paridad salen del inventario.

Sistema nuevo reproducible

Devcontainer o Compose

Fija las imágenes y los servicios de la tecnología nueva y conserva comandos conocidos como make test y make lint.
Aislamiento por porción

Acceso controlado al sistema anterior

Trabaja en una rama o worktree aparte. Si necesitas consultar el sistema anterior para el inventario, el acceso es de sólo lectura y se limita a la porción acordada. Nunca le des al agente secretos de producción de ninguno de los dos sistemas.
Pruebas de paridad

Comportamiento y contratos

Corre los casos del inventario, las pruebas de contratos y las de regresión de la porción en el entorno nuevo. Versiona el inventario y la matriz junto con el PR, y guarda los resultados como evidencia.
05

Ciclo con Fuente de verdad

En una migración se agrega la Fuente de verdad entre la implementación y la auditoría. Comprueba que el negocio se comporte igual y que de verdad se use la arquitectura nueva.

01Coordinación

Orquestador

Planea la porción con el inventario aprobado, los patrones del sistema nuevo y los límites de la tarea.

02Construcción

Implementador

Construye en la tecnología nueva y relaciona cada regla con su código y su prueba.

03Paridad

Fuente de verdad

Contrasta reglas, pruebas y arquitectura nueva, y reporta diferencias que se puedan reproducir.

04Revisión

Auditor

Revisa calidad, seguridad y definición de terminado con un contexto limpio, sin sustituir a la Fuente de verdad.

Si la Fuente de verdad o el Auditor encuentran algo, el Orquestador decide el reintento
CierreFuente de verdad y Auditor aprobados
La Fuente de verdad comprueba la paridad de negocio y la arquitectura nueva. El Auditor revisa la calidad con un contexto limpio. El Orquestador sólo cierra cuando los dos aprueban.

Quién hace qué en el ciclo

  1. 01Inventario

    Recoge las reglas de la porción, su evidencia en el sistema anterior, su criticidad y los casos de prueba. Una persona responsable valida que el inventario sea la referencia correcta.

    Entrega: Inventario aprobado.

  2. 02Orquestador

    Planea la tarea con el inventario, los patrones del sistema nuevo, los límites y la definición de terminado de la porción.

    Entrega: Un plan y una lista de cambios verificables.

  3. 03Implementador

    Lleva el comportamiento necesario a la tecnología nueva, sin copiar a ciegas el diseño anterior.

    Entrega: Implementación, pruebas y trazabilidad de cada regla.

  4. 04Fuente de verdad

    Contrasta las reglas inventariadas con la implementación y las pruebas, y señala reglas faltantes, diferencias y desviaciones de la arquitectura.

    Entrega: Veredicto de paridad y lista de brechas reproducibles.

  5. 05Auditor

    Revisa de forma independiente la calidad, la seguridad, las pruebas y la evidencia, incluida la respuesta a lo que encontró la Fuente de verdad.

    Entrega: Revisión de cumplimiento y riesgos pendientes.

  6. 06Decisión humana

    Aprueba las excepciones de negocio, resuelve las diferencias que no sean claras y autoriza la integración o la liberación según los controles del cliente.

    Entrega: La excepción o la autorización, registradas.

06

Instrucciones y evidencia de cada rol

Mantén separado lo que recibe y lo que entrega cada rol. La Fuente de verdad revisa el negocio y el uso de la tecnología nueva; el Auditor revisa la definición de terminado, la calidad y la seguridad con un contexto limpio.

Lo escribe una persona · antes del inventario

Prompt de tarea

Una persona del equipo define la porción (módulo, pantalla o conjunto de APIs); el objetivo, es decir, qué debe quedar funcionando en el sistema nuevo; los criterios de aceptación de paridad de negocio y de arquitectura nueva; las restricciones (requerimientos de la plantilla y posibles exclusiones, sujetas a un ADR); y las referencias al sistema anterior y a la plantilla. Nunca secretos.
Coordinación

Orquestador

Incluye la puerta de control del inventario aprobado (sin él no arranca el Implementador); el máximo de vueltas Implementador ↔ Fuente de verdad ↔ Auditor antes de pedir ayuda al equipo; reportes separados de la Fuente de verdad y del Auditor; límites de contexto, worktree y herramientas; y el criterio para cerrar: los dos aprueban frente al inventario y la plantilla. En cada corrida conserva PLAN.md, el inventario y la carpeta evidence/.
Construcción

Implementador

Recibe el inventario como punto de partida (no descubre reglas sobre la marcha); los patrones del sistema nuevo y las capacidades que debe aprovechar cuando aplique, como tipado, procesos asíncronos, caché, contratos y observabilidad; la CI/CD, los secretos y el ambiente nuevo, sin producción; la definición de terminado con pruebas unitarias, de integración, datos de prueba y los casos del inventario; y la lista de lo que hay que crear, adaptar o retirar del sistema anterior.
Paridad de negocio y arquitectura

Fuente de verdad

Revisa cada regla del inventario y la marca como cubierta, como cambiada con un ADR o como brecha. Comprueba que no se pierdan validaciones, flujos, persistencia ni integraciones críticas, y que se usen los patrones, capas, ADR y ventajas del sistema nuevo, sin copiar el anterior tal cual. Entrega la matriz regla ↔ implementación ↔ prueba y un veredicto de cumple o no cumple, con acciones concretas para reintentar.
Revisión independiente

Auditor

Revisa por su cuenta la definición de terminado: pruebas, lint, análisis de seguridad y estilo. Confirma que existe la evidencia del veredicto de la Fuente de verdad sin rehacer el inventario, y revisa seguridad y privacidad para que no se cuelen datos sensibles del sistema anterior al repositorio nuevo. Entrega un veredicto de cumple o no cumple, con contexto limpio y brechas reproducibles.
Descubrimiento · Inventario

Agente de inventario

Analiza una unidad concreta (módulo, pantalla o porción) y extrae evidencia del código, la configuración, la documentación y el comportamiento observable. Entrega un catálogo ordenado de campos y endpoints, validaciones, reglas, integraciones y persistencia; los casos de prueba de negocio; la evidencia de origen, y las señales de deuda que no deben copiarse sin una decisión humana o un ADR.
07

Ambiente seguro para migrar

Las capas comunes (gateway, DLP, secretos y producción) están en Estándares de ingeniería. Al migrar, además, hay que proteger de forma explícita el código y los datos del sistema anterior.

A

DLP sobre el código y los datos del sistema anterior

Los controles de datos también aplican a todo lo que viene del sistema anterior.

  • Revisa el código, los datos de negocio, los datos personales y el código clasificado antes de llevarlos a un prompt o a una herramienta.
  • Limita lo que se comparte del sistema anterior con cada herramienta aprobada.
B

Escaneo de secretos de ambos sistemas

Ninguna credencial debe llegar al espacio de trabajo, al historial ni al contexto del agente.

  • Gitleaks o equivalente bloquea .env, claves y tokens en el espacio de trabajo y en el historial.
  • No le des al agente credenciales de producción de ninguno de los dos sistemas.
C

Lectura acotada del sistema anterior

El acceso al sistema anterior se limita a lo que necesita el inventario de la porción.

  • Sólo lectura, sólo para la porción acordada y sólo por el tiempo necesario.
  • La persona responsable autoriza el acceso que hace falta para inventariar.
D

Ambientes separados

Los secretos del sistema nuevo se manejan por ambiente; producción nunca queda expuesta al agente.

  • Las credenciales sólo se configuran en desarrollo, QA o pruebas, con el gestor autorizado.
  • El agente no recibe secretos de producción de ninguno de los dos sistemas.
E

Producción bajo autorización humana

La integración y la liberación a producción siguen bajo los controles humanos del proyecto.

  • Producción se maneja con flujos de despliegue autorizados.
  • El acceso de emergencia se audita según la política del cliente.
08

La plantilla nueva como base

El sistema anterior es evidencia del negocio; no decide la arquitectura ni los requerimientos no funcionales del sistema nuevo.

Criterios del sistema nuevo

Requerimientos y arquitectura antes de migrar

Define la seguridad (OWASP, autenticación, autorización y cifrado), los objetivos de servicio (SLO), las capas, los límites entre dominios y los ADR de la migración, y los logs, trazas y métricas del entorno nuevo.
Base versionada

Qué incluye la plantilla

ADR, políticas del proyecto, módulos, capas y contratos del sistema nuevo; lint, análisis de seguridad (SAST), estructura inicial de pruebas y CI; prompts del inventario y de cada rol del ciclo; Devcontainer y scripts de verificación.
Regla para el agente

Conservar el negocio, no la deuda

Conserva las reglas inventariadas y usa los patrones de la tecnología nueva. No traslada la autenticación, los límites, las capas ni los malos patrones del sistema anterior sin un ADR y la aprobación de una persona.
09

Evidencia de paridad en el PR

Los controles generales de commit, push, PR y merge están en Estándares de ingeniería. En una migración, el PR suma la evidencia del inventario y de la paridad.

  • Cada regla tiene un identificador fijo

    Así los hallazgos se discuten por regla, no sólo por archivo o componente.

  • Cada regla apunta a su implementación

    Quien revisa puede encontrar qué parte del sistema nuevo atiende ese comportamiento.

  • Cada regla tiene una prueba o una decisión explícita

    Si no se implementa o no se prueba, queda registrada como brecha o como excepción; nunca se da por cubierta.

  • El PR incluye la evidencia de la porción

    El inventario aprobado, la matriz regla ↔ implementación ↔ prueba, el veredicto de la Fuente de verdad, los resultados de las pruebas y la evidencia de que se usó la arquitectura nueva. Cualquier brecha abierta impide cerrar la tarea y hacer el merge.

10

Prácticas específicas para migrar

Además de las prácticas comunes, estas reglas evitan que se pierda comportamiento en el camino y que la deuda del sistema anterior pase al nuevo.

01

Haz el inventario antes de escribir código

Antes de que el Implementador toque la tecnología nueva, un agente documenta las reglas de la porción y una persona experta las revisa: pantallas, campos, validaciones, endpoints, persistencia e integraciones. Ese inventario define qué tiene que seguir funcionando.

Por qué importa: Migrar de memoria, o mirando un solo archivo, puede inventar reglas o perder otras. El sistema anterior es la evidencia; el inventario la ordena.

Cómo hacerlo: El Orquestador aplica una puerta de control. Sin inventario aprobado del módulo, la pantalla o la porción, no arranca el Implementador. Documenta los campos, las condiciones y las llamadas externas antes de que arranque el ciclo.

02

Suma la Fuente de verdad al ciclo

En un proyecto nuevo puede bastar con Orquestador → Implementador → Auditor. En una migración se agrega la Fuente de verdad entre el Implementador y el Auditor.

Por qué importa: El Auditor revisa la calidad (pruebas, lint y seguridad); la Fuente de verdad comprueba que se respeten las reglas del inventario y que se usen los patrones y las ventajas del sistema nuevo. Si un solo rol hace las dos revisiones, es fácil que una quede incompleta.

Cómo hacerlo: La Fuente de verdad entrega una matriz regla ↔ código ↔ prueba y un veredicto sobre el uso de la arquitectura nueva. El Auditor revisa la definición de terminado con un contexto limpio. Para cerrar, los dos deben aprobar.

03

Migra en porciones pequeñas

No intentes migrar todo un monolito en una sola corrida. Elige una unidad acotada: una pantalla, un módulo o un conjunto de APIs.

Por qué importa: Entre más grande el lote, más reglas se escapan, más difícil es probar la paridad y más cuesta corregir. Las brechas pueden aparecer hasta las pruebas de usuario o en producción.

Cómo hacerlo: Una corrida es una porción, con su propio inventario, su PR y su evidencia. Cuando queda terminada, sigues con la siguiente.

04

Mantén la matriz de trazabilidad

Cada regla del inventario apunta al código nuevo que la implementa y a la prueba que la demuestra. Una fila sin código o sin prueba es un hueco.

Por qué importa: Sin trazabilidad, “creemos que migramos todo” no se puede comprobar. Con ella, el PR muestra la evidencia fila por fila.

Cómo hacerlo: La Fuente de verdad exige la matriz en el PR y el Auditor confirma que las pruebas citadas existen y pasan.

05

No copies el sistema anterior tal cual lift-and-shift

Traducir el código viejo línea por línea arrastra acoplamiento, malos patrones y deuda. Una buena migración conserva el negocio y lo reescribe con la arquitectura nueva.

Por qué importa: Si sólo traduces el sistema anterior sin adoptar la tecnología nueva, pagas el costo de migrar sin ganar mantenibilidad, seguridad ni desempeño.

Cómo hacerlo: La Fuente de verdad lo marca como incumplimiento si se ignoran las capas, los contratos, el tipado, la observabilidad u otros ADR de la plantilla nueva.

06

La misma CI que usa tu equipo

El PR del agente no se salta las verificaciones normales (pruebas, lint y seguridad) y además incluye el inventario de la porción y el veredicto de la Fuente de verdad.

Por qué importa: Un carril “especial para IA” con menos exigencia puede integrar migraciones incompletas.

Cómo hacerlo: Mantén la misma protección de ramas y las mismas verificaciones obligatorias. La lista del PR enlaza el inventario, la matriz y la evidencia de los veredictos de la Fuente de verdad y del Auditor.

07

Una persona aprueba lo que no se migra

Hay errores históricos, reglas obsoletas o soluciones temporales que tal vez no conviene llevar al sistema nuevo, pero esa decisión no la toma el agente.

Por qué importa: Dejar fuera una regla puede ser lo correcto o puede romper un proceso de negocio. Esa decisión le corresponde a producto o al negocio.

Cómo hacerlo: Marca la regla como “no migrar” en el inventario y adjunta un ADR o la aprobación de una persona experta. Sin esa evidencia, la Fuente de verdad la registra como brecha.

08

Paraleliza sólo porciones independientes

Trabaja varias porciones a la vez sólo si no comparten modelos críticos, contratos de API que estén cambiando ni tablas que se estén rediseñando.

Por qué importa: Si varios agentes migran al mismo tiempo piezas que dependen entre sí, cada uno puede suponer un contrato distinto y fallar al integrarlas.

Cómo hacerlo: El Orquestador sólo paraleliza porciones independientes. Si una consume algo que otra está rediseñando, espera a que esa termine.

09

Revisión humana en las zonas críticas

Migrar más rápido con agentes no significa integrar a ciegas. Autenticación, datos personales, pagos, procesos financieros por lotes e infraestructura necesitan la revisión de una persona aunque la CI esté en verde.

Por qué importa: En una migración puedes romper una regla del sistema anterior y, al mismo tiempo, meter una falla en el nuevo.

Cómo hacerlo: El agente entrega el PR, el inventario, el veredicto de la Fuente de verdad y la evidencia; una persona aprueba los cambios de alto riesgo. Las porciones cosméticas siguen el flujo normal de tu equipo.

11

Checklist antes de migrar una porción

Usa esta lista en cada avance. No des por terminada la migración sólo porque el código nuevo compila.

  • Porción y dependencias delimitadas

    Hay un alcance concreto y se sabe qué integraciones podrían verse afectadas.

  • Inventario revisado por personas

    Las reglas críticas tienen evidencia y la aprobación del negocio o de la persona experta responsable.

  • Sistema nuevo definido sin heredar decisiones del anterior

    La arquitectura, los requerimientos no funcionales y los patrones de la tecnología nueva están documentados.

  • Matriz regla ↔ implementación ↔ prueba completa

    Las brechas y las excepciones aparecen de forma explícita y nunca se presentan como paridad.

  • Hallazgos y autorizaciones resueltos

    Las personas responsables aceptan el nivel de riesgo antes de integrar o liberar.

  • Entorno, gateway y DLP listos

    El acceso al sistema anterior es limitado, los datos están protegidos y el sistema nuevo se puede reproducir.

  • Secretos bloqueados y la misma CI

    Gitleaks, las pruebas y las puertas de control se aplican en el pre-commit, el PR y el merge, sin excepciones.

  • Ciclo de agentes con roles y reintentos definidos

    El inventario aprobado va antes del Implementador, y la Fuente de verdad y el Auditor entregan veredictos independientes.

Sigue explorando