Documentación de arquitectura con IA: descubrimiento, deriva y agentes

Existe una tensión fundamental en el corazón de la documentación de arquitectura de software. El código está vivo -- cambia con cada commit, cada refactorización, cada hotfix. La documentación es estática -- cambia cuando alguien se acuerda de actualizarla. La brecha entre ambos crece en silencio hasta que el diagrama en la wiki describe un sistema que ya no existe.

Esto no es un problema de disciplina. Incluso los equipos más diligentes terminan quedándose atrás. El esfuerzo necesario para mantener manualmente diagramas precisos crece de forma lineal con la complejidad del sistema, mientras que la velocidad de cambio del código se mantiene constante o se acelera.

La IA está cambiando esta ecuación. No reemplazando el criterio arquitectónico humano, sino automatizando las partes de la documentación en las que los humanos no somos buenos: descubrimiento, sincronización y detección de drift. El resultado es una documentación de arquitectura que parte del código, se mantiene actualizada automáticamente y sirve como capa de conocimiento tanto para humanos como para agentes de IA.

El Problema con la Documentación Manual de Arquitectura

Antes de explorar como ayuda la IA, seamos específicos sobre lo que no funciona.

El Problema de Creación

Crear documentación de arquitectura desde cero para un sistema existente es doloroso. Lees código, rastreas dependencias, entrevistas a miembros del equipo y lentamente construyes un modelo mental que traduces en diagramas. Para un sistema mediano (20-30 servicios), esto toma semanas. Para un sistema grande (100+ servicios), toma meses.

Durante ese tiempo, el sistema sigue cambiando. Para cuando tu documentación está "terminada," partes de ella ya están desactualizadas. Estás documentando un objetivo en movimiento.

El Problema de Mantenimiento

Incluso si creas documentación perfecta, mantenerla precisa requiere esfuerzo continuo. Cada nuevo servicio, cada módulo renombrado, cada API deprecada necesita reflejarse en los diagramas de arquitectura. En la práctica, esto significa:

  • Los desarrolladores necesitan actualizar los diagramas junto con los cambios de código
  • Alguien necesita revisar las actualizaciones de diagramas para verificar su precisión
  • Los diagramas obsoletos necesitan ser detectados y corregidos

La mayoría de los equipos intentan resolver esto con procesos: "actualiza el diagrama de arquitectura cuando cambies la arquitectura." Esto funciona durante unos tres meses antes de que la presión de los plazos y el trabajo en funcionalidades empuje las actualizaciones de documentación al final de la lista de prioridades.

El Problema de Descubrimiento

Cuando un nuevo ingeniero se une al equipo, necesita entender la arquitectura antes de poder ser productivo. Si la documentación existe pero está desactualizada, es peor que no tener documentación porque desorienta activamente. El nuevo ingeniero construye un modelo mental basado en diagramas incorrectos, y luego pasa días depurando sus suposiciones.

Sin documentación, el descubrimiento recae en el conocimiento tribal: preguntar al ingeniero que lleva más tiempo. Esto no escala, crea cuellos de botella y falla completamente cuando las personas clave se van.

El Problema de Consistencia

En organizaciones con múltiples equipos, cada equipo documenta su arquitectura de forma diferente. El Equipo A usa Visio. El Equipo B usa Miro. El Equipo C tiene un README con arte ASCII. El Equipo D no documenta en absoluto. No hay una vista unificada de la arquitectura de la organización, no hay una notación consistente y no hay forma de entender las dependencias entre equipos.

Cómo la IA Cambia la Ecuación

La IA aborda cada uno de estos problemas, no eliminando la participación humana, sino automatizando las partes tediosas y propensas a errores y amplificando el criterio humano.

Descubrimiento de Arquitectura con IA

La aplicación más inmediata de la IA en la documentación de arquitectura es el descubrimiento automatizado. En lugar de leer código manualmente y construir diagramas, apuntas un sistema de IA a tu codebase y este genera un borrador del modelo de arquitectura.

