Graphify query, path e explain: como usar os três comandos de consulta no dia a dia

comando graphify query mostrando subgrafo de código com caminhos e citações
Resposta rápida

O graphify query é o comando que recebe uma pergunta em linguagem natural e devolve o subgrafo relevante do seu código, com caminhos explícitos e citações no formato arquivo:linha. Ele percorre o grafo em largura (BFS) por padrão, aceita --dfs pra seguir uma cadeia específica, --budget pra limitar a saída em tokens (padrão 2000) e --graph pra apontar outro arquivo. Ao lado dele vivem o path, que traça a rota entre dois nós, e o explain, que descreve um nó e a vizinhança dele. Os três leem o mesmo graphify-out/graph.json, gerado antes pela construção do grafo.

Pedir contexto pro assistente e consultar um grafo determinístico são duas coisas MUITO diferentes

No primeiro caso o modelo vasculha, chuta e às vezes acerta

No segundo, ele lê uma estrutura que já foi extraída do seu código, com origem marcada e linha de arquivo junto

É aí que entra o Graphify: uma skill open source que transforma uma pasta de código, com docs, schemas SQL, configs e PDFs, em um grafo de conhecimento consultável, usando parsing AST determinístico local e sem vector store

Funciona com Claude Code, Cursor, Codex e Gemini CLI

E depois que o grafo existe, você tem três portas pra perguntar pra ele: query, path e explain

Bora ver como cada uma se usa no dia a dia?

O que você precisa antes de consultar

Antes de qualquer pergunta, três coisas precisam estar no lugar

1. A ferramenta instalada. A instalação recomendada é via uv, e aqui tem uma pegadinha: o pacote no PyPI se chama graphifyy (com dois y), mas o comando de terminal é graphify mesmo

uv tool install graphifyy

# alternativas
pipx install graphifyy
pip install graphifyy

O erro comum deste passo: digitar pip install graphify com um y só e ficar bravo com o terminal 😀

2. A skill registrada no assistente. O comando abaixo registra o Graphify nos assistentes de código, e a flag --project instala a skill no repositório atual em vez do perfil do usuário

graphify install

# só no repositório atual
graphify install --project

3. O grafo construído. Esse é o passo que a galera esquece

A construção roda no diretório atual por padrão, e também aceita uma pasta específica

/graphify
/graphify ./raw

Existem flags de modo e atualização pra essa etapa: --mode deep, --update, --cluster-only, --no-viz e --watch

Uma execução escreve o diretório graphify-out/, e é dele que sai tudo:

  • graph.json: o grafo persistente, que as consultas leem depois
  • GRAPH_REPORT.md: relatório com god nodes e conexões inesperadas
  • graph.html: visualização interativa

Além disso sai um vault compatível com Obsidian, o que agrada quem já mistura IA com o segundo cérebro

Sem graph.json não existe consulta, porque não existe o que consultar

Guarda isso, porque é a causa de metade das frustrações com os três comandos abaixo

Como usar graphify query no dia a dia

Essa é a porta mais usada: você faz uma pergunta em linguagem natural e o Graphify percorre o grafo em largura (BFS) a partir dos nós que melhor casam com a pergunta, imprimindo o subgrafo relevante como texto

O retorno vem com caminhos explícitos e citações no formato arquivo:linha

  1. Faça a pergunta como você faria pra um colega
graphify query "what connects auth to the database?"

A saída mostra a rota com o rótulo da aresta e as citações de arquivo e linha, mais ou menos assim:

AuthService → SessionStore → DatabasePool   rótulo: EXTRACTED
src/auth/service.py:42 → src/db/pool.py:17

Repara que não é um resumo bonitinho inventado: é caminho, rótulo e linha

O erro comum deste passo: rodar a consulta antes de ter gerado o grafo

  1. Escolha a travessia conforme o tipo de pergunta

O padrão é BFS, que é ótimo pra reunir contexto amplo em volta do assunto

Quando você quer seguir UMA cadeia específica, troca pra busca em profundidade:

graphify query "how does the session token reach the pool?" --dfs

O erro comum deste passo: usar --dfs esperando aquele panorama largo da área

