Architecture drift é a distância entre o sistema que você documentou e o sistema que você realmente tem. Os conselhos habituais sobre isso (manter os docs junto do código, revisá-los na mesma pull request) são bons, e nenhum deles diz se funcionou. Este guia cobre o que é drift, as formas de detectá-lo e como colocar um número na distância que você já tem.

Detecção de Architecture Drift: Mantenha Seu Código Alinhado com o Design

Em algum lugar da sua organização, existe um diagrama de arquitetura que está errado. Talvez ele mostre um microservice que foi incorporado a outro há seis meses. Talvez liste Redis como camada de cache quando a equipe migrou para Memcached durante um incidente em produção. Talvez descreva uma arquitetura hexagonal limpa em um serviço que acumulou atalhos e gambiarras suficientes para parecer spaghetti.

Isso é architecture drift: a divergência gradual e silenciosa entre como seu sistema está documentado e como ele realmente funciona. Diferente de bugs, drift não dispara alertas. Diferente de regressões de performance, não aparece no monitoramento. Ele fica quieto até que alguém toma uma decisão baseada em documentação desatualizada -- e essa decisão se mostra errada.

Architecture drift é universal. Toda equipe experimenta. A questão não é se sua documentação vai divergir, mas quão rápido você vai detectar e o que vai fazer a respeito.

Conselhos sobre a segunda metade dessa questão não faltam. Mantenha os docs junto do código. Revise-os na mesma pull request. Torne-os parte da definition of done. São bons conselhos, a maior parte deles aparece mais abaixo nesta página, e todos compartilham um ponto cego: dizem o que fazer, não se funcionou. O que mais se aproxima de uma verificação nas recomendações comuns é um carimbo de última edição, que diz quando alguém tocou no arquivo, não se o arquivo é verdadeiro.

Detectar o drift é a metade que se pula. Este guia cobre o problema, as cinco famílias de método de detecção e o que cada uma consegue e não consegue enxergar. Dois artigos complementares aprofundam cada um em uma coisa: como um drift score é calculado e o que o número significa e as práticas que mantêm um modelo verdadeiro depois que você tem um.

O que é Architecture Drift?

Architecture drift ocorre quando a implementação real de um sistema de software diverge de sua arquitetura documentada ou pretendida. Perry e Wolf deram nome ao problema em Foundations for the Study of Software Architecture (ACM SIGSOFT Software Engineering Notes, 1992), onde separaram erosion (erosão), que vem de violar a arquitetura, de drift, que vem de ser insensível a ela. O uso cotidiano mudou desde então: hoje a maioria dos engenheiros diz "drift" para qualquer distância entre a documentação e o código, e é nesse sentido que este guia usa o termo. A distinção vale a pena ser mantida, e há uma seção sobre ela mais abaixo.

O drift se manifesta em todos os níveis da documentação arquitetural:

Drift Estrutural

A estrutura documentada não corresponde mais ao codebase:

Um serviço documentado como container independente foi absorvido em um monolito
Um componente foi renomeado mas o diagrama ainda mostra o nome antigo
Um novo serviço foi criado mas nunca adicionado ao modelo de arquitetura
Um banco de dados foi migrado de MySQL para PostgreSQL mas o diagrama de containers ainda diz MySQL

Drift Comportamental

O comportamento documentado não corresponde mais à realidade:

Uma chamada de API síncrona foi substituída por uma mensagem assíncrona, mas a relação ainda diz "REST/HTTP"
Um fluxo de dados foi alterado para passar por um API gateway, mas o diagrama mostra comunicação direta entre serviços
Uma etapa de autenticação foi adicionada e não está refletida no diagrama de contexto do sistema

Drift de Dependências

As dependências documentadas não correspondem mais às integrações reais:

Uma API de terceiros foi substituída por algo construído internamente
Uma nova dependência externa foi adicionada (provedor de pagamento, serviço de monitoramento) mas não documentada
Uma integração foi descontinuada mas ainda aparece no diagrama de contexto do sistema

Drift de Decisões

As decisões arquiteturais documentadas não estão mais sendo seguidas:

Um ADR diz "usar PostgreSQL para todo armazenamento persistente" mas uma equipe começou a usar MongoDB
As regras de conformance dizem "sem acesso direto ao banco de dados a partir do frontend" mas alguém adicionou uma integração Supabase no cliente
A arquitetura de deploy diz "região única" mas serviços foram implantados em várias regiões

Por que o Architecture Drift acontece

Entender as causas do drift é essencial para preveni-lo. O drift geralmente não é malicioso nem sequer negligente -- é uma consequência natural de como o software é desenvolvido.

