Claude Code y Codex: cómo reducir pérdidas de tokens con tres archivos markdown

Los agentes de IA para desarrollo queman contexto no porque responden mal, sino porque pasan casi todo el tiempo buscando el lugar correcto en el código. Incluso con una ventana de un millón de tokens, atraviesan directorios de nuevo, releen archivos familiares y verifican servidores como si vieran el proyecto por primera vez. Un análisis muestra que para una pregunta simple sobre pagos, el agente gastó más de 80 mil tokens y más de 15 llamadas de herramientas, mientras que la respuesta en sí consumió alrededor de 800 tokens.

En otras palabras, casi todo el presupuesto se gastó no en pensar, sino en navegación. El problema resultó no ser una particularidad local de Claude Code, sino una limitación general de los agentes de codificación modernos. Cursor, Codex y Gemini CLI funcionan de la misma manera: sin un mapa del espacio de trabajo, comienzan cada nueva sesión con reconocimiento.

Si hay un proyecto, es tolerable. Pero cuando un desarrollador tiene docenas de repositorios, instancias de VPS y entornos de staging, el agente primero hace grep en el directorio principal, encuentra archivos similares en proyectos vecinos, los lee, luego se da cuenta de que fue por el camino equivocado e inicia una nueva ronda de búsqueda. En un ejemplo real, una pregunta sobre métodos de pago en un bot se convirtió en búsqueda en múltiples proyectos, relectura de seis archivos e incluso verificación SSH de la configuración del servidor.

Tal modo no es solo costoso sino también frágil: el modelo gasta esfuerzo en orientación y fácilmente pierde lugares relevantes. El autor examina tres enfoques populares que normalmente se ofrecen como cura. El primero es RAG y búsqueda vectorial.

Hace un buen trabajo encontrando fragmentos semánticamente similares, pero entiende mal la estructura del proyecto: puede devolver chunks con auth, login y token, pero no restaurar la cadena exacta de dependencias entre middleware, lógica de refresh y configuración JWT. Además, RAG requiere infraestructura separada, un índice y reindexación, y cada consulta añade latencia. El segundo camino es análisis estático y gráficos de dependencias a través de AST y tree-sitter.

Esto es útil dentro de un repositorio, pero casi inútil a nivel de un portafolio de proyectos, donde necesitas responder no solo cómo funciona una función, sino dónde vive exactamente el servicio requerido, en qué servidor se está ejecutando y cuál es su estado. La tercera opción es mantener CLAUDE.md en cada proyecto.

Esto ayuda, pero solo después de que el agente ya ha descubierto a qué proyecto ir. En su lugar, se propone un contexto jerárquico que guía al agente de arriba hacia abajo. En el nivel cero está el mapa global de proyectos: una tabla corta con nombres, rutas, servidores y estados, que automáticamente entra en cada sesión.

En el primer nivel está CLAUDE.md en la raíz de un proyecto específico con el stack, archivos clave, comandos de despliegue, nombre del servicio y logs. Entre ellos, se puede añadir una capa intermedia en forma de Graphify si la base de código es grande y se necesita un gráfico exacto de dependencias.

Y como tercera capa markdown, el autor propone almacenar sesiones pasadas y soluciones de ingeniería como archivos markdown con frontmatter YAML, para que el agente pueda recordar qué se ha discutido ya, qué archivos fueron modificados y qué soluciones de debugging o pagos se tomaron una semana antes. La idea es simple: primero el mapa, luego la descripción del proyecto, después memoria de discusiones pasadas, y solo entonces el código fuente. Las mediciones muestran que tal esquema proporciona ganancias no cosméticas sino prácticas.

Para una pregunta sobre arquitectura del proyecto, el agente ciego necesitó 12 llamadas de herramientas versus una con la jerarquía. Para una pregunta sobre qué proyectos usan una biblioteca específica, el modo ciego hizo 44 llamadas, escaneó todo el disco y aún así perdió uno de los tres proyectos necesarios; la jerarquía se ajustó a dos consultas puntuales y proporcionó una respuesta completa. En el caso del despliegue, el efecto es aún más notable: sin estructura, el agente leía configs e iba por SSH, pero con un CLAUDE.

md debidamente completado pudo responder directamente desde el contexto sin ninguna llamada adicional. La conclusión importante aquí es que un contexto más organizado aumenta no solo la velocidad y el ahorro de tokens, sino también la precisión de la respuesta. ¿Por qué funciona esto mejor que el familiar pipeline RAG?

Porque los archivos markdown dan al agente latencia cero, previsibilidad y actualizaciones simples. El desarrollador mismo determina qué es exactamente importante saber del proyecto, en lugar de esperar que el clasificador extraiga los chunks necesarios del índice. Si el despliegue cambió o un servicio se mudó, es suficiente corregir una línea.

La escalabilidad también se ve razonable: el mapa de proyectos ocupa alrededor de 2 KB, y quince archivos de proyecto de 5 KB cada uno dan menos de 80 KB de contexto estructurado en lugar de cientos de kilobytes de código fuente bruto. En el contexto de conversaciones sobre ventanas de un millón de tokens, esto es especialmente importante: más tokens no siempre significa mejor. La información irrelevante empaña la atención del modelo, y el efecto lost in the middle sigue presente.

La conclusión principal del análisis es que el problema de tokens en agentes de codificación generalmente debe resolverse no con modelos caros ni complicando el stack, sino con disciplina de contexto. Un mapa global de proyectos, un buen CLAUDE.md y memoria de sesiones guardadas pueden ensamblarse literalmente en diez minutos, y el retorno aparece inmediatamente: menos búsqueda ciega, menos repeticiones, menos errores y un camino más corto desde la pregunta al archivo necesario.