Graphify: como descobrir quem depende da função antes de refatorar no Claude Code

Refatorar sem saber quem chama a função é apostar que ninguém do outro lado do repo vai gritar

E geralmente alguém grita 😀

O Graphify é uma CLI e uma skill open source (licença Apache 2.0) que transforma o teu repositório num grafo de conhecimento consultável pelos assistentes de IA

O parsing acontece no próprio dispositivo, com tree-sitter, AST determinística, sem telemetria e sem upload do código

Pra extração estrutural não precisa nem de conta nem de chave de API

E por que isso importa antes de uma refatoração?

Porque grep e LSP respondem UM salto: quem chama essa função aqui

A pergunta real que tu tem na cabeça é outra, "o que quebra se eu mudar isso", e essa é chamador do chamador do chamador

É multi-salto, e é exatamente o buraco que um grafo de código preenche

Bora ver na prática?

Formação Recomendada

Formação Claude Code

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

• 114 aulas
• 4 projetos
• 9h 18min

Conhecer formação

O que você precisa antes de começar:

A lista é curtinha, se liga:

• Claude Code instalado, que é a plataforma padrão da skill (ela suporta 17 assistentes, incluindo Cursor, Copilot, Codex, Gemini CLI e Aider)
• uv, que é o instalador recomendado do pacote
• o repositório que tu vai refatorar em disco, claro

Sobre cobertura de linguagem: o parser lê 36 linguagens de código, além de Markdown, SQL e outros formatos

Então não é ferramenta de uma stack só

Tome cuidado com a maturidade! O projeto ainda está na série 0.x

A versão mais recente publicada é a v0.9.47, de 19 de agosto de 2026, e antes dela vieram a v0.9.46 em 17/08, a v0.9.45 em 16/08 e a v0.9.44 em 15/08, tudo no mesmo mês

Isso é ótimo sinal de projeto vivo, mas significa que comando e comportamento podem mudar debaixo do teu pé

Passo a passo: mapear as dependências da função que você vai mexer

1. Instale o pacote com o uv

uv tool install graphifyy

Repara no nome: o pacote tem dois "y" no fim

O binário que fica instalado se chama graphify, com um "y" só

O erro comum deste passo: tentar uv tool install graphify e não achar o pacote, aí tu acha que a ferramenta sumiu do mundo kkk

2. Registre a skill no assistente

graphify install

Esse comando detecta o Claude Code e registra a skill /graphify

O erro comum deste passo: achar que instalar o pacote já habilita a skill

Não habilita! São dois momentos separados, um instala a ferramenta e o outro pluga ela no assistente

3. Construa o grafo do projeto

Agora dentro da sessão do assistente, não no terminal:

/graphify .

Ele mapeia o projeto e escreve o resultado na pasta graphify-out/

São três arquivos de saída:

4. Pergunte quem depende da função

graphify query "quem depende dessa função?"

O query percorre o grafo em largura e devolve o subgrafo relevante, com os caminhos explícitos e citações no formato arquivo:linha

É isso que tu quer antes de mexer: o caminho, não só o nome do arquivo

Se tu já sabe qual cadeia quer seguir e não quer contexto amplo, existe a opção --dfs pra seguir uma linha específica

A mesma consulta roda dentro do chat pela skill, o exemplo oficial é assim:

/graphify query "how does a request reach the cache?"

5. Feche a ponta a ponta e entenda o nó isolado

Quando tu quer saber COMO duas partes do sistema se conectam, o comando é o path, que acha o caminho mais curto entre dois nós e mostra salto a salto

Exemplo oficial pela skill:

/graphify path "ApiGateway" "RedisClient"

Os extremos são casados por label, então tu passa o nome da coisa

E pra entender um nó sozinho tem o graphify explain, que diz em linguagem natural o que aquele nó é, onde ele vive, o que chama ele e o que ele chama

6. Atualize o retrato depois de mexer no código

O grafo é uma foto do momento, e refatoração é justamente mudar o que está na foto

A flag --update re-escaneia só o que mudou, e ainda tem modo watch e git hook pra automatizar isso

O erro comum deste passo (e é o mais traiçoeiro): consultar grafo velho depois de já ter mexido no código, e decidir a próxima mudança olhando pra um mapa que não existe mais

7. Opcional: pluga o servidor MCP

Existe um servidor MCP que expõe o grafo como ferramentas nativas do assistente, são 10 ferramentas entre consultas estruturais, rastreio de caminhos e explicação de nós

