Graphify em projeto legado: ele ajuda o Claude Code a entender um código que ninguém mais entende?
Rodar o Graphify no Claude Code em base legada serve pra uma coisa bem específica: ganhar orientação rápida sobre um código que ninguém no time entende inteiro. O parsing é local, com tree-sitter, sem conta e sem chave de API pra parte estrutural, e a saída cai em graphify-out/ com grafo interativo, relatório de arquitetura e JSON. O relatório aponta god nodes, comunidades e conexões cruzadas inesperadas, e cada aresta vem etiquetada como EXTRACTED, INFERRED ou AMBIGUOUS. O que ele não entrega: intenção de negócio, motivo histórico da gambiarra e busca difusa em texto corrido, que segue sendo território de embeddings
Fala aí, beleza? Todo mundo já pegou aquele repositório: dez anos de camadas, três gerações de dev que já saíram, README de 2019 mentindo sobre como sobe o projeto
Aí você abre o Claude Code, joga uma pergunta e ele faz o que dá: lê alguns arquivos, chuta um caminho, às vezes acerta
O Graphify propõe outra entrada nesse problema: em vez de reler a base a cada pergunta, ele constrói um grafo do código, lido localmente, e deixa esse mapa disponível pro assistente consultar
O projeto foi criado por Safi Shamsi e hoje é mantido pela Graphify Labs, empresa fundada por ele e aceita no batch S26 da Y Combinator
Um detalhe que anda circulando errado por aí: Andrej Karpathy NÃO é autor nem mantenedor disso
Ele publicou a ideia de usar LLM como compilador de conhecimento (transformar documento bruto em base estruturada e navegável, em vez de refazer busca a cada pergunta) e o Graphify apareceu depois como uma implementação dessa ideia, feita por terceiros
A pergunta do post é essa: num legado sem documentação, esse mapa ajuda mesmo? E o que ele NÃO resolve?
Domine o Claude Code do básico ao avançado
Você vai aprender a criar sistemas completos com Claude Code, sem precisar ser programador. Inscreva-se para ter acesso a um desconto de lançamento e bônus especiais!
Dor do projeto legado x o que o mapa do Graphify entrega
Antes do como, o porquê: cada dor clássica de legado tem (ou não tem) um artefato correspondente ali
| Dor no legado | O que o Graphify entrega | O que sai disso na prática |
|---|---|---|
| Não sei por onde começar | graphify-out/GRAPH_REPORT.md com perguntas sugeridas sobre a base |
Um roteiro de leitura pronto, em vez de abrir arquivo no chute |
| Onde mora a lógica central? | God nodes (os nós mais conectados) e a ferramenta god_nodes no MCP |
Lista curta de pontos que concentram conexão, ótimo ponto de partida |
| O que conversa com o que? | Comunidades (clusters indexados por tamanho) e get_community |
Divide a base em blocos com sentido, em vez de pasta por pasta |
| Esse módulo devia mesmo falar com aquele? | Conexões cruzadas inesperadas entre comunidades | Acoplamento suspeito aparece explicitamente no relatório |
| O que quebra se eu mexer aqui? | get_node e get_neighbors |
O nó em si e a vizinhança direta dele, com citação de arquivo e linha |
| Como o A chega no B? | shortest_path |
O caminho entre dois pontos, sem você caçar chamada por chamada |
| Quero ver o desenho geral | graphify-out/graph.html |
Grafo interativo pra olhar com olho humano mesmo |
| Quero cruzar isso com script | graphify-out/graph.json |
Versão legível por máquina do mesmo grafo |
| Qual o tamanho da coisa? | graph_stats e query_graph |
Consulta direta no grafo pelo cliente MCP |
| Chegou PR de gente que já saiu | list_prs, get_pr_impact e triage_prs |
Três ferramentas de PR expostas pelo MCP, ao lado das de grafo |
São dez ferramentas no total no servidor MCP, chamadas nativamente pelo cliente
E tem um ponto que importa MUITO em legado: as respostas voltam como contexto em texto, com citação file:line, e cada aresta carrega sua etiqueta de confiança
Ou seja, dá pra desconfiar da resposta olhando a procedência, não só a prosa 🙂
Quatro situações de base legada em que o grafo muda o dia
1. Primeiro contato com o repositório
Você acabou de herdar a base e não tem ninguém pra perguntar
Aqui o GRAPH_REPORT.md funciona como sumário executivo da arquitetura: god nodes, comunidades por tamanho, conexões cruzadas inesperadas, auditoria de confiança e as perguntas sugeridas sobre a base
Essas perguntas sugeridas valem como pauta da primeira conversa com o assistente, e combinam bem com o roteiro que já rolou por aqui sobre entender um projeto legado herdado
2. Avaliar impacto antes de encostar num arquivo central
O clássico: o arquivo tem 3 mil linhas, todo mundo tem medo dele e ninguém sabe quem depende dali
Em vez de abrir e rezar, você pergunta e o assistente percorre o grafo: god_nodes pra confirmar se aquilo é mesmo um centro de gravidade, get_neighbors pra ver quem encosta nele, shortest_path pra entender como a chamada chega lá de outro canto do sistema
O ganho não é "a IA decide por você", é você chegar na revisão sabendo o raio de explosão
3. Revisar mudança que veio de terceiro
O MCP também expõe list_prs, get_pr_impact e triage_prs
São ferramentas de PR listadas ao lado das de grafo, voltadas justamente pra olhar mudança e impacto
Na prática isso significa que a conversa sobre um PR acontece no mesmo lugar em que o mapa da base já vive, com as mesmas citações file:line e as mesmas etiquetas de confiança
4. Juntar o código com o que NÃO é código
Essa parte é interessante e pouca gente nota
O código é lido localmente com tree-sitter, parsing determinístico de AST, com 36 linguagens empacotadas, sem chamada de modelo e sem mandar o fonte pra fora
Já o que não é código (documento, PDF, schema SQL, Postgres ao vivo, Terraform) passa por uma etapa semântica que roda pelo backend de modelo que você já tem configurado, não pelo parser local
Então são dois regimes diferentes de confiança e de privacidade dentro da mesma ferramenta, e vale saber disso antes de apontar pra um repo de cliente
O que o Graphify não substitui no entendimento do legado
Agora a parte honesta, que é onde a maioria dos posts sobre a ferramenta some
| O mapa resolve | Continua sendo trabalho seu (ou de outra ferramenta) |
|---|---|
Aresta EXTRACTED: veio direto da AST |
Saber se aquela relação faz sentido arquitetural, o parser só diz que ela existe |
Aresta INFERRED: o modelo ligou os pontos |
É julgamento marcado como julgamento, então confere no código antes de agir |
Aresta AMBIGUOUS: evidência não resolvida |
Ela é mantida e sinalizada em vez de chutada, mas quem resolve é você |
| Estrutura estática do código | Despacho dinâmico, reflexão e ligação feita por configuração ou import montado em string ficam sinalizados como incertos |
| Relação estrutural entre partes | Busca difusa em texto corrido: a própria documentação assume que aí embeddings continuam sendo a ferramenta certa |
| Onde a coisa está e com quem ela fala | Por que ela foi feita assim: intenção, regra de negócio e o motivo histórico da gambiarra não estão no grafo |
Repara na última linha, porque ela é a mais importante em legado
O grafo te diz que o PedidoService conversa com sete lugares
Ele não te diz que aquele if esquisito existe porque em 2021 um cliente grande exigiu uma exceção fiscal e ninguém documentou
Pra esse tipo de contexto que vive em documento solto, ata e PDF, a saída costuma ser outra: dá pra usar o NotebookLM pra ler documentação e tirar dúvida em cima do material antigo, enquanto o grafo cuida da estrutura
Ferramenta diferente pra pergunta diferente, beleza?
Como apontar o Graphify para um repositório legado
Bora ver na prática? São poucos passos, e dois deles têm pegadinha
- Instale a CLI. A via recomendada é o
uv
uv tool install graphifyyAlternativas: pipx install graphifyy ou pip install graphifyy
O erro comum deste passo: o pacote no PyPI é graphifyy, com dois yy, enquanto o comando no terminal é graphify, com um só. Trocar isso é o erro número um da instalação
- Ligue a skill no assistente
graphify installÉ esse comando que copia a skill /graphify pra configuração do assistente. No Claude Code, ele detecta o cliente e liga tanto a skill quanto o servidor MCP do Graphify
E não é exclusividade do Claude Code: a skill /graphify funciona também em Cursor, Codex e Gemini CLI, além do acesso por MCP e pela CLI
O erro comum deste passo: achar que instalar o pacote já habilitou a skill. Não habilita. Pacote instalado e assistente configurado são duas coisas separadas
- Se você não quer sujar seu perfil de usuário, prenda a skill só naquele repositório
graphify install --projectÚtil quando o legado é de cliente e você não quer aquilo ligado em tudo
- Dentro da sessão, dispare o mapeamento apontando pra pasta
/graphify .- Leia o que caiu em
graphify-out/
São três arquivos: graph.html (grafo interativo), GRAPH_REPORT.md (o relatório de arquitetura) e graph.json (versão legível por máquina)
Começa pelo GRAPH_REPORT.md, é o que tem god nodes, comunidades, conexões cruzadas e as perguntas sugeridas
- Mantenha o mapa vivo sem refazer tudo
A flag --update reprocessa só o que mudou, usando cache SHA256 por arquivo
- Ou deixe rodando enquanto você trabalha
graphify watch .Esse reconstrói o grafo ao salvar, o que faz sentido quando você já está mexendo na base e não quer consultar mapa vencido
Vale usar o Graphify no seu legado? Veredito
Vou ser direto
Vale pra quem chega em base grande, antiga e sem documentação e precisa de orientação: onde olhar primeiro, o que é centro de gravidade, o que conversa com o que
O custo de entrada é baixo pro que ele entrega: a parte estrutural é puro parsing on-device, sem conta e sem API key, e o fonte não sai da sua máquina nesse trecho
Não vale se a sua pergunta é sobre intenção, regra de negócio ou busca difusa em texto corrido
Nesse caso o grafo vai te dar estrutura bonita e resposta rasa, e a própria documentação admite que ali embeddings seguem sendo a escolha certa
Sobre maturidade: o projeto está na série 0.9.x, com releases publicadas ao longo de agosto de 2026 (a v0.9.47 entre elas), licença Apache 2.0 (antes era MIT) e cerca de 108 mil estrelas no GitHub
Leia isso como o que é: tração alta e produto ainda em movimento rápido, então não conte com API congelada
Conclusão
A régua é essa: o mapa acelera a ORIENTAÇÃO, ele não entrega compreensão pronta
Quem confundir as duas coisas vai sair refatorando em cima de aresta INFERRED e depois culpar a IA, e aí não foi a IA, foi a leitura ruim do sinal 😀
Próximo passo prático, se quiser tirar a limpo: roda o mapeamento em UM módulo do legado, não na base inteira
Lê o GRAPH_REPORT.md prestando atenção nas etiquetas de confiança, e usa as perguntas sugeridas como pauta da primeira conversa com o Claude Code sobre aquele código
Se der certo nesse módulo, aí sim você amplia
Pra ir mais fundo, a documentação fica em graphify.com/docs e o repositório na organização Graphify-Labs
Até o próximo post!
Perguntas frequentes
O Graphify manda o código para algum servidor externo?
Não, na parte estrutural. O código é lido localmente com tree-sitter, parsing determinístico de AST, sem chamada de modelo e sem enviar o código-fonte para fora. Já o que não é código, como documentos, PDFs, schemas SQL e Terraform, passa por uma etapa semântica que roda pelo backend de modelo que você já tem configurado, não pelo parser local.
Como instalar o Graphify no Claude Code?
A instalação recomendada da CLI é via uv, com o comando uv tool install graphifyy (o pacote no PyPI tem dois yy, o comando no terminal é graphify). Depois roda graphify install, que copia a skill /graphify e liga o servidor MCP do Graphify no Claude Code. Se quiser instalar só no repositório atual em vez do perfil do usuário, usa a flag –project.
Preciso de conta ou API key para gerar o grafo do código?
Para a parte estrutural, não. O grafo é puro parsing on-device com tree-sitter, sem conta e sem API key. A conta ou chave só entra em cena indiretamente, na etapa semântica sobre o que não é código, porque ali quem processa é o backend de modelo que você já configurou.
Qual a diferença entre as tags EXTRACTED, INFERRED e AMBIGUOUS no grafo?
EXTRACTED é a aresta que veio direto da AST, ou seja, o parser confirmou a relação no código. INFERRED é quando o modelo ligou os pontos, marcado explicitamente como julgamento. AMBIGUOUS é a evidência que o Graphify não conseguiu resolver, mantida e sinalizada em vez de chutada, como acontece com despacho dinâmico, reflexão e ligação feita por configuração.
O Graphify funciona só no Claude Code?
Não, a skill /graphify também funciona em Cursor, Codex e Gemini CLI, além do acesso via MCP e CLI. No Claude Code especificamente, o graphify install liga tanto a skill quanto o servidor MCP com as dez ferramentas sobre o grafo.
Como atualizar o grafo depois de mudar o código, sem reprocessar tudo de novo?
Tem duas formas. O –update reprocessa só o que mudou, usando cache SHA256 por arquivo, e o graphify watch . reconstrói o grafo automaticamente a cada save. Nenhum dos dois exige remapear a base inteira do zero.
Formações
Formação Vibe Coding
Do Prompt ao Produto: Crie Software Real com IA
- 474 aulas
- 20 projetos
- 39h 27min
Blog | Mais populares
As diferenças de var, let e const
Como fazer redirecionamento com PHP
Neste artigo você vai aprender a como fazer redirecionamento com PHP, utilizaremos abordagens fáceis de entender e de aplicar Fala programador(a), beleza? Bora aprender mais […]
Checklist de segurança n8n VPS pública: guia essencial para proteger sua instalação
Checklist de segurança n8n VPS pública: guia essencial para proteger sua instalação A popularidade da automação de processos com o n8n está em alta, principalmente […]
