Documentação de arquitetura com IA: descoberta, drift e agentes

Existe uma tensão fundamental no coração da documentação de arquitetura de software. O código está vivo -- muda a cada commit, cada refatoração, cada hotfix. A documentação é estática -- muda quando alguém lembra de atualiza-la. A distancia entre os dois cresce silenciosamente ate que o diagrama no wiki descreve um sistema que não existe mais.

Isso não é um problema de disciplina. Ate as equipes mais dedicadas eventualmente ficam para trás. O esforço necessário para manter diagramas precisos manualmente cresce linearmente com a complexidade do sistema, enquanto a taxa de mudança do código permanece constante ou acelera.

A IA está mudando essa equação. Não substituindo o julgamento arquitetural humano, mas automatizando as partes da documentação em que os humanos são ruins: descoberta, sincronização e detecção de drift. O resultado é uma documentação de arquitetura que parte do código, permanece atualizada automaticamente e serve como uma camada de conhecimento tanto para humanos quanto para agentes de IA.

O Problema da Documentação Manual de Arquitetura

Antes de explorar como a IA ajuda, vamos ser específicos sobre o que está quebrado.

O Problema da Criação

Criar documentação de arquitetura do zero para um sistema existente é doloroso. Você lê código, rastreá dependências, entrevista membros da equipe e lentamente constrói um modelo mental que traduz em diagramas. Para um sistema de médio porte (20-30 serviços), isso leva semanas. Para um sistema grande (100+ serviços), leva meses.

Durante esse tempo, o sistema continua mudando. Quando sua documentação esta "pronta", partes dela já estão desatualizadas. Você está documentando um alvo em movimento.

O Problema da Manutenção

Mesmo que você crie uma documentação perfeita, mante-la precisa requer esforço continuo. Cada novo serviço, cada modulo renomeado, cada API descontinuada precisa ser refletida nos diagramas de arquitetura. Na pratica, isso significa:

  • Desenvolvedores precisam atualizar diagramas junto com mudanças no código
  • Alguém precisa revisar as atualizações dos diagramas quanto a precisão
  • Diagramas obsoletos precisam ser detectados e corrigidos

A maioria das equipes tenta resolver isso com processo: "atualize o diagrama de arquitetura quando você mudar a arquitetura." Isso funciona por cerca de três meses antes que a pressão de prazos e funcionalidades empurre as atualizações de documentação para o final da lista de prioridades.

O Problema da Descoberta

Quando um novo engenheiro entra na equipe, ele precisa entender a arquitetura antes de ser produtivo. Se a documentação existe mas está desatualizada, e pior do que não ter documentação porque ativamente engana. O novo engenheiro constrói um modelo mental baseado em diagramas errados e depois passa dias depurando suas suposições.

Sem documentação, a descoberta recai sobre conhecimento tribal: perguntar ao engenheiro que está há mais tempo. Isso não escala, cria gargalos e falha completamente quando pessoas-chave saem.

O Problema da Consistência

Em organizações com múltiplas equipes, cada equipe documenta sua arquitetura de forma diferente. O Time A usa Visio. O Time B usa Miro. O Time C tem um README com arte ASCII. O Time D não documenta nada. Não há visão unificada da arquitetura da organização, nenhuma notação consistente e nenhuma forma de entender dependências entre equipes.

Como a IA Muda a Equação

A IA aborda cada um desses problemas, não eliminando o envolvimento humano, mas automatizando as partes tediosas e propensas a erros e amplificando o julgamento humano.

Descoberta de Arquitetura com IA

A aplicação mais imediata da IA na documentação de arquitetura é a descoberta automatizada. Em vez de ler código manualmente e construir diagramas, você aponta um sistema de IA para seu codebase e ele gera um rascunho do modelo de arquitetura.

