MÓDULO 3.4

🛠️ Manutenção, atualização e solução de problemas

Mantenha o grafo e o vault saudáveis ao longo do tempo — e saiba exatamente o que fazer quando algo dá errado. Cada problema vem com a causa e a correção pronta pra copiar e rodar.

6
Tópicos
~30
Minutos
Prático
Nível
0%
0 de 6
1

🔄 Re-rodar quando a fonte muda (incremental)

Seu projeto não fica parado: a documentação muda, o código cresce, arquivos entram e saem. O grafo precisa acompanhar — mas refazer tudo do zero a cada commit seria lento e caro. A resposta é o modo incremental: graphify update . reprocessa só o que mudou e reaproveita o resto do cache.

🔰 Novo aqui? O que é "incremental"

Incremental significa "só a diferença". O Graphify guarda um cache por arquivo (um hash do conteúdo) em graphify-out/cache/. Se o arquivo não mudou, ele não chama o LLM de novo — economiza tempo e dinheiro. Só os arquivos novos ou alterados são reprocessados.

O ciclo de manutenção tem dois passos. Primeiro, atualizar o grafo (graphify-out/graph.json é a fonte de verdade). Depois, se você usa o vault Obsidian, re-exportar com --obsidian para regerar as notas. Lembre: o export é derivado do grafo — atualizar o grafo não atualiza o vault sozinho.

correção · atualizar o grafo

Objetivo: manter o grafo atual depois que a fonte mudou, sem refazer tudo.

# headless (terminal puro): só reprocessa o que mudou
graphify update .

# usando a skill dentro do Claude Code, e já re-exportando o vault:
# /graphify . --update --obsidian --obsidian-dir ~/vault/graphify/meu-projeto

Verificar: o log mostra "N arquivos alterados" (não o total) e o graph.json ganha um mtime novo. Os arquivos intactos aparecem como "cache hit".

ciclo incremental ① a fonte muda ② graphify update . ③ re-export --obsidian ④ vault atual ✓

↑ O ciclo se fecha: toda vez que a fonte muda você roda update e re-exporta. O grafo é a fonte de verdade; o vault é derivado dele — por isso os dois passos.

🔑 Conceitos-chave

update
Só o que mudou
cache
Hash por arquivo
re-export
Vault derivado
incremental
Rápido e barato
2

🧯 Vault regenerado x suas edições

Aqui está a armadilha que mais machuca: o export Obsidian é regenerado do zero a cada execução. Se você abriu uma nota gerada, escreveu sua própria reflexão dentro dela e depois rodou o export de novo, aquela edição é sobrescrita. O Graphify não funde suas mudanças — ele recria o arquivo.

✓ Vault seguro

  • ✓Notas geradas numa pasta só do Graphify (ex.: /imports).
  • ✓Suas reflexões numa pasta separada (ex.: /minhas-notas).
  • ✓Você linka das suas notas para as geradas — nunca edita as geradas.

✗ Vault em risco

  • ✗Editar diretamente as notas que o export gerou.
  • ✗Misturar suas anotações com os imports na mesma pasta.
  • ✗Re-exportar por cima e perder horas de trabalho.

🔰 Regra de ouro

Trate a pasta de imports como somente-leitura: ela é uma projeção do grafo, não o seu caderno. Se você exportar sempre para --obsidian-dir ~/vault/graphify/<projeto>, suas notas pessoais ficam fora dali e nunca são tocadas pelo re-export.

🔑 Conceitos-chave

Regeneração
Recria, não funde
Separação
Imports ≠ suas notas
Somente-leitura
Não editar imports
Linkar
Conectar, não copiar
3

🐛 "graphify: command not found" (PATH)

Você instalou com uv tool install graphifyy, mas o terminal responde command not found. Calma: o pacote foi instalado, só não está no PATH do seu shell. O uv tem um comando que conserta isso em um passo.

🔰 Novo aqui? O que é "PATH"

O PATH é a lista de pastas onde o shell procura programas quando você digita um comando. Se o binário do graphify está numa pasta que não está nessa lista, o shell não o acha — mesmo ele existindo. uv tool update-shell adiciona a pasta certa e você reabre o terminal.

correção · PATH

Objetivo: fazer o comando graphify ser encontrado.

# adiciona o diretório de tools do uv ao PATH do shell
uv tool update-shell

# feche e reabra o terminal (ou recarregue o perfil), depois confirme:
graphify --help

Verificar: graphify --help lista os subcomandos. Se ainda falhar, abra um terminal novo — o PATH só recarrega numa sessão nova.

Esse não é o único tropeço comum na instalação e no dia a dia. A tabela abaixo é o seu mapa de "sintoma → causa → correção":

Sintoma Causa provável Correção
graphify: command not found Binário fora do PATH uv tool update-shell + reabrir o terminal
/graphify não aparece no Claude Code Skill não registrada graphify install e checar ~/.claude/skills/graphify/SKILL.md
Erro de chave fora do Claude Code Headless sem API key Exportar ANTHROPIC_API_KEY (ver tópico 4)
--obsidian "não existe" Tentou no headless Use a skill /graphify … --obsidian dentro do Claude Code

🔑 Conceitos-chave

PATH
Onde o shell busca
shell
Reabrir recarrega
uv
update-shell
install
Registra a skill
4

🔑 Erros de API key (só no headless)

Um erro de API key quase sempre significa uma coisa: você está rodando o Graphify headless (no terminal puro) para extrair documentos, e a extração semântica precisa de um modelo. Dentro do Claude Code, via /graphify, a sessão já fornece o modelo — você não precisa de chave nenhuma.

