Documentación viva: agentes que mantienen al día la CMDB y los diagramas

Pocas cosas generan tanta desconfianza en una organización de TI como una CMDB desactualizada. Durante un incidente, alguien consulta de qué depende un servicio, encuentra un servidor que se dio de baja hace un año y deja de confiar en la herramienta. A partir de ahí, cada equipo mantiene su propia hoja de cálculo y la CMDB queda como un requisito de auditoría que nadie usa para decidir.

Con los diagramas de arquitectura pasa algo parecido. Se dibujan con cuidado para un comité o una auditoría y empiezan a envejecer al día siguiente. Este artículo explica por qué ocurre, qué fuentes permiten reconstruir la realidad de forma automática y cómo usar agentes de IA para mantener la documentación al día sin perder el control sobre lo que se publica.

Por qué la documentación envejece

La causa de fondo no es la falta de disciplina. Es que la documentación se mantiene por un canal distinto del que produce los cambios. Los cambios ocurren en pipelines, consolas de nube, repositorios y tickets; la documentación se actualiza a mano, cuando alguien se acuerda. Algunas causas concretas:

• Infraestructura efímera. Contenedores, funciones y grupos de autoescalado crean y destruyen recursos a un ritmo que ningún proceso manual puede seguir.
• Cambios fuera del proceso. Un ajuste de emergencia en la consola resuelve el incidente y nunca vuelve al repositorio ni a la CMDB.
• Dependencias implícitas. Un servicio empieza a llamar a otro por una nueva funcionalidad. Nadie lo registra porque nadie lo considera un cambio de arquitectura.
• Dueños difusos. Si cada elemento de configuración no tiene un responsable, su actualización es tarea de todos y, por lo tanto, de nadie.
• Diagramas como imágenes. Un diagrama guardado como imagen o en una herramienta de dibujo no se puede comparar automáticamente con la realidad.

La práctica de gestión de la configuración del servicio de ITIL 4 insiste en que la información de configuración debe ser confiable y útil para decidir, no exhaustiva. Ese es un buen punto de partida: no se trata de registrarlo todo, sino de que lo registrado sea cierto.

Fuentes de descubrimiento

La buena noticia es que buena parte de la realidad ya está registrada en algún sistema. El trabajo consiste en reunir esas fuentes y conciliarlas.

Fuente	Qué aporta	Límite
APIs de inventario de la nube (por ejemplo AWS Config, Azure Resource Graph, Google Cloud Asset Inventory)	Recursos existentes, su configuración y, según el servicio, su historial de cambios	No dicen qué servicio de negocio soporta cada recurso si el etiquetado es pobre
Trazas distribuidas y mapas de servicios (OpenTelemetry, plataformas APM)	Dependencias reales entre servicios, observadas en tráfico de producción	Solo ven lo instrumentado y lo que tuvo tráfico en la ventana analizada
Repositorios de infraestructura como código (Terraform, Ansible, manifiestos de Kubernetes)	La intención: cómo debería estar configurado cada componente y quién lo cambió	No reflejan los cambios hechos fuera del repositorio
Herramientas de descubrimiento de red y de la propia CMDB	Equipos en sitio, sistemas heredados, relaciones de red	Requieren credenciales y mantenimiento de patrones de descubrimiento
Gestión de cambios e incidentes	Contexto: por qué cambió algo, quién lo aprobó, qué falló	Información en texto libre, de calidad variable

Ninguna fuente es suficiente por sí sola. La combinación más útil suele ser la intención (el código), el estado real (las APIs de la nube) y el comportamiento observado (las trazas). Cuando las tres coinciden, el dato es confiable. Cuando no coinciden, hay una deriva que merece revisión. Por eso conviene que el software se escriba para ser observable: sin propagación de contexto de trazas, el mapa de dependencias queda incompleto.

Detectar la deriva y proponer, no escribir

El papel del agente no es reemplazar la CMDB ni escribir en ella sin control. Es comparar fuentes, detectar diferencias y preparar propuestas de actualización que una persona revisa. Un ciclo razonable funciona así:

1. Recolección. El agente consulta las fuentes con permisos de solo lectura y normaliza los datos en un modelo común: componente, tipo, dueño, servicio, relaciones.
2. Conciliación. Compara ese modelo con lo registrado en la CMDB y en los diagramas. Clasifica cada diferencia: componente nuevo, componente retirado, relación nueva, atributo distinto.
3. Explicación. Para cada diferencia busca contexto en los cambios, commits y tickets recientes. Una relación nueva acompañada de un despliegue aprobado es esperable; una sin rastro merece atención, porque puede indicar un cambio no autorizado.
4. Propuesta. Prepara la actualización en el formato del destino: un registro sugerido en la CMDB, un pull request contra el repositorio de diagramas o un comentario al dueño del servicio.
5. Revisión humana. El dueño del elemento aprueba, corrige o descarta. Lo descartado alimenta las reglas para no insistir con el mismo falso positivo.

