Tu codebase tiene problemas que no puedes ver — cómo un knowledge graph revela lo que grep no muestra

Los desarrolladores gastan 70% del tiempo leyendo código, no escribiéndolo. Y la mayor parte de ese tiempo se va buscando cosas. No buscando una función específica — eso lo resuelve grep en 2 segundos. El problema es buscar lo que ni siquiera sabés que existe: dependencias ocultas, código muerto que parece vivo, módulos acoplados que nadie notó, workflows enteros que nada referencia.

Nosotros construimos un knowledge graph de nuestro codebase y, en la primera query, descubrimos 229 artefactos huérfanos, 2 workflows completamente desconectados del sistema, y que cambiar un único agente impacta 31 otros artefactos en cadena. Todo eso era invisible — por años.

Lo que grep encuentra vs. lo que grep nunca va a encontrar

Grep es una herramienta de presencia. Buscás “parseConfig” y te muestra los 5 archivos que mencionan ese string. Perfecto.

Pero grep no responde ninguna de estas preguntas:

• ¿Qué pasa si cambio parseConfig? — Grep encuentra los 5 callers directos. Pero esos 5 llaman a otros 23 módulos que dependen transitivamente. El blast radius real es 28, no 5.
• ¿Qué funciones existen pero nadie llama? — Grep encuentra presencia. Los huérfanos se definen por la ausencia de referencia. Tendrías que chequear cada función contra todas las demás — combinación explosiva.
• ¿Cuántos módulos dependen de este? — Cuando leés auth.js, ves sus imports (lo que él consume). Pero no ves quién lo importa a él (quién depende de él). El fan-in es invisible en el archivo individual.
• ¿Hay dependencia circular? — A→B→C→A. Cada archivo muestra un edge. El ciclo solo aparece cuando armás el grafo completo.

Un estudio de Microsoft Research (Nagappan et al., ICSE 2006) mostró que las métricas basadas en grafo de dependencia predicen el 73% de los defectos post-cambio. Los desarrolladores que chequeaban solo callers directos (el enfoque grep) se perdían el 60% de las roturas que pasaban en dependientes transitivos.

O sea: grep te da una foto. El grafo te da el mapa.

La capa invisible que nadie ve

Todo codebase tiene 3 capas de entendimiento:

1. Micro (legible) — Funciones individuales, clases, archivos. Los abrís y los leés.
2. Macro (documentada) — Arquitectura del sistema, diagramas, READMEs.
3. Meso (invisible) — Las conexiones reales entre los archivos. Quién llama a quién, quién depende de quién, qué se rompe si tocás acá.

La capa meso está distribuida: cada archivo contiene un pedazo (sus imports), pero la foto completa exige agregarlos todos. Es cognitivamente imposible mantener eso en la cabeza con cientos de archivos.

Fowler y Whitehead documentan un caso en el libro Building Evolutionary Architectures que lo ilustra perfectamente:

“Proyectamos el grafo de dependencias en la pared. El CTO dijo: ‘Esa no es nuestra arquitectura.’ Dijimos: ‘Esa ES su arquitectura.’ El sistema que creían tener con 8 módulos era, en la práctica, 2 mega-clusters con un cuello de botella enrutando el 67% del tráfico.”

Llevaban 5 años leyendo el código y no sabían eso. Porque es imposible verlo sin el grafo.

Lo que hicimos: dos grafos, un codebase

Nosotros trabajamos con el AIOS — un sistema de orquestación de agentes IA para desarrollo full stack. Tiene agentes (@dev, @qa, @architect), tasks (qa-gate, dev-develop-story), workflows (story-development-cycle, epic-orchestration), squads de especialistas, y minds (clones cognitivos de thought leaders como Alex Hormozi, Paul Graham, Seth Godin).

El problema: cada vez que Claude Code necesitaba entender la relación entre esos artefactos, volvía a leer los archivos. 12 agentes × 5.000 tokens cada uno = 60.000 tokens quemados solo para responder “¿qué hace el @dev?”.

Entonces construimos dos knowledge graphs complementarios:

1. code-review-graph — Para código

El code-review-graph (fork del proyecto original de tirth8205) usa Tree-sitter para parsear código fuente en AST y construir un grafo SQLite con funciones, clases, imports y llamadas.

Resultado promedio: 8.2x menos tokens por operación de review. En un monorepo con 27.000 archivos, el grafo filtra a ~15 archivos relevantes.

