El architecture drift es la brecha entre el sistema que documentaste y el sistema que realmente tienes. Los consejos habituales al respecto (mantener los docs junto al código, revisarlos en la misma pull request) son buenos, y ninguno de ellos te dice si funcionó. Esta guía cubre qué es el drift, las formas de detectarlo y cómo ponerle un número a la brecha que ya tienes.

Detección de Architecture Drift: mantén tu código alineado con el diseño

En algún lugar de tu organización hay un diagrama de arquitectura que está mal. Quizá muestra un microservicio que fue fusionado con otro hace seis meses. Quizá lista Redis como capa de caché cuando el equipo cambió a Memcached durante un incidente en producción. Quizá describe una arquitectura hexagonal limpia en un servicio que ha acumulado suficientes atajos y soluciones temporales como para parecer spaghetti.

Esto es architecture drift: la divergencia gradual y silenciosa entre cómo está documentado tu sistema y cómo realmente funciona. A diferencia de los bugs, el drift no dispara alertas. A diferencia de las regresiones de rendimiento, no aparece en el monitoreo. Se queda ahí en silencio hasta que alguien toma una decisión basada en documentación desactualizada -- y esa decisión resulta ser incorrecta.

El architecture drift es universal. Todos los equipos lo experimentan. La pregunta no es si tu documentación derivará, sino qué tan rápido lo detectarás y qué harás al respecto.

No faltan consejos sobre la segunda mitad de esa pregunta. Mantén los docs junto al código. Revísalos en la misma pull request. Hazlos parte de la definition of done. Son buenos consejos, la mayoría aparecen más abajo en esta página, y comparten un punto ciego: te dicen qué hacer, no si funcionó. Lo más parecido a una comprobación que hay en las recomendaciones habituales es una marca de última edición, que te dice cuándo alguien tocó el archivo, no si el archivo dice la verdad.

Detectar el drift es la mitad que se salta. Esta guía cubre el problema, las cinco familias de métodos de detección y qué puede y qué no puede ver cada una. Dos artículos complementarios profundizan cada uno en una cosa: cómo se calcula un drift score y qué significa ese número, y las prácticas que mantienen verdadero un modelo una vez que lo tienes.

Qué es el Architecture Drift

El architecture drift ocurre cuando la implementación real de un sistema de software diverge de su arquitectura documentada o prevista. Perry y Wolf le pusieron nombre al problema en Foundations for the Study of Software Architecture (ACM SIGSOFT Software Engineering Notes, 1992), donde separaron la erosion (erosión), que viene de violar la arquitectura, del drift, que viene de ser insensible a ella. El uso cotidiano se ha desplazado desde entonces: hoy la mayoría de los ingenieros dicen "drift" para cualquier brecha entre la documentación y el código, y ese es el sentido que usa esta guía. La distinción merece conservarse, y hay una sección sobre ella más abajo.

El drift se manifiesta en todos los niveles de la documentación arquitectónica:

Drift Estructural

La estructura documentada ya no coincide con el codebase:

Un servicio documentado como container independiente fue absorbido en un monolito
Un component fue renombrado pero el diagrama sigue mostrando el nombre antiguo
Se creó un servicio nuevo pero nunca se añadió al modelo de arquitectura
Una base de datos fue migrada de MySQL a PostgreSQL pero el diagrama de containers sigue diciendo MySQL

Drift de Comportamiento

El comportamiento documentado ya no coincide con la realidad:

Una llamada API síncrona fue reemplazada por un mensaje asíncrono, pero la relación sigue diciendo "REST/HTTP"
Un flujo de datos fue modificado para pasar por un API gateway, pero el diagrama muestra comunicación directa entre servicios
Se añadió un paso de autenticación que no se refleja en el diagrama de contexto del sistema

Drift de Dependencias

Las dependencias documentadas ya no coinciden con las integraciones reales:

Una API de terceros fue reemplazada por algo construido internamente
Se añadió una nueva dependencia externa (proveedor de pagos, servicio de monitoreo) pero no se documentó
Una integración fue dada de baja pero sigue apareciendo en el diagrama de contexto del sistema

