Clarity: Sistema inteligente para geração automatizada de documentação técnica em projetos de programação

Abstract

A documentação técnica é um artefato essencial do ciclo de vida do software, mas é frequentemente negligenciada, sobretudo em ambientes ágeis, o que resulta em arquivos README incompletos ou desatualizados e no acúmulo de dívida técnica documental. Este trabalho apresenta o Clarity, um sistema de geração automatizada de documentação técnica implementado como extensão para o Visual Studio Code. A solução emprega uma arquitetura de orquestração de agentes de Modelos de Linguagem de Grande Escala executados localmente por meio do Ollama: um agente analisa o código-fonte por meio de análise estática e outro redige o arquivo README, ambos encadeados pelo framework CrewAI. Para adequar repositórios de diferentes tamanhos à janela de contexto dos modelos locais, adota-se uma estratégia de divisão em fragmentos (chunking). O protótipo foi publicado na loja oficial do editor sob licença MIT e avaliado por meio de uma rubrica com cinco critérios — completude, atualidade, clareza, utilidade e consistência — aplicada de forma comparativa a três repositórios reais, frente à ferramenta de mercado README-AI. Os resultados indicam alta fidelidade da documentação gerada em relação ao código, principal contribuição da abordagem, enquanto as limitações concentram-se em seções de natureza inferencial deixadas como marcadores, no vazamento de prefixo de prompt e na variabilidade entre execuções. Conclui-se que a geração automatizada e local de documentação técnica é viável e promissora como apoio à mitigação da dívida técnica documental, preservando a privacidade do código-fonte.