Como manter o grafo do Graphify atualizado quando o código muda?

O agente te responde com uma confiança absurda sobre uma função que tu apagou semana passada

E ele não está mentindo de propósito, ele está lendo o mapa que tu deu pra ele

O grafo do Graphify não é um observador ao vivo do repositório, ele é uma FOTO: o estado do código no instante em que a extração rodou. Aí você refatora, move pasta, renomeia símbolo, faz merge de três branches, e a foto continua exatamente a mesma

Neste post você sai sabendo três coisas: como identificar que o mapa envelheceu, como atualizar o grafo do Graphify no fluxo normal de trabalho (na mão, em watch ou automático via git) e o que fazer quando a atualização incremental simplesmente não resolve

Bora? 😀

O que você precisa antes de atualizar o grafo

Antes de sair rodando comando, três coisas precisam estar de pé

1. O Graphify instalado. Tem uma pegadinha que confunde meio mundo: o pacote no PyPI se chama graphifyy, com dois y, mas o comando que fica na sua mão é graphify

A instalação recomendada é via uv:

uv tool install graphifyy

Se tu não usa uv, pipx e pip dão conta:

pipx install graphifyy
pip install graphifyy

E o pacote ainda publica dois extras opcionais, declarados entre colchetes logo depois do nome no pip install: um voltado pra quem vai servir o grafo por MCP e outro completão, com tudo junto

2. A skill /graphify copiada pra configuração do assistente. É isso que o comando install faz:

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

graphify install

No perfil do usuário ela fica em ~/.claude/skills/graphify/SKILL.md, valendo pra qualquer projeto

Se tu prefere que a skill viaje junto com o repositório (time inteiro na mesma versão), usa a flag de projeto:

graphify claude install --project

Aí o arquivo é gravado em .claude/skills/graphify/SKILL.md (ou .agents/skills/graphify/SKILL.md)

Se a palavra "skill" ainda é meio nebulosa pra você, vale entender antes como skills mudam o comportamento do agente, porque o resto do post assume isso funcionando

3. Um grafo já gerado. Ou seja, a pasta graphify-out/ existindo no projeto, com graph.json, manifest.json, GRAPH_REPORT.md e graph.html dentro

Além desses quatro arquivos, o contorno registrado na Issue #1007 cita ainda uma subpasta graphify-out/cache/, então não estranha se ela aparecer aí no seu projeto: ela entra na conversa lá no rebuild limpo

Sem esse primeiro grafo não tem o que atualizar, o update incremental precisa de uma base pra comparar

Como referência de versão, a mais recente publicada é a v0.9.47, de 19 de agosto de 2026. O projeto é open source e vive no repositório oficial no GitHub

Passo a passo para manter o grafo em sincronia com o código

A lógica aqui é de escada: começa no manual, sobe pro contínuo, termina no automático

1. Atualização incremental sob demanda

Este é o feijão com arroz. A skill oficial expõe o modo --update, que faz re-extração incremental apenas dos arquivos novos ou alterados:

/graphify <caminho> --update

Fora do assistente, a CLI tem o equivalente:

graphify update

A ideia é simples: terminou o bloco de mudanças, roda o update ANTES de pedir qualquer análise pro agente

O erro comum deste passo: tratar um retorno de "already clean" como prova de que o grafo está correto. Existe um caso reportado de falso negativo justamente aí, e a gente volta nele mais pra frente

2. Modo watch em terminal separado

Durante o desenvolvimento contínuo, ficar lembrando de rodar update é chato e você vai esquecer

O modo watch resolve as atualizações estruturais rápidas enquanto tu programa:

graphify . --watch

Ele roda em um terminal separado, então deixa uma aba dedicada pra ele e segue a vida na outra

O erro comum deste passo: achar que o watch cobre TODO tipo de arquivo. Tem um comportamento reportado na Issue #483 em que mudanças em docs, papers e imagens são detectadas e o arquivo de sinalização graphify-out/needs_update é escrito, mas a re-extração semântica não é acionada. Ou seja: o watch levanta a bandeira, quem age é você