Drift de Decisiones

Las decisiones arquitectónicas documentadas ya no se siguen:

Un ADR dice "usar PostgreSQL para todo el almacenamiento persistente" pero un equipo empezó a usar MongoDB
Las reglas de conformance dicen "sin acceso directo a la base de datos desde el frontend" pero alguien añadió una integración de Supabase en el cliente
La arquitectura de despliegue dice "una sola región" pero se desplegaron servicios en varias regiones

Por qué ocurre el Architecture Drift

Entender las causas del drift es esencial para prevenirlo. El drift no suele ser malicioso ni siquiera negligente -- es una consecuencia natural de cómo se desarrolla el software.

Velocidad por encima de documentación

Cuando hay que entregar una feature para el viernes, actualizar el diagrama de arquitectura es lo primero que se cae. El cambio de código es el entregable. La actualización de documentación es overhead. Es un comportamiento racional a corto plazo y devastador a largo plazo.

Muchos cambios pequeños

El drift rara vez ocurre en un momento dramático. Se acumula a través de cientos de cambios pequeños, cada uno demasiado menor como para justificar una actualización de documentación:

Renombrar un archivo
Añadir un paquete de utilidades
Cambiar una dependencia de biblioteca
Extraer una función a un módulo separado

Ningún cambio individual es lo bastante significativo como para disparar una actualización de documentación. Juntos, transforman la arquitectura.

Rotación del equipo

Cuando los ingenieros se van, se llevan el conocimiento implícito con ellos. El equipo nuevo hereda el codebase pero no la comprensión de por qué está estructurado como está. Hacen cambios basándose en lo que ven en el código, no en lo que dice la documentación, ampliando el drift.

Falta de bucles de feedback

Si nadie comprueba si la documentación coincide con la realidad, el drift es invisible. Sin un mecanismo de detección, la única forma de descubrir el drift es durante un incidente, una auditoría, o cuando un ingeniero nuevo señala que el diagrama no coincide con el código. Para entonces, el drift puede ser extenso.

Cambios de emergencia

Los incidentes de producción a menudo exigen atajos arquitectónicos: una conexión directa a la base de datos en lugar de pasar por la capa de API, una configuración hardcodeada en lugar de usar el servicio de config, una caché temporal que se vuelve permanente. Estos cambios saltan los procesos normales de revisión y rara vez se documentan.

El coste del Architecture Drift

El drift no es solo un problema estético. Tiene costes concretos y medibles.

Malas decisiones

Cuando los arquitectos toman decisiones basadas en documentación desactualizada, esas decisiones pueden ser incorrectas. "Este servicio tiene poco tráfico, así que podemos permitirnos una dependencia síncrona" -- salvo que la documentación está obsoleta y el servicio en realidad maneja 10x la carga documentada.

Onboarding lento

Los ingenieros nuevos se apoyan en la documentación de arquitectura para construir su modelo mental. Si la documentación está mal, construyen modelos mentales equivocados. Escriben código que no encaja con la arquitectura real. Hacen preguntas que revelan su confusión, consumiendo el tiempo de los ingenieros senior.

Respuesta a incidentes

Durante un incidente de producción, los diagramas de arquitectura deberían ayudar a los equipos a entender el radio de impacto y las dependencias. Si esos diagramas están mal, los equipos pierden minutos preciosos siguiendo las cadenas de dependencias equivocadas o pasando por alto sistemas upstream críticos.

Fallos de compliance y auditoría

En industrias reguladas, la documentación de arquitectura suele ser un requisito de compliance (SOC 2, ISO 27001, HIPAA). Si los auditores encuentran que la documentación no coincide con la realidad, es un hallazgo -- potencialmente uno serio.

Confusión de los agentes de IA

A medida que los agentes de codificación con IA se generalizan, dependen cada vez más de la documentación de arquitectura como contexto. Un agente que lee un modelo C4 obsoleto generará código que encaja con la arquitectura documentada, no con la real. Esto amplifica el drift en lugar de arreglarlo.

Cómo detectar el Architecture Drift