Dentro do Claude Code /graphify ./docs a sessão fornece o modelo ✓ sem API key aqui vivem --obsidian, --mode deep, --update Headless (terminal puro) graphify extract ./docs extração semântica via LLM ⚠ exige ANTHROPIC_API_KEY só código (tree-sitter/AST) dispensa a chave

↑ A chave só entra no caminho da direita (headless + documentos). Extrair código usa tree-sitter (AST) e não precisa de chave nem nesse caminho.

correção · API key headless

Objetivo: rodar a extração de documentos no terminal puro sem erro de chave.

# defina a chave na sessão (troque pelo seu valor real)
export ANTHROPIC_API_KEY=<sua-chave>

# agora a extração semântica de documentos funciona headless
graphify extract ./docs

Verificar: echo $ANTHROPIC_API_KEY mostra a chave e a extração começa sem reclamar. Dentro do Claude Code, pule isto inteiro — não é preciso.

✓ Não precisa de chave

  • ✓Rodar /graphify dentro do Claude Code.
  • ✓Extrair código (tree-sitter/AST), em qualquer caminho.

✗ Precisa de chave

  • ✗Extrair documentos/PDF via LLM…
  • ✗…no terminal puro (CI, scripts headless).

🔑 Conceitos-chave

headless
Terminal puro
skill
Modelo da sessão
API key
Só docs headless
AST
Código sem chave
5

🧹 Grafo barulhento ou raso

Às vezes o grafo sai barulhento (entidades demais, muitas irrelevantes) ou raso (poucas relações, nada conecta). Na esmagadora maioria das vezes a culpa não é do Graphify — é do corpus: a qualidade do grafo espelha a qualidade da fonte. "Lixo entra, lixo sai." A correção começa na fonte, não no comando.

🔰 Três alavancas, nesta ordem

  • 1.Limpe a fonte: tire changelogs, arquivos auto-gerados, boilerplate e duplicatas — eles inflam o grafo com ruído.
  • 2.Re-escope: aponte para a subpasta que importa (graphify extract ./src) em vez do repositório inteiro.
  • 3.Suba a profundidade: --mode deep faz uma extração mais minuciosa quando o grafo ficou raso.
correção · profundidade

Objetivo: reextrair com mais profundidade quando o grafo veio raso demais.

# dentro do Claude Code — extração minuciosa (--mode deep é da skill)
/graphify ./docs --mode deep

# alternativa: re-escopar para a parte que importa (headless)
# graphify extract ./src

Verificar: compare o GRAPH_REPORT.md antes/depois — mais relações por entidade e god nodes que fazem sentido indicam um grafo mais profundo.

Leia sempre o GRAPH_REPORT.md: ele lista god nodes, conexões entre comunidades e perguntas sugeridas — é o seu termômetro de "o grafo ficou bom?".

🔑 Conceitos-chave

corpus
Fonte = qualidade
escopo
Aponte ./src
--mode deep
Mais minucioso
REPORT
Termômetro
6

📦 Versionar e exportar a jornada

Você construiu um segundo cérebro — agora não perca. Duas frentes: versionar os artefatos do Graphify no git (para o grafo ser reprodutível e voltar no tempo), e exportar o seu progresso de leitura aqui no curso (o .json de "Minha jornada"). Backup é o que separa "eu tinha" de "eu tenho".

1

Commite o grafo

Versione graphify-out/ (ou ao menos o graph.json) no git — ele é a fonte de verdade da qual tudo deriva.

2

Backup do vault

O vault Obsidian é regenerável a partir do grafo, mas suas notas pessoais não — versione a pasta delas separada dos imports.

3

Exporte sua jornada

No painel Minha jornada deste curso, exporte o .json com leituras, dúvidas e anotações — e reimporte em outro dispositivo.

correção · versionar o grafo

Objetivo: guardar o grafo no git para nunca perder e poder reproduzir.

# versione os artefatos do Graphify (o cache pode ficar fora)
echo "graphify-out/cache/" >> .gitignore
git add graphify-out/ .gitignore
git commit -m "chore: snapshot do segundo cérebro (graphify-out)"

Verificar: git log --stat mostra o graph.json commitado. Num clone novo, o grafo está lá — sem reextrair.

🔑 Conceitos-chave

git
Versiona o grafo
backup
Vault + notas
export
.json da jornada
reprodutível
Volta no tempo

✋ Auto-recuperação (opcional, não bloqueia): o flag --obsidian existe nos subcomandos headless (graphify extract / update)?

📌 Resumo do módulo

✓
Incremental: graphify update . reprocessa só o que mudou; re-exporte o vault depois.
✓
Vault regenera: nunca edite os imports — separe suas notas em outra pasta.
✓
command not found: uv tool update-shell e reabra o terminal.
✓
API key: só no headless com documentos; dentro do /graphify não precisa.
✓
Grafo raso: limpe o corpus, re-escope ou suba pra --mode deep.
✓
Não perca: versione graphify-out/ no git e exporte sua jornada.
🎉

Você concluiu o curso!

Da teoria do segundo cérebro (Trilha 1), passando pelo passo a passo prático (Trilha 2), até o uso real e a manutenção (Trilha 3) — você agora sabe montar, consultar e manter um segundo cérebro consultável para o Claude Code. Versione, exporte e siga construindo.

← Voltar para a Trilha 3 Concluir — voltar ao início →