Veja como isso funciona na pratica com o Archyl:

  1. Conexão do repositório. Você conecta seu repositório Git (GitHub, GitLab, Bitbucket ou Azure DevOps).

  2. Varredura do código. O sistema percorre seu codebase, identificando estruturas de arquivos, arquivos de configuração, pontos de entrada e grafos de dependência.

  3. Analise com IA. Large language models analisam seu código em partes, identificando:

    • Pelo que cada modulo ou serviço é responsável
    • Quais tecnologias e frameworks estão em uso
    • Com quais sistemas externos seu código se integra
    • Como os componentes se comunicam entre si

  4. Geração do modelo C4. A IA mapeia suas descobertas para elementos do modelo C4: systems, containers, components, code elements e relationships.

  5. Revisão humana. Você revisa o modelo gerado, aceita elementos precisos, corrige erros e adiciona contexto que a IA não conseguiu inferir.

O resultado é um modelo de arquitetura C4 criado em minutos em vez de semanas. Não e perfeito -- a IA não entende seu domínio de negocio ou contexto organizacional. Mas é um ponto de partida dramaticamente melhor do que uma tela em branco.

O Que a IA Acerta

A IA se destaca nos aspectos estruturais da documentação de arquitetura:

Detecção de tecnologia. LLMs reconhecem padrões de frameworks, idiomas de bibliotecas e formatos de configuração em dezenas de linguagens e ecossistemas. Um arquivo go.mod com github.com/gofiber/fiber identifica imediatamente um serviço Go usando o framework Fiber. Um package.json com next identifica uma aplicação Next.js.

Detecção de limites de serviço. Em arquiteturas de microservices, a IA identifica de forma confiável os limites de serviço a partir da estrutura de diretórios, configurações Docker e manifestos de deploy. Um docker-compose.yml com cinco serviços dá a IA uma topologia clara para trabalhar.

Mapeamento de dependências. Instruções de import, bibliotecas de cliente de API e arquivos de configuração revelam dependências entre serviços e em sistemas externos. Cada import de SDK, cada URL base de API, cada connection string é uma pista.

Reconhecimento de padrões. A IA foi treinada em milhões de codebases. Ela reconhece estruturas MVC, arquitetura hexagonal, padrões event-driven e dezenas de outros padrões arquiteturais. Quando seu código segue convenções estabelecidas, a IA os identifica rapidamente.

O Que a IA Erra

Ser honesto sobre limitações é importante para definir expectativas:

Domínio de negocio. A IA pode dizer que processOrder() existe, mas não pode dizer o que "processar um pedido" significa no seu contexto de negocio especifico. Nomenclatura especifica do domínio, workflows customizados e regras de negocio requerem interpretação humana.

Arquiteturas não convencionais. Se seu sistema usa um framework de plugins customizado, um sistema de build próprio ou uma estrutura de projeto incomum, a IA pode ter dificuldades. Ela espera que apps React pareçam apps React e serviços Go pareçam serviços Go.

Dependências de runtime. Analise estática de código não consegue detectar dependências que existem apenas em tempo de execução: sidecar containers, configurações de service mesh, integrações especificas de ambiente ou infraestrutura que não está representada no código.

Intenção. A IA pode descrever o que o código faz, mas não por que foi escrito daquela forma. As decisões arquiteturais, trade-offs e restrições que moldaram o sistema não são visíveis no código em si. E por isso que ADRs (Architecture Decision Records) continuam essenciais -- a IA descobre estrutura, mas humanos documentam intenção.

Detecção de Drift: Mantendo a Documentação Honesta

A descoberta resolve o problema da criação. A detecção de drift resolve o problema da manutenção.

Architecture drift é a diferença entre o que sua documentação diz e o que seu código realmente faz. E o serviço renomeado que ainda está rotulado com seu nome antigo no diagrama. O componente descontinuado que ainda aparece como ativo. O novo microservice que nunca foi adicionado ao modelo de arquitetura.

Como Funciona a Detecção Automatizada de Drift

