Cuando la documentación también acumula deuda técnica

Al principio, trabajar con una IA suele parecer sencillo. Le explicas algo, resuelve una tarea y, en otra conversación, añades un poco más de contexto. Guardas una decisión importante, creas unas instrucciones para no tener que repetirlas y, poco a poco, empiezan a aparecer documentos, proyectos, memorias, agentes o fuentes de referencia.

Durante bastante tiempo todo funciona. Hasta que empieza a dejar de hacerlo de una forma difícil de detectar.

La IA recuerda una versión antigua de algo, una instrucción contradice a otra, una decisión que ya cambió sigue apareciendo como válida o descubres que para corregir un único dato necesitas tocarlo en varios sitios. Cada vez hace falta aportar más contexto para conseguir aproximadamente el mismo resultado y llega un momento en el que tienes mucha información disponible, pero cada vez menos claro cuál es la correcta.

Eso tiene un nombre que los programadores conocemos bastante bien: deuda técnica.

Solo que esta vez no está en el código. Está en el contexto.

Más contexto no siempre significa mejor contexto

Uno de los impulsos naturales cuando una IA no conoce algo es darle más información. Y funciona, así que es fácil seguir haciéndolo: añadimos instrucciones, documentos, conversaciones anteriores, notas, estados, resúmenes y cualquier otra cosa que pueda ayudarle a entender mejor nuestra situación.

El problema aparece cuando esa información empieza a solaparse.

Imaginemos algo tan simple como la versión de una herramienta. Si aparece escrita en cinco documentos distintos, en realidad no tenemos una información: tenemos cinco copias de la misma información. Mientras todas coinciden parece irrelevante, pero el día que la versión cambia aparecen cinco lugares que pueden quedarse obsoletos.

En desarrollo de software conocemos perfectamente este problema. Duplicar conocimiento crea puntos de sincronización y aumenta la posibilidad de inconsistencias. Con la IA ocurre exactamente lo mismo.

¿Cuál es la fuente de verdad?

Cuando trabajo en software intento que un dato tenga un lugar claro donde vive. No quiero calcular el mismo valor en cinco sitios ni mantener cinco implementaciones equivalentes si puedo evitarlo.

Con el contexto que proporcionamos a una IA debería ocurrir algo parecido.

Si quiero saber el estado actual de algo, debería existir un lugar claramente responsable de responder a esa pregunta. Si quiero entender por qué se tomó una decisión, probablemente necesite otro tipo de documento. Y si necesito consultar una versión, una ruta o cualquier otro dato que cambia con frecuencia, quizá no debería estar mezclado con decisiones que permanecen estables durante meses.

Son problemas distintos, y mezclar responsabilidades también es una mala idea fuera del código.

Separación de responsabilidades aplicada al conocimiento

Uno de los principios más simples del desarrollo de software es que cada componente debería tener una responsabilidad clara. Aplicarlo a la documentación cambia bastante las cosas.

Un documento de estado debería explicar dónde estamos, no toda la historia de cómo llegamos hasta ahí. Un inventario debería contener datos que pueden cambiar, no decisiones conceptuales que deberían sobrevivir a esos cambios. Una fuente estable debería explicar criterios, arquitectura o reglas sin necesitar una actualización cada vez que cambia una versión. Y el histórico debería conservar lo ocurrido sin competir constantemente con la información vigente.

No hace falta utilizar estos nombres ni construir una arquitectura documental sofisticada. La idea importante es mucho más sencilla: información distinta tiene ciclos de vida distintos.

Si almacenamos todo como si fuese equivalente, mantenerlo correctamente termina siendo caro.

El problema de actualizar cinco cosas cuando solo ha cambiado una

Aquí aparece otro concepto muy conocido para cualquiera que programe: el acoplamiento.

Si un cambio pequeño obliga a modificar cinco documentos, varios prompts y dos instrucciones diferentes, existe acoplamiento documental. Da igual que no haya código involucrado; el efecto es el mismo. Un cambio local provoca modificaciones en lugares que conceptualmente no deberían depender de él.

Cuanto mayor sea el sistema de contexto que construimos alrededor de la IA, más caro resulta mantener esa coherencia y mayor es también la probabilidad de olvidar alguna actualización. Entonces aparece una situación especialmente incómoda: dos fuentes aparentemente válidas dicen cosas diferentes.

En ese momento la IA ya no tiene un problema de falta de información.

Tiene un problema de arquitectura.

Refactorizar no significa resumirlo todo

Cuando una base de código empieza a ser difícil de mantener, la solución rara vez consiste en meterla entera dentro de un archivo más grande. Con la documentación ocurre lo mismo.

Crear “el documento definitivo con todo” puede parecer una buena simplificación, pero mezcla información que cambia a ritmos completamente diferentes. Una preferencia puede durar años. El estado de una tarea puede cambiar esta tarde. Una versión puede cambiar la semana que viene. Una decisión pasada puede ser importante precisamente porque no debe reescribirse.