É o oposto: profundidade segue a linha, largura abre o leque

  1. Limite a saída em tokens com --budget

A flag limita a consulta a um número de tokens, e o padrão é 2000, dimensionado pra caber no contexto do assistente

graphify query "what connects auth to the database?" --budget 1500
  1. Aponte outro grafo com --graph

O valor padrão é graphify-out/graph.json, então você só mexe nisso quando tem mais de um grafo por perto

graphify query "where do the SQL schemas get loaded?" --graph ./outro-projeto/graphify-out/graph.json
  1. Chame do jeito que for mais confortável

Todos os comandos podem ser chamados como slash command dentro do assistente de código (/graphify ...) e também direto no terminal (graphify ...)

A mecânica é a mesma nos dois casos, inclusive pra quem já usa o Claude em português no fluxo do dia

Como usar graphify path para traçar a rota entre dois elementos

Aqui a pergunta é outra

O query responde "me explica essa área", e o path responde "esses dois se falam? por onde?"

  1. Passe origem e destino, nessa ordem
graphify path "AuthModule" "Database"

O comando recebe dois nós e devolve o caminho entre eles, mostrando a rota e o número de saltos

  1. Leia o número de saltos como sinal, não como sentença

Dois módulos que deveriam ser independentes e aparecem colados por poucos saltos é exatamente o tipo de coisa que você quer ver antes de refatorar

  1. Confira os nomes antes de acusar o comando de não achar nada

O erro comum deste passo: inventar o nome do nó

Você escreve "Auth" ou "banco" de cabeça, o grafo tem outra coisa, e o resultado vem vazio

Antes de brigar, abre o graphify-out/graph.json ou o GRAPH_REPORT.md e confere como o elemento aparece de verdade

E pra saber exatamente quais flags a sua versão aceita em cada comando, roda graphify --help, que lista todos os comandos e flags disponíveis na CLI

Como usar graphify explain para entender um nó

Esse é o comando de "o que diabos é isso aqui?"

  1. Peça a explicação de um nó específico
graphify explain "SwinTransformer"

O retorno é uma explicação em linguagem simples do nó e da vizinhança dele: o que é, onde vive, o que o chama e o que ele chama

  1. Use isso como leitura de contexto, não como aula genérica

O erro comum deste passo: pedir explain de um conceito que não virou nó no grafo, esperando aquela resposta genérica de LLM

A graça do comando é justamente ler o graph.json, então conceito que não está lá não tem o que ser explicado

Se a resposta veio pobre, quase sempre o problema é o grafo (construção rasa, pasta errada), não o comando

Quando usar query, quando usar path e quando usar explain

Três perguntas diferentes, três comandos

Situação Comando O que você recebe
Entrar numa área do código que você nunca abriu query "..." Subgrafo relevante em texto, com caminhos e citações arquivo:linha
Investigar acoplamento entre dois módulos path "A" "B" A rota entre os dois nós e o número de saltos
Onboarding em um símbolo específico explain "Nome" O que o nó é, onde vive, quem chama e quem ele chama

E tem uma leitura que vale pros três: o rótulo da aresta

Toda aresta retornada pelas consultas vem marcada assim:

  • EXTRACTED: lido direto do AST ou do texto
  • INFERRED: implicado por coocorrência
  • AMBIGUOUS: palpite do LLM

Isso é o que define quanta confiança você dá pra cada linha da resposta

Aresta EXTRACTED você trata como fato do código

Aresta AMBIGUOUS você trata como pista pra conferir com o olho, não como verdade

Só esse rótulo já muda o jeito de trabalhar, sério 🙂

Ajustes que valem a pena: budget, grafo alternativo e log de consultas

  1. Dimensione o --budget pro seu contexto

O padrão de 2000 tokens existe pra caber no contexto do assistente

Se você está lendo no terminal e quer mais material, sobe

Se está colando dentro de uma conversa já cheia, desce

  1. Aponte o --graph quando trabalhar com mais de um projeto

O padrão é graphify-out/graph.json, e o valor de apontar outro caminho aparece quando você mantém grafos separados de repositórios diferentes

  1. Ligue o log de consultas, se quiser histórico