Para la infraestructura gestionada con Terraform, la detección de deriva básica ya existe en la herramienta. Un agente puede ejecutarla de forma periódica y usar el resultado como una señal más:

#!/usr/bin/env bash
# Detecta deriva entre el estado de Terraform y la infraestructura real.
# Requiere un directorio ya inicializado (terraform init).
# -detailed-exitcode: 0 = sin cambios, 1 = error, 2 = hay diferencias.
terraform plan -refresh-only -detailed-exitcode -no-color > drift.txt
rc=$?
if [ "$rc" -eq 2 ]; then
  echo "Deriva detectada: revisar drift.txt"
elif [ "$rc" -eq 1 ]; then
  echo "Error al ejecutar terraform plan" >&2
  exit 1
fi

Lo que agrega el agente sobre este resultado no es la detección en sí, sino la interpretación: qué servicio se ve afectado, si el cambio tiene un ticket asociado y qué debería actualizarse en la documentación.

Notas de arquitectura y borradores de runbook

Una vez que el modelo de componentes y dependencias es confiable, el agente puede generar documentación derivada. Dos casos dan buen resultado:

Diagramas como código

Si los diagramas se mantienen como texto (por ejemplo con el modelo C4 y herramientas como Structurizr, Mermaid o PlantUML), el agente puede proponer cambios concretos al archivo fuente, revisables línea a línea en un pull request. Esto es mucho más verificable que regenerar una imagen completa. Recomendamos mantener niveles separados: el contexto y los contenedores cambian poco y conviene que una persona los cuide; los niveles de detalle pueden generarse con más libertad.

Notas de arquitectura y runbooks

Con el inventario, las dependencias y el historial de incidentes, el agente puede redactar un primer borrador de nota de arquitectura por servicio (propósito, componentes, dependencias, datos que maneja, dueño) o de runbook (síntomas, verificaciones, acciones, escalamiento). Es un borrador, no un documento final. Su valor está en que el especialista corrige en lugar de escribir desde cero, y en que las secciones factuales (dependencias, endpoints, nombres de recursos) salen de fuentes verificables.

Un error frecuente es dejar que el agente complete con suposiciones lo que no encuentra en las fuentes. Conviene exigir que marque explícitamente los vacíos ("dueño no identificado", "sin trazas en los últimos 30 días") en lugar de rellenarlos. Un documento con vacíos señalados es más útil que uno completo e inexacto. Estos runbooks luego sirven como insumo para agentes de triaje de incidentes, siempre que estén revisados.

Gobierno: qué puede escribir el agente

La pregunta clave no es técnica, sino de gobierno: qué puede cambiar el agente sin revisión, qué requiere aprobación y qué no puede tocar. Esta lista de control ayuda a definirlo antes de empezar:

• Permisos de lectura separados de los de escritura. El acceso a las fuentes es de solo lectura. La escritura en la CMDB o en los repositorios usa una identidad distinta, con alcance limitado.
• Atributos que puede actualizar solo. Por ejemplo, la fecha de última observación de un componente o un atributo técnico que coincide en todas las fuentes.
• Cambios que requieren aprobación. Altas y bajas de elementos, relaciones nuevas, cambios de dueño o de criticidad, cualquier modificación en diagramas publicados.
• Datos que nunca debe escribir. Secretos, credenciales, datos personales o información clasificada que aparezca en configuraciones o tickets.
• Trazabilidad. Cada cambio propuesto o aplicado registra la fuente, la evidencia y quién lo aprobó.
• Revisión periódica. Se mide la tasa de propuestas aceptadas y descartadas; si el agente genera demasiado ruido, se ajustan las reglas antes de ampliar su alcance.

Estas reglas son una aplicación concreta de un principio más general: dar a cada agente solo la autonomía que su historial y el impacto de sus acciones justifican. La documentación es un buen lugar para empezar con agentes porque un error es visible y fácil de revertir, pero sigue siendo información en la que otros confían para tomar decisiones.

Por dónde empezar

No hace falta abordar toda la CMDB a la vez. Recomendamos elegir un dominio acotado, por ejemplo los servicios críticos de una línea de negocio, y avanzar en tres pasos: primero, que el agente solo reporte diferencias durante algunas semanas, para medir cuánta deriva existe y cuánto ruido genera; después, que proponga actualizaciones a los dueños; por último, que aplique por su cuenta los cambios de bajo riesgo que demostraron ser correctos.

El indicador que importa al final no es cuántos elementos tiene la CMDB, sino si los equipos vuelven a usarla durante un incidente. Esa es la prueba de que la documentación está viva.