A detecção de drift do Archyl adota uma abordagem leve. Ela não re-executa o pipeline completo de descoberta com IA (que seria lento e caro). Em vez disso, realiza validações direcionadas:

  • Systems: O nome do sistema documentado corresponde ao nome do repositório?
  • Containers: Os containers documentados correspondem a diretórios reais no codebase?
  • Components: Os componentes documentados ainda são validos dado a existência de seu container pai?
  • Code elements: O caminho de arquivo de cada code element documentado ainda existe no repositório?
  • Relationships: Ambos os endpoints de cada relationship documentado ainda são validos?

O resultado é um drift score entre 0 e 100, representando a porcentagem da sua arquitetura documentada que ainda corresponde a realidade. Uma pontuação de 95% significa que sua documentação é altamente precisa. Uma pontuação de 50% significa que metade da sua documentação e ficção.

Tornando o Drift Acionável

Uma pontuação sozinha não é suficiente. O Archyl fornece um detalhamento mostrando exatamente o que divergiu:

  • Quais containers estão documentados mas ausentes do codebase
  • Quais code elements referenciam arquivos que não existem mais
  • Quais relationships conectam-se a elementos que divergiram
  • Quais novos elementos existem no codebase mas não estão documentados

Esse detalhamento transforma uma sensação vaga de "nossa documentação provavelmente está desatualizada" em uma lista especifica e acionável de coisas a corrigir.

Drift no CI/CD

A aplicação mais poderosa da detecção de drift e na integração continua. O Archyl fornece uma GitHub Action que calcula o drift score a 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'

Defina um limite, e o build falha se a precisão da documentação cair abaixo dele. Isso trata a documentação de arquitetura como testes: uma barreira de qualidade que previne degradação.

Equipes que adotam essa abordagem relatam uma mudança fundamental em como pensam sobre documentação. Ela deixa de ser um pensamento posterior e se torna uma preocupação de primeira classe, verificada a cada commit.

Além do drift: regras de conformidade e uma nota de maturidade

O drift diz se a documentação ainda descreve o código. Ele não diz se o código ainda segue as decisões que a equipe tomou, nem se as práticas em torno da arquitetura estão saudáveis. Mais duas verificações cobrem isso.

Regras de conformidade transformam decisões em verificações

Uma regra de conformidade é uma restrição arquitetural escrita de forma que uma máquina consiga verificá-la: "o frontend não deve falar diretamente com o banco de dados", "handlers não devem importar a camada de repositório", "os tópicos de eventos seguem nossa convenção de nomes". O Archyl avalia vários tipos de regra (fronteiras entre camadas, restrições de dependência, nomenclatura, tecnologias permitidas, padrões de código obrigatórios e proibidos, conformidade com contratos de API e canais de eventos) nos arquivos alterados em um pull request, e publica as violações como comentário nele. O catálogo traz 169 regras prontas para 24 tecnologias, e você pode escrever as suas.

O hábito útil é combinar regras com ADRs. Quando um ADR diz que chamadas síncronas entre serviços devem dar lugar a eventos, essa decisão pode virar uma regra, e o próximo pull request que adicionar uma chamada direta é sinalizado na revisão, em vez de ser descoberto na próxima reunião de arquitetura. O ADR registra o porquê; a regra verifica se ele continua valendo.

Isso importa mais à medida que o sistema cresce. Com cinquenta serviços e algumas dezenas de restrições, nenhum revisor guarda todas as regras na cabeça, e as violações sutis são as que escapam. Uma verificação de regras executa cada regra ativa contra cada mudança.

Uma nota de maturidade com quatro sinais

Drift, insights, conformidade e métricas DORA respondem cada um a uma pergunta. O score de maturidade os combina em uma nota em letra para um projeto, um sistema ou um único container: A a partir de 90, B a partir de 80, C a partir de 70, D a partir de 60, F abaixo disso. Por padrão, o drift pesa 40%, os insights 30%, a conformidade 20% e o DORA 10%. Desative uma dimensão e o peso dela é distribuído entre as outras, então uma equipe que não acompanha releases não é penalizada por isso.

