RAG + grafo de chamadas: contexto automático de um rastreador de tarefas para o Claude Code

O contexto é o principal problema ao usar LLMs no desenvolvimento real. Não é a qualidade do modelo ou o tamanho da janela, mas sim o que e como entra no prompt. Um desenvolvedor compartilhou uma solução prática no Habr: um índice RAG do repositório com vetores e um grafo de chamadas, mais um plugin para Claude Code que coleta automaticamente o contexto de uma tarefa do rastreador de tarefas — sem seleção manual e desperdício de tokens.

Por

Que o Contexto É Mais Importante Que a Qualidade do Modelo

Quando um desenvolvedor pega uma tarefa do rastreador e abre um assistente de IA, o passo mais difícil não é o diálogo com o modelo, mas a preparação para ele. Você precisa entender quais arquivos estão relacionados à tarefa, quais funções são chamadas, quais módulos estão interconectados. Em grandes projetos, isso leva 10–20 minutos de revisão manual de código — antes de escrever o primeiro prompt.

Se você jogar tudo no contexto de uma vez — os tokens são gastos rapidamente, a solicitação fica cara, e o LLM se perde no ruído do código não relacionado. Se você tomar muito pouco — o modelo não vê as dependências, perde funções importantes e dá respostas superficiais. Encontrar o equilíbrio manualmente é difícil.

O RAG clássico usando embeddings resolve parte do problema: a busca semântica encontra fragmentos semanticamente semelhantes. Mas não entende a estrutura do código: a função A pode estar semanticamente distante de B, mas chamá-la diretamente — e ambas são necessárias no contexto.

Como a Solução Funciona

O autor construiu um sistema em dois níveis de indexação:

• Camada vetorial — embeddings de código para busca semântica: fragmentos semelhantes, comentários, nomes
• Grafo de chamadas — dependências estruturais: função A chama B, módulo C importa D, E herda de F
• Plugin do Claude Code — lê descrição da tarefa do rastreador e executa busca em ambos os níveis
• Classificação e truncagem — os resultados são ponderados por relevância e cortados até o limite de tokens
• Atualizações incrementais — o índice não é recalculado do zero a cada commit

O sistema é construído sobre um analisador de código (AST) e ferramentas de análise estática. O grafo de chamadas permite contornar as limitações da busca semântica: mesmo se os nomes das funções forem não-padrão ou comentários forem escassos, as conexões estruturais no código ainda podem ser rastreadas através da AST.

O índice é armazenado separadamente da base de código e não requer alterações no próprio repositório. O plugin Claude Code é instalado como uma extensão padrão e acessa o índice por meio de uma API local.

Economia de Tokens

É aqui que a abordagem produz resultados mensuráveis. Sem contexto inteligente, desenvolvedores frequentemente despejam arquivos inteiros ou diretórios no prompt — "por via das dúvidas." Com RAG + grafo, o sistema decide por si só o que é relevante e retorna apenas isso.

"O principal problema ao usar LLMs em um projeto real não é a

qualidade do modelo, mas o contexto", — afirma o autor do artigo.

Para grandes monorrepos, o efeito é especialmente notável: em vez de 50.000 tokens de "tudo que pode estar relacionado" — 3.000–5.000 tokens de contexto preciso. Isso é tanto velocidade de resposta quanto economia direta da API. A prática mostra: o contexto coletado corretamente reduz o número de iterações com o modelo. Quando a IA vê todas as dependências de uma vez, raramente pede fragmentos adicionais ou dá respostas incompletas.

O Que Isso Significa

A abordagem mostra uma direção real para equipes de engenharia que implementam assistentes de IA: automatizar não o diálogo com o modelo em si, mas a coleta de contexto antes dele. A integração com o rastreador de tarefas é um passo lógico: a tarefa já está descrita, você só precisa vinculá-la corretamente ao código. Para grandes equipes com centenas de tickets por dia, isso pode se tornar uma parte padrão do processo de engenharia.