Instalé un Grafo de Conocimiento en Claude Code. 14 Días Después, la Auditoría Acabó con Mi Entusiasmo.

Cuando escuché sobre graphify, pensé que iba a mejorar mi código y reducir mis tokens. Así que hace 15 días lo instalé en 2 proyectos en producción. Estaba seguro de que había mejorado mi agente. Dos semanas después, audité las transcripciones JSONL. Tuve que leer los números dos veces.

A lo largo de 60 sesiones, el agente disparó alrededor de 1,500 recordatorios de hook e invocó el grafo exactamente 0 veces. El grep ganó el arbitraje todas las veces, no porque el grafo fuera malo sino porque el grafo requería un paso extra.

Quería Que Esto Funcionara. Desesperadamente.

Me lancé de lleno con graphify. Triple promesa: memoria persistente del código base, grafo auditable que puedes leer como un mapa, sorpresas entre documentos que la caché del LLM no puede ver. Números publicados en el rango de 49-71x de ahorro de tokens en consultas que aprovechan el grafo limpiamente. Todas las casillas marcadas.

Ejecuté el proceso completo en ambos proyectos: un storefront de Next.js sobre un backend de Convex (290 archivos aprox), y un pipeline de contenido al que sigo volviendo (387 archivos TypeScript). Una pasada de AST más una capa de extracción semántica, alrededor de $0.30 a $1 por proyecto en Sonnet. El hook de git post-commit entró, el servidor MCP fue declarado, la regla CLAUDE.md fue inyectada textualmente por graphify claude install. 7 herramientas visibles en el panel. Limpio.

Luego lo llevé más lejos. Archivo de log de uso para rastrear victorias. Memoria dedicada de Claude solo para feedback de graphify. Fecha de revisión a 7 días, extendida a 14 cuando los datos se sintieron escasos. Había escrito el calendario de evaluación antes de tener un solo punto de datos, lo cual en retrospectiva es la jugada de alguien que ya quiere la respuesta. (Tú también escribiste un calendario así alguna vez, no soy el único.)

Estaba seguro de que acababa de mejorar mi agente. El servidor MCP estaba respirando. El grafo estaba caliente. El hook estaba disparando. No tenía nada que hacer más que esperar las ganancias.

La Auditoría Que Mató Mi Entusiasmo

Claude Code mantiene una transcripción de cada sesión como un archivo .jsonl bajo ~/.claude/projects/<repo>/. Cada llamada de herramienta se registra con su nombre y entradas. Una invocación real se ve como "type":"tool_use","name":"mcp__graphify__...". El deferred_tools_delta de inicio lista las herramientas disponibles pero no es una invocación. Busqué el primero, ignoré el segundo.

Esto es lo que 14 días de "estoy seguro de que esto está funcionando" realmente produjeron.

