TheFittClub Vault

Graphify — plan de adopción (dev repo + vault)

4 min read

Graphify — plan de adopción

Ticket del dev repo: T228 (_docs/03-tickets/01-pending/228-ai-harness-graphify-knowledge-graph-mcp.md en gala1234/thefittclub). Este doc captura la decisión vault-side: por qué el grafo se adopta primero en el repo de desarrollo y bajo qué condiciones se pilotaría en este vault.

Qué es

Graphify convierte una carpeta de código/docs en un grafo de conocimiento consultable (graph.json + informe + visualización) y lo expone como servidor MCP con herramientas de consulta acotadas (query_graph, get_node, get_neighbors, shortest_path, análisis de impacto affected). Para los agentes (Claude Code), responder “¿qué conecta X con Y?” pasa de greps masivos + lecturas de archivos enteros a una consulta de grafo con presupuesto de tokens explícito.

Punto técnico que decide todo el plan:

  • Código → extracción local vía tree-sitter. Cero llamadas LLM, cero coste.
  • Markdown / PDFs / imágenes → extracción semántica vía LLM. Una llamada por chunk: construir y reconstruir el grafo cuesta tokens/API.

Validación empírica (2026-06-12, contenedor remoto de Claude Code)

  • uv tool install graphifyy funciona bajo la política de red actual (v0.8.38; Python 3.11 + uv ya presentes).
  • graphify update . sobre el dev repo: ~20 s, cero llamadas LLM → 12.983 nodos / 17.789 aristas / 886 comunidades. graph.json = 11 MB (por eso se regenera por sesión y no se commitea).
  • graphify query "..." --budget N devuelve listados estructurados respetando el presupuesto.
  • Caveat observado: el seeding por palabra clave puede matchear el nodo equivocado (consultó “dashboard” y devolvió el script del dashboard del vault, no la superficie de la app). La formulación de la consulta importa; T228 documenta la guía.

Decisión

Fase 1 — Dev repo (gala1234/thefittclub): SÍ, vía T228

ROI claro: el coste de exploración (greps, lecturas de orientación, barridos de subagentes) es de los mayores consumos de tokens por sesión de implementación, y el grafo de código sale gratis (AST local). Menos tokens de exploración = más presupuesto para usar los modelos grandes (Fable/Opus) en la implementación en sí. Complementa, no sustituye, al tsserver-mcp ya montado (T149: nivel símbolo; graphify: nivel arquitectura).

Plan por fases (detalle completo en el spec T228): smoke del servidor MCP → bootstrap por sesión (install pineado + rebuild ~20 s, graphify-out/ gitignored) → validación cruzada con número de ahorro concreto → guía de selección de herramienta en _docs/00-rules/skills-catalog.md.

Fase 2 — Este vault: PILOTO CONDICIONAL, no ahora

El vault es ~100 % markdown, así que aquí el grafo no sale gratis: construirlo y reconstruirlo requiere extracción semántica LLM (coste por chunk, recurrente con cada cambio). Además el vault ya tiene su propia capa de conocimiento curada — NEGOCIO_SSOT.md + _INDEX_NEGOCIO.md + Dataview — que cumple parte de la función de un grafo (un dato vive en un sitio, los índices mapean roles). El beneficio marginal es menor y el coste mayor: exactamente lo contrario que en el dev repo.

Condiciones para activar el piloto (todas):

  1. La Fase 1 cierra en el dev repo con un ahorro de tokens medido (el número del paso de validación de T228).
  2. Sigue habiendo sesiones de vault cuyo coste dominante es orientación/exploración que los índices existentes no resuelven.
  3. El alcance del piloto se limita a los docs estratégicos (los de _INDEX_NEGOCIO.md), excluyendo 99_Archivo/, quartz/, Historico_Social/ y artefactos generados, con --token-budget explícito en la extracción.

Si se activa, abrir ticket nuevo en el dev repo (la infraestructura de tickets vive allí) y evaluar entonces graphify merge-graphs para el grafo cruzado dev+vault (responde “¿qué parte de la app implementa qué decisión de negocio?”).

Qué NO hace este plan

  • No commitea graph.json en ningún repo (11 MB regenerables en 20 s).
  • No toca las 5 reglas del vault ni el flujo SSOT — graphify sería una capa de lectura.
  • No sustituye los índices curados del vault: si el piloto demostrara que duplican función, esa decisión sería un ticket aparte, no un efecto colateral.

Graph View