3. Automatizar com hooks de git

Aqui a coisa fica boa, porque para de depender da sua memória

graphify hook install

Esse comando instala hooks que reconstroem o grafo automaticamente depois de cada commit (post-commit) e depois de cada troca de branch (post-checkout)

E tem um detalhe MUITO massa junto: ele também configura um merge driver do git pro graphify-out/graph.json, evitando que o arquivo apareça cheio de marcador de conflito toda vez que dois devs commitarem grafos diferentes

Pra conferir e pra desfazer:

graphify hook status
graphify hook uninstall

Que interpretador o hook usa? Essa é a pergunta certa. Na instalação, o graphify hook install grava o caminho do interpretador atual dentro dos scripts de hook. O motivo é prático: assim o post-commit funciona mesmo em cliente gráfico de git e em runner de CI, onde ~/.local/bin normalmente não está no PATH

E se o rebuild falhar, o hook sai com código diferente de zero, então a quebra aparece em vez de passar batido

O erro comum deste passo: instalar os hooks e nunca mais olhar. Se você reinstalou o Graphify em outro interpretador (trocou de uv pra pipx, mudou a versão do Python, recriou o ambiente), o caminho gravado lá dentro é o antigo. Roda graphify hook status pra checar

4. Entender a proteção contra perda de dados antes de forçar qualquer coisa

Desde a v0.5.0 existe uma trava: a atualização se recusa a sobrescrever o graph.json quando o grafo reconstruído tem MENOS nós que o existente

Isso é um airbag, não um bug. Um grafo que encolheu do nada geralmente significa varredura incompleta, e sobrescrever ali seria trocar um mapa bom por um mapa capenga

Quando você REALMENTE quer o encolhimento (apagou um módulo inteiro, por exemplo), dá pra forçar:

graphify update --force
GRAPHIFY_FORCE=1 graphify update

O erro comum deste passo: forçar por reflexo, sem olhar o motivo. Tome cuidado! Se você não deletou nada relevante e mesmo assim o grafo veio menor, o --force só sepulta a evidência

5. Reforçar a leitura pelo grafo em vez do código cru

Grafo atualizado que o agente não consulta não serve pra nada

O modo estrito bloqueia a primeira leitura de código-fonte cru da sessão e redireciona a consulta pro grafo:

graphify install --strict

E a consulta em si é feita pelo subcomando query da skill, que percorre nós, comunidades e caminhos pra montar a resposta:

/graphify query "quem chama a função de autenticação?"

O erro comum deste passo: ligar o modo estrito com o grafo desatualizado. Aí você juntou o pior dos dois mundos: o agente é empurrado pro mapa e o mapa está velho. Estrito pressupõe rotina de update, então instala o hook primeiro

6. Commitar sem medo do ruído de diff

Muita gente evita versionar a saída do Graphify por causa de diff barulhento a cada rodada

Esse motivo caiu: uma correção no changelog fez o graphify update parar de reescrever os timestamps do manifest.json em execução sem mudanças, e tornou estável a ordem dos campos do graph.json

Na prática: rodar update em grafo inalterado produz arquivo byte a byte idêntico, e a pasta graphify-out/ não fica aparecendo como modificada no git à toa

O erro comum deste passo: commitar o grafo sem ter instalado os hooks. Sem o merge driver, o graph.json vira campo de batalha em todo merge

Sinais de que o mapa envelheceu (e o que fazer em cada caso)

Mapa derivado de uma fonte que muda é um problema de manutenção clássico, não é exclusividade do Graphify: quem trabalha com manter um notebook do Gemini em dia conhece bem essa sensação de perguntar pra uma versão antiga da verdade

Antes dos sintomas, dois conceitos que explicam metade deles

Por que mover a pasta do projeto quebra a detecção incremental

O manifest.json guarda o cache de detecção incremental usando caminhos ABSOLUTOS, mais o mtime e o hash de cada arquivo