Velocidade acima de documentação

Quando é preciso entregar uma feature até sexta, atualizar o diagrama de arquitetura é a primeira coisa a cair. A mudança de código é a entrega. A atualização da documentação é overhead. É um comportamento racional no curto prazo e devastador no longo.

Muitas mudanças pequenas

O drift raramente acontece em um momento dramático. Ele se acumula através de centenas de mudanças pequenas, cada uma pequena demais para justificar uma atualização de documentação:

Renomear um arquivo
Adicionar um pacote utilitário
Trocar uma dependência de biblioteca
Extrair uma função para um módulo separado

Nenhuma mudança isolada é significativa o suficiente para disparar uma atualização de documentação. Juntas, elas transformam a arquitetura.

Rotatividade da equipe

Quando engenheiros saem, levam o conhecimento implícito com eles. A nova equipe herda o codebase mas não a compreensão do porquê ele está estruturado daquele jeito. Elas fazem mudanças baseadas no que veem no código, não no que a documentação diz, ampliando o drift.

Falta de ciclos de feedback

Se ninguém verifica se a documentação corresponde à realidade, o drift é invisível. Sem um mecanismo de detecção, a única forma de descobrir o drift é durante um incidente, uma auditoria, ou quando um engenheiro novo aponta que o diagrama não bate com o código. A essa altura, o drift pode ser extenso.

Mudanças emergenciais

Incidentes em produção frequentemente exigem atalhos arquiteturais: uma conexão direta com o banco de dados em vez de passar pela camada de API, uma configuração hardcoded em vez de usar o config service, um cache temporário que se torna permanente. Essas mudanças driblam os processos normais de review e raramente são documentadas.

O custo do Architecture Drift

Drift não é apenas um problema estético. Ele tem custos concretos e mensuráveis.

Decisões ruins

Quando arquitetos tomam decisões baseadas em documentação desatualizada, essas decisões podem estar erradas. "Este serviço tem pouco tráfego, então podemos bancar uma dependência síncrona" -- só que a documentação está velha e o serviço na verdade lida com 10x a carga documentada.

Onboarding lento

Engenheiros novos se apoiam na documentação de arquitetura para construir seu modelo mental. Se a documentação está errada, eles constroem modelos mentais errados. Escrevem código que não se encaixa na arquitetura real. Fazem perguntas que revelam sua confusão, consumindo o tempo dos engenheiros seniores.

Resposta a incidentes

Durante um incidente em produção, diagramas de arquitetura deveriam ajudar as equipes a entender o raio de impacto e as dependências. Se esses diagramas estão errados, as equipes desperdiçam minutos preciosos rastreando as cadeias de dependência erradas ou deixando passar sistemas upstream críticos.

Falhas de compliance e auditoria

Em setores regulados, a documentação de arquitetura é frequentemente exigida para compliance (SOC 2, ISO 27001, HIPAA). Se auditores descobrem que a documentação não corresponde à realidade, isso é um achado -- potencialmente sério.

Confusão de agentes de IA

À medida que agentes de código com IA se tornam mais comuns, eles dependem cada vez mais da documentação de arquitetura como contexto. Um agente que lê um modelo C4 desatualizado vai gerar código que se encaixa na arquitetura documentada, não na real. Isso amplifica o drift em vez de corrigi-lo.

Como detectar o Architecture Drift

Há cinco abordagens de uso comum, e elas respondem a perguntas diferentes. A revisão manual pergunta se o diagrama ainda parece certo para as pessoas na sala. Fitness functions e análise estática perguntam se regras específicas estão sendo quebradas. A avaliação por LLM pergunta se o código se lê como o design que ele afirma implementar. O drift scoring pergunta quanto do modelo documentado ainda existe. Escolha pela pergunta que está te custando caro.

Revisão manual (abordagem tradicional)

A abordagem mais simples é a revisão manual periódica: reúna a equipe, percorra os diagramas de arquitetura e verifique se eles ainda correspondem à realidade.

Quando funciona: equipes pequenas, arquiteturas simples, cadência trimestral.

Quando falha: sistemas grandes, equipes que se movem rápido, ou quando as pessoas que conhecem melhor o código não têm tempo para reuniões de revisão. A revisão manual também sofre de viés de confirmação -- as pessoas tendem a ver o que esperam ver.

Architecture fitness functions

Fitness functions, popularizadas por Neal Ford e pelo livro "Building Evolutionary Architectures", são testes automatizados que validam propriedades arquiteturais:

// 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)
        }
    }
}