Así es como funciona en la práctica con Archyl:

  1. Conexión del repositorio. Conectas tu repositorio Git (GitHub, GitLab, Bitbucket o Azure DevOps).

  2. Escaneo del código. El sistema recorre tu codebase, identificando estructuras de archivos, archivos de configuración, puntos de entrada y grafos de dependencias.

  3. Análisis con IA. Los large language models analizan tu código en fragmentos, identificando:

    • De qué es responsable cada módulo o servicio
    • Qué tecnologías y frameworks se utilizan
    • Con qué sistemas externos se integra tu código
    • Cómo se comunican los componentes entre si

  4. Generación del modelo C4. La IA mapea sus hallazgos a elementos del modelo C4: sistemas, containers, componentes, elementos de código y relaciones.

  5. Revisión humana. Revisas el modelo generado, aceptas los elementos precisos, corriges errores y agregas contexto que la IA no pudo inferir.

El resultado es un modelo de arquitectura C4 creado en minutos en lugar de semanas. No es perfecto -- la IA no entiende tu dominio de negocio ni el contexto organizacional. Pero es un punto de partida dramáticamente mejor que un lienzo en blanco.

Lo que la IA Hace Bien

La IA sobresale en los aspectos estructurales de la documentación de arquitectura:

Detección de tecnologías. Los LLMs reconocen patrones de frameworks, modismos de librerías y formatos de configuración en docenas de lenguajes y ecosistemas. Un archivo go.mod con github.com/gofiber/fiber identifica inmediatamente un servicio Go usando el framework Fiber. Un package.json con next identifica una aplicación Next.js.

Detección de límites de servicios. En arquitecturas de microservicios, la IA identifica de manera confiable los límites de los servicios a partir de la estructura de directorios, configuraciones de Docker y manifiestos de despliegue. Un docker-compose.yml con cinco servicios le da a la IA una topología clara con la cual trabajar.

Mapeo de dependencias. Las sentencias de importación, las librerías cliente de API y los archivos de configuración revelan dependencias entre servicios y con sistemas externos. Cada importación de SDK, cada URL base de API, cada cadena de conexión es una pista.

Reconocimiento de patrones. La IA ha sido entrenada con millones de codebases. Reconoce estructuras MVC, arquitectura hexagonal, patrones event-driven y docenas de otros patrones arquitectónicos. Cuando tu código sigue convenciones establecidas, la IA los identifica rápidamente.

Lo que la IA no Hace Bien

Ser honesto sobre las limitaciones es importante para establecer expectativas:

Dominio de negocio. La IA puede decirte que processOrder() existe, pero no puede decirte que significa "procesar un pedido" en tu contexto de negocio específico. Los nombres específicos del dominio, los flujos de trabajo personalizados y las reglas de negocio requieren interpretación humana.

Arquitecturas no convencionales. Si tu sistema usa un framework de plugins personalizado, un sistema de build propio o una estructura de proyecto inusual, la IA puede tener dificultades. Espera que las aplicaciones React luzcan como aplicaciones React y que los servicios Go luzcan como servicios Go.

Dependencias de runtime. El análisis estático de código no puede detectar dependencias que solo existen en tiempo de ejecución: sidecar containers, configuraciones de service mesh, integraciones específicas del entorno o infraestructura que no está representada en el código.

Intención. La IA puede describir qué hace el código, pero no por qué fue escrito de esa manera. Las decisiones arquitectónicas, las compensaciones y las restricciones que dieron forma al sistema no son visibles en el código en sí. Por eso los ADRs (Architecture Decision Records) siguen siendo esenciales -- la IA descubre la estructura, pero los humanos documentan la intención.

Detección de Drift: Manteniendo la Documentación Honesta

El descubrimiento resuelve el problema de creación. La detección de drift resuelve el problema de mantenimiento.

El architecture drift es la brecha entre lo que dice tu documentación y lo que tu código realmente hace. Es el servicio renombrado que todavía aparece con su nombre anterior en el diagrama. El componente deprecado que todavía se muestra cómo activo. El nuevo microservicio que nunca se agregó al modelo de arquitectura.

Cómo Funciona la Detección Automatizada de Drift