Hay cinco enfoques de uso común, y responden a preguntas distintas. La revisión manual pregunta si el diagrama sigue pareciendo correcto a la gente que está en la sala. Las fitness functions y el análisis estático preguntan si se están rompiendo reglas concretas. La evaluación con LLM pregunta si el código se lee como el diseño que dice implementar. El drift scoring pregunta cuánto del modelo documentado sigue existiendo. Elige según qué pregunta te esté costando dinero.

Revisión manual (enfoque tradicional)

El enfoque más simple es la revisión manual periódica: reúne al equipo, repasa los diagramas de arquitectura y comprueba si siguen coincidiendo con la realidad.

Cuándo funciona: equipos pequeños, arquitecturas simples, cadencia trimestral.

Cuándo falla: sistemas grandes, equipos que van rápido, o cuando la gente que mejor conoce el código no tiene tiempo para reuniones de revisión. La revisión manual también sufre sesgo de confirmación -- la gente tiende a ver lo que espera ver.

Architecture fitness functions

Las fitness functions, popularizadas por Neal Ford y el libro "Building Evolutionary Architectures", son tests automatizados que validan propiedades arquitectónicas:

// Example: Ensure no direct database imports in handler packages
func TestNoDatabaseImportsInHandlers(t *testing.T) {
    packages := analyzeImports("./internal/handler/...")
    for _, pkg := range packages {
        for _, imp := range pkg.Imports {
            assert.NotContains(t, imp, "database/sql",
                "Handler %s imports database/sql directly", pkg.Name)
            assert.NotContains(t, imp, "gorm.io",
                "Handler %s imports GORM directly", pkg.Name)
        }
    }
}

Las fitness functions son potentes para hacer cumplir reglas específicas, pero requieren esfuerzo inicial para escribirlas y mantenerlas. Comprueban restricciones, no el modelo completo.

Herramientas de análisis estático

Herramientas como ArchUnit (Java), Deptrac (PHP) y go-arch-lint (Go) analizan la estructura del código y hacen cumplir reglas de dependencias:

// go-arch-lint configuration
components:
  handler:
    in: ./internal/handler/
  service:
    in: ./internal/service/
  repository:
    in: ./internal/repository/

rules:
  handler:
    can_depend_on: [service]
  service:
    can_depend_on: [repository]
  repository:
    can_depend_on: []

Estas herramientas son excelentes para hacer cumplir una arquitectura en capas dentro de un solo codebase. No abordan el drift entre servicios ni validan que el modelo de arquitectura coincida con el código.

Evaluación asistida por LLM

Thoughtworks puso la reducción del architecture drift con LLM en el anillo Assess del Technology Radar Vol. 34 (abril de 2026). Vale la pena citar cómo formulan el problema, porque viene de otro sitio que no es un fabricante de software:

Increased use of AI coding agents can accelerate drift from the intended codebase and architecture designs. Left unchecked, this drift compounds as agents and humans replicate existing patterns, including degraded ones, creating a feedback loop where poor code begets poorer code.

En español: el uso creciente de agentes de codificación con IA puede acelerar el drift respecto al codebase y a los diseños de arquitectura previstos. Sin control, este drift se agrava a medida que agentes y humanos replican los patrones existentes, incluidos los degradados, creando un bucle de realimentación donde el código malo engendra código peor.

La técnica que describen combina herramientas de análisis determinista (nombran Spectral, ArchUnit y Spring Modulith) con evaluación por LLM, para capturar violaciones semánticas que un motor de reglas no sabe expresar, y luego usa el LLM para ayudar a arreglar lo que ha encontrado. Sus equipos la han aplicado a guías de calidad de API y a definir zonas arquitectónicas que guían los cambios generados por agentes.

Dos de sus lecciones merecen trasladarse a cualquier herramienta que uses. Un primer escaneo saca a la luz más violaciones de las que nadie va a triar, así que priorizar es el trabajo de verdad. Y el arreglo de un agente necesita su propio bucle de verificación, porque "cambió el código" y "mejoró el sistema" son afirmaciones distintas.

