Architecture Drift Score: a sua documentacao esta dizendo a verdade?
Existe um segredo sujo na arquitetura de software: a maioria da documentacao esta errada.
Nao errada como "contem erros". Errada como "descreve um sistema que nao existe mais". O diagrama mostra um microservico que foi fundido com outro ha seis meses. O modelo C4 lista um cache Redis que foi substituido por Memcached durante um incidente de fim de semana. O diagrama de componentes referencia um PaymentGateway que foi renomeado para BillingService em um refactoring sobre o qual ninguem informou o arquiteto.
Nao e um problema de disciplina. E um problema estrutural. O codigo muda continuamente. A documentacao muda quando alguem lembra. A lacuna entre a realidade e a documentacao -- o que chamamos de deriva arquitetonica -- cresce silenciosamente ate que o diagrama na parede nao tenha nenhuma semelhanca com o sistema em producao.
Construimos o Drift Score para tornar essa lacuna visivel, mensuravel e acionavel.
Um unico numero: de 0 a 100
O Architecture Drift Score responde a uma pergunta: qual percentual da sua arquitetura documentada realmente existe na sua codebase?
Abra qualquer projeto no Archyl, clique no icone de batimento cardiaco no cabecalho e pressione "Compute Drift Score". Em poucos segundos, voce vera um numero entre 0 e 100:
- 90-100% -- Excelente. Sua documentacao corresponde fielmente a codebase.
- 70-89% -- Bom. Majoritariamente precisa, algumas lacunas a resolver.
- 50-69% -- Regular. Deriva significativa detectada. Hora de atualizar.
- Abaixo de 50% -- Sua documentacao e ficcao.
So isso. Sem relatorios longos para ler. Sem avaliacao subjetiva. Um numero que voce pode rastrear, analisar e impor.
O que e realmente verificado
A analise de deriva e leve por design -- uma unica chamada API ao seu provedor git, sem IA, sem conteudo de arquivo obtido. Ela valida sua arquitetura em cinco dimensoes:
Systems -- O nome do seu repositorio corresponde ao sistema documentado? Usamos a mesma convencao de nomenclatura PascalCase do pipeline de discovery IA, com correspondencia fuzzy para que EkoAuthz corresponda a um repositorio chamado authz.
Containers -- Os diretorios de primeiro nivel no seu repositorio correspondem aos containers documentados? frontend/ corresponde a FrontendWebApp. backend/ corresponde a BackendApiServer. Containers de infraestrutura (bancos de dados, filas, monitoramento) que nao possuem diretorios de codigo-fonte sao corretamente excluidos -- sao documentacao valida de servicos externos, nao deriva.
Components -- Os componentes sob cada container ainda sao validos? Se o diretorio do container pai existe, seus componentes sao presumidos validos. Se o diretorio do container desapareceu, todos os seus componentes sao sinalizados.
Code Elements -- Esta e a verificacao mais precisa. Cada elemento de codigo no seu modelo C4 tem um filePath. Verificamos se cada arquivo ainda existe no repositorio. Arquivo renomeado? Classe deletada? Modulo movido? O drift score detecta instantaneamente.
Relationships -- Uma relacao e valida se tanto o elemento de origem quanto o de destino passaram na validacao. Se qualquer um dos extremos derivou, a relacao e sinalizada.
O resultado e um detalhamento por elemento mostrando exatamente o que correspondeu, o que esta faltando e o que e novo -- nao um score opaco, mas um relatorio acionavel.
Por que a leveza importa
Escolhemos deliberadamente nao executar o pipeline completo de discovery IA para deteccao de deriva. Eis o motivo:
Velocidade. A analise IA leva minutos para repositorios grandes. O calculo do drift score leva segundos. Voce pode executa-lo a cada push sem desacelerar seu pipeline.
Determinismo. A IA pode produzir resultados diferentes na mesma codebase dependendo da temperatura do modelo, variacoes de prompts e limites de tokens. A existencia de um caminho de arquivo e binaria -- ou o arquivo esta la ou nao esta. Seu score e reproduzivel.
Custo. Nenhum token de IA consumido. Nenhum limite de taxa de API atingido. Execute cem vezes por dia se quiser.
Simplicidade. O algoritmo e auditavel. Verificar caminhos de arquivos, corresponder nomes de diretorios, validar relacoes. Sem caixa preta.
Acompanhe tendencias, nao apenas instantaneos
Um score unico e util. Uma tendencia e poderosa.
Cada calculo de deriva e armazenado com seu detalhamento completo. A aba Overview mostra um grafico de barras do seu score ao longo do tempo. Clique em qualquer barra para carregar aquele relatorio historico e ver exatamente o que mudou.
Isso transforma o drift scoring de uma auditoria pontual em uma metrica de saude continua. Voce pode ver:
- O refactoring da semana passada melhorou ou piorou a precisao da documentacao?
- A deriva esta piorando ao longo do tempo? (Spoiler: sem automacao, sempre piora.)
- Qual sprint introduziu mais mudancas nao documentadas?
Aplique na CI
Uma metrica que voce nao aplica e uma metrica que voce vai ignorar. Por isso construimos uma 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'
Defina threshold: '70' e a action falha se a precisao da sua documentacao arquitetonica cair abaixo de 70%. O resumo do job mostra uma tabela formatada com o detalhamento completo -- visivel diretamente nos checks do seu PR.
Voce tambem pode publicar o score como comentario no 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 desenvolvedor ve o impacto da deriva de suas mudancas antes do merge. A documentacao de arquitetura se torna um cidadao de primeira classe no seu pipeline CI -- ao lado de testes, linting e scans de seguranca.
MCP: agentes IA que conhecem sua precisao
Se voce usa Claude Code, Cursor ou qualquer agente IA compativel com MCP junto com o servidor MCP do Archyl, o drift scoring esta disponivel como ferramenta:
compute_drift_score({ projectId: "..." })
get_drift_score({ projectId: "..." })
get_drift_history({ projectId: "..." })
get_drift_details({ scoreId: "..." })
Isso significa que um agente IA pode verificar a precisao da documentacao antes de comecar a trabalhar. A ferramenta get_agent_context ja fornece o modelo C4 completo, os ADRs e as regras de conformidade. Agora ele tambem pode verificar o quao confiavel e essa documentacao.
Um agente que ve um drift score de 45% sabe que deve ser cauteloso com o contexto arquitetonico recebido. Um agente que ve 95% pode confiar com seguranca na estrutura documentada. Esta e a base para agentes IA autoconscientes que ajustam seu comportamento com base na qualidade da documentacao.
Alertas webhook: saiba quando a deriva acontece
Dois novos eventos webhook manteem voce informado sem precisar verificar dashboards:
drift.score_computed-- Dispara toda vez que um drift score termina de ser calculado. Envie para um canal Slack para visibilidade.drift.score_degraded-- Dispara quando o score cai 10 ou mais pontos em relacao ao calculo anterior. Este e seu sistema de alerta antecipado -- a arquitetura esta derivando rapidamente.
Configure estes eventos nas configuracoes de webhook do Archyl. Eles funcionam com Slack, Microsoft Teams, Discord e qualquer endpoint HTTP generico.
A API REST
Para equipes que desejam controle 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"}'
# Obter ultimo score
curl https://api.archyl.com/api/v1/drift/latest?projectId=...
# Obter historico de scores
curl https://api.archyl.com/api/v1/drift/history?projectId=...&limit=20
O calculo e assincrono -- o POST retorna imediatamente com um ID de score, e voce faz polling ate que status se torne completed. A GitHub Action lida com isso automaticamente.
O que isso significa para a era agentica
Estamos entrando em uma era em que agentes IA escrevem uma porcao significativa do codigo de producao. Esses agentes sao rapidos, capazes e cegos ao contexto. Eles nao sabem que o AuthService foi dividido em IdentityService e AccessControl no mes passado. Eles nao sabem que o diretorio frontend/ foi renomeado para web/.
O drift score cria um ciclo de feedback:
- O agente IA le o modelo C4 via MCP antes de escrever codigo.
- Mudancas no codigo acontecem (por humanos ou agentes).
- O drift score detecta a lacuna entre documentacao e realidade.
- O gate CI impede que a lacuna cresca alem de um limiar.
- O webhook alerta a equipe quando a deriva acelera.
- A equipe atualiza a documentacao (ou executa um discovery para atualiza-la automaticamente).
- O agente IA le o modelo atualizado. O ciclo se fecha.
Sem o passo 3, o ciclo fica aberto. A documentacao deriva. Os agentes confiam em contexto desatualizado. Decisoes ruins se acumulam.
O drift score fecha o ciclo.
Para comecar
- Abra qualquer projeto no Archyl
- Clique no icone de batimento cardiaco na barra de ferramentas do cabecalho
- Clique em "Compute Drift Score"
- Configure a GitHub Action para monitoramento continuo
- Configure um webhook Slack para alertas de
drift.score_degraded
Sua documentacao de arquitetura reflete a realidade ou nao. Agora voce tem um numero que diz qual das duas opcoes e a sua.