CODENS: Transforming Code Changes into Living, Accessible, and Queryable Documentation
O CODENS é um sistema que transforma pull requests em documentação viva e consultável ao construir incrementalmente um grafo de conhecimento de software tipado para permitir o questionamento de nível de repositório guiado por agentes, conforme demonstrado por sua avaliação bem-sucedida em um projeto de produção Ruby on Rails.
Artigo original sob licença CC BY 4.0 (http://creativecommons.org/licenses/by/4.0/). Esta é uma explicação gerada por IA do artigo abaixo. Não foi escrita nem endossada pelos autores. Para precisão técnica, consulte o artigo original. Ler aviso legal completo
Imagine que você está caminhando por uma enorme e antiga biblioteca onde os livros estão sendo constantemente reescritos. Cada vez que um novo capítulo é adicionado, uma nota é rabiscada na margem ou uma página é arrancada e substituída, a história muda. No mundo do software, essa biblioteca é a "base de código" (codebase), e as notas são os "pull requests" — os tickets digitais que os desenvolvedores usam para propor mudanças. O problema é que a "história" de como o software funciona (sua documentação) muitas vezes se perde no caos dessas mudanças. Os desenvolvedores acabam adivinhando como as coisas se encaixam porque as instruções estão espalhadas por milhares de arquivos e antigos registros de chat.
Para resolver isso, cientistas começaram a construir "grafos de conhecimento". Pense neles não como uma simples lista de fatos, mas como um mapa gigante e vivo onde cada pedaço de código é uma cidade, e as conexões entre eles são estradas. Se você altera uma cidade, o mapa atualiza automaticamente as estradas que levam a ela. Outra ideia fundamental é a "Geração Aumentada de Recuperação" (RAG), que é como dar a um bibliotecário superinteligente um conjunto específico de livros para ler antes de responder à sua pergunta, garantindo que ele não apenas adivinhe, mas realmente encontre a verdade no texto. A grande questão que os pesquisadores estão fazendo é: podemos construir um mapa que não mostre apenas a biblioteca como ela é hoje, mas que se lembre de cada mudança já feita, transformando o histórico de atualizações de código em um guia vivo e pesquisável?
Apresentamos o CODENS, um novo sistema projetado para fazer exatamente isso. Imagine o CODENS como um arquivista mágico e hiperorganizado que vigia um projeto de software como uma plataforma web Ruby on Rails. Em vez de apenas ler a versão final do código, o CODENS observa o "filme" do histórico do projeto. Ele começa escaneando toda a base de código para construir um mapa esquelético, identificando 1.739 "salas" diferentes (como controllers, models e views) com base nas regras padrão do framework.
Então, a mágica acontece. O CODENS reproduz o histórico do projeto, um pull request por vez, como se estivesse assistindo a um vídeo em time-lapse da construção de um edifício. Para cada mudança, ele não olha apenas para os novos tijolos; ele pergunta a uma IA poderosa (um LLM) por que a mudança foi feita e como ela se encaixa no que já existia. Crucialmente, ele não apenas sobrescreve a história antiga; ele funde os novos detalhes com os antigos. Se um desenvolvedor adiciona um novo botão a uma página, o CODENS atualiza o mapa para mostrar que o botão existe, mas também mantém o histórico de como a página era antes. Isso cria uma camada de "documentação viva" que se torna mais inteligente e detalhada a cada atualização.
Uma vez construído esse mapa, o CODENS oferece três formas de explorá-lo, como diferentes modos de viagem. Você pode fazer uma "busca vetorial" rápida, que é como pedir ao bibliotecário livros com palavras semelhantes. Você pode fazer uma "recuperação de múltiplos saltos" (multi-hop retrieval), que é como seguir um rastro de migalhas de pão de uma sala para a próxima para ver como elas se conectam. Mas o modo mais poderoso é a "travessia guiada por agentes". Aqui, um agente de IA atua como um detetive com uma lanterna. Ele não segue apenas um caminho fixo; ele decide quais portas abrir, quais estradas tomar e até escreve suas próprias consultas personalizadas para encontrar a resposta exata. Ele usa ferramentas para espiar dentro de nós específicos, verificar seus vizinhos ou executar buscas complexas para montar uma resposta completa.
Os pesquisadores testaram este sistema em um projeto industrial real, com mais de 1.700 arquivos e centenas de pull requests. Eles fizeram ao sistema 11 perguntas diferentes que um desenvolvedor real poderia ter, tais como "Como esta funcionalidade funciona?" ou "O que acontece quando eu clico neste botão?". Os resultados foram promissores. O sistema obteve uma pontuação muito alta em precisão e "fidelidade", o que significa que as respostas foram fundamentadas no código real e não inventaram informações. Em uma escala de 1 a 5, especialistas humanos avaliaram a relevância das respostas com uma média de 4,09 e a completude com 4,45. O sistema também foi capaz de rastrear o custo e o tempo de cada consulta, mostrando que, embora o modo detetive (agente) levasse mais tempo e tokens, ele fornecia as respostas mais completas.
No entanto, o artigo também aponta um pequeno obstáculo. Embora o sistema tenha sido excelente em encontrar a informação correta, a maneira como apresentou as respostas às vezes pareceu técnica demais. Os revisores humanos observaram que algumas respostas eram "detalhadas demais" ou "centradas demais no código", listando citações linha por linha quando um resumo mais simples teria sido melhor. É como se o bibliotecário lhe desse o número exato da página e do parágrafo de um livro, mas não resumisse a história para você. Os autores sugerem que o próximo passo não é necessariamente encontrar informações melhores, mas ensinar o sistema a sintetizar essas informações em explicações mais claras e amigáveis ao usuário.
Em suma, o CODENS sugere que podemos transformar o histórico bagunçado e disperso de mudanças de código em uma memória estruturada e consultável para o software. Ele prova que, ao tratar os pull requests como um fluxo contínuo de conhecimento em vez de apenas correções temporárias, podemos construir um sistema que ajuda os desenvolvedores a entender bases de código complexas muito mais rápido. Embora ainda não seja um problema totalmente resolvido — especialmente no que diz respeito a fazer com que as respostas soem mais como um humano prestativo e menos como um robô lendo um manual — ele oferece um vislumbre vívido de um futuro onde a documentação de software é viva, atualizada e sempre pronta para responder às suas perguntas.
Afogado em artigos na sua área?
Receba digests diários dos artigos mais recentes que correspondam às suas palavras-chave de pesquisa — com resumos técnicos, no seu idioma.