Cómo leer: a la izquierda, la flecha única: la reescritura que pierde las reglas que nadie documentó. A la derecha, el camino de la ruta: primero descubrir y fijar el comportamiento actual (cian), después migrar una parte y comparar. La IA debe reducir el riesgo, no ampliarlo.
Mapa de la ruta
Contenido detallado
🏚️ Modernización segura de sistemas heredados
Mapeo de dependencias, reglas de negocio ocultas, pruebas de caracterización, integraciones ocultas, aislamiento de límites y migración gradual con comparación.
El relevamiento de lo que existe: módulos, integraciones, jobs, bases de datos, quién llama a quién y qué ya es código muerto.
La IA es excelente en esto: leer mucho código y resumir su estructura es donde más rinde. Y sin el mapa no sabes dónde es seguro recortar.
Inventario antes del plan · El código muerto es el recorte más barato · Quién llama a quién define la frontera posible.
La extracción de las reglas reales que solo viven en el código: excepciones históricas, casos especiales de clientes, redondeos, plazos y comportamientos regulatorios.
Son las que fallan en la reescritura. Y son invisibles para quien solo mira la documentación, que casi siempre describe el sistema que se pretendía tener.
El código es la verdad · Las excepciones históricas suelen tener responsable · Una regla descubierta se convierte en prueba, no en comentario.
Pruebas que registran lo que hace el sistema hoy —incluso lo que parece incorrecto— para que cualquier cambio de comportamiento aparezca de inmediato.
Es la red de seguridad que hace posible la modernización. Sin ella, «refactoricé y todo funciona» es una frase sin fundamento.
Caracterizar ≠ validar · Un bug conocido también es comportamiento · La IA genera estas pruebas en volumen y es muy buena en eso.
La búsqueda de consumidores no documentados: scripts, hojas de cálculo, jobs de otro equipo e informes que leen directamente tu base de datos.
Es la principal causa de incidentes después de una migración: desactivaste algo que «nadie usaba» y alguien sí usaba.
El log de acceso revela quién lo consume · Desactívalo por etapas (avisar, depreciar, eliminar) · El silencio no demuestra que ya no se use.
La creación de un punto de unión entre lo viejo y lo nuevo: un adaptador que permite cambiar la implementación sin modificar a quienes la consumen.
Sin un límite definido, la migración se convierte en una reescritura: cada parte arrastra a otra y el alcance se desborda.
El adaptador desacopla el cronograma · Una buena frontera es la que tiene pocos consumidores · Estrangulamiento gradual > big bang.
Ejecutar ambas implementaciones en paralelo con la misma entrada y registrar las diferencias antes de cambiar por completo.
Es la prueba más sólida de que lo nuevo hace lo mismo que lo anterior, incluso en los casos que nadie recordó probar.
La divergencia es información, no un error · Liberación gradual por porcentaje · La IA reduce el riesgo, no lo amplía.
🗺️ Arquitectura legible para agentes
Estructura predecible, límites claros entre módulos, documentación cerca del código, contratos explícitos, comandos estandarizados, AGENTS.md, skills, playbooks y fuentes únicas de verdad.
Una organización en la que el nombre del directorio y del archivo permite prever dónde está algo, tanto para las personas nuevas como para los agentes.
Un repositorio predecible reduce el contexto que el agente necesita cargar y la cantidad de suposiciones que hace.
Convención > configuración · Un nombre consistente es infraestructura · Una estructura predecible ayuda por igual a las personas y a las máquinas.
Fronteras declaradas entre dominios, con reglas de importación que se pueden verificar automáticamente.
Un agente respeta los límites que puede ver. Un límite que solo existe en la mente del arquitecto se cruzará.
Regla verificable > regla acordada · La importación es la evidencia · La frontera también limita el alcance de la tarea.
Documentación versionada en el repositorio: arquitectura, dominios, decisiones y playbooks, en la misma revisión del código que describen.
La doc en el repositorio se incluye en la revisión y en el contexto del agente. La doc fuera de él se convierte en folclore en tres meses.
La documentación es parte del diff · El registro de decisiones explica el porqué · La documentación desactualizada es peor que no tener documentación.
Un único comando documentado para instalar, probar, ejecutar lint, compilar y validar, que funciona igual en la máquina de todos y en CI.
Es lo que permite al agente cerrar el ciclo por sí solo. Sin un comando estándar, inventa uno, y lo inventa mal.
La prueba local rápida es infraestructura del agente · El mismo comando local y en CI · Script > instrucción en prosa.
Un archivo con una visión general, los comandos principales, las reglas del proyecto, dónde está la documentación, las limitaciones, los criterios de calidad, las acciones prohibidas y las referencias a skills y playbooks.
No debe concentrar todo el conocimiento del proyecto — debe funcionar como un mapa. Ni siquiera las personas leen un AGENTS.md de 900 líneas.
El mapa orienta, no lo describe todo · Las acciones prohibidas se destacan · Se revisa como código.
Un único lugar canónico para cada información —comandos, contratos, convenciones— sin copias divergentes dispersas.
Ante dos fuentes en conflicto, el agente elige una y tú descubres cuál durante la revisión, en el peor momento.
Pocas fuentes en conflicto · Referenciar > duplicar · La verdad duplicada siempre diverge.
🪓 Sobreingeniería y deuda técnica generada por IA
El cambio más pequeño posible, las abstracciones prematuras, las dependencias innecesarias, la duplicación semántica, las pruebas superficiales y el código que pasa las pruebas, pero viola la intención.
La instrucción estándar: implementa el cambio más pequeño que satisfaga los criterios de aceptación; no crees nuevas abstracciones, dependencias ni capas sin una necesidad comprobada.
La IA tiende a producir soluciones aparentemente completas incluso cuando bastaría con una más pequeña, y el costo aparece en el mantenimiento.
Preservar la estructura existente · Justificar cada componente nuevo · Un diff más pequeño es más fácil de revisar.
Capas, interfaces y "frameworks internos" creados para casos hipotéticos que nadie pidió y que quizá nunca lleguen.
Una abstracción equivocada es más cara que la duplicación: hay que deshacerla antes de cualquier cambio futuro.
Abstrae después del segundo (o tercer) uso real · Un caso hipotético no es un requisito · Simple y extensible: compara los dos.
Prohibir nuevas dependencias sin aprobación y limitar la cantidad de archivos modificados por tarea.
Toda dependencia es una superficie de ataque, un costo de actualización y un riesgo de abandono. Además, un diff demasiado grande no se revisa: se acepta.
Una dependencia tiene un costo permanente · Un límite de archivos denuncia que el alcance se excedió · La refactorización fuera del alcance queda para otro PR.
Dos o más implementaciones del mismo concepto, escritas de formas diferentes — invisibles para la búsqueda textual, detectables por un agente que lee el repositorio.
Es la forma de deuda que más genera la IA, porque cada tarea empieza sin recordar lo que ya existe.
"¿Ya existe algo así?" antes de crear · La inconsistencia entre módulos confunde al siguiente agente · Consolidar es un trabajo recurrente.
Pruebas que ejecutan el código sin afirmar un comportamiento relevante: cubren el camino feliz, aumentan la métrica y no detectan defectos.
Ofrecen la peor combinación posible: sensación de seguridad sin ninguna protección — y bloquean las refactorizaciones porque ponen a prueba la implementación.
Una buena prueba falla cuando cambia el comportamiento · Error y casos límite > camino feliz · Una prueba que solo se ejecuta es deuda, no un activo.
La solución que satisface al verificador sin resolver el problema: un caso especial incorporado para que pase la prueba, una excepción ignorada, un caché que oculta el error.
Es el defecto más peligroso del desarrollo con IA, porque atraviesa todos los gates automáticos con luz verde.
Leer el diff, no solo el resultado · La revisión de intención es humana · Cuando una métrica se convierte en objetivo, deja de ser una buena métrica.