Assess es el anillo de Thoughtworks que significa "vale la pena mirarlo, todavía no lo recomendamos". Trátalo así. Lo que zanja es que el problema es lo bastante real como para que una consultora grande lo ponga por escrito, que es más de lo que la mayoría de los argumentos sobre drift pueden señalar.

Drift scoring automatizado

Este es el enfoque de Archyl. En lugar de comprobar reglas específicas, valida el modelo de arquitectura completo contra el codebase:

¿Cada sistema documentado corresponde a un repositorio?
¿Cada container documentado corresponde a un directorio del codebase?
¿Cada elemento de código documentado referencia un archivo que todavía existe?
¿Siguen siendo válidos ambos extremos de cada relación documentada?

El resultado es una puntuación de 0 a 100 y un desglose por elemento de qué coincidió, qué está documentado pero ha desaparecido, y qué existe en el código pero nunca se escribió en ninguna parte. Donde las fitness functions comprueban las restricciones que se te ocurrió escribir, esto comprueba el modelo entero que ya tienes.

Las decisiones de diseño clave en la detección de drift de Archyl:

Ligera. Ninguna llamada a IA y ningún contenido de archivo descargado. Una sola petición recursiva del árbol a tu proveedor Git, y después correspondencia de rutas y nombres contra el modelo. El cálculo tarda segundos.

Determinista. Mismo codebase, mismo modelo, misma puntuación. Sin variabilidad por temperatura del LLM ni por prompt engineering.

Barata. Ejecútala en cada push sin preocuparte por el coste. Cien cálculos al día están bien.

Accionable. El desglose nombra qué elementos han derivado, así que sabes qué arreglar.

El compromiso está en el primer punto. Comprobar rutas y nombres en lugar de leer el código hace que la puntuación sea rápida, gratuita y reproducible, y significa que la comprobación es estructural. Ve un container cuyo directorio ha desaparecido y un elemento de código cuyo archivo se ha borrado. No ve la llamada REST que se convirtió en un mensaje de cola mientras ambos servicios conservaban sus nombres. Eso es drift de comportamiento, el único tipo de la taxonomía del principio de esta guía que ninguna comprobación barata captura. La revisión manual y la evaluación con LLM son lo que tienes para eso.

Cómo se calcula el drift score, en detalle cubre la fórmula, qué se excluye del denominador y por qué, y el resto de los límites.

Cerrar el bucle

La detección por sí sola no cambia nada. Una puntuación que alguien calcula una vez y mira es una auditoría, no un bucle de feedback. Tres mecanismos la convierten en uno, más una distinción que conviene tener clara antes de cablear ninguno de ellos. Las prácticas de workflow que van al lado -- architecture as code, la documentación en la definition of done, adoptar reglas de conformance -- son el tema de la documentación de arquitectura viva.

Automatizar la detección de drift en CI

El mecanismo con más dientes es una puerta de CI que falla cuando el drift supera un umbral, porque es el único que detiene un merge:

on:
  push:
    branches: [main]

jobs:
  drift:
    runs-on: ubuntu-latest
    steps:
      - 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'

Cuando el build falla porque la puntuación de drift ha caído, alguien tiene que arreglarlo antes de mergear. La precisión de la documentación se vuelve tan innegociable como que pasen los tests.

Pon el umbral por debajo de tu puntuación actual, no en el número que te gustaría tener. Una puerta que falla en la primera ejecución se desactiva en la primera ejecución. Súbelo a medida que el equipo construye el hábito.

Configurar alertas de drift

Archyl soporta alertas por webhook para eventos de drift:

drift.score_computed: se dispara en cada cálculo de drift. Publícalo en un canal de Slack para dar visibilidad.
drift.score_degraded: se dispara cuando la puntuación cae 10+ puntos. Este es tu sistema de alerta temprana.

Configura estas alertas hacia un canal que tu equipo vigile. La conciencia del problema es el primer paso hacia la acción.

Hacer revisiones de arquitectura

Las revisiones de arquitectura mensuales o trimestrales sirven a varios propósitos:

