🧭 Código vs. documentos: cuándo detenerse en Graphify
No todos los grafos tienen que convertirse en un vault. Aquí aprendes la diferencia entre extraer código y extraer documentos, y a decidir —con criterio, no por moda— cuándo el grafo ya es suficiente y cuándo conviene llevarlo a Obsidian.
🧱 Grafo de la base de código: AST, tree-sitter y sin clave
Cuando le indicas a Graphify un repositorio de código, no "lee" el código como texto corrido. Hace análisis estructural: lee la sintaxis del lenguaje y construye un árbol de funciones, clases, módulos y sus llamadas. El resultado se convierte en el grafo: nodos que son funciones y módulos, aristas que son "llama", "importa", "define".
🔰 ¿Eres nuevo aquí? Qué son «AST» y «tree-sitter»
AST (Abstract Syntax Tree, árbol de sintaxis abstracta) es la representación en árbol de la estructura de un programa: la función X contiene la llamada Y, que recibe el argumento Z. Es como la computadora «entiende» el código por debajo, sin ambigüedad.
tree-sitter es la biblioteca que Graphify usa para generar esa AST de forma rápida y confiable, en 12 lenguajes. Es puro análisis sintáctico: en esta etapa no se llama a ningún modelo de IA.
La consecuencia práctica es importante: extraer una base de código es determinístico, rápido y sin API key. No es posible que haya «alucinaciones»: el árbol refleja exactamente la sintaxis del archivo. Puedes ejecutarlo en un proyecto enorme sin gastar ningún token del 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 es el camino headless (terminal pura). Para el código, funciona sin ninguna clave: tree-sitter hace todo el trabajo.
✓ Fuerte en código
- ✓Estructura exacta: funciones, clases, imports.
- ✓Rápido y económico: sin llamar a un modelo.
- ✓Determinístico: cero alucinaciones.
✗ No entiende el sentido
- ✗No capta la intención detrás del código.
- ✗Ignora los comentarios y la prosa explicativa.
- ✗"¿Por qué existe esto?" no está en el AST.
🔑 Conceptos clave
📄 Grafo de documentos: LLM y semántica
Los documentos no tienen sintaxis de programa: una página de documentación o un PDF es prosa. Por eso Graphify cambia de estrategia: en lugar de tree-sitter, usa un LLM para leer cada documento y entender de qué conceptos habla y cómo se relacionan. Es una extracción semántica: por el significado, no por la forma.
🔰 ¿Eres nuevo aquí? «LLM», «corpus» y «semántica»
LLM (Large Language Model, modelo de lenguaje) es el modelo de IA que entiende y genera texto: es el motor detrás de Claude. Aquí lee los documentos y extrae los conceptos.
Corpus es el conjunto de documentos que le das para procesar: tu carpeta de documentos, PDFs, notas.
Semántica = relativo a significado. La extracción semántica capta «este texto habla de autenticación y la relaciona con sesiones», aunque la palabra exacta no se repita.
↑ El mismo Graphify, dos motores. El código se convierte en estructura (AST, sin clave); los documentos se convierten en significado (LLM, semántico). Dentro de /graphify en Claude Code, la sesión ya proporciona el modelo — no necesitas una clave tampoco aquí.
🔑 Conceptos clave
🛑 Cuándo detenerse en Graphify
Existe la tentación de llevar cualquier grafo a Obsidian «porque se puede». Pero el grafo ya es útil por sí solo. O graph.html (visualización interactiva autocontenida) se abre en el navegador sin servidor, y graphify query responde preguntas directamente. Para explorar un code base puntual o resolver una duda rápida, eso basta.
💡 La regla de oro
Si la respuesta desaparece cuando cierras la terminal —y no te molesta— detente en el grafo. El vault solo cobra sentido cuando el conocimiento necesita persistir e convivir con el resto de lo que sabes.
- •Pregunta única y descartable: grafo + query, fin.
- •Auditar un repo que no es tuyo: explore el
graph.html, no exportes. - •Sin intención de mantener: exportar sería overhead.
↑ Flechas verdes = sí, rojas = no. La pregunta nunca es «¿se puede exportar?», sino «¿este conocimiento necesita vivir fuera de la terminal?».
🔑 Conceptos clave
🔮 Cuándo llevarlo a Obsidian
Obsidian entra en escena cuando el conocimiento deja de ser una consulta puntual y se convierte en archivo. Al exportar, Graphify genera un archivo Markdown por nodo con wikilinks [[nome-do-no]] y backlinks — entonces ese grafo empieza a convivir con tus otras notas, proyectos e ideas en un único vault navegable.
# exporta o grafo como vault Obsidian (um .md por nó + backlinks) /graphify ./claude-code-docs --obsidian --obsidian-dir ~/vault/graphify/claude-code
↑ El flag --obsidian solo existe en el camino skill (/graphify dentro de Claude Code), no en el graphify extract headless.
✓ Vale la pena exportar cuando…
- ✓El conocimiento se volverá a consultar muchas veces.
- ✓Quieres vincularlo con tus notas (segundo cerebro integrado).
- ✓Quieres navegar visualmente por el grafo en Obsidian.
✗ No vale la pena cuando…
- ✗Es una sola pregunta que no volverás a revisar.
- ✗El repo ni siquiera es tuyo: solo lo estás auditando.
- ✗No vas a mantener el vault actualizado.
🔰 ¿Eres nuevo aquí? Qué es un «vault»
Vault es la «caja» de Obsidian: una carpeta de archivos markdown enlazados entre sí. La exportación de Graphify llena un vault con una nota por concepto; ahí es donde el grafo se convierte en memoria persistente y navegable, no solo en un archivo en la terminal.
🔑 Conceptos clave
🔁 Mantener el código y la documentación sincronizados
Código y documentación cambian. Un grafo congelado el día de la extracción envejece y miente. La solución no es volver a extraer todo desde cero cada vez, sino la actualización incremental: Graphify guarda un cache/ por archivo (según el hash del contenido) y solo vuelve a procesar lo que cambió.
# reprocessa só os arquivos modificados desde a última vez graphify update . # rebuild automático: fica observando e atualiza ao salvar graphify watch .
↑ graphify update . = actualización bajo demanda; graphify watch . = continuo. Dentro de Claude Code, el equivalente es /graphify . --update e /graphify . --watch.
La fuente cambia
Editas el código o agregas un doc nuevo al proyecto.
update reprocesa solo el delta
La caché por hash evita volver a llamar al LLM para archivos que no se modificaron. Barato.
Vuelve a exportar el vault (si usas Obsidian)
La exportación es regenerado desde cero — así que mantén tus notas lejos de la carpeta de imports.
⚠️ Cuidado con la reexportación
La exportación de Obsidian es regenerado cada vez. Si editaste a mano una nota generada, esa edición se pierde en la próxima exportación. Mantén las importaciones y tus notas en carpetas separadas; el módulo 2.5 se ocupa de eso.
🔑 Conceptos clave
🧮 Costo, ruido y mantenimiento
Toda esta estructura tiene un costo real, no es solo hype. Decidir bien entre código y documentos, detenerse en el grafo o pasar al vault, es una cuenta de tres variables: tiempo/costo de extracción, ruido del grafo y esfuerzo de mantenimiento. Sopesarlos antes evita que te conviertas en un coleccionista de grafos abandonados.
Costo de extracción
El código (AST) es casi gratis. Los documentos invocan al LLM — más lento y, fuera de Claude Code, consume tokens de tu clave. El cache/ se atenúa en las siguientes ejecuciones.
Ruido del grafo
Un corpus enorme genera cientos de nodos; no todos son útiles. Usa el GRAPH_REPORT.md (nodos clave, comunidades) para comprobar si la señal es buena antes de exportar.
Mantenimiento del vault
Un vault solo ayuda si se mantiene actualizado. Si no vas a ejecutar update de vez en cuando, quizá sea mejor detenerse en el grafo.
💡 La pregunta honesta
"¿Este grafo/vault me devolverá más de lo que me costará crearlo y mantenerlo?" Si la respuesta es no, detente en Graphify — o ni siquiera lo extraigas. El criterio siempre está por encima de la moda.
🔑 Conceptos clave
✋ Autorrecuperación (opcional, no bloquea): ejecutaste Graphify en un repo que no es tuyo, solo para resolver una duda puntual sobre cómo funciona una función. ¿Dónde deberías parar?
📌 Resumen del módulo
Siguiente módulo
3.4 · Mantenimiento y solución de problemas — mantener saludables el grafo y el vault y resolver los errores más comunes.