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

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

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 120 aulas
• 4 projetos
• 9h 45min

Conhecer formação

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

2. 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

3. 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

4. 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

5. 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

2. 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

3. 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

2. 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

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

2. 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

3. 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!