Aterrando agentes de codificação de IA com um grafo de conhecimento de código marcado por confiança

Divulgação: este é meu próprio projeto de código aberto (forensic-deepdive, Apache-2.0). Estou compartilhando aqui porque a comunidade do dev.to tende a ter opiniões afiadas sobre ferramentas de agentes e quero a crítica.

A maioria das ferramentas de "contexto de repositório" para agentes de IA é de recuperação: embutir os arquivos, buscar os pedaços que parecem semelhantes ao prompt, esperar que o modelo raciocine sobre eles. Isso é uma boa linha de base, mas responde "que texto parece relevante", não "o que quebra se eu mudar isso", "quais arquivos são essenciais" ou "quem é o proprietário disso e o fator de ônibus é 1". Essas são perguntas de gráfico e histórico do git.

Aqui está como eu construí uma ferramenta que responde a essas perguntas, o que ela acerta e, explicitamente, o que ainda não faz.

O problema: recuperação não é fundamentação

A onda atual de ferramentas de codificação de IA se estabeleceu em grande parte na recuperação aumentada de contexto: embutir o repositório, buscar os pedaços mais semelhantes ao prompt e deixar o modelo raciocinar sobre eles. É útil e é a linha de base certa. Mas tem um teto estrutural.

A recuperação por similaridade responde "que texto parece relevante?" Não responde às perguntas que um engenheiro competente responde reflexivamente:

• Se eu mudar esta função, o que realmente quebra, transitivamente, entre os arquivos?
• Quais 20 arquivos de 2.000 são essenciais?
• Quem historicamente possuiu este módulo e o fator de ônibus é 1?
• Este frontend chama um manipulador de backend, e qual é?

Essas são perguntas estruturais e históricas. Você as responde com um gráfico e com o histórico do git, não com similaridade de cosseno. forensic-deepdive é uma ferramenta de código aberto (Apache-2.0) construída exatamente em torno dessa premissa.

O que ela produz

Apontá-la para um repositório e ela emite três saídas coordenadas:

1. Um gráfico de conhecimento embutido persistente (<repo>/.deepdive/graph.lbug).
2. Um servidor MCP expondo 9 ferramentas compostas para qualquer agente ciente do MCP.
3. Cinco artefatos markdown duráveis como uma projeção legível por humanos.

É construído sobre tree-sitter (análise em 9 linguagens), um mapa de repositório estilo PageRank para centralidade, um banco de dados gráfico embutido e git log para a camada histórica. A extração é executada inteiramente localmente, com zero chamadas de LLM, zero rede e nenhuma chave de API necessária. Recursos de nuvem e semânticos são estritamente opt-in.

O esquema do gráfico

Tipos de nó: Arquivo, Símbolo, Módulo, Commit, Autor, Endpoint, DbTable.

Tipos de arestas: DEFINES, MEMBER_OF, IMPORTS, CALLS, EXTENDS, IMPLEMENTS, TOUCHED_BY_COMMIT, AUTHORED_BY, CO_CHANGES_WITH, e o conjunto de fronteira cruzada: HANDLES, CALLS_ENDPOINT, ROUTES_TO, INJECTS, PERSISTS_TO.

As arestas estruturais (CALLS/IMPORTS/EXTENDS) vêm da análise AST. As arestas históricas (TOUCHED_BY_COMMIT/AUTHORED_BY/CO_CHANGES_WITH) vêm do git. As arestas de fronteira cruzada vêm de extratores específicos de protocolo. Elas vivem em um único gráfico, para que um agente possa fazer uma pergunta estrutural e uma pergunta histórica na mesma respiração.

A decisão de design que mais importa: honestidade

O modo de falha de uma ferramenta de gráfico de código é a confiança silenciosa. Se o gráfico afirma uma aresta CALLS que na verdade é apenas dois símbolos com o mesmo nome em arquivos diferentes, um agente confiará nisso e "consertará" um código que nunca precisou ser tocado. Alta recuperação com falsos positivos ocultos é ativamente perigosa em um loop autônomo.

Portanto, cada aresta e cada afirmação emitida carrega uma tag de confiança:

• EXTRACTED: determinístico a partir do AST ou git log. Um fato.
• INFERRED: uma heurística resolvida de forma limpa (caminhada pelo gráfico de importação, inferência de tipo de receptor, único candidato com o mesmo nome). Alta confiança, mas derivada.
• AMBIGUOUS: múltiplos candidatos; o resolvedor não conseguiu desambiguar, então ele apresenta todos os candidatos em vez de adivinhar.

Isso aparece em toda parte. HOTPATHS carrega uma coluna de mistura de confiança por linha, para que você possa distinguir um símbolo que foi resolvido de forma limpa (principalmente EXTRACTED/INFERRED) de um que está se afogando em colisões de mesmo nome (AMBIGUOUS). A ferramenta informa quanto você pode confiar nela, por afirmação.

Uma abstração para cinco protocolos: a pedra angular do Endpoint

A rastreabilidade de fronteira cruzada é onde a maioria das ferramentas para. porque cada protocolo parece diferente. O forensic-deepdive roteia todos eles através de um único nó de junção Endpoint. Cinco protocolos, HTTP, ferramentas MCP, despacho de registro, gRPC e mensagens/AMQP, compartilham esse único nó e uma junção cega ao protocolo. Uma chamada de frontend resolve para seu manipulador de backend em toda a pilha como uma única aresta ROUTES_TO.

A consequência arquitetônica: adicionar um sexto protocolo é um novo construtor de chave mais extratores de provedor/consumidor. Ele nunca toca nas camadas de rastreamento, emissão ou serviço. A camada de apresentação é cega ao protocolo por design. trace(symbol) percorre frontend call -> CALLS_ENDPOINT -> Endpoint -> HANDLES -> handler -> CALLS tail genericamente, sem