Como ler o grafo que o Graphify gera do seu código (e o que fazer com ele)

Fala aí, beleza? Terminou de gerar, você abre o HTML e a tela vira um monte de bolinha ligada por linha

E aí, o que fazer com isso?

Essa é a parte que quase ninguém conta. O Graphify não te entrega um desenho bonito pra printar no LinkedIn, ele te entrega uma estrutura consultável

São três saídas diferentes, cada uma pra um consumidor diferente: uma pra você navegar, uma pra você ler e uma pra máquina perguntar

O valor real só aparece quando você sabe ler as três e devolve isso como contexto pro assistente, em vez de deixar o grafo aberto numa aba morrendo de tédio 😀

O que você precisa antes de ler o grafo

Lista curta, sem enrolação:

• O Graphify instalado. A instalação oficial é com uv tool install graphifyy, e o pacote também aceita pipx install graphifyy e pip install graphifyy
• O graphify install rodado, que registra a skill /graphify nos assistentes detectados, entre eles Claude Code, Cursor e GitHub Copilot
• A pasta graphify-out/ já gerada, com os três arquivos dentro: graph.html, GRAPH_REPORT.md e graph.json

uv tool install graphifyy
graphify install

Duas coisas que tiram um peso das costas antes de começar

O parsing é local e determinístico, feito com tree-sitter: não tem vector store, não tem conta, não tem chave de API e nada sai da máquina por padrão

E se o mapa já existe e o código andou, tu não precisa refazer tudo do zero: existe o graphify update, que atualiza o grafo já gerado sobre a pasta graphify-out/ (graph.json, GRAPH_REPORT.md e graph.html)

O projeto vive no repositório oficial no GitHub, caso tu queira olhar a fonte antes de instalar qualquer coisa na tua máquina

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

Como ler o grafo do Graphify passo a passo

A ordem importa MUITO aqui. Quase todo mundo começa errado, abrindo o HTML primeiro

1. Comece pelo GRAPH_REPORT.md, não pelo HTML. Ele é o resumo legível e já entrega mastigado o que tu levaria uma hora clicando pra descobrir: os god nodes, as conexões entre arquivos ranqueadas por quão inesperadas são, e um fecho com 4 a 5 perguntas que aquele grafo está em posição privilegiada de responder. O erro comum deste passo: abrir o graph.html primeiro, se perder na teia de bolinhas e concluir que a ferramenta é enfeite
2. Entenda o que é um god node antes de sair caçando um. God node é o nó de maior centralidade de intermediação (betweenness centrality), ou seja, o arquivo ou função que conecta o maior número de comunidades. Não é o arquivo maior, nem o mais chamado: é o que fica no meio do caminho de todo mundo. O erro comum deste passo: confundir god node com "arquivo grande" e sair refatorando o cara errado
3. Leia as comunidades como subsistemas. O grafo é montado com NetworkX e agrupado pelo algoritmo de Leiden (via graspologic), e cada comunidade que ele acha representa um subsistema do projeto. Se você conhece aquela sensação de "essa parte aqui é o módulo de cobrança", é exatamente isso, só que descoberto pela topologia e não pelo nome da pasta
4. Leia um nó. Cada nó carrega id (identificador estável), label (nome legível), file_type (code, document, paper, image ou rationale) e source_file, de onde ele veio. Repare no file_type: o grafo não é só código, documento e imagem entram como nó também
5. Leia uma aresta. Cada aresta carrega source e target (os ids dos nós), relation (o verbo da ligação, por exemplo calls, imports, implements, semantically_similar_to), confidence, confidence_score (só em INFERRED) e source_file. O relation é o que muda tudo: "A importa B" e "A parece semanticamente próximo de B" são histórias completamente diferentes. O erro comum deste passo: tratar toda linha do desenho como se fosse chamada de função
6. Trate as tags de confiança como níveis de prova diferentes. Isso aqui é o detalhe mais honesto da ferramenta, se liga na tabela logo abaixo
7. Aí sim abre o graph.html. Com o relatório lido, a visualização interativa no navegador vira exploração dirigida: tu clica, filtra e busca procurando uma coisa específica, não passeando. O erro comum deste passo: usar o HTML como ferramenta de descoberta em vez de ferramenta de confirmação
8. Percorra salto a salto pelos comandos. Tem /graphify query, que responde perguntas sobre a estrutura, /graphify path, que traça como duas partes do código se conectam, e /graphify explain, que percorre por que um nó importa. Na consulta tu passa a pergunta entre aspas, e ainda existem dois parâmetros opcionais documentados: --dfs e --context <c>
9. Guarde o graph.json sabendo o que ele é. Ele é o grafo completo no formato node-link do NetworkX, que é o formato que as ferramentas consultam. Não é arquivo pra você ler no olho, é arquivo pra máquina perguntar

A tabela do passo 6, que na minha opinião é a parte mais subestimada da saída:

Sacou a jogada? O AMBIGUOUS existe justamente pra evidência não resolvida ficar sinalizada como incerta em vez de virar chute silencioso no meio do mapa

E olha que isso é ouro: as arestas AMBIGUOUS são um mapa dos lugares onde o teu código é mágico demais pra ser lido estaticamente 😛

Como transformar o grafo em instrução para o Claude Code

Aqui é a virada. Ler o grafo é bom, mas o ganho de verdade é o assistente ler por você

1. Commite a pasta graphify-out/. Ela foi pensada pra ir pro repositório, assim quem faz pull recebe o mapa pronto sem precisar reconstruir nada. Um dev novo entra no time e o contexto já está lá
2. Confira a seção que a integração escreve no CLAUDE.md. Ela instrui o Claude a ler graphify-out/GRAPH_REPORT.md antes de responder perguntas de arquitetura. É o pulo do gato: em vez de o assistente adivinhar a estrutura, ele consulta o resumo que já foi calculado
3. Saiba onde a skill mora. No Claude Code, o graphify install grava a skill em ~/.claude/skills/graphify/SKILL.md. Com a flag --project, o destino passa a ser dentro do diretório atual, por exemplo .claude/skills/graphify/SKILL.md. O erro comum deste passo: instalar global, trocar de máquina e achar que a ferramenta quebrou
4. Repare no hook. A integração instala um hook PreToolUse no settings.json, que dispara antes de cada chamada de Glob e Grep. Traduzindo: bem no momento em que o assistente ia sair varrendo arquivo no braço, ele é lembrado de que existe um mapa. Vale a mesma manutenção que você faz em qualquer arquivo de config que envelhece no projeto, tipo quando descobre que o projeto ainda aponta pro Sonnet 3.5 e ninguém tinha percebido
5. Suba o servidor MCP se quiser o assistente consultando o grafo direto. O suporte a MCP vem de um extra do pacote graphifyy, o extra mcp, e o servidor sobe assim (stdio é o padrão):

python -m graphify.serve graphify-out/graph.json

6. Use o modo HTTP quando o grafo for compartilhado. Mesmo comando, com transporte e porta:

python -m graphify.serve graphify-out/graph.json --transport http --port 8080

7. Saiba o que o MCP coloca na mão do assistente. São 10 ferramentas expostas, entre elas query_graph, get_node, get_neighbors (todos os vizinhos diretos de um nó, com detalhe das arestas), shortest_path (como duas partes do código se ligam, salto a salto), list_prs, get_pr_impact e triage_prs
8. Não esqueça dos resources. O servidor também publica recursos: o GRAPH_REPORT.md completo, estatísticas do grafo, os god nodes, as conexões surpreendentes entre comunidades e as perguntas sugeridas. É contexto pronto, sem o assistente gastar token pra descobrir

O erro comum de TODA essa seção é um só: pedir arquitetura pro assistente sem apontar o relatório

Aí ele faz o que sempre fez, sai varrendo o repositório no Grep, enche a janela de contexto de arquivo irrelevante e te devolve um resumo meia boca. Tendo o mapa no repo e não usando, é desperdício puro

O que eu vi lendo o grafo na prática

Meu hábito, antes de qualquer ferramenta dessas, sempre foi o mesmo: eu quero ver o desenho antes de escrever código

No vídeo abaixo eu mostro uma skill de diagrama rodando do zero, e o caminho lá é o inverso do Graphify: em vez de partir de um repositório que já existe, eu descrevo o sistema e a IA desenha

Instalei direto pelo terminal, escolhi a opção de uso no Claude Code e aceitei a forma de instalação que o próprio instalador recomendou, sem configuração extra

Descrevi tudo em português no prompt: um e-commerce com vitrine, carrinho e checkout no frontend, uma API separada, banco relacional guardando catálogo, pedidos e clientes, cache pra produtos e sessões de carrinho, fila pra processar pedido de forma assíncrona e envio de e-mail transacional

Fechei pedindo que o checkout se integrasse a um serviço de pagamento externo, porque construir pagamento do zero não é viável, envolve integração bancária e burocracia que ninguém quer

Especificar a stack foi escolha minha, por domínio técnico. Quem não manja pode deixar a própria IA sugerir as tecnologias, funciona também

A IA localizou a skill, gerou o arquivo HTML e devolveu o caminho no fim, com aviso de diagrama pronto e validado

Abri no navegador e li o fluxo de ponta a ponta: cliente chega na loja, passa pelo checkout, o pagamento sai pro serviço externo e o webhook desse serviço volta pra API, que grava o pedido novo no banco

E aí veio a parte engraçada: eu fui lendo pela cor dos blocos pra identificar o que era banco e o que era frontend, e me corrigi ao vivo sobre qual cor era qual haha

Isso diz uma coisa que vale pro Graphify também: desenho não se lê no olho, se lê na legenda. É exatamente por isso que o file_type do nó e o relation da aresta importam mais que a bolinha na tela

