Descoberta de Arquitetura com IA: Como Funciona

No ano passado, herdei uma base de código sem nenhuma documentação. 200.000 linhas de código distribuídas em 15 serviços, escritas por uma equipe que já tinha seguido em frente. Minha tarefa era entender o sistema o suficiente para adicionar uma nova integração de pagamento. A empresa estimou que levaria de 2 a 3 semanas apenas para mapear a arquitetura.

Essa experiencia é a razão pela qual construí o recurso de descoberta com IA do Archyl. E agora, depois de meses trabalhando com modelos de linguagem de grande porte para analisar código, quero compartilhar o que realmente funciona, o que não funciona e por que a descoberta de arquitetura com IA é poderosa, mas não magica.

O Problema da Descoberta Manual

Antes de mergulhar na IA, vamos reconhecer por que precisamos disso.

Quando enfrentei aquela base de código sem documentação, meu processo de descoberta foi assim:

Semana 1: Fazer grep no código procurando palavras-chave. Encontrar os pontos de entrada principais. Desenhar algumas caixas em um quadro branco. Perceber que entendi errado os limites dos serviços. Apagar e redesenhar.

Semana 2: Entrevistar o único engenheiro que está na empresa tempo suficiente para lembrar de algo. Metade do que ele diz contradiz o que encontrei no código. Acontece que as coisas mudaram, mas ninguém atualizou o modelo mental dele.

Semana 3: Finalmente sentir que entendo o sistema o suficiente para fazer alterações. Criar documentação que juro manter atualizada. (Spoiler: não mantive.)

Esse processo e lento, propenso a erros e não escala. Cada novo membro da equipe passa pela mesma descoberta dolorosa. A documentação fica desatualizada em meses.

Como a Descoberta com IA Realmente Funciona

Quando você conecta um repositório ao Archyl e executa a descoberta, eis o que acontece por trás dos bastidores:

Etapa 1: Varredura do Repositório

Primeiro, construímos um mapa da sua base de código. Isso ainda não e IA — é uma travessia simples do sistema de arquivos:

• Listar todos os arquivos e diretórios
• Identificar arquivos de configuração (package.json, go.mod, docker-compose.yml)
• Encontrar pontos de entrada (funções main, arquivos index, rotas de API)
• Construir um grafo de dependências a partir dos imports

Isso nos dá o esqueleto. Sabemos quais arquivos existem e como eles se referenciam. Mas ainda não entendemos o que eles fazem.

Etapa 2: Analise em Blocos

Aqui é onde os LLMs entram, e também onde fica complicado.

Modelos de linguagem modernos têm limites de contexto. O GPT-4 suporta cerca de 128K tokens, o Claude consegue 200K. Parece muito, mas uma base de código de tamanho médio facilmente excede isso. Então não podemos simplesmente despejar toda a base de código em um prompt e perguntar "o que é isso?"

Em vez disso, dividimos a base de código em pedaços digeríveis:

1. Agrupar arquivos por diretório ou modulo
2. Enviar cada bloco ao LLM com contexto sobre sua localização no projeto
3. Perguntar ao modelo: Qual é a responsabilidade deste código? Quais padrões ele usa? Com quais sistemas externos ele interage?

As respostas voltam como dados estruturados — JSON descrevendo sistemas, containers e componentes com seus relacionamentos.

Etapa 3: Agregação e Reconciliação

Esta é a parte mais difícil, e onde gastei a maior parte do meu tempo de desenvolvimento.

Cada analise de bloco nos dá uma visão parcial. O bloco do serviço de usuário sabe sobre o banco de dados de usuários. O bloco de pagamento sabe sobre o Stripe. Mas nenhum dos dois conhece o quadro completo.

Precisamos reconciliar essas visões parciais:

• Mesclar entidades duplicadas ("UserDB" é o mesmo que "users_database"?)
• Inferir relacionamentos entre blocos (o serviço de pedidos chama o serviço de usuários, mas foram analisados separadamente)
• Resolver conflitos (um bloco diz que usamos PostgreSQL, outro diz MySQL — qual está certo?)

Essa reconciliação usa outra rodada de analise do LLM, além de heurísticas baseadas em padrões comuns. E imperfeita. As vezes a IA erra. Por isso a descoberta produz sugestoes que humanos revisam, não documentação final.

Etapa 4: Geração do Modelo C4

Finalmente, mapeamos as entidades descobertas para elementos do modelo C4:

• Sistemas externos (APIs de terceiros, bancos de dados que não gerenciamos)
• Containers (nossas unidades implantáveis)
• Componentes (módulos principais dentro dos containers)
• Relacionamentos (quem chama quem, que dados fluem para onde)

O resultado é um conjunto de rascunhos de diagramas C4 que capturam o entendimento da IA sobre sua arquitetura.

O Que a IA Acerta

Apos executar a descoberta em dezenas de bases de código durante o desenvolvimento, eis o que me impressionou:

Detecção da Stack Tecnológica

LLMs são notavelmente bons em identificar quais tecnologias um projeto usa. Eles reconhecem padrões de frameworks, idiomas de bibliotecas e formatos de arquivos de configuração. Quando o GPT vê uma anotação @Controller, ele sabe que você está usando Spring. Quando vê fiber.New(), sabe que você está usando Go Fiber.

Detecção de Limites de Serviços

Em arquiteturas de microsserviços, a IA identifica de forma confiável os limites dos serviços. Ela entende que o código em /services/user/ provavelmente é um serviço separado de /services/order/. Ela reconhece arquivos Docker Compose como indicadores de topologia de serviços.

Reconhecimento de Padrões Comuns