Fitness functions são poderosas para impor regras específicas, mas exigem esforço inicial para serem escritas e mantidas. Elas verificam restrições, não o modelo completo.

Ferramentas de análise estática

Ferramentas como ArchUnit (Java), Deptrac (PHP) e go-arch-lint (Go) analisam a estrutura do código e impõem regras de dependência:

// 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: []

Essas ferramentas são excelentes para impor arquitetura em camadas dentro de um único codebase. Elas não tratam do drift entre serviços nem validam que o modelo de arquitetura corresponde ao código.

Avaliação assistida por LLM

A Thoughtworks colocou a redução de architecture drift com LLMs no anel Assess do Technology Radar Vol. 34 (abril de 2026). Vale citar como eles formulam o problema, porque vem de outro lugar que não um fornecedor:

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.

Em português: o uso crescente de agentes de código com IA pode acelerar o drift em relação ao codebase e aos designs de arquitetura pretendidos. Sem controle, esse drift se agrava conforme agentes e humanos replicam os padrões existentes, incluindo os degradados, criando um ciclo de realimentação em que código ruim gera código pior.

A técnica que eles descrevem combina ferramentas de análise determinística (citam Spectral, ArchUnit e Spring Modulith) com avaliação por LLM, para pegar violações semânticas que um motor de regras não consegue expressar, e então usa o LLM para ajudar a corrigir o que foi encontrado. As equipes deles aplicaram isso a diretrizes de qualidade de API e à definição de zonas arquiteturais que orientam as mudanças geradas por agentes.

Duas das lições deles valem a pena seja qual for a ferramenta que você usar. Uma primeira varredura levanta mais violações do que qualquer um vai triar, então priorizar é o trabalho de verdade. E a correção de um agente precisa do seu próprio ciclo de verificação, porque "mudou o código" e "melhorou o sistema" são afirmações diferentes.

Assess é o anel da Thoughtworks que significa "vale a pena olhar, ainda não recomendamos". Trate assim. O que ele resolve é que o problema é real o bastante para uma grande consultoria colocá-lo no papel, o que é mais do que a maioria dos argumentos sobre drift consegue apontar.

Drift scoring automatizado

Esta é a abordagem que a Archyl adota. Em vez de verificar regras específicas, ela valida o modelo de arquitetura inteiro contra o codebase:

Cada sistema documentado corresponde a um repositório?
Cada container documentado corresponde a um diretório no codebase?
Cada elemento de código documentado referencia um arquivo que ainda existe?
Ambas as pontas de cada relação documentada continuam válidas?

O resultado é uma pontuação de 0 a 100 e um detalhamento por elemento do que bateu, do que está documentado mas sumiu, e do que existe no código mas nunca foi escrito em lugar nenhum. Onde as fitness functions verificam as restrições que você lembrou de escrever, isto verifica o modelo inteiro que você já tem.

As decisões de design principais na detecção de drift da Archyl:

Leve. Nenhuma chamada de IA e nenhum conteúdo de arquivo baixado. Uma única requisição recursiva da árvore ao seu provedor Git, depois correspondência de caminhos e nomes contra o modelo. O cálculo leva segundos.

Determinística. Mesmo codebase, mesmo modelo, mesma pontuação. Sem variabilidade por temperatura do LLM ou prompt engineering.

Barata. Rode a cada push sem preocupação com custo. Cem cálculos por dia é tranquilo.

Acionável. O detalhamento nomeia quais elementos divergiram, então você sabe o que corrigir.

O trade-off está no primeiro item. Verificar caminhos e nomes em vez de ler o código torna a pontuação rápida, gratuita e reprodutível, e significa que a verificação é estrutural. Ela enxerga um container cujo diretório sumiu e um elemento de código cujo arquivo foi apagado. Não enxerga a chamada REST que virou mensagem de fila enquanto os dois serviços mantiveram seus nomes. Isso é drift comportamental, o único tipo na taxonomia do topo deste guia que nenhuma verificação barata pega. Revisão manual e avaliação por LLM são o que você tem para isso.

Como o drift score é calculado, em detalhe cobre a fórmula, o que é excluído do denominador e por quê, e o resto dos limites.

Fechando o ciclo

Detecção sozinha não muda nada. Uma pontuação que alguém calcula uma vez e olha é uma auditoria, não um ciclo de feedback. Três mecanismos a transformam em um, mais uma distinção que vale acertar antes de ligar qualquer um deles. As práticas de workflow que ficam ao lado -- architecture as code, documentação na definition of done, adotar regras de conformance -- são o assunto de documentação de arquitetura viva.

