🛠️ Mantenimiento, actualización y solución de problemas

Tu proyecto no se queda quieto: la documentación cambia, el código crece, los archivos entran y salen. El grafo tiene que seguirle el ritmo, pero rehacer todo desde cero en cada commit sería lento y costoso. La respuesta es el modo incremental: graphify update . reprocesa solo lo que cambió y reutiliza el resto de la caché.

El ciclo de mantenimiento tiene dos pasos. Primero, actualizar el grafo (graphify-out/graph.json es la fuente de verdad). Después, si usas el vault de Obsidian, vuelve a exportar con --obsidian para regenerar las notas. Recuerda: la exportación es derivado del grafo: actualizar el grafo no actualiza el vault por sí solo.

# 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

↑ El ciclo se cierra: cada vez que cambia la fuente, ejecutas update y vuelve a exportar. El grafo es la fuente de verdad; el vault se deriva de él, por eso se hacen ambos pasos.

Aquí está la trampa que más duele: la exportación de Obsidian es regenerado desde cero en cada ejecución. Si abriste una nota generada, escribiste tu propia reflexión dentro de ella y después volviste a ejecutar la exportación, esa edición se sobrescribe. Graphify no combina tus cambios: vuelve a crear el archivo.

Instalaste con uv tool install graphifyy, pero el terminal responde command not found. Tranquilo: el paquete se instaló, solo que no está en el PATH de tu shell. El uv tiene un comando que lo corrige en un paso.

# 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

Este no es el único tropiezo común durante la instalación y en el día a día. La tabla de abajo es tu mapa de «síntoma → causa → corrección»:

Un error de API key casi siempre significa una cosa: estás ejecutando Graphify headless (en la terminal pura) para extraer documentos, y la extracción semántica necesita un modelo. Dentro de Claude Code, mediante /graphify, la sesión ya proporciona el modelo: tú no no necesita ninguna clave.

↑ La clave solo entra en el camino de la derecha (headless + documentos). Extraer código usa tree-sitter (AST) y no necesita una clave ni siquiera en esta ruta.

# 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

A veces el grafo queda ruidoso (demasiadas entidades, muchas irrelevantes) o superficial (pocas relaciones, nada conecta). En la gran mayoría de los casos, la culpa no es de Graphify: es del corpus: la calidad del grafo refleja la calidad de la fuente. "Si entra basura, sale basura." La corrección empieza en la fuente, no en el comando.

# 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

Lee siempre el GRAPH_REPORT.md: enumera god nodes, conexiones entre comunidades y preguntas sugeridas: es tu termómetro para saber si "el grafo quedó bien".

Construiste un segundo cerebro — ahora no te lo pierdas. Hay dos frentes: versionar los artefactos de Graphify en git (para que el grafo sea reproducible y puedas volver atrás en el tiempo) y exportar aquí, en el curso, tu progreso de lectura (el .json de "Mi recorrido"). La copia de seguridad es lo que separa "lo tenía" de "lo tengo".

# 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)"