Graphify para Claude Code: convierte tu repositorio en un grafo que puedes consultar

Graphify Claude Code: convierte un repositorio en un grafo que puedas consultar

Un repositorio con 800,000 líneas de código puede contener la respuesta a una pregunta aparentemente sencilla en seis lugares distintos: un módulo de Terraform, una migración de base de datos, un cliente generado, un documento OpenAPI, un manifiesto de despliegue y un manual operativo escrito hace dos años.

Claude Code puede buscar y leer esos archivos, pero el trabajo a escala de repositorio suele estar limitado por la rapidez con la que el agente puede descubrir las relaciones entre ellos. Una búsqueda de texto de customer_id encuentra coincidencias. No explica automáticamente que:

• customer_id se declara en una migración de base de datos,
• se expone mediante un esquema de API,
• se mapea en un modelo ORM,
• se copia en la carga útil de un evento,
• lo consume un proceso de trabajo en segundo plano,
• y se menciona en un procedimiento de reversión en producción.

Graphify aborda este problema convirtiendo el material del repositorio en un grafo de conocimiento: las entidades se convierten en nodos, las referencias y dependencias se convierten en aristas, y Claude Code puede consultar esa estructura como contexto adicional.

La salvedad importante es que un grafo no es una segunda fuente de verdad mágica. Es una interpretación indexada de tu repositorio. Su valor depende de la cobertura de los analizadores, de la disciplina de actualización, de los permisos y de lo bien que las relaciones resultantes respondan a preguntas reales de ingeniería.

Qué aporta Graphify a Claude Code

Claude Code ya dispone de varias formas útiles de comprender un proyecto:

• Lectura directa de archivos
• rg y otras búsquedas mediante comandos de shell
• Historial y diferencias de Git
• Instrucciones del proyecto en CLAUDE.md
• Habilidades para flujos de trabajo repetibles
• Servidores MCP para herramientas y datos externos

Graphify añade un patrón de acceso diferente: recuperación orientada a relaciones.

Una búsqueda convencional pregunta:

¿Dónde aparece este símbolo?

Una consulta de grafo pregunta:

¿Qué servicios dependen de este esquema, qué infraestructura despliega esos servicios y qué documentos describen las consecuencias operativas?

Esa distinción importa cuando la tarea abarca áreas de responsabilidad o formatos de archivo diferentes.

Un grafo típico puede contener nodos como los siguientes:

Las aristas pueden representar relaciones como las siguientes:

• imports
• calls
• implements
• extends
• reads_from
• writes_to
• publishes
• consumes
• deploys
• configured_by
• documented_by
• owned_by
• depends_on

El vocabulario exacto de nodos y aristas depende de los indexadores y la configuración actuales de Graphify. Trata el esquema del grafo como una parte del producto que puedes inspeccionar, no como una suposición. Antes de elaborar prompts en torno a una relación como publishes, verifica que la versión instalada realmente la genere.

Instalación de Graphify para Claude Code

Graphify es un proyecto activo, por lo que la instalación y los nombres de los comandos de inicio pueden cambiar. Empieza por el repositorio y utiliza el comando de instalación documentado para la versión que vayas a adoptar:

git clone https://github.com/Graphify-Labs/graphify.git
cd graphify

Si utilizas un paquete publicado, es preferible usar el comando del gestor de paquetes documentado por el proyecto en lugar de copiarlo de una entrada antigua de blog. Después de la instalación, comprueba tres aspectos antes de indexar un monorepositorio grande:

graphify --help
graphify version
graphify config --help

Los comandos anteriores ilustran las comprobaciones que debes realizar; utiliza el ejecutable y los subcomandos que ofrece la versión instalada.

Una primera ejecución segura debe realizarse sobre un repositorio pequeño de prueba:

mkdir -p /tmp/graphify-fixture
cd /tmp/graphify-fixture

git init
printf 'def charge(order):\n    return order.total\n' > billing.py
printf 'from billing import charge\n' > worker.py

graphify index .

La indexación inicial suele realizar alguna combinación de descubrimiento, análisis, extracción de relaciones y persistencia del grafo. En un repositorio real, inspecciona la configuración generada y la ubicación de almacenamiento antes de incorporarla a CI. Debes saber si el índice:

• Es local o está alojado
• Se actualiza de forma incremental o se reconstruye por completo
• Se almacena de forma persistente en una base de datos, en archivos o en un almacén embebido
• Puede ejecutarse de forma segura al mismo tiempo que otro indexador
• Permite excluir secretos, artefactos de compilación y árboles de dependencias de terceros

Para integrarse con Claude Code, Graphify debe exponerse mediante el mecanismo de integración que admita el proyecto, habitualmente MCP. Un archivo local .mcp.json podría tener este aspecto:

{
  "mcpServers": {
    "graphify": {
      "command": "graphify",
      "args": ["mcp", "--project", "."],
      "env": {
        "GRAPHIFY_INDEX": ".graphify/index"
      }
    }
  }
}

No consideres que ese subcomando concreto sea universal. Confirma el punto de entrada de MCP con:

graphify mcp --help

Después, valida el servidor desde Claude Code:

/mcp

Deberías ver el servidor de Graphify y sus herramientas disponibles. Los nombres de las herramientas y la sintaxis de las consultas dependen de la versión. La verificación útil es operativa: pide a Claude Code que enumere las herramientas del grafo, ejecute una consulta acotada e indique qué revisión del repositorio se indexó.

Un problema habitual es iniciar Claude Code desde el directorio equivocado. Las rutas relativas del proyecto en .mcp.json, los archivos de exclusión y la configuración de Graphify se resuelven según el directorio de trabajo del proceso del servidor, que no es necesariamente el directorio que tenías en mente.

Las relaciones que importan en la práctica

El grafo resulta más útil cuando expone relaciones que son tediosas de reconstruir a partir del texto.

Del código al linaje de los datos

Supongamos que una migración cambia el nombre de accounts.status a accounts.lifecycle_state. Una búsqueda de texto puede identificar referencias, pero un grafo puede organizar el alcance del impacto:

table accounts
  -> column lifecycle_state
  -> migration 2025_04_rename_status
  -> model Account
  -> repository AccountRepository
  -> API response AccountSummary
  -> dashboard query active_accounts

Esto proporciona a Claude Code un mejor punto de partida para revisar una migración. Puede inspeccionar los archivos reales después de que el grafo identifique los elementos que probablemente dependan de ella.

Topología de servicios e infraestructura

Las relaciones de infraestructura son especialmente valiosas en monorepositorios donde conviven el código de la aplicación y el código de despliegue:

service payments-api
  -> container image payments-api
  -> Kubernetes deployment payments
  -> reads secret PAYMENTS_DATABASE_URL
  -> writes queue payment-events
  -> consumed by reconciliation-worker

Esto ayuda a responder preguntas como las siguientes:

• ¿Qué despliegue debe cambiar si cambia un puerto?
• ¿Qué consume esta cola?
• ¿Qué servicios comparten esta base de datos?
• ¿Qué configuración es específica de cada entorno?
• ¿Qué recurso de Terraform crea la dependencia?

Graphify no puede inferir perfectamente el comportamiento en tiempo de ejecución a partir de archivos estáticos. El descubrimiento dinámico de servicios, la reflexión, la configuración generada y la indirección mediante variables de entorno pueden dejar lagunas. Utiliza los resultados de topología como un mapa de impacto y, después, verifica las aristas críticas en la configuración de despliegue y de ejecución.

De la documentación a la implementación

La documentación suele quedar desconectada de las búsquedas de código porque la relación es semántica en lugar de sintáctica. Un manual operativo puede referirse al «procesador de liquidaciones», mientras que el repositorio lo llama reconciliation-worker.

Si Graphify vincula las referencias de la documentación con entidades de código o infraestructura, Claude Code puede responder preguntas operativas con menos exploración manual:

"Where is the rollback procedure for the component that consumes payment-events?"

La respuesta solo es fiable si los nombres de la documentación se mapean con precisión. La terminología desactualizada crea aristas plausibles pero incorrectas, lo cual es más peligroso que una búsqueda que claramente no encuentra resultados.

Graphify, las habilidades y MCP son capas diferentes

Graphify debe complementar los puntos de extensión existentes de Claude Code en lugar de sustituirlos.

Una arquitectura útil es la siguiente:

1. Graphify descubre entidades candidatas y dependencias.
2. Claude Code usa esos resultados para seleccionar archivos.
3. Las herramientas nativas de archivos verifican la implementación actual.
4. Una habilidad aplica el procedimiento de revisión o modificación del equipo.
5. Las pruebas, los analizadores de código y las comprobaciones de despliegue aportan la evidencia final.

Por ejemplo, una habilidad de revisión de migraciones podría estar en .claude/skills/review-migration/SKILL.md:

# Review Database Migration

When reviewing a migration:

1. Identify renamed, removed, or changed columns.
2. Query Graphify for code, schema, event, and infrastructure dependents.
3. Read each high-confidence dependent from the working tree.
4. Check backward compatibility for deployed application versions.
5. Run the repository migration and contract tests.
6. Report uncertain graph relationships separately from verified findings.

La habilidad define el flujo de trabajo. Graphify aporta contexto sobre las relaciones. MCP es el medio de transporte y el límite de las herramientas.

Esta separación es importante. Incluir todo el conocimiento del grafo en una habilidad produciría instrucciones estáticas que quedarían obsoletas rápidamente. Incluir todas las políticas del flujo de trabajo en Graphify haría que el indexador fuera responsable de decisiones que no puede tomar de forma fiable.

Gestión del coste y la actualización del índice

La indexación tiene un coste en recursos de cómputo, disco, latencia y complejidad operativa. El coste no se limita al primer análisis. Los repositorios grandes también requieren trabajo de actualización cuando cambian las ramas, se reconstruyen los archivos generados o se invalidan los grafos de dependencias.

Empieza por las exclusiones:

# .graphifyignore
.git/
node_modules/
vendor/
dist/
build/
coverage/
tmp/
*.min.js
*.map
.env
*.pem

La sintaxis puede diferir de .gitignore, así que confirma cómo gestiona Graphify los archivos de exclusión. Excluye explícitamente las credenciales y las exportaciones sensibles, aunque Git ya las ignore. Una herramienta que indexa un archivo puede exponer su contenido a través de una vía de consulta.

Usa una política de indexación por etapas:

• Indexa el código fuente de la aplicación, los esquemas, la infraestructura y la documentación que se mantiene actualizada.
• Excluye los resultados generados, salvo que sean el artefacto de referencia.
• Construye un índice completo en CI o mediante una tarea programada.
• Actualiza el índice de una rama de forma incremental cuando sea compatible.
• Registra el commit de origen junto a los metadatos del grafo.
• Reconstruye el índice después de cambios en el analizador o la configuración.

La revisión de origen debe ser visible para el agente. Una estructura de respuesta como esta es mucho más segura que una lista sin información adicional:

{
  "query": "dependents of table accounts",
  "indexed_revision": "9f31a7c",
  "generated_at": "2025-05-14T10:22:11Z",
  "results": [
    {
      "entity": "AccountRepository",
      "relationship": "reads_from",
      "target": "accounts",
      "confidence": "high",
      "path": "src/accounts/repository.py"
    }
  ]
}

Cuando Claude Code modifica un árbol de trabajo después de la última indexación, los resultados del grafo son contexto histórico. Los archivos actuales tienen prioridad. En la práctica, le indico al agente que incluya indexed_revision en su razonamiento y que vuelva a comprobar cada afirmación derivada del grafo con el árbol de trabajo.

Precisión, privacidad y límites en producción

Un grafo puede hacer que la información incompleta parezca autorizada. Hay varios tipos de fallos que conviene prever:

• No se detectan las importaciones dinámicas ni la reflexión.
• Los scripts de shell ocultan relaciones mediante la expansión de variables.
• Los clientes generados ocultan el esquema de origen.
• Los enlaces de la documentación usan alias que el analizador no reconoce.
• Los archivos eliminados permanecen hasta que se ejecuta una limpieza o reconstrucción.
• Se consulta el índice de una rama mientras el agente trabaja en otra.
• Los módulos de infraestructura se interpretan sin los valores específicos del entorno.

En los flujos de trabajo de producción, muestra el nivel de confianza y la procedencia siempre que sea posible. Una relación sin una ruta de archivo, una revisión o un método de extracción es difícil de auditar.

La privacidad requiere la misma atención. Los grafos de repositorios pueden revelar:

• Nombres de servicios internos
• Modelos de datos de clientes y pagos
• Topología de la red
• Secretos a través del nombre de archivo o de referencias en la configuración
• Dependencias sensibles desde el punto de vista de las vulnerabilidades
• Documentación propietaria

Mantén los índices sensibles en local o dentro del mismo perímetro de confianza que el repositorio. Usa una configuración de MCP con privilegios mínimos, excluye el material secreto y evita enviar el contenido del grafo a un servicio alojado, salvo que la organización haya aprobado ese flujo de datos. La capacidad de Claude Code para consultar un grafo no cambia los requisitos de control de acceso del repositorio.

La popularidad tampoco equivale a fiabilidad. Un proyecto puede atraer mucha atención y aun así tener una cobertura inmadura del analizador, esquemas de grafo inestables, garantías de actualización limitadas o un comportamiento insuficiente ante cambios frecuentes a escala de monorepositorio. Evalúalo con un conjunto de casos de prueba extraído de tu propio repositorio:

• ¿Identifica las importaciones y las dependencias de servicios conocidas?
• ¿Elimina las relaciones borradas?
• ¿La indexación incremental converge al mismo resultado que una reconstrucción desde cero?
• ¿Pueden los usuarios distinguir los resultados desactualizados y los de baja confianza?
• ¿El servidor MCP indica claramente el fallo cuando el índice no está disponible?
• ¿Las consultas son lo suficientemente rápidas para el trabajo interactivo del agente?
• ¿Puedes reproducir el índice en CI?

No conviertas Graphify en un requisito obligatorio para cada acción del agente. Es esencial contar con un modo degradado que recurra a la búsqueda habitual de archivos.

Un patrón práctico de adopción

Empieza con un flujo de trabajo en el que descubrir relaciones sea costoso y los errores sean visibles, como los cambios en API, las migraciones de bases de datos o las refactorizaciones de infraestructura.

Mide resultados útiles en lugar del tamaño del grafo:

• Tiempo para identificar los componentes afectados
• Número de componentes dependientes no detectados durante la revisión
• Proporción de relaciones desactualizadas o incorrectas
• Tiempo de indexación después de commits habituales
• Fallos de consulta y frecuencia de uso del mecanismo alternativo
• Datos adicionales expuestos al modelo

Usa Sonnet 4.6 para investigaciones amplias del repositorio cuando importe la profundidad del razonamiento, Haiku 4.5 para clasificaciones ligeras o tareas de consulta repetidas, y Fable 5, con su mayor capacidad de contexto, cuando el flujo de trabajo del proyecto con contexto de 1M realmente se beneficie de incluir una gran cantidad de evidencia. La elección del modelo no corrige un grafo deficiente. Un modelo más pequeño con relaciones precisas y actuales puede ser más útil que uno más grande que recibe un volcado del índice sin filtrar.

El patrón práctico del prompt consiste en indicar explícitamente la procedencia:

Use Graphify to identify likely dependents of the `accounts.lifecycle_state`
column. For every result, include its path, indexed revision, relationship,
and confidence. Then read the current files and discard relationships that
do not exist in the working tree. Do not treat graph results as proof.

Esa última frase no es una formalidad. Evita que una capa de contexto desactualizada se convierta en una autoridad incuestionada.

Conclusiones prácticas

• El valor principal de Graphify es la recuperación de relaciones entre código, esquemas, infraestructura y documentación.
• Instala la herramienta con una versión específica, inspecciona sus comandos reales de CLI y MCP, y pruébala con un caso de prueba antes de indexar un monorepositorio.
• Mantén a Graphify como responsable del contexto del repositorio; usa las habilidades de Claude Code para los procedimientos de ingeniería repetibles.
• Incluye la revisión del índice, la procedencia y el nivel de confianza en las respuestas del grafo.
• Excluye los secretos, el ruido generado y el contenido innecesario de terceros.
• Trata los resultados del grafo como pistas que deben verificarse con el árbol de trabajo actual.
• Prueba la indexación incremental, la gestión de eliminaciones, el aislamiento entre ramas y el funcionamiento en modo degradado antes de adoptarlo en producción.
• La popularidad puede justificar una evaluación, pero solo la precisión específica para el repositorio y el comportamiento operativo justifican depender de la herramienta.