A nota vale pelo detalhamento, não pela letra. Um projeto pode ter um modelo preciso e ADRs em dia enquanto entrega uma vez por mês com uma alta taxa de falha de mudanças. Outro pode fazer deploy dez vezes por dia ignorando todas as regras que definiu. Cada métrica isolada esconde um desses casos; as quatro dimensões lado a lado mostram os dois, e a tendência entre os cálculos mostra se as coisas estão melhorando. O post sobre o score de maturidade cobre o painel de detalhes e a visão da organização.

A Revolução MCP: Agentes de IA que Entendem Arquitetura

O Model Context Protocol (MCP) é um padrão aberto que permite que agentes de IA interajam com ferramentas e fontes de dados externas. O servidor MCP do Archyl expõe todo o seu modelo de arquitetura -- diagramas C4, ADRs, regras de conformidade, drift scores -- para qualquer agente de IA compatível com MCP.

Isso cria um novo paradigma: agentes de IA que possuem consciência arquitetural.

Como Funciona

Quando você usa o Claude Code, Cursor ou outro assistente de codificação compatível com MCP com o servidor MCP do Archyl conectado:

  1. O agente pode chamar get_agent_context para receber o modelo C4 completo, ADRs e regras de conformidade de um projeto.
  2. Antes de escrever código, o agente entende a arquitetura documentada: quais serviços existem, como se comunicam, quais tecnologias estão em uso, quais decisões foram tomadas.
  3. O agente pode verificar get_drift_score para avaliar quão confiável é a documentação.
  4. O agente pode ler ADRs específicos para entender por que certas escolhas arquiteturais foram feitas.

Por Que Isso Importa

Sem contexto arquitetural, agentes de codificação com IA são poderosos mas cegos. Eles podem escrever código excelente que viola seus princípios arquiteturais, introduz dependências indesejadas ou duplica funcionalidade que já existe em outro serviço.

Com MCP, o agente sabe:

  • "Este sistema usa PostgreSQL, não MongoDB -- devo gerar queries SQL, não queries MongoDB."
  • "A comunicação entre serviços usa eventos Kafka, não chamadas HTTP -- devo publicar um evento, não fazer uma requisição REST."
  • "A equipe decidiu contra GraphQL (ADR-0019) -- não devo sugerir uma implementação GraphQL."
  • "O drift score da arquitetura e 45% -- devo ter cautela ao confiar na estrutura documentada."

Isso transforma agentes de IA de geradores de código em colaboradores conscientes da arquitetura.

Regras de Conformidade

As regras de conformidade descritas acima também podem ser lidas via MCP, então um agente pode verificar a própria mudança antes que um revisor humano a veja. É uma governança que acompanha o ritmo do desenvolvimento assistido por IA em vez de ficar para trás.

Impacto no Mundo Real

Antes da Documentação com IA

Um cenário tipico sem assistência de IA:

  • Novo engenheiro entra na equipe
  • Passa 2-3 semanas lendo código, fazendo perguntas e construindo um modelo mental
  • Cria anotações pessoais das quais ninguém mais se beneficia
  • Diagramas de arquitetura foram atualizados pela ultima vez há 8 meses e estão 40% errados
  • Ninguém sabe quais ADRs ainda são relevantes
  • Toda discussão arquitetural começa do zero porque o contexto foi perdido

Depois da Documentação com IA

O mesmo cenário com documentação alimentada por IA:

  • Novo engenheiro abre o Archyl e vê o modelo C4 atual (drift score: 92%)
  • Navega do system context para containers e components
  • Clica em serviços complexos para ler ADRs vinculados explicando decisoes-chave
  • Usa o chat de arquitetura para fazer perguntas: "Como o serviço de pedidos se comunica com o serviço de pagamentos?"
  • Começa a contribuir com código em dias, não semanas
  • Agentes de IA escrevendo código respeitam a arquitetura e decisões documentadas