La detección de drift de Archyl toma un enfoque ligero. No vuelve a ejecutar el pipeline completo de descubrimiento con IA (lo cual sería lento y costoso). En cambio, realiza validaciones dirigidas:

  • Sistemas: ¿El nombre del sistema documentado coincide con el nombre del repositorio?
  • Containers: ¿Los containers documentados corresponden a directorios reales en el codebase?
  • Componentes: ¿Los componentes documentados siguen siendo válidos dada la existencia de su container padre?
  • Elementos de código: ¿La ruta del archivo de cada elemento de código documentado todavía existe en el repositorio?
  • Relaciones: ¿Ambos extremos de cada relación documentada siguen siendo válidos?

El resultado es un drift score entre 0 y 100, que representa el porcentaje de tu arquitectura documentada que aún coincide con la realidad. Un score de 95% significa que tu documentación es altamente precisa. Un score de 50% significa que la mitad de tu documentación es ficción.

Haciendo el Drift Accionable

Un score solo no es suficiente. Archyl proporciona un desglose detallado que muestra exactamente qué ha cambiado:

  • Qué containers están documentados pero faltan en el codebase
  • Qué elementos de código hacen referencia a archivos que ya no existen
  • Qué relaciones conectan a elementos que han derivado
  • Qué nuevos elementos existen en el codebase pero no están documentados

Este desglose transforma una vaga sensación de "nuestra documentación probablemente está desactualizada" en una lista específica y accionable de cosas que corregir.

Drift en CI/CD

La aplicación más poderosa de la detección de drift está en la integración continua. Archyl proporciona una GitHub Action que calcula el drift score en cada push:

- uses: archyl-com/actions/drift-score@v1
  with:
    api-key: ${{ secrets.ARCHYL_API_KEY }}
    organization-id: ${{ secrets.ARCHYL_ORG_ID }}
    project-id: 'your-project-uuid'
    threshold: '70'

Establece un umbral, y el build falla si la precisión de la documentación cae por debajo de él. Esto trata la documentación de arquitectura como tests: una puerta de calidad que previene la degradación.

Los equipos que adoptan este enfoque reportan un cambio fundamental en como piensan sobre la documentación. Deja de ser algo secundario y se convierte en una preocupación de primera clase, verificada en cada commit.

Más allá de la deriva: reglas de conformidad y una nota de madurez

La deriva te dice si la documentación sigue describiendo el código. No te dice si el código sigue las decisiones que tomó el equipo, ni si la práctica en torno a la arquitectura está sana. Otras dos comprobaciones cubren eso.

Las reglas de conformidad convierten las decisiones en comprobaciones

Una regla de conformidad es una restricción arquitectónica escrita para que una máquina pueda comprobarla: «el frontend no debe hablar directamente con la base de datos», «los handlers no deben importar la capa de repositorio», «los topics de eventos siguen nuestra convención de nombres». Archyl evalúa varios tipos de reglas (límites entre capas, restricciones de dependencias, nombres, tecnologías permitidas, patrones de código obligatorios y prohibidos, cumplimiento de contratos API y canales de eventos) sobre los archivos modificados en un pull request, y publica las infracciones como comentario en él. El catálogo incluye 169 reglas listas para usar en 24 tecnologías, y puedes escribir las tuyas.

El hábito útil es emparejar reglas con ADR. Cuando un ADR dice que las llamadas síncronas entre servicios deben dar paso a eventos, esa decisión puede convertirse en una regla, y el siguiente pull request que añada una llamada directa se marca en la revisión en lugar de descubrirse en la siguiente reunión de arquitectura. El ADR registra el porqué; la regla comprueba que sigue cumpliéndose.

Esto importa más a medida que el sistema crece. Con cincuenta servicios y unas cuantas decenas de restricciones, ningún revisor tiene todas las reglas en la cabeza, y las infracciones sutiles son las que se cuelan. Una comprobación de reglas ejecuta cada regla activada sobre cada cambio.

Una nota de madurez a partir de cuatro señales

La deriva, los insights, la conformidad y las métricas DORA responden cada uno a una pregunta. La puntuación de madurez los combina en una nota con letra para un proyecto, un sistema o un solo contenedor: A a partir de 90, B a partir de 80, C a partir de 70, D a partir de 60 y F por debajo. Por defecto, la deriva pesa un 40 %, los insights un 30 %, la conformidad un 20 % y DORA un 10 %. Si desactivas una dimensión, su peso se reparte entre las demás, así que un equipo que no registra sus releases no sale penalizado por ello.