O log grava em ~/.cache/graphify-queries.log no formato JSON Lines, com timestamp, pergunta, corpus, nós retornados e duração

Só que ele vem DESLIGADO por padrão e precisa de opt-in por variável de ambiente:

export GRAPHIFY_QUERY_LOG_ENABLE=1

# ou apontando um caminho seu
export GRAPHIFY_QUERY_LOG=./logs/graphify-queries.log

O erro comum deste passo: assumir que o log já está gravando desde a instalação e ir procurar histórico que nunca foi escrito

Conclusão

O hábito aqui é simples: constrói o grafo uma vez, depois escolhe a porta conforme a pergunta

Contexto de uma área inteira vai de query

Relação entre dois pontos vai de path

Entender um símbolo isolado vai de explain

E sempre olhando o rótulo da aresta antes de sair confiando 😀

Próximo passo concreto: roda graphify --help e vê todos os comandos e flags que a sua versão traz

Vale lembrar que as consultas também aparecem como slash command dentro do assistente, então dá pra deixar o assistente puxar o grafo sozinho enquanto trabalha

O repositório oficial fica em github.com/Graphify-Labs/graphify (o caminho antigo safishamsi/graphify aponta pro mesmo projeto), e a branch de desenvolvimento ativa é a v8

Até o próximo post!

Perguntas frequentes

Qual a diferença entre graphify query e graphify explain?

O query varre o grafo inteiro em busca de uma pergunta ampla, tipo "o que conecta auth ao banco?", e devolve um subgrafo com caminhos e citações arquivo:linha. Já o explain foca em UM nó só, tipo "SwinTransformer", e devolve o que ele é, onde vive, quem o chama e o que ele chama. Use query pra explorar uma área e explain quando já sabe o nome do elemento.

O que significam as marcações EXTRACTED, INFERRED e AMBIGUOUS nas respostas do Graphify?

São a origem de cada aresta retornada pela consulta. EXTRACTED é o que foi lido direto do AST ou do texto do código, INFERRED é o que foi implicado por coocorrência, e AMBIGUOUS é palpite do LLM. É essa marcação que separa fato de suposição na resposta.

Como deixar a resposta do graphify query mais curta ou mais longa?

Use a flag –budget, que limita a saída a um número de tokens e vem com padrão de 2000. Rodar a consulta com –budget 1500, por exemplo, reduz o tamanho da resposta.

Dá pra consultar mais de um grafo com o Graphify?

Sim, com a flag –graph, que aponta pro arquivo graph.json usado na consulta. O valor padrão é graphify-out/graph.json, então essa flag só entra em jogo quando você tem mais de um projeto com grafo gerado por perto.

O Graphify guarda um histórico das consultas feitas?

Existe um log de consultas, mas ele vem desligado por padrão. Pra ligar, é preciso opt-in pela variável de ambiente GRAPHIFY_QUERY_LOG_ENABLE=1 ou apontando um caminho com GRAPHIFY_QUERY_LOG, e aí o registro sai em ~/.cache/graphify-queries.log no formato JSON Lines, com timestamp, pergunta, corpus, nós retornados e duração.

Preciso estar no Claude Code pra usar o graphify query, path e explain?

Não, os três comandos funcionam direto no terminal, como graphify query, graphify path e graphify explain. Mas eles também podem ser chamados como slash command dentro do assistente de código, já que o Graphify é uma skill open source pra Claude Code, Cursor, Codex e Gemini CLI.



Escrito por | Matheus Battisti

Matheus Battisti
Fundador da Hora de Codar

Programador apaixonado pelo mundo das tecnologias, sempre buscando em aprender e se aprofundar em linguagens, frameworks e o que mais for necessário para executar um bom trabalho. Agora tem uma nova missão que é de passar seu conhecimento adiante para formar novos programadores e especializar mais os que já são.

Formações

Formação Vibe Coding

Formação Vibe Coding

Do Prompt ao Produto: Crie Software Real com IA

  • 474 aulas
  • 20 projetos
  • 39h 30min

Blog | Mais populares