Já os nós do graph.json usam caminhos RELATIVOS

Então são duas convenções diferentes no mesmo diretório de saída. Se o repositório foi clonado em outro caminho, movido de pasta ou está rodando em outra máquina (CI, por exemplo), o manifest está falando de endereços que não existem mais ali

O que é um rebuild limpo, na prática:

Essa expressão vai aparecer várias vezes daqui pra frente, então bora fixar UMA receita e não ficar mudando o combinado a cada sintoma

Rebuild limpo é apagar o estado acumulado dentro de graphify-out/ e gerar o grafo de novo do zero:

rm graphify-out/graph.json
rm graphify-out/manifest.json
rm -rf graphify-out/cache/

De onde vem cada linha: o relato da Issue #1116 fala em limpar graph.json e o manifest, e o contorno da Issue #1007 fala em apagar manifest.json e a pasta cache/. A receita acima é a união das duas, pra você não ficar adivinhando qual apagar

Se a pasta cache/ não existir no seu projeto, o rm -rf simplesmente não tem o que apagar, sem drama

Sintoma: símbolo que você apagou continua aparecendo

Causa provável: existe um comportamento reportado na Issue #1116, aberta em 2 de junho de 2026, em que símbolos removidos de arquivos que CONTINUAM existindo não são podados do grafo. Eles sobrevivem a todo rebuild incremental, e o relato atinge tanto o graphify update quanto o hook post-checkout

Correção: rebuild limpo, a receita ali de cima, e gerar o grafo de novo

Como prevenir: depois de refatoração pesada (extrair função, renomear em massa, apagar métodos de uma classe que continua no lugar), não confie no incremental. Trata refatoração grande como gatilho de rebuild limpo

Sintoma: arquivo deletado ou movido ainda tem nós e arestas no grafo

Causa provável: a Issue #1007 reporta exatamente isso, nós e arestas de arquivos deletados ou movidos persistindo, com direito a um falso "already clean" que te dá a impressão de que está tudo certo

Correção: rebuild limpo de novo, a mesma receita. O contorno descrito na issue foca em apagar o graphify-out/manifest.json e a pasta graphify-out/cache/, que já estão lá dentro

Como prevenir: movimentação de arquivo é o caso mais perigoso, porque some do lugar antigo e nasce no novo. Se a sua semana foi de reorganizar diretórios, já entra no rebuild limpo direto

Sintoma: as arestas semânticas sumiram, mas a estrutura está certa

Causa provável: a Issue #857 descreve o manifest compartilhado entre modos causando o problema. O update carimba o hash novo do arquivo, e depois o extract olha esse hash, acha que está tudo em dia e pula o arquivo. Resultado: arquivo semanticamente desatualizado, arestas semânticas que nunca são inferidas

Correção: a proposta registrada na própria issue é separar ast_hash e semantic_hash no manifest. Enquanto isso, quem zera o carimbo é o rebuild limpo

Como prevenir: se você alterna entre update e extract no mesmo repositório, desconfie quando o grafo tiver os arquivos certos mas as relações entre eles parecerem rasas

Sintoma: mudei a documentação e nada aconteceu

