A IA Que Lê Seu Código Antes de Responder: Um Guia Básico de RAG Para Quem Está Cansado de Explicar o Projeto do Zero

Imagine a seguinte cena. Você abre o chat da sua ferramenta de IA favorita e pergunta: “como funciona a regra de desconto para clientes antigos no nosso sistema?”. A resposta vem rápida, bem escrita, cheia de confiança — e completamente errada. A IA descreveu uma regra genérica de e-commerce, que não tem nada a ver com a lógica específica que o seu time implementou há dois anos, numa função perdida em um módulo de faturamento. Você perde dez minutos corrigindo a IA, colando trechos de código no chat, explicando o contexto do negócio, e só então recebe uma resposta útil. No dia seguinte, em uma nova conversa, tudo se repete, porque a IA não lembra de nada do que foi dito antes.

Esse problema é tão comum que já tem nome entre quem trabalha com IA aplicada ao desenvolvimento: falta de contexto. Os modelos de linguagem são treinados com uma quantidade enorme de informação pública, mas eles simplesmente não conhecem o seu projeto, a sua base de código, as decisões de arquitetura que o seu time tomou ou as regras de negócio específicas da sua empresa. E colar manualmente arquivos inteiros no chat, toda vez, não escala — além de estourar o limite de tamanho que o modelo consegue processar de uma vez (o chamado “contexto”).

É exatamente esse problema que a técnica de RAG, sigla em inglês para Retrieval-Augmented Generation (algo como “geração aumentada por recuperação”), foi criada para resolver. Neste artigo, vamos entender o que é RAG do zero, como ele funciona por dentro, e vamos construir um exemplo simples e funcional em Python, para você sair daqui com uma base real sobre como dar contexto à IA sobre o seu próprio projeto.

O que é RAG, explicado sem rodeios

RAG é uma técnica que combina duas coisas: um mecanismo de busca (retrieval) e um modelo de geração de texto (generation), que é a própria IA. A ideia central é simples: em vez de perguntar algo diretamente para a IA e torcer para que ela “saiba” a resposta, você primeiro busca informações relevantes em uma base de conhecimento sua — pode ser a documentação do projeto, o código-fonte, tickets de suporte, atas de reunião — e só depois entrega essas informações, junto com a pergunta, para a IA responder.

Uma analogia sóbria ajuda aqui. Pense em um advogado experiente que vai depor em um tribunal sobre um caso específico. Ele não confia apenas na memória de tudo que estudou na faculdade de Direito, anos atrás. Antes de falar, ele consulta os autos do processo, os documentos daquele caso específico, e só então formula a resposta. O conhecimento geral de Direito (equivalente ao treinamento do modelo de IA) continua sendo essencial, mas é a consulta aos documentos do caso (a busca, o retrieval) que torna a resposta precisa e aplicável àquela situação concreta.

Segundo a Red Hat, em artigo sobre o tema, a RAG tem potencial para revolucionar como o software é concebido e implementado, justamente porque permite que a IA trabalhe com informação atualizada e específica, sem a necessidade de retreinar o modelo inteiro cada vez que algo muda no projeto.

Por que não simplesmente colar tudo no prompt?

Uma dúvida natural de quem está começando é: por que não colar o projeto inteiro na mensagem e pronto? A resposta tem dois lados. Primeiro, existe um limite técnico: todo modelo de IA tem uma “janela de contexto”, ou seja, uma quantidade máxima de texto que ele consegue processar em uma única interação. Projetos reais, com milhares de arquivos, simplesmente não cabem nesse espaço.

Segundo, mesmo quando cabe, colar tudo é ineficiente e caro. Modelos de IA cobram (ou consomem recursos) proporcionalmente à quantidade de texto processado. Enviar um projeto inteiro para responder uma pergunta sobre uma única função é como entregar a biblioteca inteira para alguém que só queria saber o significado de uma palavra. O RAG resolve isso entregando apenas os trechos relevantes, encontrados por meio de busca, e não o conteúdo inteiro.

As peças que compõem um sistema de RAG

Antes de escrever qualquer código, vale entender as partes que formam esse mecanismo. São quatro peças principais, e cada uma tem um papel bem definido.

1. Os documentos (sua base de conhecimento)

É o material que você quer que a IA conheça: arquivos de código, documentação em Markdown, descrições de regras de negócio, tickets resolvidos, o que for relevante para o seu projeto. Esse material precisa ser dividido em pedaços menores, chamados de chunks (fragmentos), porque a busca funciona melhor com trechos focados do que com arquivos gigantes.

