🛠️ Passo a passo prático

O Graphify é escrito em Python (precisa de 3.10+) e o uv é um instalador de ferramentas Python rápido. Confira sua versão com python --version antes de seguir.

A base certa garante que o graphify instale limpo, sem conflito de versões. É o pré-requisito que evita a maioria dos erros de instalação.

python --version · uv · PATH.

Rode uv tool install graphifyy (o pacote tem dois 'y'); como alternativa, pipx install graphifyy ou pip install graphifyy. Isso instala o binário graphify que você vai chamar.

É o programa central do curso — sem ele, nada roda. Um único comando deixa o graphify disponível no terminal.

graphifyy · uv tool · uv tool update-shell.

graphify install escreve ~/.claude/skills/graphify/SKILL.md; com --project ele grava dentro do repositório atual. É o que ensina o Claude Code a usar o Graphify.

É esse passo que ativa o comando /graphify dentro do Claude Code. Sem registrar a skill, só existe a CLI headless.

skill · SKILL.md · --project.

Baixe o Obsidian em obsidian.md, instale e abra — é gratuito e roda no desktop. Ainda não precisa criar nada, só deixá-lo pronto.

É onde o vault gerado vai morar e ser navegado. Tê-lo aberto agora encurta o caminho quando o markdown chegar.

Obsidian · vault · desktop.

Rodando via /graphify dentro do Claude Code você NÃO precisa de chave; só o modo headless (terminal puro sobre documentos) pede a ANTHROPIC_API_KEY. Extração de código por AST não usa chave nenhuma.

Evita travar achando que falta configurar uma chave. Saber quando ela entra poupa tempo e confusão.

ANTHROPIC_API_KEY · skill vs headless · tree-sitter sem chave.

Rode graphify --help e confira que existe ~/.claude/skills/graphify/SKILL.md. Se os dois respondem, o ambiente está pronto.

Pegar um problema agora é muito mais barato que descobrir no meio da extração. É o sanity check que fecha a instalação.

--help · checklist · sanity check.

O Graphify aceita um code base OU um corpus de documentos (PDF, markdown). A escolha define o tipo de fonte que ele vai ler.

Muda como ele extrai — código vira grafo pela AST (sem chave), documentos passam por um LLM. Decidir cedo evita retrabalho.

code base · corpus · escolha.

Peça ao próprio Claude Code para baixar a documentação oficial numa pasta local, por exemplo ./claude-code-docs. É o corpus usado no exemplo do vídeo.

Ter um corpus real e conhecido facilita comparar seu resultado com o do vídeo (lá deram ~145 documentos). Bom ponto de partida antes de usar fontes próprias.

pasta local · docs · 145 docs (exemplo).

Junte os arquivos numa pasta dedicada e sem lixo (rascunhos, temporários). Essa pasta é exatamente o que o Graphify vai varrer.

Uma raiz limpa gera um grafo mais limpo, com menos ruído. O que entra na pasta vira nó no grafo.

pasta dedicada · estrutura · ruído.

Comece apontando para um subconjunto dos arquivos, não o corpus inteiro de uma vez. Você amplia o escopo depois que o fluxo funcionar.

Extração menor é mais rápida e barata para testar e ajustar. Iterar pequeno evita esperar (e pagar) por um grafo que talvez não sirva.

escopo · subconjunto · iterar.

Tire binários, builds, duplicatas e tudo que não carrega significado. Deixe só os arquivos que descrevem o conhecimento.

Cada arquivo a mais é ruído potencial no grafo. Menos lixo significa nós e relações mais relevantes.

exclusões · estilo .gitignore · sinal/ruído.

Rode o Graphify na raiz do projeto; a saída vai para uma pasta graphify-out/ ali mesmo. O diretório atual (cwd) define onde os arquivos aparecem.

Saber de onde rodar dá previsibilidade aos caminhos das saídas. Você sempre sabe onde achar o graph.json depois.