A IA viu milhões de bases de código em seus dados de treinamento. Ela reconhece padrões de repositório, estruturas MVC, arquiteturas orientadas a eventos e configurações de API gateway. Quando seu código segue padrões comuns, a IA os identifica rapidamente.

Descoberta de Integrações Externas

Cada constante de chave de API, URL de webhook ou importação de SDK é uma pista sobre integrações externas. A IA captura a maioria delas, construindo uma imagem dos serviços de terceiros dos quais seu sistema depende.

O Que a IA Erra

Aqui é onde tive que definir expectativas realistas:

Logica de Domínio Personalizada

A IA não entende o domínio do seu negocio. Ela pode identificar que você tem uma função processOrder, mas não sabe o que "processar um pedido" significa no contexto especifico do seu negocio. Ela pode identificar incorretamente o proposito de componentes específicos do domínio.

Arquiteturas Incomuns

Se sua arquitetura não segue padrões comuns, a IA tem dificuldades. Um sistema de plugins personalizado, uma estrutura de pastas não convencional ou um framework caseiro vai confundi-la. A IA espera que aplicações Rails pareçam aplicações Rails.

Dependências Ocultas

Nem todas as dependências são explicitas no código. Talvez seu serviço exija uma versão especifica do Redis que só existe em produção. Talvez haja um container sidecar que a IA nunca vê. Dependências de tempo de execução são frequentemente invisíveis para analise estática.

Caminhos de Código Obsoletos

A IA não sabe qual código é ativamente usado versus qual é legado que ninguém mexe há anos. Ela pode destacar de forma proeminente um serviço deprecado que ainda está na base de código mas não é mais implantado.

Fazendo a Descoberta com IA Funcionar Melhor

Através de tentativa e erro, encontrei maneiras de melhorar a precisão da descoberta:

Fornecer Contexto

Antes de executar a descoberta, conte a IA sobre seu sistema. "Esta é uma plataforma de e-commerce com processamento de pagamentos" da ao modelo um ponto de referencia. Sem contexto, ele está adivinhando no escuro.

Começar pela Estrutura

Se você tem alguma documentação existente — mesmo um README com um esboço grosseiro da arquitetura — forneça. A IA usa isso como referencia para guiar sua analise.

Revisar Incrementalmente

Não execute a descoberta em toda a sua base de código de uma vez. Comece com um serviço. Revise e corrija os resultados. Depois expanda para o próximo serviço. As correções que você faz informam analises futuras.

Confiar Mas Verificar

Trate as sugestões da IA como um ponto de partida, não como a resposta final. A IA pode ter 80% de precisão. Você precisa verificar os outros 20%. Clique nos links do código fonte, confirme que os relacionamentos fazem sentido e corrija erros.

Os Detalhes Técnicos

Para os curiosos sobre a implementação:

Estrategia de Divisão em Blocos

Usamos divisão semântica em vez de blocos de tamanho fixo. Um bloco é tipicamente um modulo, um serviço ou uma arvore de diretórios. Isso mantém o código relacionado junto, o que melhora a compreensão da IA.

Engenharia de Prompts

Os prompts evoluíram significativamente. As versões iniciais produziam descrições verbosas e narrativas. Os prompts atuais exigem saída estruturada com campos específicos. Usamos exemplos few-shot para demonstrar o formato esperado.

Concorrência

Bases de código grandes têm milhares de arquivos. Processar sequencialmente levaria uma eternidade. Analisamos blocos em paralelo, com limites de concorrência configuráveis para evitar limites de taxa da API.

Seleção de Modelo

Diferentes modelos têm diferentes pontos fortes. O GPT-4 produz analises mais precisas, mas custa mais. O Claude é melhor em seguir requisitos de saída estruturada. Suportamos ambos, além de modelos locais via Ollama para equipes que não podem enviar código para APIs externas.

O Futuro da Descoberta com IA

O que temos hoje é a versão 1. Aqui está o que estou trabalhando para alcançar:

Descoberta Continua

Em vez de uma analise única, monitorar sua base de código continuamente. Quando o código muda, atualizar os diagramas relevantes automaticamente. Detectar desvios arquiteturais antes que se tornem um problema.

Compreensão Mais Profunda

A analise atual é principalmente estrutural. Versões futuras poderiam entender comportamento: "Este endpoint valida a entrada, chama o serviço de pagamento e depois envia um e-mail de confirmação." Diagramas de sequencia gerados a partir do código.

Analise Entre Repositórios

A maioria das organizações tem múltiplos repositórios. A descoberta deveria entender como eles se conectam — quais serviços no repositório A chamam serviços no repositório B.

Pontuação de Confiança

Nem todas as descobertas são igualmente certas. Estamos adicionando pontuações de confiança para que você saiba quais sugestões examinar com mais cuidado.

Conclusão

A descoberta de arquitetura com IA não é magica. E uma ferramenta que acelera as partes tediosas de entender uma base de código enquanto ainda requer julgamento humano para as partes mais sutis.

Quando executo a descoberta naquela base de código de 200K linhas hoje, obtenho um rascunho de diagrama de arquitetura em 10 minutos em vez de 3 semanas. Não e perfeito — ainda preciso revisar e corrigir. Mas é um ponto de partida dramaticamente melhor do que um quadro branco em branco.

Se você está afogado em código sem documentação, experimente a descoberta com IA. Vá com expectativas realistas: ela não vai entender o domínio do seu negocio, pode perder padrões incomuns e definitivamente requer revisão humana. Mas vai te levar 80% do caminho em uma fração do tempo.

Quer saber mais? Confira nossa guia do modelo C4, o modelo que a descoberta com IA gera, ou leia sobre por que a documentação de arquitetura importa.