Knowledge graph de tu código: el antídoto al vibe coding

Generas 800 líneas con Claude Code en una tarde, pasan los tests, haces commit. Tres semanas después aparece un bug en producción y nadie del equipo sabe explicar por qué ese módulo funciona. Esa es la caja negra del vibe coding, y un knowledge graph del código es la forma más directa de abrirla.

TL;DR

• Qué es: un knowledge graph del código convierte tu codebase en un grafo navegable donde cada función, clase y archivo es un nodo y cada llamada o import es una arista, de modo que tú (y el agente) recorréis relaciones reales en vez de adivinar con grep.
• Por qué importa: el 45% del código generado por IA introduce vulnerabilidades del OWASP Top 10 (Veracode, 2025) y cada vez más desarrolladores despliegan código que no entienden. El grafo cierra esa brecha de comprensión.
• Qué aprenderás: a montar un grafo de tu repo con Understand-Anything en Claude Code, a complementarlo con herramientas de dependencias como madge o dependency-cruiser, y a usarlo en producción sin fiarte ciegamente de él.

El problema: código que funciona pero nadie entiende

El vibe coding (generar con un agente, mirar por encima y commitear) es el flujo dominante en 2026. A principios de año, la mayoría de desarrolladores profesionales usan herramientas de IA al menos cada semana. El problema no es la velocidad, es lo que queda debajo.

La deuda técnica del código generado por IA no se acumula, compone. Veracode probó más de 100 modelos sobre 80 tareas en Java, Python, C# y JavaScript: casi la mitad del código introducía fallos de seguridad serios, y los modelos más nuevos no mejoraban esa cifra. Es un problema estructural, no de versión. Si esto te suena al reto de auditar lo que un modelo decide por dentro, es el mismo espíritu que cuando hablamos de explicabilidad de modelos de IA con LIME y SHAP: necesitas ver qué hay dentro antes de confiar.

El fallo concreto en producción es sutil: el agente optimiza para terminar la feature, no para que esté bien. Clava el happy path y trata los edge cases como si no existieran. En una transición de estado de un pago, un humano que ha operado el sistema añade el guard contra transiciones ilegales porque ha sentido el dolor de que el dinero se mueva hacia atrás. El agente no. Ese conocimiento no está en los datos de entrenamiento.

¿Qué es un knowledge graph del código?

Un knowledge graph del código es una representación donde cada función, clase y archivo es un nodo, y cada llamada, import o herencia es una arista tipada, de forma que se pueden recorrer las relaciones estructurales del proyecto en vez de buscarlas a ciegas.

La construcción casi siempre sigue el mismo patrón: un parser determinista (normalmente tree-sitter) convierte el código en un árbol sintáctico (AST), extrae los símbolos y las relaciones, y los guarda en una base de datos de grafo o en un JSON navegable. Es la misma lógica de partir un documento grande en piezas con sentido que aplicamos al procesar PDFs para IA con chunking, solo que aquí las piezas son funciones y sus dependencias.

Por qué grep no basta en repos grandes

Conviene entender un detalle clave: Claude Code no indexa tu código con embeddings. Navega el sistema de archivos, lee ficheros y usa grep para encontrar lo que necesita, igual que un ingeniero. Funciona muy bien hasta cierto punto. Según la documentación de Anthropic, a partir de unas 30.000 líneas el agente deja de mantener un mapa mental útil: un grep de un nombre de función común devuelve miles de coincidencias y quema contexto. El grafo hace el trabajo de curado que un índice habría hecho, pero fuera del modelo. Esa idea de que el harness importa tanto como el modelo es exactamente lo que estás aplicando aquí.

Implementación paso a paso

Hay tres familias de herramientas según lo que necesites. Empieza por la primera fila si quieres entender un repo entero, y baja a las otras para casos concretos.

Herramienta	Qué hace	Cuándo usarla
Understand-Anything	Grafo completo + dashboard interactivo, multi-agente	Onboarding, entender un repo entero o código que no escribiste
madge / dependency-cruiser	Grafo de dependencias de módulos JS/TS, detecta ciclos	Ver arquitectura y dead code, validar reglas en CI
code2flow	Call graphs por análisis estático (Python, JS, Ruby, PHP)	Trazar el flujo de llamadas de una función concreta
claude-context / cocoindex (MCP)	Búsqueda semántica del código vía MCP	Reducir tokens en repos grandes dentro del agente

Paso 1: instalar Understand-Anything en Claude Code

Es un plugin nativo de Claude Code (también funciona con Cursor, Copilot, Codex y Gemini CLI). Se instala desde el marketplace de plugins.

# Añade el marketplace y instala el plugin (dos comandos slash dentro de Claude Code)
/plugin marketplace add Lum1104/Understand-Anything
/plugin install understand-anything

Paso 2: construir el grafo

El comando /understand lanza un pipeline de varios agentes (escáner de proyecto, analizador de archivos, analizador de arquitectura) que parsea con tree-sitter y resume cada pieza con el modelo.

# Analiza el repo y genera .understand-anything/knowledge-graph.json + dashboard
/understand

# Abre el dashboard visual con los nodos coloreados por capa (API, servicio, datos, UI)
/understand-dashboard

Output esperado: un fichero knowledge-graph.json en la raíz y un dashboard donde cada nodo trae un resumen en lenguaje plano de qué hace, de qué depende y dónde encaja. La gracia es que, una vez construido, consultar el grafo no gasta más llamadas al modelo.