La nota se gana su sitio por el desglose, no por la letra. Un proyecto puede tener un modelo preciso y ADR al día y, aun así, desplegar una vez al mes con una tasa alta de fallos en los cambios. Otro puede desplegar diez veces al día ignorando todas las reglas que definió. Cada métrica por separado oculta uno de esos casos; las cuatro dimensiones una junto a otra muestran ambos, y la tendencia entre cálculos muestra si las cosas mejoran. El artículo sobre la puntuación de madurez explica el panel de detalle y la vista de organización.

La Revolución MCP: Agentes de IA que Entienden la Arquitectura

El Model Context Protocol (MCP) es un estándar abierto que permite a los agentes de IA interactuar con herramientas externas y fuentes de datos. El servidor MCP de Archyl expone todo tu modelo de arquitectura -- diagramas C4, ADRs, reglas de conformidad, drift scores -- a cualquier agente de IA compatible con MCP.

Esto crea un nuevo paradigma: agentes de IA que son conscientes de la arquitectura.

Cómo Funciona

Cuando usas Claude Code, Cursor u otro asistente de programación con IA compatible con MCP con el servidor MCP de Archyl conectado:

  1. El agente puede llamar a get_agent_context para recibir el modelo C4 completo, ADRs y reglas de conformidad de un proyecto.
  2. Antes de escribir código, el agente entiende la arquitectura documentada: qué servicios existen, cómo se comunican, qué tecnologías se usan, qué decisiones se han tomado.
  3. El agente puede consultar get_drift_score para evaluar qué tan confiable es la documentación.
  4. El agente puede leer ADRs específicos para entender por qué se tomaron ciertas decisiones arquitectónicas.

Por Qué Esto Importa

Sin contexto arquitectónico, los agentes de programación con IA son poderosos pero ciegos. Pueden escribir código excelente que viole tus principios arquitectónicos, introduzca dependencias no deseadas o duplique funcionalidad que ya existe en otro servicio.

Con MCP, el agente sabe:

  • "Este sistema usa PostgreSQL, no MongoDB -- debo generar consultas SQL, no consultas MongoDB."
  • "La comunicación entre servicios usa eventos Kafka, no llamadas HTTP -- debo publicar un evento, no hacer una petición REST."
  • "El equipo decidió no usar GraphQL (ADR-0019) -- no debería sugerir una implementación GraphQL."
  • "El drift score de la arquitectura es 45% -- debo ser cauteloso al confiar en la estructura documentada."

Esto transforma a los agentes de IA de generadores de código en colaboradores conscientes de la arquitectura.

Reglas de Conformidad

Las reglas de conformidad descritas arriba también se pueden leer por MCP, así que un agente puede comprobar su propio cambio contra ellas antes de que lo vea un revisor humano. Es una gobernanza que sigue el ritmo del desarrollo asistido por IA en lugar de quedarse atrás.

Impacto en el Mundo Real

Antes de la Documentación con IA

Un escenario típico sin asistencia de IA:

  • Un nuevo ingeniero se une al equipo
  • Pasa 2-3 semanas leyendo código, haciendo preguntas y construyendo un modelo mental
  • Crea notas personales que nadie más aprovecha
  • Los diagramas de arquitectura se actualizaron por última vez hace 8 meses y están un 40% incorrectos
  • Nadie sabe qué ADRs siguen siendo relevantes
  • Cada discusión arquitectónica empieza desde cero porque el contexto se pierde

Después de la Documentación con IA

El mismo escenario con documentación impulsada por IA:

  • El nuevo ingeniero abre Archyl y ve el modelo C4 actual (drift score: 92%)
  • Navega desde el contexto del sistema a containers y componentes
  • Hace clic en servicios complejos para leer ADRs vinculados que explican decisiones clave
  • Usa el chat de arquitectura para hacer preguntas: "¿Cómo se comunica el servicio de pedidos con el servicio de pagos?"
  • Comienza a contribuir código en días, no semanas
  • Los agentes de IA que escriben código respetan la arquitectura y las decisiones documentadas

