🧭 Código vs documentos: quando parar no Graphify
Nem todo grafo precisa virar vault. Aqui você aprende a diferença entre extrair código e extrair documentos, e a decidir — com critério, não por hype — quando o grafo já basta e quando vale levar pro Obsidian.
🧱 Grafo de code base: AST, tree-sitter e sem chave
Quando você aponta o Graphify a um repositório de código, ele não "lê" o código como texto corrido. Ele faz parsing estrutural: lê a sintaxe da linguagem e monta uma árvore de funções, classes, módulos e suas chamadas. O resultado vira o grafo: nós que são funções e módulos, arestas que são "chama", "importa", "define".
🔰 Novo aqui? O que é "AST" e "tree-sitter"
AST (Abstract Syntax Tree, árvore de sintaxe abstrata) é a representação em árvore da estrutura de um programa: a função X contém a chamada Y, que recebe o argumento Z. É como o computador "entende" o código por baixo, sem ambiguidade.
tree-sitter é a biblioteca que o Graphify usa pra gerar essa AST de forma rápida e confiável, em 12 linguagens. É puro parsing — nenhum modelo de IA é chamado nessa etapa.
A consequência prática é importante: extrair um code base é determinístico, rápido e sem API key. Não há "alucinação" possível — a árvore reflete exatamente a sintaxe do arquivo. Você pode rodar num projeto enorme sem gastar um token de modelo.
# extrai a AST do código em ./src — tree-sitter, sem API key graphify extract ./src # pergunta direto ao grafo de código já extraído graphify query "quais funções chamam autenticar()?"
↑ graphify extract é o caminho headless (terminal puro). Pra código, ele roda sem chave nenhuma — o tree-sitter faz todo o trabalho.
✓ Forte em código
- ✓Estrutura exata: funções, classes, imports.
- ✓Rápido e barato — sem chamar modelo.
- ✓Determinístico: zero alucinação.
✗ Cego ao sentido
- ✗Não capta a intenção por trás do código.
- ✗Ignora comentários e prosa explicativa.
- ✗"Por que isto existe?" não está na AST.
🔑 Conceitos-chave
📄 Grafo de documentos: LLM e semântica
Documentos não têm sintaxe de programa — uma página de docs ou um PDF é prosa. Então o Graphify muda de estratégia: em vez de tree-sitter, ele usa um LLM para ler cada documento e entender de que conceitos ele fala e como eles se relacionam. É extração semântica: pelo sentido, não pela forma.
🔰 Novo aqui? "LLM", "corpus" e "semântica"
LLM (Large Language Model, modelo de linguagem) é o modelo de IA que entende e gera texto — é o motor por trás do Claude. Aqui ele lê os documentos e extrai os conceitos.
Corpus é o conjunto de documentos que você dá pra ele processar — sua pasta de docs, PDFs, notas.
Semântica = relativo ao significado. Extração semântica capta "este texto fala de autenticação e a liga a sessões", mesmo que a palavra exata não se repita.
↑ Mesmo Graphify, dois motores. Código vira estrutura (AST, sem chave); documentos viram significado (LLM, semântico). Dentro do /graphify no Claude Code, a sessão já fornece o modelo — você não precisa de chave nem aqui.
🔑 Conceitos-chave
🛑 Quando parar no Graphify
Existe uma tentação de levar todo grafo pro Obsidian "porque dá". Mas o grafo já é útil sozinho. O graph.html (visualização interativa self-contained) abre no navegador sem servidor, e graphify query responde perguntas direto. Pra explorar um code base pontual ou tirar uma dúvida rápida, isso basta.
💡 A regra de ouro
Se a resposta morre quando você fecha o terminal — e tudo bem com isso — pare no grafo. O vault só ganha sentido quando o conhecimento precisa persistir e conviver com o resto do que você sabe.
- •Pergunta única e descartável: grafo + query, fim.
- •Auditar um repo que não é seu: explore o
graph.html, não exporte. - •Sem intenção de manter: exportar seria overhead.
↑ Setas verdes = sim, vermelhas = não. A pergunta nunca é "dá pra exportar?" — é "esse conhecimento precisa viver fora do terminal?".
🔑 Conceitos-chave
🔮 Quando levar pro Obsidian
O Obsidian entra quando o conhecimento deixa de ser uma consulta avulsa e vira acervo. Ao exportar, o Graphify gera um markdown por nó com wikilinks [[nome-do-no]] e backlinks — então esse grafo passa a conviver com suas outras notas, projetos e ideias num único vault navegável.
# exporta o grafo como vault Obsidian (um .md por nó + backlinks) /graphify ./claude-code-docs --obsidian --obsidian-dir ~/vault/graphify/claude-code
↑ O flag --obsidian só existe no caminho skill (/graphify dentro do Claude Code), não no graphify extract headless.
✓ Vale exportar quando…
- ✓O conhecimento vai ser consultado de novo, muitas vezes.
- ✓Você quer ligar com notas suas (segundo cérebro integrado).
- ✓Quer navegar visualmente pelo grafo no Obsidian.
✗ Não vale quando…
- ✗É uma pergunta única que você não vai revisitar.
- ✗O repo nem é seu — só está auditando.
- ✗Você não vai manter o vault atualizado.
🔰 Novo aqui? O que é "vault"
Vault é a "caixa" do Obsidian: uma pasta de arquivos markdown ligados entre si. O export do Graphify enche um vault com uma nota por conceito — e é aí que o grafo vira memória persistente e navegável, não só um arquivo no terminal.
🔑 Conceitos-chave
🔁 Manter código e docs sincronizados
Código e docs mudam. Um grafo congelado no dia da extração envelhece e mente. A solução não é re-extrair tudo do zero toda vez — é a atualização incremental: o Graphify guarda um cache/ por arquivo (pelo hash do conteúdo) e só reprocessa o que mudou.
# reprocessa só os arquivos modificados desde a última vez graphify update . # rebuild automático: fica observando e atualiza ao salvar graphify watch .
↑ graphify update . = atualização sob demanda; graphify watch . = contínuo. Dentro do Claude Code, o equivalente é /graphify . --update e /graphify . --watch.
A fonte muda
Você edita o código ou adiciona um doc novo no projeto.
update reprocessa só o delta
O cache por hash evita re-chamar o LLM em arquivos intocados. Barato.
Re-exporte o vault (se usa Obsidian)
O export é regenerado do zero — então mantenha suas notas longe da pasta de imports.
⚠️ Cuidado com o re-export
O export Obsidian é regenerado a cada vez. Se você editou à mão uma nota gerada, essa edição se perde no próximo export. Mantenha imports e suas notas em pastas separadas — o módulo 2.5 trata disso.
🔑 Conceitos-chave
🧮 Custo, ruído e manutenção
Toda essa estrutura tem um preço — e ele é real, não só hype. Decidir bem entre código e documentos, parar no grafo ou ir pro vault, é uma conta de três variáveis: tempo/custo de extração, ruído do grafo e esforço de manutenção. Pesá-las antes evita virar um colecionador de grafos abandonados.
Custo de extração
Código (AST) é quase grátis. Documentos chamam o LLM — mais lento e, fora do Claude Code, gasta tokens da sua chave. O cache/ ameniza nas re-rodadas.
Ruído do grafo
Um corpus enorme gera centenas de nós — nem todos úteis. Use o GRAPH_REPORT.md (god nodes, comunidades) pra ver se o sinal está bom antes de exportar.
Manutenção do vault
Um vault só ajuda se ficar atual. Se você não vai rodar update de vez em quando, talvez seja melhor parar no grafo.
💡 A pergunta honesta
"Esse grafo/vault vai me devolver mais do que vai me custar pra criar e manter?" Se a resposta for não, pare no Graphify — ou nem extraia. Critério bate hype todas as vezes.
🔑 Conceitos-chave
✋ Auto-recuperação (opcional, não bloqueia): você rodou o Graphify num repo que não é seu, só pra tirar uma dúvida pontual sobre como uma função funciona. Onde você deveria parar?
📌 Resumo do módulo
Próximo módulo
3.4 · Manutenção e troubleshooting — manter grafo e vault saudáveis e resolver os erros mais comuns.