No vídeo tu vê em movimento a instalação, o prompt em português e a navegação no HTML depois de pronto

Na própria página eu troquei o tema da visualização e mostrei a exportação como caminho pra mandar o diagrama pro sócio ou pro cliente

O que eu destaquei lá e repito aqui: o valor do desenho é enxergar a responsabilidade de cada peça e a ordem das chamadas, não a lista de serviços. Lista de serviço qualquer um escreve no papel

Outra coisa que eu gosto: devolver o diagrama pra própria IA depois, como material pra ela revisar o plano e apontar o que ficou faltando. O mapa deixa de ser enfeite e vira insumo

E elogiei o fato de rodar uma checagem de qualidade antes de entregar, que é bem diferente do resultado bruto de pedir "desenha a arquitetura aí" pra uma IA genérica

Posicionei aquilo como etapa de pré-planejamento, antes de escrever código, com o diagrama guardado em algum lugar (repositório, drive) pra ser consultado e ampliado conforme o sistema cresce. Que é, olha só, exatamente o argumento de commitar a graphify-out/

Mostrei ainda que não é só arquitetura: dá pra fazer workflow (CI/CD, aprovações, chamadas de ferramenta, resposta a incidente), diagrama de sequência de quem chama quem e em que ordem, fluxo de dados e ciclo de vida da aplicação

No fim do trecho eu começo a mostrar que a ferramenta também lê repositório já existente, mas a fala corta antes da demonstração…

Sobre economia de contexto, um aviso honesto pra tu não criar expectativa errada: o benchmark oficial de 71,5x menos tokens por consulta foi medido em um corpus misto de 52 arquivos (os repositórios nanoGPT, minGPT e micrograd, mais 5 PDFs do ArXiv e 4 imagens)

O próprio README avisa que o ganho escala com o tamanho e a composição do corpus, e que em base puramente de código o esperado fica na faixa de 5x a 10x

Não é número meu, é o que está documentado. E 5x a 10x já é MUITA coisa pra quem vive vendo o assistente torrar contexto no Grep

Quando vale abrir o grafo (e o que perguntar em cada caso)

Entrei num projeto novo e não sei por onde tudo passa:

Abre o GRAPH_REPORT.md e vai direto nos god nodes

É o nó de maior betweenness centrality, o cara que conecta o maior número de comunidades. Se tu entender esses poucos arquivos, tu já entendeu por onde o sangue do projeto circula

Preciso mexer aqui, mas não sei o que isso encosta lá:

Use /graphify path pra traçar como duas partes do código se conectam, ou shortest_path pelo MCP, que devolve a ligação salto a salto

Pergunta boa: "como o checkout chega no banco de pedidos?" e leia o caminho inteiro antes de encostar em qualquer linha

Vou refatorar esse arquivo, ele importa mesmo?

/graphify explain percorre por que um nó importa, e get_neighbors te dá todos os vizinhos diretos com detalhe das arestas

Olha o relation de cada vizinho: calls e imports doem de um jeito, semantically_similar_to dói de outro (ou nem dói)

Chegou PR e eu preciso saber o tamanho do estrago:

Aqui entram list_prs, get_pr_impact e triage_prs

Serve bem pra PR chato de manutenção, aquele que troca uma dependência ou um modelo chamado no projeto inteiro, tipo quando o código ainda chama o Opus 4.1 em canto que ninguém lembrava que existia

Não sei nem o que perguntar:

Sério, esse é o caso mais comum e tem resposta pronta

O GRAPH_REPORT.md termina com 4 a 5 perguntas que aquele grafo está em posição privilegiada de responder. Começa por elas e você já entra no assunto com pergunta que o mapa sabe responder bem

E não pula as conexões entre arquivos ranqueadas por quão inesperadas são: é ali que mora o acoplamento que ninguém documentou

Conclusão

Recapitulando o que interessa

O grafo do Graphify não vira produtividade enquanto ele estiver bonito numa aba do navegador. Ele vira produtividade quando entra no fluxo do assistente

A ordem que funciona: lê o GRAPH_REPORT.md primeiro, entende god node e comunidade, aprende a ler nó e aresta (principalmente as tags EXTRACTED, INFERRED e AMBIGUOUS), e só depois abre o graph.html pra confirmar o que você já sabe

O próximo passo prático é bem curto: roda graphify update pra manter o mapa em dia, commita a graphify-out/ pro time inteiro receber o contexto no pull, e começa pelas perguntas sugeridas no relatório

Pra fechar, quem está por trás: o repositório oficial vive em github.com/Graphify-Labs/graphify, mantido pela Graphify Labs, empresa fundada por Safi Shamsi e integrante do batch Summer 2026 da Y Combinator

Bora abrir esse relatório e ver o que teu projeto tem escondido? 🙂

até o próximo post!