cwd · graphify-out/ · raiz do projeto.

Dentro do Claude Code use /graphify ./claude-code-docs; no terminal puro use graphify extract ./claude-code-docs. Os dois geram o mesmo grafo por caminhos diferentes.

É o comando que dá o pontapé na extração. Saber os dois modos deixa você escolher o que cabe no momento.

skill vs headless · extract.

Ele lê os arquivos, extrai entidades e relações e detecta comunidades com o algoritmo Leiden. O resultado é cacheado para não refazer tudo a cada vez.

Entender a espera e o cache evita ansiedade e re-execuções desnecessárias. Você sabe que o tempo está virando nós e arestas.

extração · comunidades · cache.

Abra graphify-out/graph.html no navegador — é um arquivo self-contained, sem servidor. Mostra os nós, conexões e comunidades de forma interativa.

É a primeira vez que você vê o seu grafo de verdade. Explorar o visual cria a intuição que o resto do curso usa.

graph.html · navegador · interativo.

O graphify-out/GRAPH_REPORT.md é uma auditoria em texto que lista os god nodes e sugere perguntas. Funciona como um índice do que o grafo sabe.

Ele te diz por onde explorar sem adivinhar — os hubs e as boas perguntas já vêm prontos. Ótimo ponto de entrada num grafo grande.

GRAPH_REPORT.md · god nodes · perguntas sugeridas.

Use graphify explain "Context Window", graphify path "Hooks" "Subagents" e graphify query "..." para interrogar o grafo. São respostas direto da estrutura, sem abrir o vault.

Dá respostas rápidas sobre conceitos e caminhos entre eles. É a forma mais leve de usar o conhecimento já extraído.

explain · path · query.

graphify update . reprocessa apenas os arquivos alterados; --watch refaz automaticamente ao salvar. Os dois evitam reprocessar o corpus inteiro.

Mantém o grafo vivo conforme a fonte muda, sem pagar o custo total toda vez. Atualização incremental é o que torna o stack sustentável.

update · watch · incremental.

Dentro do Claude Code rode /graphify ./claude-code-docs --obsidian --obsidian-dir ~/vault/graphify/claude-code. O --obsidian liga o export de vault.

Esse flag só existe na skill, não no modo headless — é o detalhe que muita gente erra. É o que transforma o grafo em notas.

--obsidian · --obsidian-dir · skill-only.

O --obsidian-dir define a pasta de saída; sem ele, a skill cria um diretório próprio (uma espécie de quarentena). Você controla onde os arquivos caem.

Apontar o destino evita espalhar markdown em lugar errado. O default isolado é seguro, mas escolher dá organização.

destino · pasta dedicada · default isolado.

Sai um arquivo .md por nó, com [[wikilinks]] para os relacionados, mais um graph.canvas com as comunidades agrupadas. É o vault navegável.

Entender o que cada arquivo é tira o mistério do export. Um nó igual a uma nota é o modelo mental do vault inteiro.

md por nó · wikilink · graph.canvas.

O export é regenerado do zero a cada execução, sempre a partir do graph.json. Não há merge manual — o grafo é a fonte de verdade.

Significa que o vault sempre reflete o grafo atual, sem estados intermediários. Você pode re-rodar à vontade sem medo de inconsistência.

regeneração · idempotente · fonte de verdade.

/graphify ./docs --wiki gera artigos por comunidade com um index.md de entrada. É outro formato de export, voltado a leitura.

É uma alternativa navegável por texto, boa para humanos e agentes que preferem ler artigos. Vale conhecer antes de decidir entre vault e wiki.

--wiki · index.md · artigo por comunidade.

Olhe a pasta de destino — conte os arquivos .md e veja se o graph.canvas está lá. É uma checagem rápida no sistema de arquivos.

Confirma que o export funcionou antes de você investir tempo no Obsidian. Pega exportações vazias ou truncadas cedo.