En nuestro fork, contribuimos con el PR #95 que agrega 10 subcomandos CLI y parsing de CommonJS require().

2. aios-graph — Para artefactos no-código

Pero el código es solo la mitad de la historia. Nuestro sistema tiene 206 tasks, 14 workflows, 13 agentes, 93 squads y 115 minds — todo definido en YAML y Markdown, fuera del alcance del code-review-graph.

Entonces construimos el aios-graph: un knowledge graph local (Python + SQLite + PyYAML) que parsea esos artefactos y mapea relaciones como DEPENDS_ON_TASK, ASSIGNED_TO, MIND_IN_SQUAD, DELEGATES_TO.

Ningún otro tool en el mercado hace esto. El Augment Code, codebase-memory-mcp, GitHub Stack Graphs — todos se enfocan en entidades de código. Grafar agentes, tasks y workflows es una categoría nueva.

aios-graph query agent dev          # ¿Qué hace el @dev?
aios-graph impact agent:dev         # Blast radius si cambiás el @dev
aios-graph who-uses qa-gate         # ¿Quién depende del qa-gate?
aios-graph mind-search --tier S     # Minds listas para producción
aios-graph dead                     # Artefactos que nadie referencia

200 tokens por query. Antes eran 60.000.

Lo que descubrimos el primer día

Corrimos aios-graph build y las queries revelaron cosas que ningún grep jamás hubiera mostrado:

229 artefactos huérfanos

48 tasks (23.5% del total) existían en el repositorio pero ningún agente las declaraba en las dependencias. Eran tasks de orquestación, seguridad y build que funcionaban en la práctica — pero el sistema no sabía que existían.

Esto importa porque si alguien borraba una pensando que era “código muerto”, rompería workflows que dependían implícitamente de ella.

Seguime en Instagram @murilloimparavel — ahí muestro los detrás de escena de cómo uso IA en el día a día, sin filtro.

Blast radius de 31 para el @dev

El agente @dev (nuestro implementador principal) tiene 43 dependencias y 24 dependientes. Cambiar su interfaz — un comando, un formato de input — impacta 31 artefactos en 2 niveles de profundidad: 8 workflows, 6 rules, 10 agentes, 7 workflows indirectos.

Sin el grafo, alguien editaría el @dev creyendo que es “solo un archivo”. En realidad, es el nodo más acoplado de todo el sistema.

2 workflows fantasma

epic-orchestration y development-cycle existían como archivos YAML completos, bien escritos, con fases y agentes definidos. Pero el grafo mostró 0 edges — nada los referenciaba, nada los conectaba al resto del sistema. Eran workflows que alguien creó, hizo commit, y olvidó conectar.

Descubrimos que el parser no entendía el formato YAML de ellos (usaban phases como dict en vez de sequence como lista). Corregimos el parser y de repente: 12 nuevos edges aparecieron. Los workflows volvieron a la vida.

98.3% de las minds sin frameworks extraídos

De las 115 minds (clones cognitivos de thought leaders), solo 2 tenían frameworks operacionales extraídos (Gary Vaynerchuk y Pedro Sobral). Las otras 113 eran bibliotecas brutas — el agente tenía que releer todo el material fuente cada vez para derivar principios.

Es como tener un libro de recetas con 115 libros pero solo 2 con el índice listo. Los demás, tenés que leerlos enteros para encontrar lo que necesitás.

Duplicados invisibles

squads/copy/ y squads/copy-squad/ tenían agentes idénticos byte a byte. Sin el grafo, serían 2 squads aparentemente diferentes (nombres distintos, directorios distintos). La comparación de edges CONTAINS_AGENT reveló que eran lo mismo.

La economía de tokens — calculadora de panadero

Según el paper Codebase-Memory, una graph query retorna resultado en ~200 tokens. Leer los mismos archivos manualmente cuesta 8.000-60.000 tokens.

Hagamos la cuenta con la calculadora de panadero:

Con Claude Opus 4.6 a $9/1M input tokens, una sesión pesada de exploración que consume 500K tokens cuesta $4.50. Con graph queries, la misma sesión cuesta $0.45. En un mes con 50 sesiones, son $225 vs $22.50. $200 ahorrados por mes solo cambiando de grep a graph.

Y eso sin contar el beneficio cualitativo: el modelo performa mejor con menos contexto. Factory.ai mostró que el contexto irrelevante degrada la performance — no solo es más caro, hace que el modelo parezca peor.

Por qué CLI y no MCP