Validar que la arquitectura documentada sigue coincidiendo con la realidad
Identificar el drift que las herramientas automatizadas no vieron (el drift de comportamiento, por ejemplo)
Discutir si los components que han derivado deben actualizarse en el código o en la documentación
Revisar y actualizar los ADR de decisiones que quizá haya que replantear

No confundas drift con conformance

Se ejecutan juntos con suficiente frecuencia como para que merezca la pena separarlos, porque se calculan de forma distinta y fallan por motivos distintos.

La detección de drift pregunta si tu modelo coincide con la realidad. Compara la arquitectura documentada contra el repositorio y produce una puntuación.

Las reglas de conformance preguntan si la realidad sigue tus reglas: el container de frontend no debe depender del container de base de datos, toda API pública pasa por el gateway, cada servicio es dueño de su propia base de datos. Una comprobación de conformance puede pasar sobre un modelo que ha derivado gravemente, y un modelo perfectamente exacto puede violar todas las reglas que tengas.

Quieres las dos cosas, y no deberías leer un número como si fuera el otro.

Architecture drift vs. erosión de arquitectura

Estos términos están relacionados pero son distintos:

El architecture drift es la divergencia entre documentación e implementación. El código puede estar perfectamente bien -- la documentación es lo que está mal.

La erosión de arquitectura es la degradación de la arquitectura en sí. El código viola principios arquitectónicos, acumula deuda técnica y se vuelve más difícil de mantener. La erosión es un problema de calidad de código. El drift es un problema de precisión de la documentación.

Perry y Wolf trazaron la línea en otro sitio en 1992: para ellos ambas eran propiedades del sistema y no de la documentación, con la erosión causada por violar la arquitectura y el drift causado por ser insensible a ella. El uso moderno es más laxo y más útil para un equipo que trabaja, pero si lees la literatura académica sobre erosión de arquitectura, cuenta con que los términos se sitúen de otra manera que aquí.

Suelen coexistir. Cuando la documentación deriva, los equipos pierden conciencia de la arquitectura prevista. Sin esa conciencia, hacen cambios que erosionan la arquitectura. El drift habilita la erosión.

Por eso la detección de drift importa más allá de la mera precisión de la documentación. Una documentación precisa sirve de referencia que previene la erosión. Cuando todo el mundo puede ver la arquitectura prevista, es más probable que la mantengan.

Medir y seguir el drift a lo largo del tiempo

Una sola puntuación de drift es útil. Una tendencia es poderosa.

Establecer una línea base

Ejecuta el primer cálculo antes de cambiar nada sobre cómo trabaja el equipo. Lo que devuelva es tu línea base, y un primer número bajo es información, no un veredicto. Una documentación que nadie ha tenido el encargo de mantener no ha fracasado; simplemente no se había medido.

Resiste el impulso de arreglar cosas antes de la primera ejecución. Quieres el número que describe la situación en la que realmente estás, no el que sale después de un fin de semana de limpieza.

Seguir la tendencia

Una puntuación aislada es un hecho sobre hoy. La tendencia es lo que te dice si algo de lo que cambiaste funcionó:

¿El drift mejora o empeora con el tiempo?
¿Un sprint o una release concretos provocaron una caída?
¿El umbral de CI está aguantando la línea, o lo va bajando todo el mundo?

Archyl guarda cada cálculo con su desglose completo, de modo que un informe histórico puede reabrirse y compararse elemento por elemento. Uses la herramienta que uses, conserva el historial. Una puntuación de drift que recalculas desde cero cada trimestre y luego tiras es otra vez una auditoría.

Fija un objetivo que puedas sostener de verdad

Elige el siguiente número en lugar del ideal. Si hoy es 58, el objetivo útil es 65 y la conversación útil trata de qué cinco elementos te llevan hasta ahí. Un equipo que acuerda llegar al 90 % para final de trimestre normalmente no acuerda nada.

El papel de la detección de drift en el desarrollo asistido por IA

Esta es la parte que ha cambiado más recientemente, y es la razón por la que Thoughtworks escribió la entrada citada antes: los agentes replican los patrones que encuentran, degradados incluidos, así que el drift que antes se acumulaba a la velocidad de los commits humanos ahora se acumula a la velocidad de los commits generados.

