Un agente abre tu repo, hace grep de una función, lee el fichero donde vive, y la cambia. El cambio es razonable en local. También rompe un llamador dos directorios más allá que nadie mencionó, porque nada le dijo al agente que ese llamador existía. Te enteras por la tarde, cuando lo que antes funcionaba deja de funcionar.
Ese fallo tiene nombre en cuanto lo buscas. El agente puede leer cualquier fichero suelto cuando se lo pides, pero no tiene mapa de cómo se relacionan los ficheros. Trabaja con búsqueda de texto, y la búsqueda de texto no sabe que esta función se llama desde ahí, que este tipo fluye por esos tres módulos, ni que una config decide qué rama corre en producción. Ve el árbol que tiene al lado. No ve el bosque.
Un grafo de conocimiento del código es ese bosque, dibujado para que se pueda leer y recorrer. Esta pieza es la referencia de qué es uno, qué responde que una búsqueda no puede, y por qué los agentes en concreto se desmontan sin él. La categoría es joven y casi todo lo que se escribe sobre “la IA que entiende tu codebase” es vago. Esta es la versión concreta.
Qué es de verdad un grafo de conocimiento del código
Coge tu codebase y deja de pensarlo como una carpeta de ficheros de texto. Piénsalo como nodos y relaciones.
Los nodos son las cosas que existen: ficheros, módulos, funciones, clases, tipos, endpoints, tablas de base de datos, tests, claves de config, y las decisiones que pidieron cualquiera de ellos. Las relaciones son las aristas que conectan esas cosas, y son tipadas, que es justo el punto. Esta función llama a aquella. Este módulo importa ese paquete. Esta clase implementa esa interfaz. Este test cubre esa función. Este servicio depende de esa tabla. Esta decisión reemplaza a una anterior.
Una carpeta no te puede decir nada de eso. Una carpeta sabe nombres y rutas. No tiene ni idea de que chargeCard en la línea 40 de un fichero es lo que se rompe cuando renombras un campo de un struct tres directorios más allá. La relación es real en el sistema que corre, pero no vive en ningún sitio que puedas consultar. La reconstruyes cada vez leyendo, saltando, con grep, y aguantando las piezas en la cabeza.
Un grafo convierte la relación en un hecho de primera clase. “Qué llama a esta función” deja de ser una conjetura de texto completo y pasa a ser un salto por una arista. “Qué acaba escribiendo este endpoint en la base de datos” pasa a ser un camino que trazas nodo a nodo. La estructura que estaba implícita en el código, y que solo se ensamblaba entera dentro de la memoria de un ingeniero con experiencia, pasa a ser algo que una máquina puede aguantar y responder.
Esa es la definición que merece la pena guardar. Un grafo de conocimiento del código es tu codebase representado como un sistema de relaciones tipadas, para que la estructura sea consultable en vez de re-derivarla en cada lectura.
Qué responde que una búsqueda no puede
La búsqueda no es inútil. Grep y la recuperación vectorial son excelentes en un trabajo — la división que formalizó GraphRAG: encontrar dónde aparece una cadena, o algo semánticamente cercano. Cuando sabes más o menos qué buscas y quieres las ubicaciones, tira de búsqueda. Casi todo lo que hacen hoy los agentes corre exactamente sobre esto, y por eso parecen capaces justo hasta que dejan de serlo.
Las preguntas que rompen la búsqueda son las de conexión, no las de ubicación.
búsqueda
- encuentra dónde se menciona
- empareja cadenas
- se salta llamadores
- sin fronteras
grafo
- encuentra cómo se conecta
- recorre aristas tipadas
- radio de impacto completo
- lee la costura
- Radio de impacto. Cambia la firma de esta función, ¿qué se rompe? La búsqueda encuentra la definición. No encuentra de forma fiable cada llamador, cada test que la ejercita, cada sitio donde se desempaqueta el valor de retorno. El grafo recorre las aristas llama y cubre y te da el conjunto real.
- Provenance. ¿Por qué existe este código? La búsqueda encuentra el código. No te puede decir qué decisión, historia o criterio de aceptación lo pidió, porque ese enlace no es texto cerca de la función, es una relación con otro artefacto entero.
- Alcanzabilidad. ¿Esto se usa siquiera? El código muerto se lee exactamente igual que el vivo para una búsqueda de texto. El grafo sabe si algo llega a este nodo, o si es una isla que nadie llama.
- El camino. ¿Cómo llega una petición desde este endpoint HTTP hasta aquella escritura en base de datos? Eso es una ruta por muchos nodos. La búsqueda te enseña el endpoint y, por separado, la escritura. No te enseña los siete saltos de en medio, ni que uno de esos saltos pasa por una cola que habías olvidado.
- La costura entre dos mundos. ¿Qué funciones son el único puente entre el módulo de pagos y el de cuentas? Un grafo lo lee como un conjunto pequeño de aristas que cruzan una frontera. La búsqueda no tiene ni el concepto de frontera.
La recuperación encuentra dónde se menciona algo. Un grafo te dice cómo se conecta. Son preguntas distintas, y la segunda es la que de verdad necesitas contestada antes de dejar que un agente toque algo que sostiene peso.
Por qué los agentes lo necesitan más de lo que jamás lo necesitó un humano
Aquí está la parte que hace esto urgente y no académico.
Los humanos siempre tuvieron un grafo de conocimiento del código. Vivía en su cabeza. La antigüedad en un equipo es, en buena parte, la construcción lenta de un mapa privado: aprendes que tocar el middleware de auth significa revisar cuatro servicios aguas abajo, que el código de facturación tiene una mina en la lógica de reintentos, que un directorio entero es legacy que nadie se atreve a borrar. Nadie lo escribió. Te lo ganaste rompiendo cosas y acordándote.
Un agente empieza cada sesión sin nada de eso. No tiene antigüedad. No tiene memoria del mapa de ayer. Tiene una ventana de contexto y lo que pueda meter en esa ventana ahora mismo, que es una mirilla a una casa en la que no ha vivido nunca. La razón de que un agente competente siga rompiendo un llamador que nunca vio no es que el modelo sea flojo. Es que el mapa que un ingeniero lleva gratis simplemente no existe para el agente, así que trabaja a ciegas en cuanto pasa el borde del fichero que tiene delante.
El instinto es arreglar esto echándole más al modelo. Más contexto. Un prompt más largo y detallado describiendo la arquitectura. Un modelo mejor el trimestre que viene. Nada de eso reconstruye el mapa, porque el problema no es que el agente esté poco informado dentro de un fichero, es que las relaciones entre ficheros nunca se le entregaron en una forma que pueda recorrer. Un prompt más largo es más texto que buscar. No es un grafo. Este es el razonamiento detrás de la frase a la que vuelvo una y otra vez: mapas del código, no prompts más largos. La palanca está en darle al agente la estructura, no en darle más prosa y rezar para que infiera la estructura cada vez. Va pegado a context engineering para agentes de código: el trabajo no es un modelo más listo, es poner la estructura correcta delante del que tienes.
En cuanto el agente puede consultar el grafo, se cierra el modo de fallo del principio de este artículo. Antes de renombrar el campo, le pregunta al grafo qué depende de ese campo, obtiene los llamadores y los tests, y o los actualiza o te dice que no puede. El cambio encaja porque el agente por fin tiene lo que tú tienes cuando haces ese mismo cambio con seguridad: una vista de todo lo que toca.
Grafo del código, grafo de producto: dos capas de la misma idea
Un grafo de conocimiento del código lee el código. Responde preguntas estructurales, de ingeniería: qué llama a qué, qué se rompe, qué es alcanzable.
Hay una capa por encima que lee el producto. Esa responde otra familia de preguntas, sobre forma, provenance y deuda de validación, y la escribí aparte en el grafo de conocimiento de producto. La versión corta de la diferencia: el grafo del código te dice que el pull request romperá tres llamadores, y el grafo de producto te dice a qué decisión de producto servían esos llamadores y si esa decisión se validó alguna vez. Quieres los dos. Son la misma técnica, un grafo de relaciones tipadas, apuntada a dos preguntas distintas. El grafo del código evita que los agentes rompan el sistema. El grafo de producto evita que construyas lo equivocado rápido.
Si solo montas uno primero, monta el del código, porque es el que corta la hemorragia inmediata cuando los agentes escriben la mayor parte de tu código.
El grafo tiene que ser verdad, o es peor que nada
Un mapa que miente es más peligroso que ningún mapa, porque te fías de él. Esta es la trampa en la que cae todo esfuerzo de documentación, y un grafo del código no es inmune por defecto.
La única versión que sobrevive al contacto con un codebase que se mueve es una derivada del código, no mantenida al lado. Si el grafo se genera leyendo el código real, la estructura de llamadas real, los tests reales, entonces cuando el código cambia el grafo cambia, porque son el mismo hecho expresado una vez. Si el grafo es un diagrama que alguien dibujó en una wiki, empieza a pudrirse en cuanto entra el siguiente commit, y se pudre en silencio. Ese es el argumento entero de la documentación viva: el artefacto deja de envejecer solo cuando nadie tiene que acordarse de actualizarlo, porque es una proyección del sistema en vez de una segunda copia.
Así que la prueba de si un grafo de conocimiento del código merece confianza no es lo bonito que renderiza. Es si está aguas abajo del código. Un grafo que editas a mano es un grafo que le mentirá a tus agentes un martes, con seguridad, sobre una estructura que cambió el lunes.
Dónde encaja PaellaDoc
Esta es la capa que construyo en PaellaDoc, porque operar agentes sin ella es lo que me quemó. El sistema lee tu repo en tu máquina y construye el grafo: los nodos, las relaciones tipadas, los enlaces del código hacia arriba a las decisiones que lo pidieron. Los agentes consultan la estructura antes de cambiarla, en vez de hacer grep y rezar. El grafo se deriva del código, así que se mueve cuando el código se mueve. Sin nube, sin cuenta, y tu código no sale de la máquina.
Esa es la apuesta entera de este cluster. Cuando los modelos pueden escribir cualquier fichero que pidas, la restricción ya no es la generación. Es si lo que escribe el código puede ver cómo se conecta el código. Un grafo de conocimiento del código es como le entregas esa vista.
FAQ
¿Un grafo de conocimiento del código no es solo un call graph?
Un call graph es parte de él. Un call graph captura qué función llama a cuál, y ese es uno de los tipos de relación más útiles. Un grafo de conocimiento del código completo lleva más: tipos, flujo de datos, tests, config, endpoints, y los enlaces hacia los artefactos de producto y las decisiones. El call graph te dice la estructura de control del código. El grafo de conocimiento añade por qué existe el código y qué se supone que satisface.
¿Necesito un grafo si mi codebase es pequeño?
Probablemente todavía no. Un codebase pequeño cabe en una cabeza y a menudo en una ventana de contexto, y el mapa es barato de reconstruir leyendo. El grafo se gana el sueldo cuando el código crece más de lo que una persona puede aguantar, cuando varios agentes trabajan en paralelo sobre él, o cuando la gente que llevaba el mapa en la cabeza se va. Que es también, no por casualidad, justo cuando los agentes empiezan a romper cosas que nunca vieron.
¿Se puede generar un grafo de conocimiento del código de forma automática?
Sí, y deberías, porque uno mantenido a mano se pudre. El grafo debería construirse leyendo el código, la estructura de llamadas y los tests, para que siga siendo una proyección del sistema real. Las partes que no se pueden leer del código, sobre todo el enlace de provenance del código a la decisión que lo pidió, son las que merece la pena adjuntar a propósito según se completa el trabajo, para capturar el porqué mientras todavía se conoce.
¿Qué se rompe en tu codebase que una búsqueda nunca te habría avisado? Cuéntame en el foro.