Vamos a delirar un poco acá. Todo el ecosistema está empujando MCP (Model Context Protocol) como la forma de conectar AI agents a herramientas. Nosotros construimos el aios-graph inicialmente con MCP server (FastMCP). Después lo borramos.

Los datos son claros:

El aios-graph hace queries stateless contra SQLite. No tiene connection pooling, no tiene streaming, no tiene comunicación bidireccional — los únicos escenarios donde MCP agrega valor real. Para todo lo demás, un CLI con --json lo resuelve.

El Nx borró la mayoría de sus MCP tools por la misma razón. El CTO de Perplexity abandonó MCP internamente. La tendencia es clara: CLI para herramientas de desarrollo, MCP solo para integraciones externas que necesitan auth.

Cómo construir el tuyo

El aios-graph fue construido en ~2 horas con esta arquitectura:

aios_graph/
  graph.py    — SQLite store (WAL mode, parameterized queries)
  parser.py   — 7 parsers (agent, task, workflow, squad, mind, rule, framework)
  tools.py    — Core functions (stateless queries)
  cli.py      — Entry point com --json global flag

Dependencias: pyyaml. Solo eso.

El pipeline es simple:

1. Descubrir — rglob en los directorios de artefactos
2. Parsear — Extraer YAML blocks de markdown, cargar YAML puro
3. Indexar — Upsert nodes + edges en SQLite con SHA-256 para change detection
4. Consultar — BFS para impact, in-degree=0 para huérfanos, LIKE para search

Build completo: 420 nodos, 993 edges, <15 segundos. Update incremental: <2 segundos.

El código es open source. El fork del code-review-graph está en mi GitHub con el PR #95 que agrega CLI-first expansion. El aios-graph está en el mvp-system.

El futuro: todo workspace de AI debería tener un grafo

La investigación académica está convergiendo hacia esto. En 2024-2026, se publicaron al menos 7 papers sobre grafos + AI agents:

• CodeXGraph (NAACL 2025) — agentes LLM escriben queries Cypher contra grafos de código
• GraphCodeAgent — +43.8% pass rate con GPT-4o usando dual graph
• Codebase-Memory — 83% de la calidad con 10x menos tokens
• Augment Code — +70% quality improvement con graph context

El patrón que está emergiendo:

Nosotros estamos en L3 con una inversión de $0 en infra. Cero servidor, cero embedding model, cero API key. SQLite + Tree-sitter + PyYAML.

Si este contenido te hizo sentido, compartilo con alguien que necesite escucharlo. Y si querés intercambiar ideas sobre knowledge graphs, AI agents, o cómo orquestar todo esto, escribime en Instagram.

FAQ

¿Qué es un knowledge graph de codebase?

Es una base de datos de grafos (nodos + aristas) que mapea entidades de tu código (funciones, clases, módulos) y las relaciones entre ellas (quién llama a quién, quién importa a quién, quién testea a quién). A diferencia de un índice de búsqueda, permite queries de relacionamiento: “¿qué se rompe si cambio X?” o “¿qué funciones nadie usa?”.

¿Necesito Neo4j o alguna base de datos de grafos para esto?

No. El code-review-graph y el aios-graph usan SQLite puro. Dos tablas (nodes y edges) con índices son suficientes para la mayoría de los casos. Neo4j tiene sentido si necesitás queries Cypher complejas o escala de millones de nodos. Para un codebase típico (<100K archivos), SQLite lo resuelve.

¿Cuánto código muerto probablemente tiene mi codebase?

Según FlagShark, los repositorios típicos tienen 10-30% de código muerto. Codebases enterprise con 5+ años llegan a 20-35%. Post-adquisición, puede llegar al 50%. Una empresa SaaS descubrió que ~50% del código no se usaba.

¿MCP o CLI para servir el grafo al AI agent?

CLI con --json. Los benchmarks muestran que MCP cuesta 32x más tokens y tiene 72% de reliability vs 100% del CLI. MCP tiene sentido para database connections (connection pooling), browser automation (estado persistente) y OAuth delegation. Para queries stateless contra SQLite, CLI es estrictamente superior.

¿Esto funciona solo para código o para otros artefactos también?

Funciona para cualquier cosa que tenga relaciones estructuradas. El aios-graph parsea YAML y Markdown — agentes, tasks, workflows, squads, minds. El mismo patrón sirve para Terraform modules, Kubernetes manifests, GitHub Actions workflows, o cualquier configuración declarativa que referencia otras configuraciones.