Descoberta de Arquitetura com IA: Como Funciona
No ano passado, herdei uma base de codigo sem nenhuma documentacao. 200.000 linhas de codigo distribuidas em 15 servicos, escritas por uma equipe que ja tinha seguido em frente. Minha tarefa era entender o sistema o suficiente para adicionar uma nova integracao de pagamento. A empresa estimou que levaria de 2 a 3 semanas apenas para mapear a arquitetura.
Essa experiencia e a razao pela qual construi o recurso de descoberta com IA do Archyl. E agora, depois de meses trabalhando com modelos de linguagem de grande porte para analisar codigo, quero compartilhar o que realmente funciona, o que nao funciona e por que a descoberta de arquitetura com IA e poderosa, mas nao magica.
O Problema da Descoberta Manual
Antes de mergulhar na IA, vamos reconhecer por que precisamos disso.
Quando enfrentei aquela base de codigo sem documentacao, meu processo de descoberta foi assim:
Semana 1: Fazer grep no codigo procurando palavras-chave. Encontrar os pontos de entrada principais. Desenhar algumas caixas em um quadro branco. Perceber que entendi errado os limites dos servicos. Apagar e redesenhar.
Semana 2: Entrevistar o unico engenheiro que esta na empresa tempo suficiente para lembrar de algo. Metade do que ele diz contradiz o que encontrei no codigo. Acontece que as coisas mudaram, mas ninguem atualizou o modelo mental dele.
Semana 3: Finalmente sentir que entendo o sistema o suficiente para fazer alteracoes. Criar documentacao que juro manter atualizada. (Spoiler: nao mantive.)
Esse processo e lento, propenso a erros e nao escala. Cada novo membro da equipe passa pela mesma descoberta dolorosa. A documentacao fica desatualizada em meses.
Como a Descoberta com IA Realmente Funciona
Quando voce conecta um repositorio ao Archyl e executa a descoberta, eis o que acontece por tras dos bastidores:
Etapa 1: Varredura do Repositorio
Primeiro, construimos um mapa da sua base de codigo. Isso ainda nao e IA — e uma travessia simples do sistema de arquivos:
- Listar todos os arquivos e diretorios
- Identificar arquivos de configuracao (package.json, go.mod, docker-compose.yml)
- Encontrar pontos de entrada (funcoes main, arquivos index, rotas de API)
- Construir um grafo de dependencias a partir dos imports
Isso nos da o esqueleto. Sabemos quais arquivos existem e como eles se referenciam. Mas ainda nao entendemos o que eles fazem.
Etapa 2: Analise em Blocos
Aqui e onde os LLMs entram, e tambem onde fica complicado.
Modelos de linguagem modernos tem limites de contexto. O GPT-4 suporta cerca de 128K tokens, o Claude consegue 200K. Parece muito, mas uma base de codigo de tamanho medio facilmente excede isso. Entao nao podemos simplesmente despejar toda a base de codigo em um prompt e perguntar "o que e isso?"
Em vez disso, dividimos a base de codigo em pedacos digeriveis:
- Agrupar arquivos por diretorio ou modulo
- Enviar cada bloco ao LLM com contexto sobre sua localizacao no projeto
- Perguntar ao modelo: Qual e a responsabilidade deste codigo? Quais padroes 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: Agregacao e Reconciliacao
Esta e a parte mais dificil, e onde gastei a maior parte do meu tempo de desenvolvimento.
Cada analise de bloco nos da uma visao parcial. O bloco do servico de usuario sabe sobre o banco de dados de usuarios. O bloco de pagamento sabe sobre o Stripe. Mas nenhum dos dois conhece o quadro completo.
Precisamos reconciliar essas visoes parciais:
- Mesclar entidades duplicadas ("UserDB" e o mesmo que "users_database"?)
- Inferir relacionamentos entre blocos (o servico de pedidos chama o servico de usuarios, mas foram analisados separadamente)
- Resolver conflitos (um bloco diz que usamos PostgreSQL, outro diz MySQL — qual esta certo?)
Essa reconciliacao usa outra rodada de analise do LLM, alem de heuristicas baseadas em padroes comuns. E imperfeita. As vezes a IA erra. Por isso a descoberta produz sugestoes que humanos revisam, nao documentacao final.
Etapa 4: Geracao do Modelo C4
Finalmente, mapeamos as entidades descobertas para elementos do modelo C4:
- Sistemas externos (APIs de terceiros, bancos de dados que nao gerenciamos)
- Containers (nossas unidades implantaveis)
- Componentes (modulos principais dentro dos containers)
- Relacionamentos (quem chama quem, que dados fluem para onde)
O resultado e 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 codigo durante o desenvolvimento, eis o que me impressionou:
Deteccao da Stack Tecnologica
LLMs sao notavelmente bons em identificar quais tecnologias um projeto usa. Eles reconhecem padroes de frameworks, idiomas de bibliotecas e formatos de arquivos de configuracao. Quando o GPT ve uma anotacao @Controller, ele sabe que voce esta usando Spring. Quando ve fiber.New(), sabe que voce esta usando Go Fiber.
Deteccao de Limites de Servicos
Em arquiteturas de microsservicos, a IA identifica de forma confiavel os limites dos servicos. Ela entende que o codigo em /services/user/ provavelmente e um servico separado de /services/order/. Ela reconhece arquivos Docker Compose como indicadores de topologia de servicos.
Reconhecimento de Padroes Comuns
A IA viu milhoes de bases de codigo em seus dados de treinamento. Ela reconhece padroes de repositorio, estruturas MVC, arquiteturas orientadas a eventos e configuracoes de API gateway. Quando seu codigo segue padroes comuns, a IA os identifica rapidamente.
Descoberta de Integracoes Externas
Cada constante de chave de API, URL de webhook ou importacao de SDK e uma pista sobre integracoes externas. A IA captura a maioria delas, construindo uma imagem dos servicos de terceiros dos quais seu sistema depende.
O Que a IA Erra
Aqui e onde tive que definir expectativas realistas:
Logica de Dominio Personalizada
A IA nao entende o dominio do seu negocio. Ela pode identificar que voce tem uma funcao processOrder, mas nao sabe o que "processar um pedido" significa no contexto especifico do seu negocio. Ela pode identificar incorretamente o proposito de componentes especificos do dominio.
Arquiteturas Incomuns
Se sua arquitetura nao segue padroes comuns, a IA tem dificuldades. Um sistema de plugins personalizado, uma estrutura de pastas nao convencional ou um framework caseiro vai confundi-la. A IA espera que aplicacoes Rails parecam aplicacoes Rails.
Dependencias Ocultas
Nem todas as dependencias sao explicitas no codigo. Talvez seu servico exija uma versao especifica do Redis que so existe em producao. Talvez haja um container sidecar que a IA nunca ve. Dependencias de tempo de execucao sao frequentemente invisiveis para analise estatica.
Caminhos de Codigo Obsoletos
A IA nao sabe qual codigo e ativamente usado versus qual e legado que ninguem mexe ha anos. Ela pode destacar de forma proeminente um servico deprecado que ainda esta na base de codigo mas nao e mais implantado.
Fazendo a Descoberta com IA Funcionar Melhor
Atraves de tentativa e erro, encontrei maneiras de melhorar a precisao da descoberta:
Fornecer Contexto
Antes de executar a descoberta, conte a IA sobre seu sistema. "Esta e uma plataforma de e-commerce com processamento de pagamentos" da ao modelo um ponto de referencia. Sem contexto, ele esta adivinhando no escuro.
Comecar pela Estrutura
Se voce tem alguma documentacao existente — mesmo um README com um esboco grosseiro da arquitetura — forneca. A IA usa isso como referencia para guiar sua analise.
Revisar Incrementalmente
Nao execute a descoberta em toda a sua base de codigo de uma vez. Comece com um servico. Revise e corrija os resultados. Depois expanda para o proximo servico. As correcoes que voce faz informam analises futuras.
Confiar Mas Verificar
Trate as sugestoes da IA como um ponto de partida, nao como a resposta final. A IA pode ter 80% de precisao. Voce precisa verificar os outros 20%. Clique nos links do codigo fonte, confirme que os relacionamentos fazem sentido e corrija erros.
Os Detalhes Tecnicos
Para os curiosos sobre a implementacao:
Estrategia de Divisao em Blocos
Usamos divisao semantica em vez de blocos de tamanho fixo. Um bloco e tipicamente um modulo, um servico ou uma arvore de diretorios. Isso mantem o codigo relacionado junto, o que melhora a compreensao da IA.
Engenharia de Prompts
Os prompts evoluiram significativamente. As versoes iniciais produziam descricoes verbosas e narrativas. Os prompts atuais exigem saida estruturada com campos especificos. Usamos exemplos few-shot para demonstrar o formato esperado.
Concorrencia
Bases de codigo grandes tem milhares de arquivos. Processar sequencialmente levaria uma eternidade. Analisamos blocos em paralelo, com limites de concorrencia configuraveis para evitar limites de taxa da API.
Selecao de Modelo
Diferentes modelos tem diferentes pontos fortes. O GPT-4 produz analises mais precisas, mas custa mais. O Claude e melhor em seguir requisitos de saida estruturada. Suportamos ambos, alem de modelos locais via Ollama para equipes que nao podem enviar codigo para APIs externas.
O Futuro da Descoberta com IA
O que temos hoje e a versao 1. Aqui esta o que estou trabalhando para alcancar:
Descoberta Continua
Em vez de uma analise unica, monitorar sua base de codigo continuamente. Quando o codigo muda, atualizar os diagramas relevantes automaticamente. Detectar desvios arquiteturais antes que se tornem um problema.
Compreensao Mais Profunda
A analise atual e principalmente estrutural. Versoes futuras poderiam entender comportamento: "Este endpoint valida a entrada, chama o servico de pagamento e depois envia um e-mail de confirmacao." Diagramas de sequencia gerados a partir do codigo.
Analise Entre Repositorios
A maioria das organizacoes tem multiplos repositorios. A descoberta deveria entender como eles se conectam — quais servicos no repositorio A chamam servicos no repositorio B.
Pontuacao de Confianca
Nem todas as descobertas sao igualmente certas. Estamos adicionando pontuacoes de confianca para que voce saiba quais sugestoes examinar com mais cuidado.
Conclusao
A descoberta de arquitetura com IA nao e magica. E uma ferramenta que acelera as partes tediosas de entender uma base de codigo enquanto ainda requer julgamento humano para as partes mais sutis.
Quando executo a descoberta naquela base de codigo de 200K linhas hoje, obtenho um rascunho de diagrama de arquitetura em 10 minutos em vez de 3 semanas. Nao e perfeito — ainda preciso revisar e corrigir. Mas e um ponto de partida dramaticamente melhor do que um quadro branco em branco.
Se voce esta afogado em codigo sem documentacao, experimente a descoberta com IA. Va com expectativas realistas: ela nao vai entender o dominio do seu negocio, pode perder padroes incomuns e definitivamente requer revisao humana. Mas vai te levar 80% do caminho em uma fracao do tempo.
Quer saber mais? Confira nossa introducao ao modelo C4 que a descoberta com IA gera, ou leia sobre por que a documentacao de arquitetura importa.