Causa provável: aquele comportamento do watch que a gente viu no passo 2. Mudanças em docs, papers e imagens são detectadas e o arquivo graphify-out/needs_update é escrito, porém a re-extração semântica não é disparada (Issue #483)

Correção: rodar a atualização na mão depois de mexer nesse tipo de arquivo

Como prevenir: olha a existência do graphify-out/needs_update como um recado, não como um relatório de trabalho concluído

Sintoma: atualizei o grafo e o MCP continua respondendo o antigo

Causa provável: a Issue #874 reporta que o servidor MCP faz cache do graph.json na inicialização e segue servindo o grafo antigo, mesmo depois de um graphify update bem sucedido

Correção: reiniciar o processo MCP

Como prevenir: se o seu fluxo é via MCP, coloca o restart do servidor no mesmo ritual do rebuild. Não adianta o arquivo em disco estar novo se quem responde está com a cópia velha na memória

E as correções que já entraram

Nem tudo é sintoma em aberto, se liga em duas melhorias que reduziram falso positivo de poda

A v0.9.13 corrigiu a remoção indevida de nós de arquivo que saiu do corpus de varredura mas ainda existe em disco (referente à #1795), mantendo a poda só pra deleção genuína

E a v0.9.35 passou a remover do grafo existente os arquivos que foram recém-ignorados (referente à #2495), o que resolve o caso de você adicionar um padrão no ignore e o conteúdo continuar fantasma no mapa

Moral: manter a versão em dia faz parte da estratégia de sincronia

Qual estratégia de regeneração usar em cada rotina de trabalho

Comando solto não ajuda ninguém, o que ajuda é saber qual liga em qual rotina

Destrinchando cada uma

Sessão curta de refatoração. Você entra no repositório pra mexer em duas ou três coisas e sair. Aqui watch é overkill, roda o update na mão, depois pergunta. A ordem importa: primeiro atualiza, depois consulta

Desenvolvimento contínuo. Dia inteiro no mesmo projeto, dezenas de arquivos tocados. O watch em terminal separado segura as atualizações estruturais rápidas, e você complementa com update manual quando mexer em docs e afins

Time com muitos merges e trocas de branch. É o cenário que mais quebra grafo, porque o post-checkout troca meio repositório de uma vez. Os hooks resolvem sem depender de ninguém lembrar, e o merge driver do graph.json evita que o arquivo de saída vire fonte de conflito em todo pull request

Pipeline de CI. Como o interpretador fica embutido no script do hook na instalação, o rebuild roda no runner mesmo sem ~/.local/bin no PATH. E o exit code diferente de zero em falha de rebuild te dá o sinal: grafo quebrado aparece como falha, não como silêncio

Faxina periódica. Essa é escolha SUA, não é comportamento do Graphify. Como existem relatos de símbolo órfão e de arquivo deletado sobrevivendo ao incremental, marcar um rebuild limpo de tempos em tempos é seguro de vida barato

Onde está a fronteira, pra ficar bem claro: hooks, watch, update incremental, proteção da v0.5.0 e merge driver são comportamento da ferramenta. A cadência da faxina, o que entra no CI e quando você força um rebuild são decisão sua

Vídeo: o contexto de Claude Code por trás desse fluxo

Todo esse fluxo acontece dentro do assistente onde a skill /graphify roda, então vale conhecer o terreno

Pra pegar o contexto do Claude Code atual, este vídeo do canal mostra 5 novidades do Claude Opus 4.7 que mexem no jeito de trabalhar com o assistente

Conclusão

A régua fica bem simples quando você separa em três níveis

Incremental pro dia a dia, com graphify update e /graphify <caminho> --update

Hooks pra não depender da sua disciplina, com graphify hook install cuidando de post-commit, post-checkout e do merge driver do graph.json

Rebuild limpo quando o grafo mente, apagando graph.json, manifest.json e a pasta cache/ de dentro de graphify-out/ antes de reconstruir

Próximo passo prático, e é coisa de dois minutos: roda graphify hook install no seu repositório principal, confere com graphify hook status e valida o resultado fazendo uma pergunta com /graphify query sobre algo que você acabou de mudar. Se a resposta refletir o código de agora, tá em sincronia

E vale saber onde tudo isso vive: o Graphify é licenciado como MIT, faz parsing local determinístico via tree-sitter e não usa banco vetorial, o que explica por que a atualização é uma questão de re-extração de arquivo, e não de reindexar embedding. O repositório oficial é o Graphify-Labs/graphify, criado por Safi Shamsi (safishamsi no GitHub), fundador da Graphify Labs, e é lá que as issues de sincronia ficam registradas pra quem quiser acompanhar de perto

Bora deixar o mapa em dia? 😀

até o próximo post!