Inteligencia Artificial

Cómo dar a la IA el contexto suficiente para entender código legacy

La primera explicación que obtengas dependerá tanto de la pregunta como del contexto disponible. En código legacy, una función aislada rara vez permite entender qué papel desempeña dentro del sistema, porque su comportamiento puede depender de configuración, llamadas externas, estado compartido o decisiones tomadas en otros módulos.

Por eso, antes de buscar una explicación detallada, conviene situar el código dentro del repositorio y decidir qué recorrido quieres investigar. El objetivo inicial no es que la IA explique todo, sino que ayude a construir un mapa que indique qué conocemos, qué relaciones parecen relevantes y qué información necesitamos consultar después.

Qué información aportar antes de pedir una explicación

No necesitas empezar cargando todo el proyecto. Es más útil seleccionar las piezas que permitan orientarse y ampliar el contexto conforme aparezcan nuevas preguntas.

• El árbol de directorios relevante ayuda a localizar módulos, capas y posibles puntos de entrada.
• README y documentación técnica permiten interpretar qué responsabilidad debería tener cada componente y qué problema intenta resolver el sistema.
• Antes de sacar conclusiones, incorpora archivos de configuración y dependencias cuando puedan revelar servicios, implementaciones o comportamientos externos.
• Los puntos de entrada conocidos, como controladores, comandos o jobs, resultan más útiles si indicas qué operación concreta quieres seguir.
• Añade después los tests relacionados para comprobar qué comportamiento se espera conservar, incluidas excepciones que no resultan evidentes al leer la implementación.

Las tres herramientas pueden incorporar contexto de GitHub, pero lo hacen de forma diferente. ChatGPT puede recuperar bajo demanda contenido permitido de repositorios conectados, aunque su disponibilidad varía según el plan, el espacio de trabajo y la interfaz. Claude permite seleccionar archivos y carpetas de GitHub y, cuando se añaden al conocimiento de un Proyecto, volver a sincronizarlos para incorporar cambios. Gemini permite importar un repositorio desde su aplicación web, pero esa copia permanece en el estado que tenía al importarla y no se actualiza automáticamente.

Antes de analizar, comprueba por tanto qué versión del código está viendo realmente la herramienta. Si trabajas con código corporativo, aplica además las políticas de acceso de tu organización y evita proporcionar secretos, credenciales o información que no deba compartirse.

Cómo construir un mapa inicial de módulos, entradas y dependencias

La primera tarea no debería ser encontrar código que mejorar. Pide a la IA que identifique responsabilidades aparentes, relaciones entre archivos, puntos de entrada, dependencias y huecos de información.

Petición inicial sugerida: No propongas cambios todavía. Identifica los puntos de entrada, los componentes implicados, las dependencias que puedas justificar con el código disponible, qué relaciones son solo hipótesis y qué archivo o evidencia deberíamos revisar después.

El resultado debe servir como mapa para continuar investigando, no como arquitectura definitiva. Si la IA afirma que un servicio escribe en base de datos, localiza la operación que lo demuestra. Si detecta una integración externa, busca su configuración y sus llamadas. Cuando falte contexto, interesa que la herramienta lo señale en lugar de completar el hueco con una explicación plausible.

Cómo reconstruir el comportamiento real del sistema

Una vez localizados los componentes principales, toca averiguar qué ocurre realmente cuando el sistema ejecuta una operación. En código legacy, seguir únicamente nombres de clases o métodos suele ser insuficiente: el comportamiento puede repartirse entre varias capas y depender de datos, configuración o servicios externos.

El mapa inicial sirve para saber por dónde investigar, pero ahora hay que convertir relaciones aparentes en recorridos comprobables. Para ello conviene partir de una operación concreta, seguir qué componentes intervienen y contrastar cada salto con evidencias del propio sistema.

Seguir flujos de ejecución, datos y efectos laterales

El análisis funciona mejor si parte de un recorrido concreto. Puede ser una petición HTTP, un comando, un proceso programado o cualquier acción cuyo resultado conozcas. Pide a la IA que siga ese flujo paso a paso y que indique qué archivos necesita consultar para continuar.

No busques solo qué funciones se llaman. Conviene reconstruir qué datos entran, cómo se transforman y qué efectos produce cada etapa. Una operación aparentemente local puede terminar escribiendo en una base de datos, publicando un evento, actualizando una caché o llamando a otro servicio.

Cuando ChatGPT, Claude o Gemini no puedan justificar una relación con el contexto disponible, esa relación debe tratarse como hipótesis y no como parte confirmada del flujo.

Contrastar hipótesis con tests, configuración y archivos relacionados

A medida que aparece una explicación, busca evidencias independientes dentro del proyecto. Los tests pueden mostrar resultados esperados, mientras que la configuración revela qué implementación, servicio o entorno interviene realmente.

También merece la pena localizar quién llama al componente analizado y qué código consume después su resultado. Una función puede parecer sencilla hasta que observas los contratos que existen alrededor de ella.