A diferença não e sutil. E a diferença entre conhecimento tribal e conhecimento institucional. Entre documentação que é um fardo e documentação que é um ativo.

Para onde vai a documentação de arquitetura com IA

Ainda estamos no inicio. Veja para onde a documentação de arquitetura com IA está indo:

Descoberta Continua

A descoberta atual é uma operação pontual: você a executa, revisa os resultados e segue em frente. A descoberta futura sera continua -- monitorando seu codebase para mudanças e sugerindo atualizações no modelo de arquitetura em tempo real. Fez merge de um PR que adiciona um novo serviço? O sistema detecta e propõe adiciona-lo ao modelo C4.

Analise Comportamental

A analise de IA atual e estrutural: ela entende o que existe no código. A analise futura entendera comportamento: como componentes interagem em tempo de execução, quais dados fluem pelo sistema, como erros se propagam. Isso possibilita diagramas dinâmicos gerados a partir do trafego de produção, não apenas analise estática.

Inteligencia Cross-Repository

A maioria das organizações tem arquiteturas que abrangem múltiplos repositórios. A descoberta futura com IA entendera dependências cross-repo: este serviço no repo A chama aquele serviço no repo B, que escreve neste banco de dados gerenciado no repo C. Um modelo de arquitetura unificado em toda a organização.

Documentação Auto-Reparavel

O objetivo final: documentação que se corrige sozinha. Quando drift é detectado, a IA gera a atualização, cria um pull request com o modelo corrigido e solicita aprovação humana. O papel do humano muda de criar documentação para revisar atualizações propostas pela IA -- um esforço muito mais leve.

Geração de Código Consciente da Arquitetura

A medida que agentes de codificação com IA se tornam mais capazes, a consciência arquitetural se torna critica. Agentes que entendem sua arquitetura podem:

  • Gerar código que segue padrões estabelecidos
  • Sugerir refatorações que se alinham com objetivos arquiteturais
  • Alertar quando mudanças propostas aumentariam o drift
  • Atualizar automaticamente modelos de arquitetura quando o código muda

Começando

Você não precisa adotar tudo de uma vez. Aqui está uma progressão pratica:

Fase 1: Descoberta (Dia 1)

Conecte seu repositório ao Archyl e execute a descoberta com IA. Revise o modelo C4 gerado. Corrija erros óbvios. Você agora tem um modelo de arquitetura base que provavelmente e 70-80% preciso.

Fase 2: Enriquecimento (Semana 1)

Adicione o contexto que a IA não consegue descobrir: ADRs para decisoes-chave, documentação para workflows importantes, regras de conformidade para restrições arquiteturais. Vincule ADRs aos elementos C4 que eles afetam.

Fase 3: Detecção de Drift (Semana 2)

Configure a GitHub Action de drift score. Estabeleça uma pontuação base e defina um limite. Comece a monitorar o drift a cada push.

Fase 4: Integração MCP (Semana 3)

Conecte o servidor MCP do Archyl as suas ferramentas de codificação com IA. De aos seus agentes contexto arquitetural. Observe-os gerar código que respeita sua arquitetura.

Fase 5: Governança (Continuo)

Defina regras de conformidade. Monitore tendencias de drift. Revise e atualize ADRs trimestralmente. A documentação de arquitetura se torna um ativo vivo e mantido -- não um projeto único.

O futuro da documentação de arquitetura não e sobre escrever diagramas melhores. E sobre construir sistemas onde a documentação se cria sozinha, se mantém sozinha e serve tanto humanos quanto agentes de IA como uma fonte compartilhada de verdade arquitetural.

Comece a construir documentação de arquitetura com IA hoje. Experimente o Archyl gratuitamente -- conecte um repositório e veja sua arquitetura descoberta em minutos. Saiba mais: Descoberta com IA: Como Funciona | Architecture Drift Score | Servidor MCP para documentação de arquitetura.