grep "tool_use" ~/.claude/projects/pbn/*.jsonl | grep graphify
grep "tool_use" ~/.claude/projects/rentier/*.jsonl | grep graphify

Los números, lado a lado:

• Llamadas CLI a graphify query / path / explain: 0 en pbn, 0 en rentier
• Herramientas MCP graphify invocadas por el agente: 0 en pbn, 0 en rentier
• Lecturas activas de GRAPH_REPORT.md: 1 en pbn, 0 en rentier
• Líneas añadidas a mi log de uso: 1 línea en pbn, archivo nunca creado en rentier
• Memorias de proyecto citando una perspectiva del grafo: 0 en ambos

La infraestructura hizo su trabajo perfectamente. 290 commits en el pipeline de contenido y 38 en el storefront fueron digeridos por el hook post-commit sin una sola falla. Cero sobrecostos, cero fricción, el grafo se mantuvo fresco a través de cada push. El servidor MCP arrancó limpio en cada sesión, las 7 herramientas estaban visibles en el panel, la regla estaba sentada en la parte superior de CLAUDE.md donde supuestamente el agente la lee en cada arranque en frío. Todo lo que podía controlar mecánicamente funcionó. La única cosa que no podía controlar, la lectura en sí, no ocurrió.

El único uso productivo documentado fue un bug 404 en un sitio partner que estaba depurando el 2 de mayo. El reporte apuntó al clúster correcto de módulos. Bien. El diagnóstico inicial aún estaba mal, el agente acusó a humanize.ts, el verdadero culpable era mesh.ts:tryInsertLink. El grafo ayudó a estrechar la zona. No resolvió. Tuve que verificar contra los archivos .meta.json reales para voltear el diagnóstico. Ahorré tal vez 500 tokens de trabajo de grep y 3 lecturas de archivo. Marginal comparado con los números publicados de 49-71x de ahorro de tokens, como documentó Mustafa Genc en GoPenAI y la guía de integración CLSkills (abril 2026). Esos números se miden en benchmarks controlados donde un agente debe usar el grafo. Mi auditoría mide lo opuesto. Lo que hace un agente cuando tiene la opción.

El Grep Ganó Porque Grep Es Más Corto

Un agente de IA ejecuta un arbitraje en tiempo real en cada paso. ¿Cuál es el camino más barato hacia el final? Las reglas de texto entran en ese arbitraje como señales, no como leyes. Yajin Zhou lo puso claramente en su post de marzo 2026: para la IA, las reglas no son leyes, son sugerencias. Christoph Schweres documentó el lado arquitectónico un mes antes: después de la compresión de contexto, CLAUDE.md cambia de estatus, deja de ser una regla y se convierte en información que el agente puede o no ponderar. Eso es exactamente lo que se desarrolló a través de mis 1,500 recordatorios de hook ignorados.

Dos razones concretas por las que graphify perdió el arbitraje.

Razón 1, el camino corto siempre gana. Para responder "dónde está X definido", "quién llama a Y", "qué toca Z": grep -r da líneas exactas en 1-2 segundos. Leer GRAPH_REPORT.md da 500 tokens de resumen temático, luego el agente aún tiene que abrir los archivos. Un paso versus dos. El arbitraje en tiempo real elige el camino corto, sin importar lo que escribiste en mayúsculas dentro de CLAUDE.md. Eso no es un bug. Esa es la ponderación como fue entrenada.

Razón 2, las reglas de texto no tienen disciplina persistente. Mi hook PreToolUse:Bash disparó más de 1,500 recordatorios diciéndole al agente "3 archivo(s) en alcance cambiaron, re-ejecuta /graphify update". Ni uno solo desencadenó una consulta del grafo. Los recordatorios se volvieron ruido para parsear y saltar. El patrón está muy documentado ahora: issues de GitHub #18660, #22022, #19635, y el muy reciente #57200 archivado el 8 de mayo (el reportero quemó 85K tokens re-descubriendo una decisión que ya estaba en memoria, porque las reglas de laws.md no sobrevivieron la compresión de contexto). Mustafa Morbel enmarcó bien la distinción en su pieza de abril: CLAUDE.md es consultivo por naturaleza, los hooks son determinísticos. El texto se debate. La mecánica no.

Escribí sobre higiene de CLAUDE.md antes, 47 líneas en mi CLAUDE.md y por qué Claude quema 50 instrucciones antes de que las mías siquiera carguen. Ese artículo decía escribir mejores reglas. Este dice que incluso la regla mejor escrita permanece consultiva y pierde ante el arbitraje. Ambas son ciertas. Ninguna es suficiente.

Dónde Debería Haberlo Usado (Y Dónde Probablemente Deberías)

Cometí un error de configuración. Dos de ellos, en realidad.

Error 1, instalé una herramienta de descubrimiento en terreno familiar. Los docs de graphify son explícitos sobre los casos de uso objetivo: un código base que estás tocando por primera vez, una lista de lectura (papers, tweets, notas), un corpus de investigación, una carpeta personal /raw donde tiras todo. Ninguno de mis dos proyectos es alguno de esos. Escribí la mitad del código y releí el resto muchas veces. Lo mismo para Claude, la memoria de trabajo del modelo de estos repos ya estaba caliente. Las sorpresas entre documentos que se supone que una pasada de detección de comunidad revela no sorprenden a nadie que ya conoce los enlaces. Instalé una brújula dentro de un apartamento en el que he vivido por 5 años.

Error 2, lo desplegué frío en lugar de caliente. Una herramienta de contexto gana el arbitraje en tiempo real cuando el agente no tiene alternativa más barata. En un repo fresco, grep sigue siendo caro (el agente barre a ciegas), así que leer el grafo primero se convierte en el camino corto. Después de 3-6 meses de exposición, grep tiene una caché de calor, y el grafo se convierte en el desvío otra vez. Ya había cruzado esa línea hace meses en ambos proyectos. Para cuando llegó graphify, el agente ya había construido lo que sea que pase por memoria muscular en un sistema sin estado, y esa memoria muscular decía "grep primero, nunca hagas preguntas."

Este es el mapa de uso que debería haber respetado desde el día uno.

Incorporación en un repo heredado que estás tomando sin conocerlo. El grafo probablemente gana, porque grep está ciego al inicio y un mapa temático ahorra tiempo real de lectura. Este es el caso que Jo Van Eyck argumentó en su video "AI coding agents are useless on large codebases", y en ese marco específico tiene razón. Mientras más grande la superficie desconocida, más se gana su lugar un mapa global.

Auditoría de seguridad entre módulos en un repo legacy donde estás cazando dependencias ocultas. Caso explícito de los docs de graphify, y tiene sentido, ya que el agente necesita una vista global que ningún grep único da. No estás buscando una cadena, estás buscando una topología.

Lista de lectura mixta (papers + notas + tweets + código de referencia) donde la detección de comunidad genuinamente saca a la superficie una vista que ningún grep puede producir. Probablemente el caso de uso más fuerte, y el más cercano a la filosofía original /raw que inició toda la conversación. Los corpora heterogéneos se benefician más de la extracción estructural precisamente porque grep a través de formatos es una mala broma.

No para mantener un proyecto que ya conoces. Eso es lo que hice, y fue la aplicación equivocada.

Este matiz no rescata mi experiencia. Clarifica lo que debería haber probado primero. Rajistics tiene una pieza de YouTube titulada "GraphRAG (you probably don't need it)" que llega a una posición similar desde el lado RAG. La conclusión es la misma en grafos de conocimiento: caso por caso, no siempre.

(Nota al margen que realmente no va a ningún lado: sigo notando que las herramientas que instalo con más entusiasmo son las que menos leo de antemano. Las herramientas aburridas que ojeo una vez y olvido son usualmente las que sigo usando 6 meses después. Probablemente hay una lección ahí sobre cómo el entusiasmo distorsiona la evaluación. O tal vez simplemente tengo mal gusto para las herramientas. Difícil de decir honestamente.)

La Lección Real: El Texto No Cambia el Comportamiento del Agente. La Mecánica Sí.

Este patrón es más grande que graphify. Le das al agente una nueva herramienta, un nuevo doc, una nueva regla. La escribes bien. Se la recuerdas en CLAUDE.md. Creas un hook que hace ping. El agente asiente. Luego hace otra cosa. El patrón aparece a través de issues de GitHub, hilos de r/ClaudeAI, y al menos una docena de piezas recientes de Medium. Es el modo de falla dominante del tooling contextual en 2026.

Lo que realmente funciona son 3 palancas mecánicas.

Palanca 1, bloquea en lugar de recordar. Un hook PreToolUse que rechaza la acción alternativa fuerza el camino. Mustafa Morbel ya documentó el contraste: CLAUDE.md es consultivo, los hooks son determinísticos. Cualquier regla que pueda ser ignorada será ignorada en el momento que el arbitraje en tiempo real encuentre una ruta más corta. La solución no es mejor redacción. La solución es quitar la alternativa del menú. Si tu hook solo recuerda, has construido una voz educada que el agente aprende a ignorar. Si tu hook bloquea la llamada, has construido una pared.

Palanca 2, haz que la herramienta sea el camino corto, no un desvío. Un grafo de conocimiento que responde la pregunta gana. Un grafo de conocimiento que apunta a archivos que el agente aún tiene que abrir pierde, porque añadió un paso en lugar de quitar uno. Mismo principio para servidores MCP: un servidor que elimina N llamadas de herramienta gana, un servidor que añade N+1 pierde. Argumenté lo mismo sobre CLIs versus MCP en why CLIs beat MCP for AI agents: los CLIs ganan precisamente porque se insertan en el camino nativo del agente en lugar de pedirle que se desvíe hacia un handshake JSON-RPC. El mecanismo se generaliza a cualquier herramienta contextual. Si añade un paso, pierde. Si quita uno, gana. Ese es todo el juego.

Palanca 3, introduce la herramienta en el momento correcto. Una herramienta de contexto gana en arranque frío, no en mantenimiento caliente. Ese es el error que cometí con graphify, pero también es el error que cometen los desarrolladores cuando añaden 200 líneas a su CLAUDE.md 6 meses después de un proyecto. Muy tarde. Para entonces el patrón de comportamiento del agente en ese repo está fijado por las herramientas existentes (grep, ls, cat, el árbol de archivos que ya aprendió a navegar). Una nueva herramienta añadida encima tiene que superar la inercia, e inercia en un arbitraje en tiempo real significa "este camino fue barato la última vez, tómalo otra vez."

Las 3 palancas vienen con un costo. Hacen el tooling más invasivo. Un hook bloqueante te molesta cuando quieres hacer una excepción. Una herramienta de camino corto reemplaza la flexibilidad de grep con la rigidez de un esquema fijo. Una herramienta de arranque frío significa que tienes que planear tu tooling antes de tener un proyecto, lo cual la mayoría de nosotros nunca hacemos, porque instalamos herramientas cuando sentimos el dolor, no antes. Así que todos recurren a la capa consultiva en su lugar, escriben más líneas en CLAUDE.md, crean otro hook recordatorio, y se dicen a sí mismos que las reglas son lo suficientemente claras esta vez. He hecho esto. Tú probablemente también. La capa consultiva es cómoda precisamente porque nos deja pretender que hemos cambiado el comportamiento del agente sin pagar el costo de realmente cambiarlo.

En realidad, espera. Déjame ponerlo diferente. La capa consultiva es como escribir un email fuertemente redactado a tu yo pasado y esperar que tu yo futuro lo obedezca. Buena suerte con eso. 😅

La lección se mantiene más allá de Claude Code. Si construyes un flujo de trabajo de IA que depende de que el modelo siga reglas escritas, estás apostando en una propiedad que el modelo no tiene. El modelo tiene pesos, no leyes. Escribí sobre un ángulo relacionado en Vibe Coding, For Real: los vibe-coders creen que escribir las reglas correctas al agente es suficiente para enviar. El envío viene de la mecánica de la construcción, no de la prosa alrededor de ella. Mismo principio aquí, escalado a la capa de tooling.

Audita Tus Propias Transcripciones Antes de Confiar en Tus Propias Reglas

Mi hallazgo sobre graphify no es que la herramienta sea mala. La herramienta funciona como se anuncia cuando el agente realmente la usa. El problema es que la adopción de herramientas por agentes es 10 veces más difícil que la instalación de herramientas. Cualquier herramienta que le pida a un agente cambiar su camino por defecto pasa por el mismo arbitraje en tiempo real. Mi CLAUDE.md pasa por él, mis hooks recordatorios pasan por él, incluso los prompts de los que estoy más orgulloso pasan por él. Todos tienen su graphify, y no lo saben hasta que auditan.

Así que audita. El comando cabe en una línea:

grep "tool_use" ~/.claude/projects/<repo>/*.jsonl | grep <tool_name>

Cuenta las invocaciones reales. Compara contra lo que tu CLAUDE.md, tus hooks, y tus reglas pretenden que el agente debería estar haciendo. La brecha es el costo real de lo que escribiste en palabras. Si la brecha es cero, sabes qué hacer después: mover las reglas que importan del texto a la mecánica. El resto puede quedarse consultivo, nadie lo lee de todas formas.

Un grafo de conocimiento que el agente no lee no es una herramienta. Es documentación. Lo mismo va para tus reglas. C'est la vie.

Fuentes

• repositorio y docs de graphify, github.com/safishamsi/graphify
• Christoph Schweres, Claude Code Ignores the CLAUDE.md, HOW Is That Possible? (Feb 2026)
• Yajin Zhou, Why an AI Agent Broke Its Own Rules (Marzo 2026)
• Mustafa Morbel, Taming Claude Code: A Guide to CLAUDE.md and Hooks (Abril 2026)
• Mustafa Genc, Graphify: Build a Knowledge Graph From Your Entire Codebase (GoPenAI, Abril 2026)
• Issues de GitHub anthropics/claude-code #18660, #22022, #19635, #57200
• Jo Van Eyck, AI coding agents are useless on large codebases. Unless you do THIS. (YouTube)
• Rajistics, GraphRAG (you probably don't need it) (YouTube)

Este post puede contener enlaces de afiliado. Si los clickeas, podría ganar una pequeña comisión, no te cuesta nada, y me ayuda a seguir enviando artículos de calidad todos los días para tu placer de lectura.