Los agentes de IA dependen cada vez más de la documentación de arquitectura como contexto. Mediante protocolos como MCP, los agentes pueden leer tu modelo C4, tus ADR y tus reglas de conformance antes de generar código. Esto los hace más efectivos -- generan código que encaja con tu arquitectura en lugar de adivinar.

Pero esto solo funciona si la documentación es precisa. Un agente que lee un modelo C4 obsoleto y genera código basándose en él producirá código que encaja con la arquitectura equivocada. El agente amplifica el drift en lugar de prevenirlo.

La detección de drift crea el bucle de feedback que mantiene honestos a los agentes de IA:

El agente lee la arquitectura vía MCP
El agente genera código que encaja con la arquitectura documentada
El código se mergea, cambiando potencialmente la arquitectura real
La detección de drift se ejecuta y captura cualquier divergencia
La puerta de CI falla si el drift supera el umbral
El equipo actualiza la documentación para reflejar la realidad
El agente lee la arquitectura actualizada -- el bucle se cierra

Sin el paso 4, el bucle está abierto. La documentación se vuelve cada vez más ficticia. Los agentes generan cada vez más código que encaja con una arquitectura de fantasía. La brecha se ensancha con cada commit.

La detección de drift es el mecanismo que cierra este bucle.

Empezar con la detección de drift

Si ya tienes un modelo en alguna parte

Mídelo antes de cambiar nada más. Es el primer movimiento más barato disponible y no te compromete a nada.

Si tu arquitectura ya vive en Structurizr DSL, LikeC4, IcePanel o un catálogo de Backstage, tráete ese modelo y calcula una puntuación contra él tal cual está. Estás midiendo la documentación que ya escribiste, en el estado en que la dejaste. Sin cambio de workflow, sin ningún hábito nuevo para el equipo, sin ninguna decisión de tooling todavía. El número es la entrada de esa decisión, no su resultado.

Dos salvedades honestas. Los importadores no son sin pérdidas: las vistas, los estilos y el layout no sobreviven, y el parser de Structurizr se salta los entornos y los nodos de despliegue, aunque los nombra con su número de línea en la lista de avisos, así que lee esa lista y el modelo importado antes de fiarte del denominador. Y la puntuación describe el modelo que llegó, no el archivo que exportaste.

Lo que vuelve es una lista por elemento. Una puntuación de 84 es un problema de mantenimiento que puedes planificar. Una puntuación de 41 significa que se han estado tomando decisiones contra un documento que describe otro sistema, y es mejor enterarse ahora que durante el próximo incidente.

Si no tienes documentación de arquitectura

Empieza con el descubrimiento por IA. Conecta un repositorio, deja que el descubrimiento proponga el modelo C4, y aprueba o rechaza lo que sugiere en lugar de dibujarlo. Una vez que hay un modelo, la detección de drift es lo que lo mantiene honesto.

Si ya estás siguiendo el drift

Métela en CI. Pon un umbral por debajo de tu puntuación actual. Configura la alerta de degradación. Haz del drift una métrica que el equipo vea cada semana, no un número que una persona calcula antes de una revisión.

Sea cual sea tu punto de partida

El drift se acumula como la deuda técnica: cuanto más lo dejes, más hay que reconciliar, y menos confía nadie en el documento mientras tanto. La diferencia es que puedes averiguar en qué punto estás hoy sin arreglar nada primero.

Tu documentación de arquitectura o refleja la realidad o no la refleja. La gracia de un drift score es que ya no tienes que adivinar cuál de las dos.

Para profundizar: cómo se calcula el drift score para el mecanismo, documentación de arquitectura viva para las prácticas que mantienen verdadero un modelo, y qué es el modelo C4 si empiezas desde cero. Definiciones: el architecture drift, la documentación viva y la detección de drift en el producto. El plan Developer es gratis y no pide tarjeta, si quieres ponerle un número a la documentación que ya tienes: archyl.com.

Detección de Architecture Drift: mantén tu código alineado con el diseño - Archyl Blog