O Estagiário Amnésico: Como Dar à IA Memória Real Sobre o Seu Projeto Usando RAG

Imagine contratar um estagiário muito inteligente, capaz de escrever código limpo e explicar conceitos complexos com clareza. Há apenas um problema: todos os dias, ao chegar, ele esquece completamente o projeto em que está trabalhando. Não lembra das regras de negócio, não sabe como as funções do sistema se conectam, não conhece as decisões que a equipe tomou na semana passada. Todos os dias você precisa reexplicar tudo do zero.

Esse estagiário existe, e você provavelmente já trabalha com ele: é o assistente de IA que você usa para programar. Modelos como os que alimentam o Claude ou o ChatGPT são treinados com uma quantidade enorme de informação genérica sobre programação, mas eles não nascem sabendo nada sobre o seu projeto específico — sua arquitetura, suas convenções, suas regras internas. Sem esse conhecimento, a IA improvisa, e improvisar em cima de um sistema real custa caro: sugestões que ignoram padrões já definidos, código duplicado porque a IA não sabia que aquela função já existia, ou respostas genéricas quando você precisava de algo específico do seu domínio.

É exatamente esse problema que a técnica chamada RAG (Retrieval-Augmented Generation, ou “Geração Aumentada por Recuperação”) resolve. Neste artigo, você vai entender o que é RAG, como ela funciona por baixo dos panos e vai construir, passo a passo, um exemplo funcional que dá à IA acesso ao contexto real de um projeto — sem precisar copiar e colar arquivos inteiros toda vez que fizer uma pergunta.

O que é RAG, afinal?

RAG é a combinação de duas etapas: recuperação (retrieval) de informação relevante e geração (generation) de uma resposta usando essa informação como apoio. Em vez de perguntar diretamente ao modelo de IA e esperar que ele “adivinhe” a resposta com base apenas no que aprendeu durante o treinamento, você primeiro busca em uma base de dados própria — pode ser a documentação do seu projeto, o código-fonte, tickets de suporte, atas de reunião — os trechos mais relevantes para a pergunta feita. Depois, você entrega esses trechos junto com a pergunta para o modelo, que então gera uma resposta fundamentada nesse material.

É como transformar aquele estagiário amnésico em um profissional que, antes de responder qualquer coisa, consulta rapidamente um caderno de anotações específico do projeto. Ele continua sendo o mesmo modelo genérico e inteligente, mas agora com uma “cola” contextualizada na mão.

💡 Dica do Mestre: A Red Hat publicou um artigo detalhado sobre como o RAG está redefinindo a engenharia de software, mostrando o impacto dessa técnica além do uso pontual em chats — ela está mudando como equipes projetam sistemas inteiros de apoio à IA.

Por que não simplesmente colar tudo no prompt?

Uma pergunta natural de quem está começando é: “por que não colo o projeto inteiro na conversa com a IA?”. A resposta tem dois motivos práticos.

• Limite de contexto: todo modelo de IA tem um limite de quantidade de texto que consegue processar em uma única interação, chamado de “janela de contexto”. Projetos reais, com milhares de linhas de código e documentação, ultrapassam esse limite facilmente.
• Ruído: mesmo quando cabe, jogar informação em excesso no prompt faz o modelo perder o foco. É como pedir para alguém encontrar uma frase específica dentro de uma enciclopédia inteira, em vez de entregar diretamente o capítulo certo.

O RAG resolve isso filtrando, antes de conversar com a IA, apenas os pedaços de informação realmente relevantes para aquela pergunta específica.

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

Para entender como o RAG funciona na prática, é preciso conhecer quatro peças fundamentais. Vamos explicar cada uma com uma analogia antes de partir para o código.

1. Os documentos-fonte

São os materiais que você quer que a IA “conheça”: arquivos de código, documentação em Markdown, especificações técnicas, tickets do sistema de gestão de projetos. É o conteúdo bruto da sua base de conhecimento.

2. Chunking (divisão em pedaços)

