🗺️ Mapea dependencias y haz el inventario
La IA puede mapear dependencias, explicar código, documentar interfaces y encontrar código muerto: leer mucho código y resumir su estructura es donde más rinde. Empieza por ahí: saber el tamaño real del problema antes de proponer una solución.
Cómo leer: todo el proceso en una imagen. Las cajas en cian son las etapas de evidencia: caracterizar, ejecutar en paralelo, comparar. Son las que convierten "creo que es igual" en una prueba, y por eso ninguna es opcional.
🆕 ¿Nuevo por aquí?
Legado aquí no significa «viejo»: significa código en producción que nadie entiende por completo y que no tiene suficientes pruebas para cambiarlo de forma segura. Prueba de caracterización es una prueba que describe lo que hace el sistema hoy (no lo que debería hacer). Adaptador es una capa delgada que traduce entre el mundo antiguo y el nuevo.
Inventario
Antes del plan
Código muerto
Recorte más barato
Quién llama a quién
Define el límite
Riesgo
Disminuye, no aumenta
🔎 Identifica las reglas de negocio ocultas
Todo sistema antiguo lleva reglas que nunca se escribieron en ningún lugar: excepciones históricas, casos especiales de clientes grandes, redondeos por motivos fiscales, plazos heredados de un contrato de 2014. Son las que fallan en la reescritura.
⚠️ Riesgos típicos del legado
🧪 Ejercicio copiable — extraer las reglas del código
Objetivo: transformar código heredado en una lista de reglas auditable. Elige un módulo que necesites modernizar.
Leia <caminho do módulo legado> inteiro. Não altere nada. Produza uma tabela de REGRAS DE NEGÓCIO observadas no código, com colunas: regra (em português, uma frase) | onde está (arquivo:linha) | condição que a dispara | o que acontece quando não vale | parece intencional ou acidental? Regras: - descreva o que o código FAZ, não o que deveria fazer; - inclua casos especiais, exceções, valores mágicos e datas fixas; - não invente justificativa de negócio — se não souber, escreva "desconhecido"; - ao final, liste em "PERGUNTAR AO NEGÓCIO" as regras que parecem acidentais ou que você não consegue explicar.
Cómo verificar: lleva la lista «PERGUNTAR AO NEGÓCIO» a quien opera el sistema. Toda regla que alguien reconozca se convierte en una prueba de caracterización en el siguiente tema; toda regla que nadie reconozca es candidata a eliminarse — pero solo después de confirmarlo.
El código = la verdad
La doc expresa una intención antigua
Valor mágico
Suele ser una regla
Regulatorio
No se «simplifica»
Preguntar
Antes de eliminar
🧪 Escribe pruebas de caracterización
La prueba de caracterización registra el comportamiento actual — incluso lo que parece incorrecto. No juzga; toma una instantánea. Es la red de seguridad que hace posible la modernización.
✓ Caracterización bien hecha
- ✓Registra la salida actual, aunque sea extraña, con un comentario "comportamiento actual, no validado"
- ✓Cubre entradas reales recopiladas de producción (anonimizadas)
- ✓Incluye casos límite: nulo, vacío, negativo, fecha límite, valor máximo
- ✓Se ejecuta contra el sistema anterior antes de cualquier cambio
✗ Trampas
- ✗"Corregir" el comportamiento extraño mientras escribes la prueba
- ✗Probar solo el camino feliz: el legado vive en los casos especiales
- ✗Escribir la expectativa a partir de la documentación, no de la ejecución
- ✗Usar datos de producción sin anonimizar
💡 Consejo práctico
Generar pruebas de caracterización en volumen es una de las mejores aplicaciones de IA que existen: pídele al agente que produzca decenas de casos a partir de entradas reales, los ejecute contra el sistema actual y guarde la salida como expectativa. Tú revisas la lista, no escribes las pruebas una por una.
Toma una foto
No juzga
Bug incluido
También es comportamiento
Entrada real
Anonimizada
Volumen
Dónde brilla la IA
🕵️ Descubre integraciones ocultas
El mayor generador de incidentes posteriores a una migración es simple: desactivaste algo que «nadie usaba» y alguien sí lo usaba. Un script, una hoja de cálculo, un informe que lee directamente la base de datos, un job de otro equipo.
Revisa los accesos, no el código
Logs de API, conexiones a la base de datos, llamadas al endpoint, lecturas del archivo. Quien lo consume aparece en el tráfico, no en el repositorio.
Observa durante un ciclo completo
Una semana no basta si hay un cierre mensual, un informe trimestral o una rutina anual. El consumidor más peligroso es el que solo aparece el día 1.º.
Desactiva por etapas
Avisar → depreciar (con una alerta cada vez que se use) → degradar → eliminar. Cada etapa da la oportunidad de que alguien aparezca diciendo «esto es mío».
Tráfico
Revela al consumidor
Ciclo completo
Mensual, trimestral, anual
Deprecar
Antes de eliminar
Silencio
No demuestra desuso
🧱 Aísla límites y crea adaptadores
Antes de cambiar cualquier cosa, crea el punto de conexión: una interfaz entre quien consume y la implementación. Con el adaptador en su lugar, cambias el motor sin tocar a quien lo conduce, y puedes volver atrás con una línea.
📐 Cómo elegir el límite adecuado
- •Pocos consumidores (puedes avisarles a todos).
- •Contrato acotado: pocas operaciones, datos simples.
- •Comportamiento ya cubierto por pruebas de caracterización.
- •Valor claro en migrar primero (un problema conocido, no solo «se ve feo»).
⚠️ Atención
Sin un límite definido, la migración se convierte en una reescritura: cada parte arrastra a otra, el alcance se desborda y el proyecto entra en ese estado en el que el sistema nuevo no está listo y el antiguo ya no recibe mantenimiento. Es el peor lugar posible.
Costura
Antes del cambio
Contrato acotado
Facilita el cambio
Cuello de botella
Poco a poco
Volver fácilmente
Cambia la implementación
⚖️ Ejecuta en paralelo y compara
Las dos implementaciones reciben la misma entrada; la antigua sigue respondiendo; la nueva solo registra lo que respondería. Cada divergencia se convierte en un caso para investigar. Es la prueba más sólida que existe.
Panel de comparación (recreación ilustrativa, no es una captura de pantalla real)
solicitudes comparadas .......... 148.302
idénticas ...................... 148.061 (99,84%)
divergentes .................... 241
├─ redondeo a centavos ..... 233 <- regla fiscal olvidada
├─ cliente con contrato 2014 ... 7 <- excepción histórica
└─ fecha 29/02 ................. 1 <- año bisiesto
no se modificó ninguna respuesta al cliente (modo sombra)
Cómo leer: 99,84% de igualdad no es aprobación: las 241 divergencias son el contenido real del informe. Cada una es una regla que la caracterización no detectó. Por eso se ejecuta en modo sombra antes de cambiar.
Chequeo rápido: vas a modernizar un módulo antiguo sin pruebas. ¿Cuál es el primer paso?
Modo sombra
Lo nuevo solo observa
Divergencia
Es información valiosa
Gradual
1%, 10%, 50%, 100%
Volver
Disponible hasta el final
📌 Resumen del módulo
Próximo módulo:
4.2 - Arquitectura legible para agentes: estructura predecible, AGENTS.md y fuentes únicas de verdad.