La IA puede escribir el código. Pero no conoce tus cicatrices

El lunes deja de funcionar la facturación

Le das el repositorio a un agente de IA. Analiza el proyecto, localiza el módulo, sigue las dependencias y propone el cambio. Modifica siete archivos, actualiza los tests y todo pasa. De paso, elimina doce líneas bastante feas que llevaban allí desde 2019.

El código queda mejor: más limpio, más fácil de entender, incluso ligeramente satisfactorio de mirar. Pero el lunes deja de funcionar la facturación de un cliente.

Resulta que aquellas doce líneas horribles estaban compensando un comportamiento incorrecto de una integración externa que nadie había documentado. El agente había entendido perfectamente el código. El problema es que la historia no estaba en el código.

Y cada vez que damos más autonomía a la IA para trabajar sobre sistemas existentes, esa diferencia importa más.

El repositorio no cuenta toda la historia

Conviene reconocer algo antes de seguir: una buena IA puede obtener una cantidad extraordinaria de contexto de un repositorio. Puede recorrer clases, módulos, llamadas, contratos, tipos, tests, configuraciones y dependencias. Si tiene acceso al historial de Git, puede estudiar cómo ha evolucionado una pieza y detectar patrones que a una persona recién incorporada le llevaría bastante tiempo descubrir.

En algunas tareas, probablemente comprenda una codebase mejor que alguien que lleva tres días en el proyecto intentando averiguar qué demonios significa CustomerLegacyAdapterV2Final.

El código explica bastante bien qué hace el sistema. Lo que no siempre explica es por qué terminó haciéndolo precisamente así. Y esa segunda pregunta suele ser la interesante.

Todo sistema acaba acumulando cicatrices

Hay código que parece absurdo. Por ejemplo:

if ($provider === 'legacy') {
    sleep(2);
}

Una pausa arbitraria en mitad de una integración. Lo ves durante una refactorización y tu primera reacción es bastante razonable: «Esto hay que quitarlo». Hasta que descubres que el proveedor devuelve 200 OK antes de haber terminado realmente de procesar la operación. Si consultas inmediatamente el resultado, responde que el registro no existe. Dos segundos después, sí.

¿Es bonito? No. ¿Deberíamos diseñar una solución mejor? Probablemente. ¿Puedes borrar tranquilamente esas líneas porque parecen una barbaridad? Tampoco.

Otro clásico: un proceso nocturno debería ejecutarse a las 02:00, pero el cron dice 5 2 * * *. Cinco minutos tarde. Alguien decide «arreglarlo» y a las 02:01 empieza a fallar porque otro sistema termina su cierre diario aproximadamente a las 02:03.

En 2021 hubo una incidencia, alguien desplazó el proceso cinco minutos y aquello resolvió el problema. El ticket se cerró. La documentación nunca se actualizó. El cron sobrevivió.

A veces eso es deuda técnica. A veces es una cicatriz. Y distinguir una de otra importa bastante.

Mantener software es hacer arqueología

Quien hereda aplicaciones acaba desarrollando una habilidad bastante particular: la arqueología del software. Empiezas en el código, después haces git blame. 2019. La cuenta del desarrollador está desactivada. Perfecto. Buscas el commit y el mensaje dice: fix customer issue. Excelente documentación histórica.

Entonces empiezas a ampliar el radio de excavación: tickets antiguos, pull requests, comentarios, logs, wikis abandonadas, correos, runbooks y cualquier persona que lleve suficiente tiempo en la empresa. A veces la investigación termina así:

—¿Por qué hacemos esto así?
—Pregúntale a Miguel.
—Miguel se fue en 2022.
—Ah.

El problema es que una parte importante de la arquitectura real de muchos sistemas nunca llegó a representarse formalmente. Ahí se entiende por qué IA y contexto del código deben ir juntos: una parte de la arquitectura está en el repositorio y otra sigue repartida por la organización.