Paso 3: preguntarle al grafo en vez de leer 40 archivos

# Pregunta en lenguaje natural qué partes manejan autenticación
/understand-chat

# Antes de commitear: analiza el blast radius de tus cambios actuales
/understand-diff

El comando /understand-diff es el que más valor aporta en el día a día: te dice qué se ve afectado por un cambio antes de que lo subas, que es justo el punto ciego del vibe coding.

Paso 4 (alternativa ligera): grafo de dependencias sin IA

Si solo quieres ver la arquitectura y detectar ciclos en un proyecto JS/TS, no necesitas un pipeline de agentes. madge o dependency-cruiser hacen el trabajo en segundos y sin coste de tokens.

# Detecta dependencias circulares (el síntoma clásico de arquitectura enredada)
npx madge --circular src/

# Genera un grafo SVG navegable de todo el directorio src
npx depcruise src --include-only "^src" --output-type dot | dot -T svg > arquitectura.svg

Un grafo de dependencias limpio es la mejor prueba de que respetas la separación de responsabilidades: si ves flechas cruzando capas que no deberían tocarse, ahí tienes la deuda.

Caso práctico: heredar un repo vibe-coded

Un escenario común en equipos de producto: te asignan un servicio que generó otra persona a base de prompts y que ya nadie mantiene. El flujo que funciona es construir antes de tocar.

1. Mapea primero. Corre /understand y abre el dashboard. En 10 minutos tienes el mapa de dominios y los puntos de fragilidad sin leer una línea.
2. Localiza el riesgo. Usa /understand-chat para preguntar por las zonas sensibles (auth, pagos, acceso a datos).
3. Edita con contexto limpio. Ya en Claude Code, pide el cambio sabiendo qué nodos dependen de qué. Antes de commitear, /understand-diff.

La diferencia frente al flujo manual es de horas a minutos en la fase de orientación, que es donde más se pierde tiempo al heredar código ajeno.

En Producción

Aquí es donde el tutorial y la realidad divergen. Tres avisos honestos.

Rendimiento y coste. Construir el grafo con Understand-Anything consume tokens, porque el pipeline analiza el repo con el modelo. Para un proyecto pequeño o mediano hablamos de un coste puntual asumible (del orden de unos pocos euros por reconstrucción completa, según el tamaño). Consultar el grafo después es gratis. Si quieres coste cero, las opciones local-first como cocoindex o codegraph corren con embeddings locales sin API key. Si tu cuello de botella es el gasto del agente, esto se conecta con por qué cruzar los 200k tokens te vacía el presupuesto.

Los benchmarks son marketing. Casi todos los proyectos de code graph prometen reducciones de tokens del 40%, 70% o 90%. Son cifras auto-reportadas, sin validación independiente, y dependen del baseline del modelo. Con Opus 4.8 la navegación nativa ya es más eficiente, así que la ventaja relativa se estrecha. Trátalas como orientación, no como verdad medida.

El grafo solo ve estructura estática. tree-sitter parsea sintaxis. El comportamiento en runtime, la reflexión y el dynamic dispatch no se representan. En código muy dinámico (factories, duck-typing, funciones renombradas) el grafo se queda corto. No sustituye a leer el código crítico ni a los tests.

Errores comunes y depuración

• Error: el grafo no refleja un refactor reciente. Causa: está stale, no se reindexó. Solución: usa updates incrementales (--auto-update) o reconstruye; las herramientas solo reprocesan los archivos cambiados.
• Error: el agente afirma relaciones que no existen. Causa: el AST no captura llamadas dinámicas ni reflexión. Solución: complementa con LSP y tests; no decidas un refactor solo con el grafo en código dinámico.
• Error: la factura de tokens se dispara al construir el grafo. Causa: el pipeline multi-agente analiza todo el repo con el modelo. Solución: limita el análisis a un subdirectorio o usa una herramienta local-first con embeddings locales.

Preguntas frecuentes

¿Un knowledge graph sustituye a leer el código?

No. Te da el mapa para saber dónde mirar y qué depende de qué, pero la regla de no commitear código que no puedes explicar sigue en pie. El grafo acelera la comprensión, no la reemplaza.

¿Funciona en repos grandes?

Sí, y es justo donde más aporta. Por encima de unas 30.000 líneas Claude Code pierde el mapa mental con grep; un grafo o una búsqueda semántica vía MCP devuelven solo lo relevante y ahorran contexto.

¿Necesito una base de datos vectorial?

Depende de la herramienta. Understand-Anything genera un JSON, sin servicios externos. Opciones como cocoindex corren local con embeddings propios. Solo MCP como claude-context piden una vector DB y embeddings, con un coste de unos pocos euros al mes según el volumen.

Cierre

Hemos visto que el vibe coding no falla por generar rápido, sino por desplegar lo que no entiendes, y que un knowledge graph del código es la herramienta más directa para cerrar esa brecha. La clave está en mapear antes de tocar, complementar el grafo con dependencias y tests, y recordar que los números bonitos de reducción de tokens son auto-reportados. El grafo te da el mapa, pero el juicio sobre los edge cases sigue siendo tuyo.

¿Has usado Understand-Anything u otra herramienta de code graph para entender un repo heredado? Cuéntame qué tal te ha ido en los comentarios o en Twitter @sergiomarquezp_. En el próximo artículo entro en cómo medir si tu suite de tests realmente protege ese código generado, con mutation testing.