Pra registrar manualmente no Claude Code, tu adiciona a entrada no .mcp.json na raiz do projeto apontando pro comando python -m graphify.serve graphify-out/graph.json

Como ler o resultado para dimensionar o estrago da refatoração

Ter o subgrafo na tela é metade do trabalho

A outra metade é ler ele com três perguntas na cabeça, antes de pedir qualquer coisa pro assistente

Raio de impacto: quantos saltos acima existe gente chamando isso?

Se o query devolve dois chamadores diretos e para por aí, tu tem uma mudança local

Se ele sobe três, quatro níveis e vai parar em módulos que tu nem lembrava que existiam, o pedido de refatoração muda de tamanho

Esse é o momento de decidir se vale fatiar a mudança, e é MUITO parecido com a régua de saber se vale delegar a tarefa antes de escrever o prompt

Caminho crítico: como as duas pontas se conectam de fato

O path te dá a cadeia salto a salto entre duas partes do sistema

Serve pra confirmar (ou destruir) aquela tua suposição de "ah, isso aqui só é usado pelo módulo X"

É o tipo de conferência que economiza uma tarde inteira quando o assunto é refatorar um projeto legado, onde a suposição costuma estar errada

Confiança da evidência: o rótulo de procedência da aresta

Essa parte é a que eu acho mais massa

Toda aresta do grafo carrega de onde ela veio:

• EXTRACTED: veio direto da AST, é o chão firme
• INFERRED: um modelo ligou os pontos
• AMBIGUOUS: existe evidência, mas não deu pra resolver

E quais casos caem em AMBIGUOUS? Dynamic dispatch, reflection e imports montados por string

Ou seja: em vez de chutar uma ligação que ficaria bonita no desenho, a ferramenta marca que ali tem dúvida

Isso é honestidade de ferramenta, e é o que te diz ONDE olhar com olho humano

Vale saber também que a parte estrutural não chama modelo nenhum, mas os passos semânticos mais ricos (nomeação de comunidades, modo profundo) e a leitura de arquivos não-código usam modelo, rodando pela sessão do assistente ou por um backend configurado (que pode ser local, tipo Ollama, pra CI headless)

O que continua sendo trabalho humano de conferência

Aqui mora o limite da festa

O grafo mostra quem chama quem

Ele NÃO mostra o que a função faz com o estado compartilhado lá dentro

E dependência invisível é exatamente isso: nenhuma aresta aponta pra ela

No vídeo eu mostro esse efeito com o caso mais clássico do Python, a variável global usada dentro de uma função

A variável começa com 10 no escopo maior, a função recebe 20 como argumento e a soma imprime 30

Até aí tudo certo, ninguém se machucou

Aí eu reatribuo a variável pra 15 lá dentro, e a impressão seguinte vira 35

Quando o arquivo termina de rodar e eu imprimo a variável de novo, ela vale 15

O valor global mudou permanentemente

valor = 10

def somar(numero):
    global valor
    print(valor + numero)
    valor = 15
    print(valor + numero)

somar(20)
print(valor)

O ponto que fica desse exemplo é o seguinte: aquela alteração vaza pro resto da aplicação

Qualquer outra função ou trecho que dependa daquele valor passa a receber outra coisa, e o valor deixa de representar o que representava antes

Agora liga isso na refatoração: nenhuma aresta do grafo denuncia esse efeito

O grafo te entrega o mapa das chamadas, e o mapa está certo

Mas o efeito colateral no estado compartilhado é semântica de execução, não topologia

Por isso a ordem que eu sigo é: as arestas AMBIGUOUS e os pontos de estado compartilhado passam por leitura humana ANTES de aprovar a mudança

O resto tu delega tranquilo

Conclusão

A ordem de trabalho que faz o Graphify valer a pena é essa, e ela é chata de propósito:

1. constrói o grafo
2. consulta quem depende da função
3. confere à mão o que ficou AMBIGUOUS e o que toca estado compartilhado
4. só então pede a refatoração pro Claude Code

Inverter essa ordem é o mesmo que pedir a mudança e descobrir o raio de impacto pelo stack trace, depois

Próximo passo? Roda /graphify . no repositório que tu está mexendo hoje e abre o GRAPH_REPORT.md antes da próxima mudança grande

E não esquece do --update depois que o código mudar, senão tu volta a consultar um mapa velho…

até o próximo post! 🙂