Si la explicación cambia al añadir un test o un archivo relacionado, no significa necesariamente que la IA haya fallado: indica que la primera conclusión se construyó con contexto insuficiente. Lo importante es registrar ese cambio y no conservar como cierta la hipótesis anterior.

Detectar reglas de negocio y zonas sensibles que la IA puede pasar por alto

Parte del riesgo del código heredado está en las reglas que nunca se documentaron como tales. Validaciones aparentemente extrañas, excepciones específicas, órdenes de ejecución o condiciones duplicadas pueden responder a comportamientos que el negocio todavía necesita.

Por eso, antes de interpretar una anomalía como deuda técnica que debería eliminarse, conviene preguntar qué comportamiento podría estar protegiendo ese código y buscar evidencias.

Las zonas con persistencia de datos, permisos, integraciones, cálculos críticos o efectos difíciles de revertir merecen especial atención. Si todavía no puedes explicar qué consecuencias tendría modificar una de ellas, el siguiente paso no es generar una solución con IA, sino ampliar la investigación.

Qué verificar antes de modificar una sola línea

Reconstruir los principales flujos del sistema no significa que todo esté preparado para cambiarse. Antes de intervenir conviene comprobar si las conclusiones obtenidas están respaldadas por el propio proyecto o si todavía dependen de interpretaciones que la IA ha construido a partir de contexto parcial.

Esta distinción es especialmente importante en código legacy, donde una decisión aparentemente extraña puede conservar compatibilidad, resolver una excepción histórica o proteger un comportamiento que nadie documentó. El objetivo no es eliminar todas las incertidumbres, sino saber cuáles afectan directamente a la zona que vas a modificar y cuáles impiden todavía hacerlo con suficiente criterio.

Separar hechos, inferencias y dependencias pendientes

Una conclusión gana solidez cuando puedes relacionarla con evidencias observables: código ejecutado, tests, configuración, contratos, consultas, logs o comportamiento reproducible. Lo que ChatGPT, Claude o Gemini deduzcan a partir de nombres, patrones o fragmentos incompletos debe mantenerse como hipótesis hasta encontrar ese respaldo.

Imagina que una función calculateTotal() parece limitarse a aplicar descuentos al importe de un pedido. La primera interpretación de la IA puede encajar con el código visible. Sin embargo, al incorporar un test aparece una excepción para determinados clientes y, al revisar la configuración relacionada, descubres que existe una regla adicional vinculada al mercado. La primera explicación no era necesariamente incorrecta, sino incompleta.

Cada nueva evidencia debería servir para confirmar, matizar o descartar una hipótesis anterior. Si no puedes determinar qué prueba una conclusión concreta, todavía no tienes un hecho: tienes una interpretación útil para continuar investigando.

Aplicar una checklist de comprensión previa al cambio

Para evitar que hechos e inferencias terminen mezclándose, puedes clasificar cada zona relevante del código en uno de estos cuatro estados:

• Considera Entendido aquello cuyo comportamiento puedes explicar y respaldar con evidencia suficiente del propio sistema.
• Si la explicación encaja con lo observado pero todavía faltan pruebas, mantén la zona como Inferido pero no verificado y anota qué evidencia necesitas localizar.
• Utiliza Dependencia por revisar cuando comprendes la función local, pero todavía desconoces qué componentes dependen de ella o qué efectos externos provoca.
• Cuando una incógnita pueda alterar el comportamiento esperado o producir consecuencias difíciles de anticipar, el estado adecuado es No tocar todavía.

Para cada elemento, registra la zona analizada, qué crees que hace, qué evidencia respalda esa conclusión y qué comprobación sigue pendiente. La utilidad de esta checklist está en hacer visibles los huecos de conocimiento, no en conseguir que todo termine rápidamente marcado como entendido.

Solo cuando la parte que vas a modificar y sus dependencias relevantes estén suficientemente verificadas tiene sentido pasar de analizar a cambiar. Si esa intervención forma parte de una modernización más amplia, la comprensión previa del sistema se convierte también en una de las bases para abordar una migración de sistemas legacy sin trasladar al nuevo entorno comportamientos que el equipo todavía no comprende.

Conclusiones

ChatGPT, Claude y Gemini pueden reducir mucho el tiempo necesario para orientarse dentro de una base de código legacy, pero su utilidad depende de cómo se plantee el análisis. Pedir una explicación de un archivo aislado puede servir como punto de partida, aunque comprender el sistema exige reconstruir relaciones, flujos y dependencias con contexto suficiente.

El criterio importante no es cuánto código puede explicar una IA, sino qué parte de esa explicación puedes comprobar. Tests, configuración, llamadas entre componentes y comportamiento observable permiten transformar hipótesis razonables en conocimiento útil para intervenir con menos incertidumbre.

Antes de modificar una sola línea, deberías poder distinguir con claridad qué sabes, qué estás infiriendo y qué sigue pendiente de verificar. Si una dependencia relevante continúa siendo desconocida, investigar un poco más suele aportar más valor que pedir a la IA que genere inmediatamente el siguiente cambio.