¿Se puede generar un grafo semántico que conecte las specs con el código real?
Existen herramientas que van más allá del AST: extraen también la semántica de las especificaciones (tipo OpenSpec) y relacionan cada endpoint documentado con su implementación real. Cómo funcionan y cuándo compensa su coste.
La pregunta real
Cuando un repositorio crece, un agente de IA que solo analiza el AST (el árbol de sintaxis del código) ve funciones, clases e imports — pero no ve qué especificación de negocio dio origen a cada una de ellas. Si además el equipo trabaja con documentos de especificación tipo OpenSpec, separados físicamente del código, surge una pregunta práctica: ¿existe alguna forma de construir un grafo que relacione ambos mundos, de modo que una especificación quede conectada con su implementación real, y no solo con el archivo donde vive?
La respuesta es sí, y ya hay herramientas experimentales orientadas exactamente a esto: grafos de conocimiento semántico que combinan el AST con la semántica extraída de la documentación.
Cómo funciona por debajo
En el fondo, este tipo de herramienta convierte las relaciones código-especificación en vectores y hace búsqueda semántica por distancia vectorial — el mismo principio que usa cualquier sistema RAG, pero aplicado a la relación entre "lo que dice la spec" y "lo que hace el código", no solo entre fragmentos de texto. Un LLM recorre el repositorio, genera un embedding de cada especificación y de cada unidad de código relevante, y construye un grafo donde las aristas son esa cercanía semántica: un endpoint documentado en OpenSpec queda enlazado con el controlador, servicio y modelo de datos que realmente lo resuelven, aunque no compartan nombres literales.
El coste no es trivial. Generar esa semántica con un LLM sobre un repositorio completo consume bastantes tokens y tiempo, y por defecto un agente de codificación no usa el grafo — hay que forzarlo explícitamente en el contexto o en el comando para que lo consulte antes de actuar.
Para qué sirve en la práctica
Refactors dirigidos
Antes de tocar una función o módulo, el grafo indica qué otras partes del código y qué especificaciones están semánticamente relacionadas con él, no solo las que lo importan directamente.
Interpretar mejor un ticket
Al recibir un ticket ambiguo, el agente puede consultar el grafo para encontrar el endpoint o modelo de datos ya existente que más se parece semánticamente a lo que se describe, en vez de asumir que es funcionalidad nueva.
Detectar especificaciones huérfanas
Documentos de especificación que no tienen ninguna arista hacia código real delatan funcionalidad documentada pero nunca implementada — o al revés, código sin spec asociada.
Cuándo compensa construirlo
Este enfoque tiene sentido sobre todo en repositorios grandes y con historia — donde el AST solo cuenta la mitad de la historia y encontrar "qué parte del código resuelve esta especificación" a mano ya no es viable. En un proyecto pequeño o reciente, donde spec y código siguen una convención de nombres consistente, el grafo aporta poco frente a su coste de generación.
También conviene tratarlo como una capa auxiliar, no como fuente de verdad: el grafo describe relaciones probables por similitud semántica, no relaciones garantizadas por el compilador. Sigue haciendo falta que un humano valide una recomendación antes de actuar sobre ella.
Resumen rápido
- Un grafo semántico combina AST y semántica de especificaciones para enlazar cada spec con su implementación real, no solo por nombre de archivo.
- Por debajo funciona igual que un RAG: embeddings y distancia vectorial, aplicados a la relación spec-código en lugar de a fragmentos de texto sueltos.
- Generarlo consume tokens y tiempo, y hay que forzar explícitamente al agente a consultarlo — no ocurre por defecto.
¿Quieres aplicar esto en tu equipo?
En Kuuli Technologies llevamos estas metodologías a equipos reales. Escríbenos si quieres una sesión de trabajo o una consultoría sobre agentes IA y SDD.