Automatizar a detecção de drift na CI

O mecanismo com mais dentes é um gate de CI que falha quando o drift ultrapassa um limite, porque é o único que barra um 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'

Quando o build falha porque o drift score caiu, alguém precisa corrigir antes de mergear. A precisão da documentação se torna tão inegociável quanto os testes passarem.

Coloque o limite abaixo da sua pontuação atual, não no número que você gostaria de ter. Um gate que falha na primeira execução é desativado na primeira execução. Suba-o conforme a equipe constrói o hábito.

Configurar alertas de drift

A Archyl suporta alertas via webhook para eventos de drift:

drift.score_computed: dispara a cada cálculo de drift. Publique em um canal do Slack para dar visibilidade.
drift.score_degraded: dispara quando a pontuação cai 10+ pontos. Este é seu sistema de alerta antecipado.

Configure esses alertas para um canal que sua equipe acompanha. A consciência do problema é o primeiro passo para a ação.

Fazer reviews de arquitetura

Reviews de arquitetura mensais ou trimestrais servem a vários propósitos:

Validar que a arquitetura documentada ainda corresponde à realidade
Identificar o drift que as ferramentas automatizadas deixaram passar (o drift comportamental, por exemplo)
Discutir se os componentes que divergiram devem ser atualizados no código ou na documentação
Revisar e atualizar ADRs de decisões que talvez precisem ser reconsideradas

Não confunda drift com conformance

Os dois são executados juntos com frequência suficiente para valer a pena separá-los, porque são calculados de formas diferentes e falham por motivos diferentes.

A detecção de drift pergunta se o seu modelo corresponde à realidade. Ela compara a arquitetura documentada com o repositório e produz uma pontuação.

As regras de conformance perguntam se a realidade segue as suas regras: o container de frontend não deve depender do container de banco de dados, toda API pública passa pelo gateway, cada serviço é dono do próprio banco. Uma verificação de conformance pode passar em um modelo que divergiu feio, e um modelo perfeitamente exato pode violar todas as regras que você tem.

Você quer as duas coisas, e não deveria ler um número como se fosse o outro.

Architecture drift vs. erosão de arquitetura

Estes termos são relacionados mas distintos:

Architecture drift é a divergência entre documentação e implementação. O código pode estar perfeitamente bem -- a documentação é que está errada.

Erosão de arquitetura é a degradação da arquitetura em si. O código viola princípios arquiteturais, acumula dívida técnica e fica mais difícil de manter. Erosão é um problema de qualidade de código. Drift é um problema de precisão da documentação.

Perry e Wolf traçaram a linha em outro ponto em 1992: para eles, ambos eram propriedades do sistema e não da documentação, com a erosão causada por violar a arquitetura e o drift causado por ser insensível a ela. O uso moderno é mais frouxo e mais útil para uma equipe que trabalha, mas se você ler a literatura acadêmica sobre erosão de arquitetura, espere que os termos se posicionem de forma diferente da daqui.

Eles frequentemente coexistem. Quando a documentação diverge, as equipes perdem a consciência da arquitetura pretendida. Sem essa consciência, elas fazem mudanças que erodem a arquitetura. O drift habilita a erosão.

É por isso que a detecção de drift importa além da simples precisão da documentação. Documentação precisa serve como referência que previne a erosão. Quando todos conseguem ver a arquitetura pretendida, é mais provável que a mantenham.

Medindo e acompanhando o drift ao longo do tempo

Um drift score isolado é útil. Uma tendência é poderosa.

Estabelecer uma baseline

Rode o primeiro cálculo antes de mudar qualquer coisa em como a equipe trabalha. O que ele devolver é sua baseline, e um primeiro número baixo é informação, não veredito. Uma documentação que ninguém foi incumbido de manter não fracassou; ela apenas nunca foi medida.

Resista à vontade de arrumar as coisas antes da primeira execução. Você quer o número que descreve a situação em que você realmente está, não o que sai depois de um fim de semana de faxina.

Acompanhar a tendência

Uma pontuação isolada é um fato sobre hoje. A tendência é o que diz se alguma coisa que você mudou funcionou:

O drift está melhorando ou piorando ao longo do tempo?
Uma sprint ou release específica causou uma queda?
O limite da CI está segurando a linha, ou todo mundo está baixando ele?

A Archyl armazena cada cálculo com seu detalhamento completo, então um relatório histórico pode ser reaberto e comparado elemento por elemento. Seja qual for a ferramenta que você usar, guarde o histórico. Um drift score que você recalcula do zero a cada trimestre e depois joga fora é uma auditoria de novo.

