RAG + grafo de chamadas: contexto automático do gerenciador de tarefas para o Claude Code

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

Por que o contexto importa mais que a qualidade do modelo

Quando o desenvolvedor pega uma tarefa do tracker e abre um assistente de IA, o passo mais difícil não é a conversa com o modelo, mas a preparação para ela. É preciso entender quais arquivos pertencem à tarefa, quais funções são chamadas e quais módulos estão interligados. Em projetos grandes, isso leva de 10 a 20 minutos de estudo manual do código antes de escrever o primeiro prompt.

Se você joga tudo no contexto, os tokens acabam rápido, a requisição fica mais cara e o LLM se perde no ruído de código sem relação. Se inclui pouco, o modelo não enxerga as dependências, deixa passar funções importantes e dá respostas superficiais. Achar o equilíbrio na mão é difícil.

O RAG clássico baseado em embeddings resolve parte do problema: a busca semântica encontra trechos de sentido parecido. Mas ele não entende a estrutura do código: a função A pode estar semanticamente distante de B e, mesmo assim, chamá-la diretamente, e as duas são necessárias no contexto.

Como a solução funciona

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

• Camada vetorial — embeddings do código para busca semântica: trechos semelhantes, comentários, nomes
• Grafo de chamadas — dependências estruturais: a função A chama B, o módulo C importa D, E herda de F
• Plugin para o Claude Code — lê a descrição da tarefa no tracker e dispara a busca nos dois níveis
• Ranqueamento e corte — os resultados são ponderados por relevância e cortados até o limite de tokens
• Atualização incremental — o índice não é recalculado do zero a cada commit

O sistema é construído sobre um parser de código (AST) e ferramentas de análise estática. O grafo de chamadas contorna as limitações da busca semântica: mesmo que os nomes das funções fujam do padrão ou os comentários sejam escassos, as ligações estruturais do código ainda podem ser rastreadas pela AST. O índice fica armazenado separado da base de código e não exige mudanças no repositório em si. O plugin para o 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 entrega um resultado mensurável. Sem um contexto inteligente, os desenvolvedores costumam colar arquivos ou diretórios inteiros no prompt, "só por precaução". Com RAG e grafo, o sistema decide o que é relevante e entrega só isso.

"O principal problema de trabalhar com LLMs em um projeto real não é a

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

Em grandes monorrepositórios o efeito é especialmente visível: em vez de 50.000 tokens de "tudo o que pode estar relacionado", são de 3.000 a 5.000 tokens de contexto preciso. Isso significa respostas mais rápidas e economia direta na API.

A prática mostra que um contexto bem montado reduz o número de iterações com o modelo. Quando a IA vê todas as dependências logo de início, ela pede trechos adicionais ou dá respostas incompletas com menos frequência.

O que isso significa

A abordagem aponta uma direção real para equipes de engenharia que estão adotando assistentes de IA: automatizar não o diálogo com o modelo, mas a coleta de contexto antes dele. A integração com o tracker é um passo lógico: a tarefa já está descrita, só falta vinculá-la corretamente ao código. Para grandes equipes com centenas de tickets por dia, isso pode virar parte padrão do processo de engenharia.