🕸️ Grafo de conhecimento sem mistério
Nós, arestas, comunidades e god nodes — o vocabulário que torna o resto do curso óbvio. Cada palavra é definida na primeira vez que aparece; ao final, o "grafo" deixa de ser jargão e vira uma imagem mental.
⚪ O que é um grafo (nós e arestas)
No fundo, todo o curso gira em torno de uma estrutura simples: o grafo. Não tem mistério — é a forma mais antiga de desenhar "coisas e como elas se ligam". Pense num mapa de metrô: cada estação é um ponto, e cada trilho é uma linha que liga duas estações. O grafo do Graphify é exatamente isso, só que em vez de estações ele guarda ideias, e em vez de trilhos ele guarda relações entre ideias.
🔰 Novo aqui? O que é um "grafo"
Um grafo é um conjunto de pontos ligados por linhas. Os pontos chamam-se nós (em inglês, nodes) e as linhas chamam-se arestas (em inglês, edges). Nada além disso: nó = coisa, aresta = ligação entre duas coisas. Esqueça a palavra "grafo" assustadora — é o mapa de metrô.
Dois detalhes dão poder ao grafo. O primeiro é a vizinhança: a partir de um nó, você enxerga imediatamente quem está ligado a ele — os vizinhos diretos. O segundo é o grau de um nó: quantas arestas saem dele, ou seja, com quantas outras coisas ele se conecta. Um nó de grau alto é um cruzamento movimentado; um nó de grau baixo é um beco. Guarde esses dois — eles voltam nos tópicos 3 e 4.
🔰 Novo aqui? "Vizinhança" e "grau"
Vizinhança de um nó = todos os nós ligados a ele por uma aresta. Grau = o número dessas ligações. Estação central com muitas linhas → grau alto. Estação de ponta de linha → grau baixo. Simples assim.
↑ Os círculos são nós; as linhas são arestas. O círculo brilhante no centro tem muitas ligações (grau alto) — é o god node. O tracejado cerca um grupo bem conectado — uma comunidade. Tudo que vem a seguir está nesta única figura.
🔑 Conceitos-chave
🔗 Entidades, relações e procedência
"Nó" e "aresta" são os nomes genéricos. Quando o Graphify olha de fato para o seu conteúdo, ele dá nomes mais específicos: cada nó vira uma entidade e cada aresta vira uma relação tipada. É o mesmo grafo do tópico 1 — só com vocabulário preciso por cima.
🔰 Novo aqui? "Entidade" e "relação tipada"
Uma entidade é uma coisa identificável: uma ideia, uma função de código, uma pessoa, um conceito ("Context Window", "Hooks"). Uma relação tipada é uma aresta que diz o que ela é — não só "A liga em B", mas "A usa B", "A é parte de B", "A depende de B". O "tipo" é o rótulo da ligação.
Cada entidade e cada relação carrega ainda uma etiqueta invisível: a procedência — de qual arquivo aquilo veio. É o que permite o agente dizer "isto eu li em hooks.md, linha tal" em vez de inventar. Procedência é o que separa um mapa confiável de um chute bonito.
🔰 Novo aqui? "Procedência" e "reconciliação"
Procedência (em inglês, provenance) = o registro da origem de cada pedaço de conhecimento: qual documento o gerou. Reconciliação = juntar apelidos do mesmo conceito num só nó (ex.: "janela de contexto", "context window" e "ctx window" viram uma entidade, não três). Sem reconciliar, o mesmo conceito apareceria espalhado.
Aqui mora uma pegadinha de vocabulário que vale guardar: o vídeo que inspira o curso fala em "conceitos" e "conexões"; a ferramenta, na prática, diz "entidades" e "relações". São a mesma coisa com nomes diferentes. Saber os dois evita você travar quando o GRAPH_REPORT.md usar um termo e o vídeo usar outro.
🛠️ O que a ferramenta diz
- ›Entidade — um nó nomeado e tipado.
- ›Relação — uma aresta com rótulo (usa, contém…).
- ›Procedência — o arquivo-fonte de cada item.
🎬 O que o vídeo chama
- ›Conceito — o mesmo que entidade.
- ›Conexão — o mesmo que relação.
- ›"De onde veio" — o mesmo que procedência.
🔑 Conceitos-chave
🫧 Comunidades e o algoritmo Leiden
Quando você tem centenas de nós, repara que alguns grupos conversam muito entre si e pouco com o resto — como panelinhas numa festa. Esses grupos têm um nome: comunidades. No diagrama do tópico 1, o tracejado cercava uma delas. Comunidades são o que transforma um emaranhado de pontos num conjunto de temas legível.
🔰 Novo aqui? "Comunidade" e "clustering"
Uma comunidade é um grupo de nós muito ligados entre si e pouco ligados a quem está de fora. Clustering (agrupamento) é o nome geral da tarefa de "achar os grupos naturais" dentro de um monte de dados. Detectar comunidades é fazer clustering em cima de um grafo.
Mas quem decide onde uma comunidade começa e a outra termina? Um algoritmo — e o que o Graphify usa chama-se Leiden. Você não precisa entender a matemática dele; precisa saber que ele varre o grafo sozinho e devolve os grupos, sem você ter de marcar nada à mão.
🔰 Novo aqui? O que é o "Leiden"
Leiden é o nome de um algoritmo de detecção de comunidades (batizado pela cidade holandesa). Para você, ele é uma caixa-preta útil: entra um grafo, saem grupos coesos. É o sucessor de um algoritmo mais antigo (Louvain), com grupos mais "bem fechados".
Por dentro, em linguagem de gente, o Leiden faz três passos repetidamente até não conseguir melhorar:
Cada nó num grupo só dele
Começa com todo mundo isolado — nenhuma panelinha ainda.
Juntar quem se conecta muito
Cada nó "se muda" para o grupo dos vizinhos com quem tem mais arestas.
Repetir até estabilizar
Refina e recomeça enquanto os grupos ficarem mais coesos. Aí para.
💡 Por que isso importa pra você
Cada comunidade vira um tema do seu projeto — e, no export Obsidian, um grupo nomeado no canvas. É assim que um grafo de 600 nós deixa de ser intimidante: você navega por dezenas de temas, não por centenas de pontos soltos.
🔑 Conceitos-chave
🌟 God nodes: os hubs do grafo
Lembra do nó brilhante no centro do diagrama? Aquele era o god node: a entidade mais conectada do grafo, o cruzamento por onde quase tudo passa. Num grafo da documentação do Claude Code, "Context Window" costuma ser um god node — dezenas de outros conceitos puxam para ele.
🔰 Novo aqui? O que é um "god node" / "hub"
Um god node (literalmente "nó-deus") é simplesmente o nó de grau mais alto — o que tem mais arestas. Outro nome para ele é hub (centro). Não tem nada de místico: é o aeroporto de conexões do grafo. O GRAPH_REPORT.md já lista os god nodes pra você.
Por que você se importa? Porque os god nodes são os melhores pontos de partida para perguntar ao agente. Em vez de começar por um conceito obscuro de canto, você começa por um hub e deixa o agente "descer" pela vizinhança. É o equivalente a entrar numa cidade pela estação central, não por um beco.
✓ Começar por um god node
- ✓Toca muitos temas de uma vez.
- ✓Dá ao agente uma vizinhança rica para navegar.
- ✓Já vem listado no relatório — sem caça ao tesouro.
✗ Começar por um nó de ponta
- ✗Grau baixo: poucas conexões para seguir.
- ✗O agente esbarra num beco sem saída.
- ✗Você perde a visão do todo.
💡 Dica de uso
Quando abrir o grafo pela primeira vez, vá direto ao GRAPH_REPORT.md, leia a lista de god nodes e use o primeiro como ponto de entrada da sua primeira pergunta. É o atalho mais rápido para "entender de que projeto esse grafo trata".
🔑 Conceitos-chave
🗺️ GraphRAG: mapa vs busca
Agora juntamos tudo numa sigla que você vai ouvir muito: GraphRAG. Para entendê-la, primeiro o "RAG" simples. Quando um agente precisa responder sobre documentos que não cabem na janela, ele busca os trechos mais relevantes e os cola no contexto antes de responder. Isso é RAG.
🔰 Novo aqui? O que é "RAG"
RAG = Retrieval-Augmented Generation (geração aumentada por recuperação). Em português claro: antes de responder, o sistema recupera (busca) os pedaços de texto úteis e entrega ao modelo. A recuperação é só esse passo de "ir buscar o que importa". RAG comum trabalha com chunks — trechos soltos de texto.
O problema do RAG comum: ele entrega uma pilha de trechos sem relação entre si. O modelo recebe páginas avulsas e precisa adivinhar como elas se conectam. O GraphRAG resolve isso fazendo a recuperação por cima do grafo: além dos trechos, ele entrega as relações entre eles — vizinhança, comunidade, god nodes. Texto + mapa, não texto solto.
🔰 Novo aqui? O que é "GraphRAG"
GraphRAG é RAG que usa um grafo de conhecimento como fonte. Em vez de devolver só trechos parecidos com a pergunta, devolve os trechos e como eles se ligam. É a diferença entre receber recortes de jornal e receber um infográfico anotado. O Graphify é, no fundo, uma ferramenta para montar esse grafo de GraphRAG.
↑ Mesma pergunta, duas respostas. O RAG comum despeja trechos avulsos; o GraphRAG entrega o conceito e a vizinhança dele. Por isso o mapa responde mais rápido e com menos alucinação.
🔑 Conceitos-chave
⚡ Por que o mapa ajuda o agente
Fechando o módulo, o payoff prático. Com o mapa na mão, o Claude Code sabe o que está perto de quê. Você pergunta sobre sub-agentes; em vez de varrer o repositório inteiro com grep, ele pula direto para o nó "Subagentes", lê a vizinhança dele — "agent teams", "contexto separado", "orquestração" — e responde no contexto certo.
🔰 Lembrete rápido: "navegar a vizinhança"
Navegar a vizinhança é ir de um nó aos seus vizinhos diretos e, de lá, aos vizinhos deles — seguindo as arestas como se fossem corredores. É exatamente o que o grep não faz: ele acha onde a palavra aparece, mas não sabe seguir as conexões. O mapa, sim.
O ganho cresce com o tamanho do projeto. Em repositórios grandes, ler tudo é caro e lento; seguir o mapa é barato e direto. Esse é o argumento de venda do stack inteiro: respostas melhores em bases grandes, porque o agente gasta a janela de contexto no que importa, guiado pelas relações em vez de adivinhando.
✓ Com o mapa
- ✓Vai direto ao nó e à vizinhança certa.
- ✓Gasta a janela só no que é relevante.
- ✓Responde com as relações, não só com trechos.
✗ Sem o mapa
- ✗Varre arquivos com grep, sem rumo.
- ✗Enche a janela com texto irrelevante.
- ✗Perde as conexões entre conceitos.
🔑 Conceitos-chave
✋ Auto-recuperação (opcional, não bloqueia): o que é um god node no grafo?
📌 Resumo do módulo
Próximo módulo
1.3 · Graphify por dentro — a CLI e a skill, como ele extrai (AST vs LLM) e o que ele cospe na pasta graphify-out/.