contagem de notas · canvas · verificação.

No Obsidian, no canto inferior esquerdo, abra Manage vaults → Open folder as vault e escolha a pasta gerada. O Obsidian passa a tratar aquela pasta como um vault.

O Obsidian precisa ser apontado ao diretório — ele não acha sozinho. É o passo que liga o markdown gerado à interface.

manage vault · open folder as vault · reconhecer.

Abra uma nota-nó e siga os [[backlinks]] para os conceitos ligados a ela. Cada clique te leva de uma ideia à sua vizinha.

É o segundo cérebro em ação — você percorre o conhecimento pelas relações, não por busca. Treinar essa navegação é o objetivo do módulo.

nota-nó · backlink · navegação.

Abra o graph.canvas no Obsidian e veja as comunidades como grupos nomeados num quadro. É a visão macro dos temas do corpus.

O canvas dá o panorama que as notas individuais não dão. Bom para escolher de qual tema começar a explorar.

canvas · comunidade · grupo nomeado.

Cada nó guarda sua procedência no graph.json; traga os documentos-fonte para perto e ligue cada nó ao seu arquivo de origem (uma placa de sinalização). Assim o conceito aponta para o texto completo.

Permite que o agente vá do conceito ao documento inteiro quando precisar de detalhe. Fecha a lacuna entre resumo e fonte.

procedência · doc-fonte · link de origem.

A graph view do Obsidian desenha os links entre as notas markdown — é um espelho, não o grafo do Graphify. Ela mostra ligações de notas, não as relações tipadas originais.

O vídeo alerta justamente para isso, para você não confundir uma coisa com a outra. Ajustar a expectativa evita frustração.

graph view · espelho · ≠ original.

Há um prompt pronto: peça ao Claude Code para trazer os documentos-fonte e ligar cada nó à sua origem dentro da pasta do vault. Ele faz a etapa de linkar automaticamente.

Automatiza o trabalho manual do tópico 4, em um comando. É o atalho que torna a conexão das fontes prática.

prompt · wire · automação.

Mantenha o vault gerado como um vault próprio e separado do seu principal. Ele vive sozinho, sem se misturar ao resto.

É bom para quem só quer o conhecimento dentro do ecossistema Obsidian, sem integrar. É o comportamento padrão e o mais seguro.

standalone · isolado · default.

Jogue tudo numa subpasta do seu vault principal (ex.: graph-imports/claude-code-docs) que dá para apagar inteira. Fica no contexto, mas isolável.

Traz o conhecimento para perto sem risco — se não gostar, deleta a pasta e acabou. É o meio-termo entre isolado e integrado.

quarentena · subpasta · deletável.

Peça ao Claude Code para trazer só as notas relevantes (ex.: as ~100 sobre subagents) e ignorar o resto. Você colhe um recorte, não o corpus inteiro.

Evita despejar 600 arquivos que você nunca vai usar. Curadoria mantém o vault principal enxuto.

harvest · seleção · curadoria.

O Claude Code redistribui cada nota para a subpasta do seu vault que faz mais sentido. O conhecimento se dilui na sua estrutura existente.

Dá a máxima coerência com o que você já tem, mas é o mais difícil de reverter. É uma escolha consciente de trocar reversibilidade por integração.

redistribuição · coerência · risco.

Prompt pronto: peça para mover a estrutura do vault gerado para dentro do principal, numa subpasta própria. Ele transfere os arquivos por você.

Integra o conteúdo em menos de um minuto, sem arrastar pasta a pasta. É a execução prática da estratégia de quarentena.

mover · subpasta · prompt.

Regra prática — code base? pare no Graphify. Quer no Obsidian isolado? standalone. Integrar com segurança? quarentena. Curar? harvest. Coerência total? redistribuição.

Te dá um caminho de decisão para não travar na hora de integrar. Cada opção é um trade-off entre coerência e reversibilidade.

decisão · trade-off · reversibilidade.