Una excepción para aquel cliente. Una migración que falló. Una API que incumple su documentación. Una configuración que evita saturar un servidor antiguo. Un feature flag que iba a durar tres semanas y acaba de celebrar su quinto cumpleaños. Y, naturalmente, el legendario:

// TODO: temporal

Si llevas suficiente tiempo desarrollando software, probablemente ya hayas descubierto que temporal es una de las estructuras de almacenamiento más persistentes de nuestra industria.

La IA tampoco puede leer lo que nunca escribimos

Aquí sería muy fácil culpar a la IA, pero sería hacer trampas. Si el motivo de una decisión solo existe en la memoria de una persona, tampoco lo encontrará el próximo desarrollador, ni el nuevo arquitecto, ni el proveedor al que externalizamos un módulo. Y nosotros mismos, dentro de tres años, probablemente tampoco lo recordaremos.

La llegada de la IA no ha creado el problema del contexto. Lo ha hecho mucho más visible. Y aunque las herramientas evolucionan rápidamente para ingerir historiales de Git o tickets, ninguna IA puede inferir una restricción de negocio crítica que nunca se llegó a digitalizar.

Durante años hemos podido compensar esa falta de documentación mediante conversaciones: «No toques eso», «Pregunta antes de cambiar aquello», «Ese servicio es especial», «Luis sabe cómo funciona». Ahora queremos agentes capaces de recorrer el repositorio, abrir una tarea, implementar el cambio, ejecutar los tests y preparar un pull request con muy poca intervención.

Pero entonces el conocimiento tácito empieza a convertirse en una dependencia técnica, porque el agente solo puede razonar con aquello a lo que tiene acceso.

Documentar las cicatrices (sin escribir una novela)

No estoy proponiendo escribir una novela cada vez que hacemos un if. Eso acabaría exactamente como suelen acabar esas iniciativas: una Wiki enorme que nadie actualiza y que seis meses después describe una aplicación que ya no existe. Hay que documentar intención, no producir documentación por volumen.

// [CONTEXT-ADR-042] NO ELIMINAR este sleep(2).
// El proveedor LegacyX devuelve 200 OK antes de persistir en BD.
// Sin este delay, la consulta inmediata de verificación falla con "NotFound".
// Ver ticket INC-2019-884 y ADR-042 para la refactorización planificada en Q3.

Porque probablemente alguien lo hará. Y ahora ese alguien puede ser extremadamente rápido escribiendo código.

El trabajo técnico se está desplazando

Que la IA pueda generar cada vez más código no reduce la importancia de la ingeniería. Cambia dónde está parte del valor. Si implementar una función cuesta menos, ganan peso otras tareas: definir bien el problema, proporcionar contexto, establecer límites, diseñar tests, identificar riesgos, revisar decisiones y entender las consecuencias de un cambio.

La IA puede implementar una solución técnicamente impecable para una comprensión incompleta del problema. Los humanos también llevamos décadas haciéndolo, por cierto. La diferencia es la velocidad.

Por eso, mejores agentes no deberían llevarnos únicamente a pedir más código. También deberían obligarnos a construir mejores fuentes de contexto: código, tests, ADRs, tickets, runbooks, documentación, historial y decisiones explicadas donde alguien —humano o máquina— pueda encontrarlas.

Hay código feo que se merece desaparecer

Por supuesto. Dentro de cualquier repositorio hay código bonito, código feo, deuda técnica, decisiones equivocadas y auténticas barbaridades que sobrevivieron mucho más de lo que deberían. No hace falta convertir cada anomalía en patrimonio histórico protegido.

Pero también hay cicatrices: pequeñas marcas que cuentan que allí ocurrió algo. Una incidencia. Un cliente. Una migración. Una noche demasiado larga. Una decisión temporal que dejó de ser temporal hace muchísimo tiempo.

Antes de pedirle a una IA que las elimine, conviene asegurarse de que también pueda conocer cómo llegaron hasta allí. Porque una IA puede reescribir el código. Lo que no puede reconstruir con certeza es una historia que nunca dejamos escrita.