Defina uma meta que você consiga sustentar

Escolha o próximo número em vez do ideal. Se hoje é 58, a meta útil é 65 e a conversa útil é sobre quais cinco elementos te levam até lá. Uma equipe que concorda em chegar a 90% até o fim do trimestre normalmente não concorda com nada.

O papel da detecção de drift no desenvolvimento assistido por IA

Esta é a parte que mudou mais recentemente, e é por isso que a Thoughtworks escreveu a entrada citada acima: agentes replicam os padrões que encontram, degradados inclusive, então o drift que antes se acumulava na velocidade dos commits humanos agora se acumula na velocidade dos gerados.

Agentes de IA dependem cada vez mais da documentação de arquitetura como contexto. Através de protocolos como MCP, agentes podem ler seu modelo C4, ADRs e regras de conformance antes de gerar código. Isso os torna mais eficazes -- eles geram código que se encaixa na sua arquitetura em vez de chutar.

Mas isso só funciona se a documentação for precisa. Um agente que lê um modelo C4 desatualizado e gera código a partir dele vai produzir código que se encaixa na arquitetura errada. O agente amplifica o drift em vez de preveni-lo.

A detecção de drift cria o ciclo de feedback que mantém os agentes de IA honestos:

O agente lê a arquitetura via MCP
O agente gera código que se encaixa na arquitetura documentada
O código é mergeado, potencialmente mudando a arquitetura real
A detecção de drift roda e pega qualquer divergência
O gate da CI falha se o drift ultrapassar o limite
A equipe atualiza a documentação para refletir a realidade
O agente lê a arquitetura atualizada -- o ciclo se fecha

Sem o passo 4, o ciclo fica aberto. A documentação vai ficando cada vez mais ficcional. Os agentes geram cada vez mais código que se encaixa em uma arquitetura de fantasia. A distância aumenta a cada commit.

A detecção de drift é o mecanismo que fecha esse ciclo.

Começando com detecção de drift

Se você já tem um modelo em algum lugar

Meça antes de mudar qualquer outra coisa. É o primeiro passo mais barato disponível e não te compromete com nada.

Se sua arquitetura já vive em Structurizr DSL, LikeC4, IcePanel ou em um catálogo Backstage, traga esse modelo e calcule uma pontuação contra ele do jeito que está. Você está medindo a documentação que já escreveu, no estado em que a deixou. Sem mudança de workflow, sem hábito novo para a equipe, sem decisão de tooling ainda. O número é a entrada dessa decisão, não o resultado dela.

Duas ressalvas honestas. Os importadores não são lossless: views, estilos e layout não sobrevivem, e o parser do Structurizr pula ambientes e nós de deploy, mas os nomeia com o número da linha na sua lista de avisos, então leia essa lista e o modelo importado antes de confiar no denominador. E a pontuação descreve o modelo que chegou, não o arquivo que você exportou.

O que volta é uma lista por elemento. Uma pontuação de 84 é um problema de manutenção que você pode agendar. Uma pontuação de 41 significa que decisões vêm sendo tomadas contra um documento que descreve outro sistema, e é melhor descobrir isso agora do que durante o próximo incidente.

Se você não tem documentação de arquitetura

Comece com a descoberta por IA. Conecte um repositório, deixe a descoberta propor o modelo C4, e aprove ou rejeite o que ela sugere em vez de desenhar. Uma vez que existe um modelo, a detecção de drift é o que o mantém honesto.

Se você já acompanha o drift

Coloque na CI. Defina um limite abaixo da sua pontuação atual. Configure o alerta de degradação. Faça do drift uma métrica que a equipe vê toda semana, não um número que uma pessoa calcula antes de uma review.

Independente de onde você comece

O drift se acumula como dívida técnica: quanto mais você deixa, mais há para reconciliar, e menos alguém confia no documento nesse meio-tempo. A diferença é que você pode descobrir onde está hoje sem corrigir nada antes.

Sua documentação de arquitetura ou reflete a realidade ou não reflete. A graça de um drift score é que você não precisa mais adivinhar qual das duas.

Para se aprofundar: como o drift score é calculado para o mecanismo, documentação de arquitetura viva para as práticas que mantêm um modelo verdadeiro, e o que é o modelo C4 se você está começando do zero. Definições: architecture drift, documentação viva e detecção de drift no produto. O plano Developer é gratuito e não pede cartão, se você quiser colocar um número na documentação que já tem: archyl.com.

Detecção de Architecture Drift: Mantenha Seu Código Alinhado com o Design - Archyl Blog