2. Os embeddings (a “impressão digital” do significado)

Aqui está o coração técnico do RAG, e vale explicar com calma porque é o conceito que mais confunde quem está começando. Um embedding é uma representação numérica de um texto, criada por um modelo de IA especializado, que captura o significado daquele texto — e não apenas as palavras usadas literalmente.

Pense em um embedding como as coordenadas de um ponto em um mapa gigantesco de significados. Textos com significados parecidos ficam em pontos próximos nesse mapa, mesmo que usem palavras completamente diferentes. A frase “como cancelar um pedido” e a frase “quero desfazer minha compra” ficariam próximas nesse mapa, porque tratam do mesmo assunto, mesmo sem repetir palavras.

3. O banco de dados vetorial

É onde esses embeddings ficam armazenados, de forma organizada para permitir buscas rápidas por proximidade. Quando você faz uma pergunta, ela também é transformada em um embedding, e o banco de dados vetorial encontra os trechos de texto cujos embeddings estão mais próximos do embedding da pergunta — ou seja, os trechos com significado mais relacionado.

💡 Dica do Mestre: existem bancos de dados vetoriais populares, como o Neo4j (que também trabalha com grafos), e soluções mais simples para estudo e projetos pequenos, como o FAISS e o Chroma. No vídeo RAG in Practice: How to Teach AI to Search for Answers in Your Database, há uma demonstração prática de como montar um buscador combinando IA, Ollama e Neo4j, que vale assistir para visualizar o processo de ponta a ponta.

4. O modelo de geração (a IA que responde)

É o modelo de linguagem propriamente dito — pode ser um modelo local, rodando na sua máquina, ou um modelo acessado por API. Ele recebe a pergunta original do usuário junto com os trechos de texto recuperados pela busca, e gera a resposta final com base nessas duas informações combinadas.

Montando um exemplo de RAG na prática

Vamos construir uma versão simplificada, mas funcional, de um pipeline de RAG em Python. O objetivo é didático: entender o fluxo completo, não construir algo pronto para produção. Vamos simular uma base de conhecimento sobre um projeto fictício, com algumas regras de negócio documentadas em texto simples.

Passo 1 — preparando o ambiente

Para este exemplo, vamos usar duas bibliotecas populares em Python: não é necessário um banco externo para este exercício básico — vamos simular a busca vetorial com uma biblioteca leve chamada sentence-transformers, que gera embeddings localmente, e cálculos de similaridade feitos com numpy.

Passo 2 — criando a base de conhecimento

Vamos simular trechos de documentação de um projeto real, divididos em pequenos fragmentos (chunks):

Passo 3 — transformando os documentos em embeddings

Agora usamos um modelo pré-treinado para converter cada trecho de texto em um vetor numérico (o embedding):

Esse código converte cada frase em uma lista de números (um vetor). Não se preocupe em entender cada número individualmente — o importante é que textos com significados parecidos geram vetores matematicamente próximos entre si.

Passo 4 — buscando o trecho mais relevante para uma pergunta

Com os documentos já transformados em vetores, o próximo passo é pegar a pergunta do usuário, transformá-la também em um vetor, e comparar com os vetores da base usando uma medida de similaridade chamada similaridade de cosseno — uma forma de medir o quão “alinhados” dois vetores estão.

Ao rodar esse trecho, a busca deve retornar o documento sobre a regra de desconto como o mais relevante, mesmo que a pergunta não repita exatamente as mesmas palavras do texto original. Isso acontece porque a busca é feita pelo significado, e não por correspondência literal de palavras — essa é a grande diferença entre o RAG e uma simples busca por palavra-chave.

Passo 5 — montando o prompt final para a IA

Com os trechos relevantes em mãos, o último passo é montar uma instrução (prompt) que combine a pergunta original com o contexto encontrado, e enviar isso para o modelo de IA responder:

Esse prompt final é o que você enviaria para um modelo de IA — seja via API, seja em uma ferramenta de assistente de código. Note a instrução explícita pedindo para a IA usar apenas o contexto fornecido: isso reduz bastante a chance de o modelo “inventar” uma resposta genérica, um comportamento conhecido como alucinação.

💡 Dica do Mestre: instruir o modelo a dizer “não sei” quando a resposta não estiver no contexto é uma das práticas mais simples e eficazes para reduzir alucinações em sistemas de RAG. É uma linha a mais no prompt que evita muita dor de cabeça depois.

