Architecture Drift Score: tu documentacion dice la verdad?
Hay un secreto a voces en la arquitectura de software: la mayoria de la documentacion esta equivocada.
No equivocada como "contiene errores". Equivocada como "describe un sistema que ya no existe". El diagrama muestra un microservicio que fue fusionado con otro hace seis meses. El modelo C4 lista un cache Redis que fue reemplazado por Memcached durante un incidente de fin de semana. El diagrama de componentes referencia un PaymentGateway que fue renombrado a BillingService en un refactoring del que nadie informo al arquitecto.
Esto no es un problema de disciplina. Es un problema estructural. El codigo cambia continuamente. La documentacion cambia cuando alguien se acuerda. La brecha entre la realidad y la documentacion -- lo que llamamos deriva arquitectonica -- crece silenciosamente hasta que el diagrama en la pared no tiene ninguna semejanza con el sistema en produccion.
Construimos el Drift Score para hacer esa brecha visible, medible y accionable.
Un unico numero: de 0 a 100
El Architecture Drift Score responde a una pregunta: que porcentaje de tu arquitectura documentada existe realmente en tu codebase?
Abre cualquier proyecto en Archyl, haz clic en el icono de latido en el encabezado y pulsa "Compute Drift Score". En unos segundos, veras un numero entre 0 y 100:
- 90-100% -- Excelente. Tu documentacion coincide estrechamente con la codebase.
- 70-89% -- Bien. Mayormente precisa, algunas brechas por resolver.
- 50-69% -- Regular. Deriva significativa detectada. Es hora de actualizar.
- Por debajo de 50% -- Tu documentacion es ficcion.
Eso es todo. Sin informes extensos que leer. Sin evaluacion subjetiva. Un numero que puedes rastrear, analizar y hacer cumplir.
Que se verifica realmente
El analisis de deriva es ligero por diseno: una unica llamada API a tu proveedor git, sin IA, sin contenido de archivos obtenido. Valida tu arquitectura en cinco dimensiones:
Systems -- El nombre de tu repositorio coincide con el sistema documentado? Usamos la misma convencion de nombres PascalCase que el pipeline de descubrimiento IA, con coincidencia difusa para que EkoAuthz coincida con un repositorio llamado authz.
Containers -- Los directorios de primer nivel en tu repositorio corresponden a los containers documentados? frontend/ coincide con FrontendWebApp. backend/ coincide con BackendApiServer. Los containers de infraestructura (bases de datos, colas, monitoreo) que no tienen directorios de codigo fuente se excluyen correctamente: son documentacion valida de servicios externos, no deriva.
Components -- Los componentes bajo cada container siguen siendo validos? Si el directorio del container padre existe, sus componentes se presumen validos. Si el directorio del container ha desaparecido, todos sus componentes se marcan.
Code Elements -- Esta es la verificacion mas precisa. Cada elemento de codigo en tu modelo C4 tiene un filePath. Verificamos que cada archivo siga existiendo en el repositorio. Archivo renombrado? Clase eliminada? Modulo movido? El drift score lo detecta al instante.
Relationships -- Una relacion es valida si tanto su elemento origen como destino pasaron la validacion. Si cualquiera de los extremos ha derivado, la relacion se marca.
El resultado es un desglose por elemento que muestra exactamente que coincidio, que falta y que es nuevo: no un puntaje opaco, sino un informe accionable.
Por que importa la ligereza
Elegimos deliberadamente no ejecutar el pipeline completo de descubrimiento IA para la deteccion de deriva. He aqui por que:
Velocidad. El analisis IA toma minutos para repositorios grandes. El calculo del drift score toma segundos. Puedes ejecutarlo en cada push sin ralentizar tu pipeline.
Determinismo. La IA puede producir resultados diferentes en la misma codebase dependiendo de la temperatura del modelo, variaciones de prompts y limites de tokens. La existencia de una ruta de archivo es binaria: o el archivo esta ahi o no. Tu puntaje es reproducible.
Costo. Sin tokens de IA consumidos. Sin limites de tasa de API alcanzados. Ejecutalo cien veces al dia si quieres.
Simplicidad. El algoritmo es auditable. Verificar rutas de archivos, hacer coincidir nombres de directorios, validar relaciones. Sin caja negra.
Rastrea tendencias, no solo instantaneas
Un puntaje unico es util. Una tendencia es poderosa.
Cada calculo de deriva se almacena con su desglose completo. La pestana Overview muestra un grafico de barras de tu puntaje a lo largo del tiempo. Haz clic en cualquier barra para cargar ese informe historico y ver exactamente que cambio.
Esto transforma el scoring de deriva de una auditoria puntual a una metrica de salud continua. Puedes ver:
- El refactoring de la semana pasada mejoro o degradio la precision de la documentacion?
- La deriva empeora con el tiempo? (Spoiler: sin automatizacion, siempre lo hace.)
- Que sprint introdujo la mayor cantidad de cambios no documentados?
Aplicalo en CI
Una metrica que no aplicas es una metrica que ignoraras. Por eso construimos una GitHub Action.
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'
Establece threshold: '70' y la action falla si la precision de tu documentacion arquitectonica cae por debajo del 70%. El resumen del job muestra una tabla formateada con el desglose completo, visible directamente en los checks de tu PR.
Tambien puedes publicar el puntaje como comentario en el PR:
- uses: archyl-com/actions/drift-score@v1
id: drift
with:
api-key: ${{ secrets.ARCHYL_API_KEY }}
organization-id: ${{ secrets.ARCHYL_ORG_ID }}
project-id: 'your-project-uuid'
- uses: actions/github-script@v7
if: github.event_name == 'pull_request'
with:
script: |
github.rest.issues.createComment({
issue_number: context.issue.number,
owner: context.repo.owner,
repo: context.repo.repo,
body: '## Architecture Drift: ' +
'${{ steps.drift.outputs.score }}%\n' +
'Matched: ${{ steps.drift.outputs.matched-count }}' +
' / ${{ steps.drift.outputs.total-elements }}'
})
Cada desarrollador ve el impacto de la deriva de sus cambios antes del merge. La documentacion de arquitectura se convierte en un ciudadano de primera clase en tu pipeline CI, junto con tests, linting y escaneos de seguridad.
MCP: agentes IA que conocen su precision
Si usas Claude Code, Cursor o cualquier agente IA compatible con MCP junto con el servidor MCP de Archyl, el scoring de deriva esta disponible como herramienta:
compute_drift_score({ projectId: "..." })
get_drift_score({ projectId: "..." })
get_drift_history({ projectId: "..." })
get_drift_details({ scoreId: "..." })
Esto significa que un agente IA puede verificar la precision de la documentacion antes de comenzar a trabajar. La herramienta get_agent_context ya proporciona el modelo C4 completo, los ADRs y las reglas de conformidad. Ahora tambien puede verificar que tan confiable es esa documentacion.
Un agente que ve un drift score de 45% sabe que debe ser cauteloso con el contexto arquitectonico recibido. Un agente que ve 95% puede confiar con seguridad en la estructura documentada. Esta es la base para agentes IA autoconscientes que ajustan su comportamiento segun la calidad de la documentacion.
Alertas webhook: enterate cuando ocurre la deriva
Dos nuevos eventos webhook te mantienen informado sin necesidad de revisar dashboards:
drift.score_computed-- Se dispara cada vez que un drift score termina de calcularse. Envialo a un canal de Slack para visibilidad.drift.score_degraded-- Se dispara cuando el puntaje cae 10 o mas puntos respecto al calculo anterior. Este es tu sistema de alerta temprana: la arquitectura esta derivando rapidamente.
Configura estos eventos en los ajustes de webhook de Archyl. Funcionan con Slack, Microsoft Teams, Discord y cualquier endpoint HTTP generico.
La API REST
Para equipos que desean control programatico completo:
# Iniciar calculo
curl -X POST https://api.archyl.com/api/v1/drift/compute \
-H "X-API-Key: $API_KEY" \
-H "X-Organization-ID: $ORG_ID" \
-H "Content-Type: application/json" \
-d '{"projectId": "your-project-uuid"}'
# Obtener ultimo puntaje
curl https://api.archyl.com/api/v1/drift/latest?projectId=...
# Obtener historial de puntajes
curl https://api.archyl.com/api/v1/drift/history?projectId=...&limit=20
El calculo es asincrono: el POST retorna inmediatamente con un ID de puntaje, y tu haces polling hasta que status sea completed. La GitHub Action maneja esto automaticamente.
Lo que esto significa para la era agentica
Estamos entrando en una era donde los agentes IA escriben una porcion significativa del codigo de produccion. Estos agentes son rapidos, capaces y ciegos al contexto. No saben que el AuthService fue dividido en IdentityService y AccessControl el mes pasado. No saben que el directorio frontend/ fue renombrado a web/.
El drift score crea un bucle de retroalimentacion:
- El agente IA lee el modelo C4 via MCP antes de escribir codigo.
- Los cambios de codigo ocurren (por humanos o agentes).
- El drift score detecta la brecha entre documentacion y realidad.
- La puerta CI impide que la brecha crezca mas alla de un umbral.
- El webhook alerta al equipo cuando la deriva se acelera.
- El equipo actualiza la documentacion (o ejecuta un descubrimiento para actualizarla automaticamente).
- El agente IA lee el modelo actualizado. El bucle se cierra.
Sin el paso 3, el bucle esta abierto. La documentacion deriva. Los agentes se apoyan en contexto obsoleto. Las malas decisiones se acumulan.
El drift score cierra el bucle.
Para comenzar
- Abre cualquier proyecto en Archyl
- Haz clic en el icono de latido en la barra de herramientas del encabezado
- Haz clic en "Compute Drift Score"
- Configura la GitHub Action para monitoreo continuo
- Configura un webhook de Slack para alertas de
drift.score_degraded
Tu documentacion de arquitectura refleja la realidad o no. Ahora tienes un numero que te dice cual de las dos es.