01 El problema: Claude leyendo a ciegas
Cuando le preguntas a Claude Code cómo está organizado un proyecto grande, lo habitual es que empiece a buscar archivos y a abrirlos uno tras otro. En un repositorio pequeño no importa, pero en uno con cientos de archivos se llena el contexto antes de llegar a una respuesta, y cada lectura consume tokens de tu plan.
Graphify ataca ese problema construyendo antes un mapa del proyecto. Es una herramienta de código abierto (licencia Apache 2.0) que se instala como paquete de Python y como skill de tu asistente. Una vez generado el grafo, Claude consulta las relaciones ya calculadas y solo abre los archivos que realmente necesita.
Análisis de código local
El código se analiza con árboles de sintaxis (tree-sitter) en tu equipo: sin modelo de lenguaje y sin enviar nada fuera. Reconoce unos 40 lenguajes.
Pasada semántica para documentos
Markdown, PDF, imágenes y vídeo pasan por el modelo de tu asistente para extraer conceptos y relaciones que no están escritos como código.
Comunidades
Agrupa los nodos en subsistemas según cómo se conectan (algoritmo Leiden), sin bases vectoriales ni embeddings.
Relaciones etiquetadas
Cada conexión lleva la etiqueta EXTRACTED si aparece explícita en el código o INFERRED si la ha deducido, para que sepas qué es dato y qué es interpretación.
02 Instalación paso a paso
-
1
Comprueba Python
Ejecuta python3 --version y verifica que tienes la 3.10 o superior. En Mac puedes instalarlo junto con uv mediante Homebrew.
-
2
Instala la herramienta
La opción recomendada es uv, que la deja aislada del Python del sistema. Si prefieres pipx, funciona igual.
-
3
Registra la skill
graphify install detecta tu asistente y registra la skill. Con --project la instala solo en el repositorio actual, dentro de .claude/skills, para que la comparta el equipo.
-
4
Genera el primer grafo
Abre Claude Code en la raíz del proyecto y escribe /graphify . (con el punto). La primera vez tarda más; las siguientes solo procesan lo que haya cambiado.
uv tool install graphifyy
# alternativa: pipx install graphifyy
graphify install
# solo para este repositorio:
# graphify install --project03 Qué genera y cómo leerlo
| Archivo en graphify-out/ | Para qué sirve |
|---|---|
| GRAPH_REPORT.md | Resumen legible: nodos más conectados, comunidades, conexiones sorprendentes y preguntas sugeridas |
| graph.json | El grafo completo, que se consulta con query, path y explain sin releer los archivos |
| graph.html | Visualización interactiva en el navegador: clic en nodos, búsqueda y filtro por comunidad |
Empieza siempre por el informe. Los nodos más conectados (los «god nodes») suelen ser las piezas de las que depende todo; si alguno te sorprende, ahí tienes un posible problema de diseño. Las comunidades te dan la división real en módulos, que no siempre coincide con las carpetas.
/graphify query "¿qué conecta la autenticación con la base de datos?"
/graphify path "UserService" "DatabasePool"
/graphify explain "RateLimiter"
# actualizar solo lo que ha cambiado
/graphify . --update04 Prompts para sacarle partido
Acabo de generar el grafo de este proyecto con Graphify. Lee graphify-out/GRAPH_REPORT.md antes de abrir ningún archivo.
Explícame en lenguaje sencillo:
1. Qué hace el proyecto y cuáles son sus 4 o 5 subsistemas principales.
2. Qué piezas concentran más dependencias y por qué eso puede ser un riesgo.
3. Por dónde entra una petición típica del usuario hasta la base de datos (usa graphify path si te hace falta).
Solo abre archivos concretos cuando el grafo no baste, y dime cuáles has abierto.Quiero modificar [componente o función]. Antes de tocar nada, usa graphify explain y graphify query para listar todo lo que depende de él, directa e indirectamente.
Devuélveme una tabla con: elemento afectado, tipo de relación, si la relación es EXTRACTED o INFERRED y el riesgo estimado (alto, medio, bajo). Después propón el orden de cambios más seguro y qué pruebas debería ejecutar en cada paso.Añade a CLAUDE.md una sección breve que diga: si existe graphify-out/graph.json, usa primero graphify query, path o explain para preguntas de arquitectura o dependencias, y solo después lee archivos concretos. Si el grafo parece desactualizado, avísame y propón ejecutar /graphify . --update. No borres nada de lo que ya hay en CLAUDE.md.05 Mantener el grafo al día
- ✓Instala el hook de git con graphify hook install para que el grafo se regenere en cada commit y cambio de rama.
- ✓Después de un git pull, ejecuta graphify update . para incorporar los cambios de otros.
- ✓Crea un archivo .graphifyignore en la raíz (misma sintaxis que .gitignore) para excluir dependencias, compilados y recursos pesados.
- ✓Graphify ya respeta tu .gitignore, así que normalmente solo tienes que añadir lo que esté versionado pero no aporte, como fixtures enormes.
- ✓Si solo te interesa el código, la extracción sin modelo (graphify extract con --code-only) funciona totalmente sin conexión.
06 Casos de uso en una agencia o empresa
Auditar código de un cliente
Recibes un proyecto que no conoces y necesitas presupuestar mejoras. El informe del grafo te da en minutos la estructura, los puntos frágiles y las zonas sin documentar.
Incorporar a alguien al equipo
El archivo graph.html es una forma visual de enseñar cómo encaja todo. Combinado con GRAPH_REPORT.md, sustituye buena parte de la primera semana de preguntas.
Documentación y PDF dispersos
Una carpeta con manuales, actas y presentaciones se convierte en un mapa de conceptos relacionados. Con --wiki genera además artículos en Markdown por comunidad.
Revisar refactorizaciones
Antes de mover un módulo, el grafo te dice quién lo usa. Reduce el riesgo de romper algo en una parte del sistema que nadie revisa.
07 Límites y privacidad
El ahorro de tokens depende del tamaño: en un proyecto de cinco archivos no ganarás nada, porque Claude ya puede leerlo entero. Donde compensa es en repositorios grandes o carpetas que mezclan código, documentos e imágenes. Tampoco es un buscador semántico: si lo que necesitas es encontrar textos parecidos por significado, un sistema con embeddings resuelve otro problema distinto.
En cuanto a privacidad, el código se procesa en local. Los documentos, PDF e imágenes, en cambio, se envían al modelo de tu asistente para la pasada semántica. Las consultas se registran en un archivo local de tu equipo; puedes desactivarlo con la variable GRAPHIFY_QUERY_LOG_DISABLE=1.
Preguntas frecuentes
No. Además de Claude Code admite Cursor, Codex, Gemini CLI, GitHub Copilot y otros asistentes. graphify install detecta el tuyo y con la opción --platform eliges uno concreto.
Si lo usas desde la skill, no: la pasada semántica usa el modelo de tu sesión. Solo necesitas una clave si ejecutas la extracción sin asistente sobre documentos; para código puro no hace falta ninguna.
Depende del equipo. Compartir el grafo hace que todos consulten el mismo contexto, pero añade archivos generados. Una opción equilibrada es no versionarlo y que cada persona lo regenere con el hook de git.
El código se procesa rápido porque es local. Lo que más tarda es la pasada semántica sobre documentos y PDF. Las siguientes ejecuciones usan una caché y solo reprocesan lo que ha cambiado.
No, lo complementa. CLAUDE.md recoge decisiones, convenciones y normas; el grafo describe la estructura real del código. Lo ideal es que CLAUDE.md indique a Claude que consulte el grafo primero.
Sobre el autor
Equipo editorial de appyweb
Marketing, SEO y desarrollo con IA
Especialistas de appyweb en SEO, publicidad, desarrollo web y automatización con IA.