God nodes e communities do Graphify: como enxergar a arquitetura de um projeto que você nunca viu

Cair num repositório que ninguém documentou é tipo pousar numa cidade sem mapa, sem placa e sem ninguém por perto pra perguntar

Você abre a pasta, vê 40 diretórios com nomes bonitos e continua sem saber onde o sistema de verdade acontece

O Graphify mira exatamente nesse ponto: é uma skill /graphify, criada por Safi Shamsi, que transforma um codebase (com docs, schemas SQL, configs e PDFs) num knowledge graph consultável

E dentro dele existem dois recursos que entregam a visão macro do projeto: os god nodes, os nós que ligam o maior número de subsistemas, e as communities, a divisão do grafo em subsistemas

Bora ver como cada um funciona?

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

De onde vem o grafo que o Graphify desenha:

Antes de olhar god node nenhum, vale entender COMO esse desenho aparece

O pipeline tem três passes, e o Pass 1 é o que faz o trabalho pesado no código: ele usa Tree-sitter pra extrair classes, funções, imports, call graphs e comentários

Isso roda local e determinístico, sem LLM e sem vector store

E esse detalhe importa mais do que parece: o mapa não é palpite de modelo, é a estrutura que o parser leu do teu código…

Se você já mexeu com qualquer linter ou formatador que monta a árvore do arquivo antes de opinar, a ideia é bem parecida: primeiro lê a estrutura, depois interpreta

E arquivo SQL, entra no grafo?

Entra, e com tratamento próprio no Pass 1: tabelas, views, foreign keys e relações de JOIN são extraídas de forma determinística

Ou seja, o banco não fica de fora do desenho, ele vira parte do mapa

Já o Pass 3, que é a etapa com LLM, fica reservado a docs, papers, imagens e transcrições

Se o teu corpus é só código, o Pass 3 é pulado por completo

A skill roda em Claude Code, Cursor, Codex e Gemini CLI

Ah, e um detalhe que aparece torto por aí: Andrej Karpathy não é autor do projeto

Ele é creditado como origem do conceito da pasta /raw, que inspirou a ferramenta

A autoria é do Safi Shamsi, e o repositório oficial hoje vive na organização Graphify-Labs, pra onde foi transferido a partir da conta pessoal safishamsi (as URLs antigas redirecionam)

O que é um god node e por que ele importa em código que você nunca viu

Definição curta: god node é o nó de maior betweenness centrality do grafo

"Betweenness o quê?"

Calma que é mais simples do que o nome sugere: é o nó por onde passa o maior número de caminhos entre partes diferentes do sistema

Na prática, são os arquivos ou funções que conectam o maior número de communities

Pensa numa rodoviária central: ela não é o destino de ninguém, mas quase toda rota passa por lá

É por isso que god node é o melhor ponto de partida pra ler um projeto desconhecido

Cada minuto gasto ali te devolve contexto de vários subsistemas de uma vez, em vez de você abrir arquivo aleatório e torcer

E você nem precisa encarar o grafo pra ter isso mastigado: o GRAPH_REPORT.md resume os god nodes e as conexões inesperadas em linguagem simples

Tem ainda um uso bem esperto disso antes da etapa semântica: no Pass 2, vídeos e áudios são transcritos com faster-whisper, e o prompt da transcrição é semeado com os principais god nodes já encontrados no grafo de código

Ou seja, o Pass 2 é quem gera o texto da transcrição, e é esse texto que depois chega no Pass 3

Sacou a jogada? O vocabulário do teu projeto entra na transcrição, então nome de classe esquisito tem mais chance de sair escrito certo

Communities: como o Leiden separa o projeto em subsistemas

As communities são detectadas pelo algoritmo Leiden, que agrupa nós por densidade de arestas

Traduzindo: pedaços que conversam MUITO entre si viram um grupo, e esse grupo é um subsistema

O que aparece ali é a arquitetura que o projeto pratica, não a que alguém prometeu quando criou as pastas

Se aquele utils/ inocente virou metade do sistema, o grafo entrega isso na hora, sem dó 😀

Os rótulos das communities são determinísticos? Não

Aqui vale corrigir uma ideia que circula por aí

O agrupamento é determinístico, mas o NOME dado a ele não é

Existe uma função label_communities que consome orçamento de tokens de um modelo, e o rastreador de issues do projeto trata a rotulagem como saída de LLM

Então a régua é simples: trate o agrupamento como dado sério e o rótulo como sugestão

O que você precisa antes de rodar:

A lista é curta, e isso é parte da graça

• Python 3.10 ou mais novo
• Um dos assistentes suportados: Claude Code, Cursor, Codex ou Gemini CLI

Só isso

Nada de vector store, nada de serviço externo pro Pass 1, nada de PC da Nasa pra rodar embedding de repositório inteiro

Se o teu setup de assistente ainda está cru, vale ver antes o fluxo completo do Claude Code pra não misturar dois aprendizados no mesmo dia

Como gerar o grafo e chegar nos god nodes:

1. Instale a ferramenta (o método recomendado é o uv):

uv tool install graphifyy

Se preferir, dá pra usar as alternativas:

pipx install graphifyy
# ou
pip install graphifyy

O erro comum deste passo: escrever o nome do pacote com um y só

O pacote que você instala é o graphifyy, terminando em dois y, e o comando que ele deixa disponível é o graphify, terminando em um y

Tome cuidado, porque a mensagem de "não encontrado" aqui não é bug da ferramenta, é o dedo mesmo

2. Registre a skill no seu assistente:

graphify install

Esse passo é o que faz a skill /graphify existir dentro do assistente

3. Leia as três saídas, nesta ordem de preguiça crescente:

• GRAPH_REPORT.md: o resumo em linguagem simples dos god nodes e das conexões inesperadas
• graph.html: a visualização interativa, onde você clica nos nós e filtra por community
• graph.json: o grafo consultável, que é onde a brincadeira fica séria

4. Explore o grafo com /graphify query, que percorre o graph.json salto a salto

Essa é a parte que economiza contexto de verdade: você navega as conexões sem precisar reler as fontes originais a cada pergunta

Quando god nodes e communities valem o esforço

Nem todo projeto precisa disso, seja honesto

Mas tem quatro cenários onde a visão macro paga o pedágio rapidinho

Onboarding em código legado

Você não sabe por onde começar a ler, então começa pelos pontos de passagem

Combina bem com a etapa de entender um projeto legado herdado antes de encostar em qualquer refatoração

Auditoria de arquitetura

As conexões inesperadas entre subsistemas são o prato principal aqui

Quando dois módulos que "não se falam" aparecem colados no grafo, você achou uma conversa que ninguém documentou

Projetos com muito SQL

Tabelas, views, foreign keys e JOINs entram no grafo, então o modelo de dados aparece junto com o código, não num diagrama paralelo que envelheceu em 2023

Acompanhamento ao longo do tempo

graph.json e GRAPH_REPORT.md são texto puro, então podem ser versionados no git

Dois commits, duas datas, e você compara como a arquitetura andou (ou como ela apodreceu, hehe)

Dois limites conhecidos hoje (e como conviver com eles)

Nada de vender maravilha: tem relato registrado no projeto e é melhor você já saber antes de rodar

Sintoma: as communities continuam como "Community 0", "Community 1"…

Existe uma issue reportando exatamente isso, a #1097: os rótulos seguem no padrão mesmo quando a extração semântica via Gemini roda com sucesso

A causa mora na etapa de rotulagem, que é a parte que depende de LLM, e não no agrupamento em si

Contorno: abra o graph.html, filtre por community e nomeie pelo conteúdo dos nós

É chato, mas leva dois minutos e o nome que VOCÊ dá costuma ser melhor que o genérico mesmo

Sintoma: o ID da community muda entre execuções

Esse é o assunto da discussion #1090: o clustering não devolve ordem estável, então os IDs dançam de uma run pra outra

O agrupamento em si é reproduzível, o que muda é o número na etiqueta

Prevenção: nunca use o ID como referência fixa

Nada de anotar "o bug mora na community 4", nada de script apontando pro ID, nada de diff comparando número de community entre duas execuções

Referencie pelos nós, que esses continuam os mesmos

Conclusão

God nodes e communities resolvem um problema bem específico e bem doloroso: enxergar a arquitetura que o código PRATICA, e não a que o README promete

O Pass 1 monta o mapa localmente com Tree-sitter, o Leiden separa os subsistemas por densidade de arestas, e os god nodes te dizem por onde a leitura rende mais

Só lembre da parte honesta: agrupamento é determinístico, rótulo é saída de modelo, ID é volátil

Próximo passo concreto? Rode primeiro num repositório que você já conhece de cor

É ali que você calibra a leitura, vê se os god nodes batem com o que você sabe que é o coração do sistema, e só depois aponta a ferramenta pro legado que ninguém entende

até o próximo post! 🙂