RAG aplicado ao código-fonte do seu projeto

O exemplo acima usou textos de documentação, mas o mesmo princípio se aplica diretamente ao código. A diferença está em como você divide os documentos em chunks: em vez de parágrafos, você costuma dividir por função, classe ou arquivo, preservando o contexto de cada bloco de código.

O restante do processo é idêntico: gerar embeddings para cada chunk de código, buscar os trechos mais relevantes para a pergunta do desenvolvedor, e montar o prompt com esse contexto. É exatamente esse mecanismo, em versões mais sofisticadas, que permite que ferramentas de IA integradas ao editor de código consigam responder perguntas específicas sobre o seu projeto, sem que você precise colar arquivos manualmente toda vez.

Segundo o artigo RAG como base para agentes de IA em engenharia de software, levar essa técnica para um ambiente de produção exige cuidados adicionais de integração, governança e medição de resultado — algo que ultrapassa o escopo deste artigo introdutório, mas que vale ter em mente como próximo passo natural de evolução.

Quando o RAG faz sentido (e quando não faz)

RAG é uma ótima escolha quando você precisa que a IA responda com base em informação específica, que muda com frequência, e que não faria sentido “ensinar” ao modelo de forma permanente. Documentação interna, regras de negócio, histórico de decisões de arquitetura e o próprio código do projeto são exemplos clássicos.

Por outro lado, se o seu problema é apenas executar uma tarefa pontual e bem definida — como renomear uma variável em um arquivo específico — você provavelmente não precisa de um pipeline de RAG completo. Nesses casos, soluções mais diretas, como um bom prompt com o arquivo colado manualmente, resolvem com menos complexidade.

💡 Dica do Mestre: vale notar a diferença entre RAG, workflows e agentes de IA — são conceitos relacionados, mas distintos. O post RAG, Workflow ou Agente: você sabe qual escolher no seu projeto? traz uma reflexão útil sobre como decidir qual abordagem se encaixa melhor em cada tipo de projeto.

Erros comuns de quem está começando com RAG

Alguns tropeços aparecem com frequência em quem está implementando RAG pela primeira vez, e vale conhecê-los antes de cair neles.

• Chunks grandes demais: dividir o conteúdo em fragmentos muito longos prejudica a precisão da busca, porque o embedding acaba representando uma mistura de assuntos diferentes.
• Chunks pequenos demais: o extremo oposto também é um problema — fragmentos curtos demais perdem contexto e geram respostas fragmentadas.
• Base de conhecimento desatualizada: RAG não corrige sozinho uma documentação defasada. Se os documentos originais estão errados, a IA vai responder errado com confiança.
• Ignorar o número de resultados retornados: trazer poucos trechos pode deixar a resposta incompleta; trazer trechos demais pode confundir o modelo com informação irrelevante.

Participe da Comunidade Dev’s AI

Entender RAG na teoria é o primeiro passo, mas o verdadeiro aprendizado acontece quando você troca experiências com outros desenvolvedores que estão enfrentando os mesmos desafios: qual banco vetorial usar, como dividir os chunks do seu projeto específico, como integrar tudo isso ao seu fluxo de trabalho diário. Se você quer discutir essas questões com outros profissionais que também estão aplicando IA no desenvolvimento de software, venha para a Comunidade Dev’s AI. É um espaço para compartilhar dúvidas reais, exemplos de código e aprender com quem já está colocando essas técnicas em prática no dia a dia.

Conclusão

O RAG resolve um problema muito concreto: a distância entre o conhecimento geral de um modelo de IA e o conhecimento específico do seu projeto. Em vez de depender da sorte de a IA “adivinhar” regras de negócio ou decisões de arquitetura que nunca viu, você constrói um mecanismo de busca que entrega à IA exatamente a informação relevante, no momento em que ela é necessária.

Neste artigo, você viu o fluxo completo de ponta a ponta: dividir documentos em chunks, transformar texto em embeddings, buscar por similaridade de significado e montar um prompt final combinando pergunta e contexto. É esse mesmo princípio, em versões mais robustas e com bancos de dados vetoriais dedicados, que sustenta boa parte das ferramentas de IA que hoje ajudam desenvolvedores a navegar em bases de código complexas sem precisar explicar tudo do zero, todos os dias.

O próximo passo natural é experimentar: pegue uma pasta pequena de documentação ou código do seu próprio projeto, aplique o pipeline que construímos aqui, e observe como as respostas mudam quando a IA finalmente tem contexto real para trabalhar.