Si todo vive junto, cada actualización obliga a tocar una pieza que contiene demasiadas responsabilidades.

La solución se parece mucho más a una refactorización de software: separar, eliminar duplicación, definir autoridad, reducir dependencias y conservar el histórico sin convertirlo en estado actual.

Exactamente el tipo de trabajo que haríamos con un sistema que ha crecido orgánicamente.

Hay otra deuda que no vemos: el coste de contexto

Con los sistemas actuales existe además una consecuencia específica: toda esa información puede acabar formando parte del contexto que procesa el modelo.

Y aquí vuelve a aparecer una idea que resulta contraintuitiva. Más información puede producir peores resultados.

No porque el modelo necesite saber menos, sino porque necesita recibir información más clara. Cargar contexto redundante consume recursos y aumenta el espacio en el que pueden existir contradicciones, estados obsoletos o instrucciones que compiten entre sí.

La optimización correcta no consiste en eliminar contexto hasta dejar al modelo sin información. Consiste en reducir aquello que no aporta conocimiento nuevo.

También aquí la analogía con el software es útil: optimizar no significa borrar código porque haya muchas líneas, sino eliminar complejidad innecesaria.

El histórico no sobra

Que algo ya no represente el estado actual no significa que haya dejado de tener valor.

Un commit antiguo puede explicar por qué existe una decisión. Un incidente pasado puede impedir que repitamos un error. Una hipótesis descartada puede ahorrar varias horas dentro de seis meses. La documentación histórica cumple una función parecida.

El error aparece cuando todo ese material permanece en el mismo nivel de autoridad que la información actual. El histórico debería poder consultarse, pero no competir constantemente con el presente.

Archivar conocimiento no significa perderlo. Significa cambiar su función.

Y esa diferencia resulta especialmente importante cuando quien consume la documentación no es solamente una persona, sino también un sistema que utiliza esos textos como contexto para razonar.

Esto va mucho más allá de organizar documentos

Lo interesante para mí no es encontrar una manera ordenada de mantener unos cuantos archivos. Lo realmente interesante es comprobar hasta qué punto las estrategias que utilizamos para construir software siguen siendo válidas cuando trabajamos con IA.

Separación de responsabilidades, fuente única de verdad, bajo acoplamiento, eliminación de duplicación, estados explícitos, versionado, refactorización, diferenciación entre configuración e histórico o validación del estado efectivo en lugar de confiar únicamente en lo declarado.

No son conceptos creados para trabajar con modelos de lenguaje, pero funcionan extraordinariamente bien.

Y creo que ahí aparece una diferencia importante entre simplemente utilizar una IA y entender el sistema que estamos construyendo alrededor de ella.

Saber programar cambia la forma de utilizar una IA

No porque haya que escribir código para aprovecharla. Muchas veces no hace falta escribir una sola línea.

La ventaja está en otra parte.

Un programador lleva años entrenándose para reconocer determinados problemas antes incluso de que sean evidentes. Detecta duplicación, desconfía de estados implícitos, busca cuál es la fuente de verdad, intenta aislar responsabilidades, sabe que añadir una capa puede resolver un problema y crear otros tres, y entiende que algo puede funcionar hoy y seguir estando mal diseñado.

También sabe que los sistemas que crecen necesitan refactorización aunque todas sus piezas sigan funcionando individualmente.

Todo eso es aplicable directamente a nuestra relación con la IA.

Prompts, memorias, agentes, automatizaciones, instrucciones, documentos y fuentes están formando sistemas cada vez más complejos. No solemos llamarlos software, pero muchos de sus problemas empiezan a parecerse bastante.

Y ahí el conocimiento de desarrollo marca una diferencia real. No porque permita hacer preguntas más sofisticadas, sino porque proporciona un marco mental para entender qué está ocurriendo cuando el sistema empieza a crecer.

La IA no elimina la ingeniería

En cierto sentido ocurre lo contrario.

Cuanto más capaz es la herramienta, más valor tiene saber estructurar el sistema que construimos alrededor de ella.

Durante un tiempo se ha hablado mucho de la capacidad de escribir buenos prompts como una habilidad diferencial. Sigue siendo útil, pero creo que en trabajos continuados la ventaja empieza a desplazarse hacia capacidades bastante más profundas: entender estados, gestionar contexto, diseñar flujos, separar responsabilidades, reducir ambigüedad, mantener fuentes fiables y saber cuándo un sistema necesita ser refactorizado.

Para alguien que desarrolla software son habilidades muy familiares.

No porque una IA deba tratarse exactamente como un programa, sino porque estamos descubriendo que muchos de los problemas de los sistemas complejos siguen siendo los mismos aunque una de sus piezas ahora sea capaz de conversar con nosotros.

La documentación también acumula deuda técnica.

Y saber reconocerla puede marcar tanta diferencia como reconocerla en el código.