Cómo se documenta una arquitectura de IA para que sobreviva al equipo

Para qué se documenta, de verdad

No para cumplir un entregable. Para responder cuatro preguntas concretas que llegan siempre.

• ¿Por qué el sistema hizo esto? Cuando alguien reclama por una decisión concreta.
• ¿Podemos cambiar esto sin romper aquello? Cuando hay que evolucionar.
• ¿A qué tiene acceso? Cuando alguien pregunta por seguridad o por cumplimiento.
• ¿Quién sabe de esto? Cuando la persona que lo construyó ya no está.

Toda documentación que no responda estas cuatro es decorativa, por muy completa que parezca.

La página que hay que tener sí o sí

Si sólo se va a escribir una cosa, que sea esta. Cabe en una hoja y responde el 80 % de lo que se pregunta.

Cinco apartados. Media hora de escritura. Es la diferencia entre un activo de la empresa y una dependencia de una persona.

Una recomendación sobre el segundo apartado, la tabla de tres columnas: conviene que esté también donde la ve quien opera el sistema, no sólo en la documentación.

Quien atiende los casos que el sistema escala necesita saber por qué llegaron a él. Y quien recibe una queja necesita poder decir si eso lo decidió el sistema o una persona.

Es la misma tabla en dos sitios, y el segundo es el que evita la mitad de las conversaciones confusas.

Qué documentación no sirve

Cuatro formatos habituales que se ven bien y no responden ninguna de las cuatro preguntas.

Lo que hay que documentar y en otros sistemas no hace falta

Un sistema de IA tiene cuatro cosas que un sistema determinista no tiene, y son las que la documentación tradicional se salta.

• El prompt o las instrucciones, versionadas y con el porqué de sus reglas raras.
• Qué versión de qué modelo se está usando, y desde cuándo.
• Qué se consideró aceptable. El criterio con el que se evaluó que funcionaba.
• Qué se probó y falló. Los intentos descartados evitan que el siguiente equipo repita el mismo camino.

El cuarto es el que más tiempo ahorra a futuro y el que nunca se escribe, porque documentar lo que no funcionó parece admitir un error en vez de dejar un aprendizaje.

Sobre el tercer punto, el criterio de evaluación: es el que convierte «funciona bien» en algo verificable meses después.

Sin él, cuando alguien pregunte si el sistema sigue funcionando igual de bien que al principio, no hay forma de responder: no se sabe contra qué se comparó la primera vez.

Basta con dejar escrito qué se consideró respuesta correcta, qué aceptable y qué error, más el resultado de la primera muestra. Media página.

Dónde vive la documentación

La regla que funciona: lo más cerca posible de lo que describe.

• El prompt y la configuración, en el repositorio, versionados con el código.
• La página de arquitectura, donde el equipo ya busca cosas, no en una carpeta nueva.
• La tabla de la frontera, donde la vea quien opera el sistema, no sólo quien lo construyó.
• El registro de decisiones, en el sistema, no en un documento.

Una documentación que vive en una carpeta que sólo conoce el proveedor es equivalente a no tenerla, y es exactamente lo que hay en la mayoría de empresas.

El problema real: mantenerla viva

Toda documentación envejece. La de un sistema de IA envejece más rápido, porque el sistema cambia sin que nadie lo toque.

Tres mecanismos que funcionan, en orden de eficacia:

El primero es el más importante con diferencia. La causa número uno de documentación desactualizada no es la desidia: es que actualizarla cuesta demasiado porque es demasiado larga.

Cómo saber si sirve: la prueba de la persona nueva

Hay una prueba objetiva y cuesta una tarde. Se le da la documentación a alguien que no participó y se le piden cuatro cosas.

• Que explique qué hace el sistema, en dos frases.
• Que diga qué pasaría si el modelo se equivoca en un caso concreto.
• Que localice a qué sistemas tiene acceso.
• Que diga a quién habría que avisar si algo va mal.

Si no puede con las cuatro en veinte minutos, la documentación no sirve, por muy completa que sea. Y esa prueba se puede hacer antes de que la persona que lo construyó se vaya, que es cuando todavía tiene arreglo.

Qué exigir si lo construyó un proveedor

Se pide antes de firmar, no al terminar. Después de terminar es un favor y no una obligación.

• La página de arquitectura con los cinco apartados.
• El prompt y la configuración en un formato que puedas leer y editar.
• Qué versión de qué modelo y qué pasa cuando cambie.
• El criterio de evaluación con el que se dio por bueno.
• Qué se probó y se descartó, aunque sea en una lista corta.

Es el mismo criterio de qué documentos exigir a un proveedor de IA, aplicado a la parte de arquitectura.

Si tu sistema ya está funcionando y no hay nada escrito

No hace falta parar nada. Hace falta una sesión de dos horas con quien lo construyó, mientras siga disponible.

Dos horas, y el sistema deja de ser una dependencia. Es de las cosas con mejor relación entre esfuerzo y riesgo evitado que se pueden hacer en una tarde.