Documentos grandes precisam ser divididos em pedaços menores, chamados de “chunks”. Isso acontece porque a busca funciona melhor em blocos pequenos e focados do que em arquivos gigantes. Pense em um livro: se alguém pergunta sobre um assunto específico, é mais eficiente indicar o parágrafo exato do que entregar o livro inteiro.

3. Embeddings (representação numérica de significado)

Aqui está o coração técnico do RAG. Um embedding é uma representação numérica — um vetor, ou seja, uma lista de números — que captura o significado de um texto. Dois textos com significados parecidos geram vetores numericamente próximos, mesmo que usem palavras diferentes. É assim que a busca consegue encontrar “como faço para me conectar ao banco de dados” mesmo quando o documento fala em “configuração da conexão com o PostgreSQL” — as palavras diferem, mas o significado é próximo.

4. O banco vetorial

É onde os embeddings ficam armazenados, organizados de forma que seja possível buscar rapidamente “quais chunks têm significado mais próximo desta pergunta”. Existem soluções especializadas para isso, mas também é possível montar uma versão simples usando apenas estruturas de dados comuns, como faremos no exemplo a seguir.

💡 Dica do Mestre: Se você quer ver esses quatro conceitos aplicados em um cenário mais avançado, com banco de grafos, vale assistir a este vídeo que demonstra como criar um buscador com RAG usando Ollama e Neo4j. É um passo além do que faremos aqui, mas ajuda a visualizar onde a técnica pode chegar.

Construindo um RAG simples do zero, em Python

Vamos construir um exemplo funcional e minimalista, usando apenas Python puro e uma biblioteca leve para gerar embeddings. O objetivo não é criar um sistema de produção, mas fazer você entender o mecanismo com as próprias mãos.

Passo 1: preparando o ambiente

Vamos usar a biblioteca sentence-transformers, que gera embeddings de forma local e gratuita, sem depender de uma API externa paga. Instale com:

Passo 2: simulando os documentos do projeto

Imagine que você tem uma pequena base de conhecimento sobre um projeto fictício: um sistema de pedidos. Cada item representa um “chunk” de documentação.

Em um cenário real, esses textos viriam de arquivos de documentação, comentários no código ou até do próprio código-fonte processado.

Passo 3: gerando os embeddings

Esse trecho transforma cada um dos quatro textos em um vetor numérico. É esse vetor que permite comparar significados matematicamente.

Passo 4: implementando a busca por similaridade

Para encontrar o documento mais relevante para uma pergunta, comparamos o embedding da pergunta com os embeddings dos documentos, usando uma medida chamada similaridade de cosseno — quanto mais próxima de 1, mais parecidos os significados.

Agora podemos testar com uma pergunta real:

Mesmo sem a palavra “pagamento” aparecer em uma pergunta genérica sobre “falhas”, o sistema deve retornar o trecho sobre o PagamentoGateway como o mais relevante, porque o significado da pergunta está semanticamente próximo daquele conteúdo.

Passo 5: montando o prompt aumentado

Com o contexto relevante em mãos, o próximo passo é montar o prompt que será enviado à IA, combinando a pergunta original com os trechos recuperados:

Esse prompt final é o que você envia à API do modelo de IA de sua escolha — seja via chamada de API, seja colando manualmente em uma conversa. A diferença crucial é que agora a IA não está “chutando” com base em conhecimento genérico: ela está respondendo com base em fatos específicos do seu projeto.

💡 Dica do Mestre: Instruir o modelo a dizer “não sei” quando a resposta não estiver no contexto é uma prática essencial. Sem essa instrução, o modelo tende a preencher lacunas com suposições plausíveis, mas incorretas — um comportamento conhecido como alucinação.

Como isso se conecta ao seu fluxo de trabalho real

O exemplo acima usou quatro frases fixas para fins didáticos, mas o mesmo princípio se aplica a bases de conhecimento muito maiores: documentação inteira de um projeto, histórico de decisões técnicas, ou até o próprio código-fonte dividido em funções e classes. A lógica não muda — apenas a escala e as ferramentas usadas para armazenar os embeddings de forma eficiente.

