Cómo ahorrar tokens de agentes de IA al trabajar con bases de código grandes: 5 patrones

El problema: los tokens se consumen en la exploración

Los agentes de IA se están integrando cada vez más en el proceso de desarrollo: ya no solo generan funciones, sino que exploran proyectos, buscan archivos, analizan la arquitectura y ejecutan pruebas. En bases de código grandes surge un problema agudo: una parte considerable de los tokens se gasta antes de escribir la primera línea de código. Antes de hacer un cambio pequeño, el agente puede necesitar estudiar la estructura del repositorio, encontrar el servicio correcto, leer la documentación, entender las convenciones y revisar cómo están organizadas las pruebas.

En la siguiente tarea, parte de esa exploración se repite de nuevo. En un proyecto pequeño esto pasa desapercibido, pero cuanto más grande es el repositorio, más caro resulta explorar el sistema.

Intentar darle al agente toda la documentación de golpe, o usar un modelo más barato, da un efecto pequeño o simplemente traslada el gasto de tokens a otro lugar. El enfoque correcto es tratar la gestión de tokens como un problema de gestión de contexto, aplicando los principios de lazy loading, localidad de datos, caché y separación de responsabilidades al flujo de información del agente de IA.

Cinco patrones de optimización de contexto

1. Minimize Permanent Context

La trampa de acumular conocimiento siempre se ve igual: creamos un AGENTS.md o CLAUDE.md y empezamos a meter cada vez más información. Primero la arquitectura y la estructura del repositorio, luego las reglas de escritura de código, las convenciones de los servicios, las particularidades de la base de datos, las pruebas, el CI/CD y las integraciones.

El problema es que todo ese conjunto se convierte en contexto permanente. Al modificar el servicio de facturación, es poco probable que el agente necesite las reglas de desarrollo de la app móvil, pero si están en el contexto global, el modelo las recibe una y otra vez. Las instrucciones globales deben ser un mapa del proyecto (¿dónde está la información?), no una enciclopedia (¿qué hay que contar de todo?). El AGENTS.md raíz debe indicar dónde están las instrucciones detalladas para auth, billing, database e infrastructure; todo lo demás se carga a demanda.

2. Progressive Context

El conocimiento se organiza en capas: contexto global → contexto de dominio/servicio → instrucciones específicas de la tarea → implementación de referencia → código fuente relevante. Para la tarea de añadir un nuevo proveedor de pagos, el agente recorre este camino: AGENTS.md → services/payments/AGENTS.

md → skills/add-payment-provider.md → implementación existente del proveedor → archivos fuente relevantes. Para una app móvil, el camino es completamente distinto; para infraestructura, hay un tercero.

En lugar de 20.000 tokens sobre "todo el proyecto", se obtiene: contexto global (500) + contexto de servicio (700) + instrucciones de tarea (600) + referencia (800) + archivos fuente (2500). La mayor parte del conocimiento del proyecto existe por separado y entra en el contexto solo cuando se vuelve relevante.

3. Reduce Exploration

Incluso con un contexto permanente pequeño, queda una fuente importante de gasto: explorar la base de código. El agente necesita averiguar dónde están los manejadores de pagos, qué servicio publica eventos, qué message broker se usa, dónde están los consumers, cómo se crean las notificaciones, dónde están las plantillas y cómo se prueba todo. Un repositorio bien organizado ofrece puntos de entrada: un mapa del proyecto con secciones (HTTP handlers: services//handlers/, business logic: services//domain/, etc.), golden examples (para un nuevo message consumer, un enlace a services/orders/consumers/order-created/ muestra la estructura, el naming, el manejo de errores, el logging, la interacción entre capas y las pruebas), y search before read (primero buscar con rg, git grep o herramientas LSP, luego leer).

4. Reuse Knowledge

Cuando un agente investiga cómo funciona el pago de un pedido, descubre la cadena: solicitud HTTP → servicio de pedidos → servicio de facturación → proveedor de pagos → evento de pago → message broker → consumer de pedidos. Para ello lee cientos de archivos. Luego la sesión termina, llega una nueva tarea una semana después, y un nuevo agente empieza la exploración desde cero.

Esta duplicación de conocimiento hay que eliminarla. Si la exploración reveló una característica importante y estable del sistema, vale la pena guardar el resultado en docs/payment-flow.md con una breve descripción, una lista de archivos y un enlace a una implementación de referencia.

La siguiente sesión de IA empezará con unos pocos cientos de tokens de descripción estructurada en lugar de volver a leer los archivos. El conocimiento útil se puede guardar en AGENTS.md, instrucciones de servicio, documentación, skills específicos de la tarea, notas de arquitectura, golden examples o comentarios en el código, según el alcance.

El resultado es un ciclo: descubrimiento costoso → conocimiento estructurado → recuperación futura barata.

5. Keep Context Clean

La otra cara de este enfoque: si cada descubrimiento útil se guarda, la documentación crece sin parar y aparece la contaminación del contexto (context pollution): instrucciones obsoletas, ejemplos desactualizados y convenciones olvidadas conviven con las nuevas. Hay que limpiar el contexto con regularidad: eliminar información obsoleta, actualizar ejemplos y quitar duplicados. Igual que con el código, es mejor eliminar la documentación obsoleta que dejarla con un comentario explicando que está desactualizada.

Los cinco patrones funcionan juntos: minimizamos el contexto permanente, cargamos el conocimiento por capas según se necesite, ayudamos al agente a explorar menos mediante puntos de entrada claros, no repetimos una exploración costosa dos veces y eliminamos la información obsoleta. El resultado es un menor gasto de tokens, no gracias a modelos más baratos, sino a gestionar qué información ve el agente y cuándo.