La diferencia no es sutil. Es la diferencia entre conocimiento tribal y conocimiento institucional. Entre documentación que es una carga y documentación que es un activo.

Hacia dónde va la documentación de arquitectura con IA

Aún estamos al principio. Esto es hacia donde se dirige la documentación de arquitectura con IA:

Descubrimiento Continuo

El descubrimiento actual es una operación puntual: lo ejecutas, revisas los resultados y sigues adelante. El descubrimiento futuro sera continuo -- monitoreando tu codebase en busca de cambios y sugiriendo actualizaciones al modelo de arquitectura en tiempo real. ¿Fusionas un PR que agrega un nuevo servicio? El sistema lo detecta y propone agregarlo al modelo C4.

Análisis de Comportamiento

El análisis actual de IA es estructural: entiende lo que existe en el código. El análisis futuro entenderá el comportamiento: cómo interactúan los componentes en tiempo de ejecución, qué datos fluyen a través del sistema, cómo se propagan los errores. Esto permite diagramas dinámicos generados a partir del tráfico de producción, no solo del análisis estático.

Inteligencia entre Repositorios

La mayoría de las organizaciones tienen arquitecturas que abarcan múltiples repositorios. El descubrimiento futuro con IA entenderá dependencias entre repositorios: este servicio en el repo A llama a ese servicio en el repo B, que escribe en esta base de datos gestionada en el repo C. Un modelo de arquitectura unificado en toda la organización.

Documentación que se Auto-repara

El objetivo final: documentación que se corrige sola. Cuando se detecta drift, la IA genera la actualización, crea un pull request con el modelo corregido y solicita aprobación humana. El rol del humano cambia de crear documentación a revisar actualizaciones propuestas por la IA -- un esfuerzo mucho más ligero.

Generación de Código Consciente de la Arquitectura

A medida que los agentes de programación con IA se vuelven más capaces, la conciencia arquitectónica se vuelve crítica. Los agentes que entienden tu arquitectura pueden:

  • Generar código que siga patrones establecidos
  • Sugerir refactorizaciones que se alineen con los objetivos arquitectónicos
  • Advertir cuando los cambios propuestos aumentarían el drift
  • Actualizar automáticamente los modelos de arquitectura cuando el código cambia

Cómo Empezar

No necesitas adoptar todo de una vez. Aquí tienes una progresión práctica:

Fase 1: Descubrimiento (Día 1)

Conecta tu repositorio a Archyl y ejecuta el descubrimiento con IA. Revisa el modelo C4 generado. Corrige errores obvios. Ahora tienes un modelo de arquitectura base que probablemente es 70-80% preciso.

Fase 2: Enriquecimiento (Semana 1)

Agrega el contexto que la IA no puede descubrir: ADRs para decisiones clave, documentación para flujos de trabajo importantes, reglas de conformidad para restricciones arquitectónicas. Vincula los ADRs a los elementos C4 que afectan.

Fase 3: Detección de Drift (Semana 2)

Configura la GitHub Action de drift score. Establece un score base y define un umbral. Comienza a monitorear el drift en cada push.

Fase 4: Integración MCP (Semana 3)

Conecta el servidor MCP de Archyl a tus herramientas de programación con IA. Dale a tus agentes contexto arquitectónico. Observa cómo generan código que respeta tu arquitectura.

Fase 5: Gobernanza (Continuo)

Define reglas de conformidad. Monitorea las tendencias de drift. Revisa y actualiza los ADRs trimestralmente. La documentación de arquitectura se convierte en un activo vivo y mantenido -- no un proyecto puntual.

El futuro de la documentación de arquitectura no se trata de escribir mejores diagramas. Se trata de construir sistemas donde la documentación se crea sola, se mantiene sola y sirve tanto a humanos como a agentes de IA como una fuente compartida de verdad arquitectónica.

Comienza a construir documentación de arquitectura con IA hoy. Prueba Archyl gratis -- conecta un repositorio y ve tu arquitectura descubierta en minutos. Más información: Descubrimiento con IA: Cómo Funciona | Architecture Drift Score | Servidor MCP para documentación de arquitectura.