Onde o RAG aparece nas ferramentas que você já usa

Se você já usa assistentes de IA integrados ao editor de código, provavelmente já se beneficiou de uma versão de RAG sem perceber. Quando uma ferramenta “entende” o projeto aberto e sugere código coerente com o padrão do repositório, ela normalmente está indexando arquivos localmente e recuperando trechos relevantes antes de gerar a resposta — exatamente o mecanismo que construímos aqui, em uma versão simplificada.

💡 Dica do Mestre: Vale destacar que RAG em produção envolve muito mais cuidado do que o exemplo didático mostrado aqui. Segundo um post da Roga DX sobre bastidores de IA corporativa, construir um sistema de RAG confiável em escala real exige atenção a atualização constante da base, controle de qualidade dos dados de origem e monitoramento de respostas — desafios que vão além do experimento inicial.

RAG e agentes de IA

Um ponto importante para quem está começando: RAG não é uma ferramenta isolada, é uma técnica que pode ser combinada com outras práticas de IA aplicada ao desenvolvimento. Sistemas mais sofisticados usam o RAG dentro de agentes — programas de IA que decidem, sozinhos, quando buscar informação, quando executar uma ação e quando responder diretamente. Como destacado em uma discussão sobre a diferença entre usar IA para programar e construir software com IA, entender conceitos como chunking, contexto e boas práticas de recuperação de informação é o que separa quem usa IA de forma superficial de quem constrói soluções sólidas com ela.

Da mesma forma, um post de Michelli Brito sobre RAG aplicado a sistemas agênticos em Java reforça essa ideia: o RAG permite que um agente de software busque informações relevantes dinamicamente e as injete no prompt em tempo real, em vez de depender de um contexto estático e desatualizado.

Cuidados básicos ao aplicar RAG no seu projeto

Antes de sair implementando RAG em tudo, vale conhecer algumas armadilhas comuns para quem está começando:

• Chunks mal dimensionados: pedaços muito pequenos perdem contexto; pedaços muito grandes trazem ruído. É preciso testar e ajustar o tamanho ideal para o seu tipo de conteúdo.
• Base desatualizada: se a documentação-fonte não é atualizada junto com o código, o RAG passa a “ensinar” a IA com informação obsoleta — o que é pior do que não ter contexto algum.
• Confiar cegamente na resposta: mesmo com contexto correto, o modelo pode interpretar mal a informação recuperada. Revisão humana continua sendo indispensável, especialmente em decisões críticas.

Vá além: pratique com a comunidade

Entender RAG na teoria é o primeiro passo, mas o verdadeiro aprendizado acontece quando você aplica a técnica em um projeto de verdade, discute decisões de implementação e troca experiências com quem está resolvendo problemas parecidos com os seus. É exatamente esse tipo de troca que acontece na Comunidade Dev’s AI, um espaço para desenvolvedores que querem ir além do uso superficial de IA e realmente entender como construir soluções sólidas com ela — seja você iniciante ou alguém com anos de experiência buscando atualização prática. Participe, compartilhe seus experimentos e aprenda com quem já passou pelos mesmos obstáculos.

Conclusão

RAG não é uma tecnologia misteriosa reservada a grandes empresas de tecnologia — é uma técnica acessível, com fundamentos simples, que qualquer desenvolvedor pode começar a aplicar hoje. No fundo, tudo se resume a três passos: transformar informação em uma representação que capture significado, buscar os pedaços mais relevantes para cada pergunta, e entregar esse contexto ao modelo de IA antes de pedir uma resposta.

O exemplo construído neste artigo é deliberadamente simples, mas contém exatamente os mesmos princípios usados em sistemas de produção mais sofisticados. Ao entender essa base, você deixa de ver a IA como uma caixa-preta que às vezes acerta e às vezes erra, e passa a enxergá-la como uma ferramenta que você pode alimentar, ajustar e melhorar — transformando aquele estagiário amnésico em um colega de equipe que, finalmente, conhece o seu projeto.