Optimización de Tokens en Agentes de Código: Más Allá de CLAUDE.md

Introducción

La obsesión por la cantidad de contexto es un problema recurrente en la adopción de agentes de IA para desarrollo. Los desarrolladores frecuentemente sienten la necesidad de empujar toda la información posible hacia los modelos, creyendo que más datos generarán mejores respuestas. Esta intuición es intuitivamente atractiva pero empíricamente falsa. Lo que investigadores y profesionales en producción han descubierto es que la calidad del contexto supera vastamente la cantidad de contexto.

La realidad es más matizada: los LLMs funcionan como funciones sin estado (stateless) con ventanas de contexto finitas. Cada token es precioso, y la forma en que estructuras y entregas la información determina si el agente se mantiene enfocado en la tarea o se "pierde" en contexto irrelevante. Este artículo va más allá de simples configuraciones de .cursorrules y CLAUDE.md, explorando estrategias de ingeniería de contexto que profesionales utilizan diariamente con Cursor, Windsurf, Zed y Claude Code.

1. El Problema Real: Degradación de Atención, No Escasez de Datos

La Realidad Empírica

La investigación reciente en generación de código basada en LLMs revela un patrón contraintuitivo: cuanto más tokens proporcionas, peor se comporta el modelo — hasta cierto umbral donde la calidad se estabiliza o degrada aún más.

Un caso de estudio de Refine AI lo ilustra claramente. Al intentar mejorar la generación de dashboards y componentes de análisis de datos:

• Iteración 1: Incluir toda la documentación de la biblioteca, guías de estilo y ejemplos. Resultado: 10% de tasa de éxito, ~100k tokens de entrada.
• Iteración 2: Intentar estructurar esto en un prompt de tres etapas. Resultado: 20% de tasa de éxito, pero con crecimiento paradójico de tokens a ~500k.
• Iteración 3: Arquitectura aislada multi-agente. Resultado: 80% de tasa de éxito, con reducción del 90% en consumo de tokens comparado con la iteración anterior.

El insight crítico: el modelo no estaba fallando por falta de información. Estaba fallando porque la atención del modelo estaba diluida entre contexto relevante y ruido.

Por Qué Ocurre

Los LLMs asignan "poder atencional" de forma no uniforme. Cuando proporcionas 500k tokens de contexto, el modelo:

1. No puede procesar efectivamente todo el contexto — la atención se degrada uniformemente conforme aumenta la cantidad de tokens.
2. Prioriza periferias — el modelo tiende a prestar más atención al inicio (system prompt, CLAUDE.md) y final (tu pregunta actual) que al medio.
3. Sufre de "path-of-least-resistance" — prefiere generar respuestas genéricas usando patrones comunes en lugar de explorar el contexto proporcionado.

2. Arquitectura Multi-Agente: Divide y Conquistarás

La Paradoja de la Ventana de Contexto

Esperar ventanas de contexto más grandes es una estrategia equivocada. Incluso con 200k tokens (Claude 3.5 Opus), 128k-200k (Cursor Max Mode), o 2M (modelos experimentales), el problema persiste: la información no es el problema, el enfoque sí lo es.

La solución establecida por comunidades de producción es separación de responsabilidades a través de múltiples agentes especializados.

Patrón: Research-Plan-Implement-Review

En lugar de un único agente haciéndolo todo (el problema que CLAUDE.md intenta resolver), distribuye la tarea:

┌──────────────────────┐
│ Research Agent       │ (Identifica patrones y referencias relevantes)
└──────────┬───────────┘
           │
           ↓
┌──────────────────────┐
│ Planning Agent       │ (Estructura el enfoque y roadmap)
└──────────┬───────────┘
           │
           ↓
┌──────────────────────┐
│ Implementation Agent  │ (Ejecuta con contexto enfocado)
└──────────┬───────────┘
           │
           ↓
┌──────────────────────┐
│ Review Agent        │ (Valida y refina iterativamente)
└──────────────────────┘

Por qué funciona:

• Cada agente hereda solo el contexto relevante para su fase
• El Research Agent no carga todo el histórico de la conversación anterior
• El Implementation Agent recibe especificaciones claras, no un braindump
• El resultado general es mejor (80% vs 10%), pero usando 90% menos tokens

Implementación en Cursor 2.0 / Windsurf / Claude Code

Cursor 2.0 (lanzado en octubre 2025) ofrece hasta 8 agentes paralelos vía git worktrees o máquinas remotas. Cada agente funciona independientemente sin conflictos:

# Cursor 2.0 crea automáticamente worktrees aisladas
cursor-agent-1: feature-backend (Composer model)
cursor-agent-2: feature-frontend (Composer model)
cursor-agent-3: tests-e2e (GPT-4 Codex)
# Comparas los resultados y eliges el mejor

Windsurf implementa Cascade 2.0 (en desarrollo) con patrón "un agente escribe, otro revisa y marca". Cada uno tiene contexto separado y puede ejecutar hasta 20 llamadas de herramienta (tool calls) secuencialmente sin intervención manual.

Claude Code ofrece Sub-agents (nativo desde agosto 2025) — especializaciones con sus propios system prompts, permisos de herramientas, y ventana de contexto aislada. Estructura de ejemplo:

# .claude/agents/code-reviewer.md
---
name: code-reviewer
description: Analiza código para patrones, seguridad y rendimiento
tools:
  - grep
  - file-read
model: haiku  # Usa modelo más rápido/barato para tareas enfocadas
---

Eres un revisor de código sénior especializado en...

3. Compresión Contextual Intencional

El Problema con Auto-Compactación

Claude Code resume automáticamente al 95% de la ventana. Cursor trunca internamente para "mantener rendimiento". Ninguna herramienta ofrece control explícito sobre qué se preserva y por qué.

Estrategia: Notas Estructuradas con Decisiones Explícitas

En lugar de dejar que el agente resuma automáticamente, defines qué es importante de antemano:

# Estado del Proyecto - Sprint 24

## Decisiones Arquitectónicas (✗ cambia solo con justificación explícita)
- **Usar FastAPI + SQLAlchemy** — motivo: soporte async nativo, comunidad activa
- **Base de datos: PostgreSQL 14+** — motivo: JSONB, búsqueda full-text, restricciones avanzadas
- **Autenticación: JWT con refresh tokens** — motivo: sin estado, ideal para escalado horizontal

## Problemas Resueltos
- ✓ Consultas N+1 en endpoint /users (eager loading agregado)
- ✓ Memory leak en limpieza de WebSocket (implementado context manager)

## Problemas en Progreso
- 🔴 CRÍTICO: Timeout en reportes con >100k filas (optimizar consulta, agregar paginación)
- 🟡 MEDIO: Validación insuficiente en cargas de archivos (agregar sanitización)

## Contexto Técnico Reciente
- Modificado schema de `profiles` para incluir `last_sync_at` (migración #47)
- Implementada paginación en endpoint GET /reports (20-100 items/página)

Este enfoque es superior a resúmenes automáticos porque:

1. Preserva intención — el agente sabe por qué cada decisión fue tomada
2. Facilita búsqueda — encontrar "por qué usamos FastAPI" es trivial
3. Reduce re-explicación — nuevos agentes entienden contexto sin ambigüedad
4. Soporta versionamiento — confirma esto en git, rastrea evolución de decisiones

Implementación Práctica en Tus Proyectos

Crea un archivo .agent-state/progress.md en tu repositorio:

# .agent-state/progress.md

## Última Sesión de Agente
- **Agente Anterior**: ImplementationAgent (endpoints FastAPI)
- **Tiempo Usado**: 2.5 horas
- **Completado**: 3 endpoints GET/POST/PATCH implementados + tests unitarios
- **Estado**: 🟢 Listo para revisión

## Próximos Pasos
1. ReviewAgent: Validar tipos de datos, casos extremos, seguridad
2. TestAgent: Agregar tests de integración (base de datos)
3. DocsAgent: Actualizar especificación Swagger/OpenAPI

## Problemas Conocidos para Próxima Sesión
- Caché en memoria causando inconsistencia con datos de BD (pending debugging)
- Endpoint POST /items aún no paginado

Instruye a tu agente: "Lee .agent-state/progress.md antes de comenzar cualquier tarea nueva y actualízalo antes de terminar."

4. Búsqueda Inteligente y Recuperación Contextual (RAG Mejorado)

El Anti-Patrón: "Adjuntar Todo"

Muchos desarrolladores adjuntan 50 archivos esperando que el agente "encuentre" los relevantes. Resultado: tokens desperdiciados, atención diluida, latencia aumentada.

Solución: Recuperación Iterativa Bajo Demanda

Windsurf usa indexación semántica en Abstract Syntax Tree (AST) — no archivos completos, sino bloques semánticos (función, clase, etc). Resultado: 3x mejor precisión de recuperación comparado con métodos simples como grep ingenuo.

Cursor 2.0 con modelo Composer usa búsqueda en tres capas:

1. Embeddings semánticos — "¿qué archivo probablemente contiene validación de emails?"
2. Grep para coincidencias exactas — buscar por email_validator
3. Análisis AST — entender estructura y dependencias

Cómo Implementar Con Tus Agentes

Instruye al agente para explorar de forma proactiva:

"Explora el repositorio de forma proactiva:
1. Lista la estructura con profundidad=2 (tree -L 2)
2. Identifica archivos críticos por tamaño/frecuencia
3. Busca patrones específicos: /^\s*class\s+\w+.*Exception/
4. Lee solo lo necesario para la tarea
5. Si tienes dudas sobre patrones, busca ejemplos (grep -r 'patrón' --include='*.py')"

Esto mantiene la ventana de contexto limpia y enfocada. El agente no carga 50 archivos — carga 3-4 directamente relevantes.

5. Sub-Agents vs. Slash Commands vs. Skills

La confusión sobre "cuándo usar qué" es común. Aquí está la matriz de decisión (basada en Claude Code stack):

Paradigma "Divide & Conquer": Usa sub-agents para paralelización real, slash commands para flujos manuales frecuentes, skills para detección automática de contexto.

6. Gestión de Estado con MCPs (Model Context Protocol)

El Problema con Contexto Efímero

Cada nueva sesión/conversación es un reinicio. Pierdes:

• Decisiones arquitectónicas previas
• Patrones que funcionaron
• Bugs conocidos
• Contexto acumulado del proyecto

Solución: MCPs como Memoria Persistente

MCPs (protocolo estandarizado para integración de herramientas) permiten a los agentes acceder a datos estructurados sin cargarlos en contexto:

{
  "name": "project-state-mcp",
  "description": "Acceso a estado persistente del proyecto",
  "tools": [
    {
      "name": "get_architecture_decisions",
      "description": "Retorna decisiones arquitectónicas con justificaciones"
    },
    {
      "name": "get_known_issues",
      "description": "Bugs conocidos y resoluciones previas"
    },
    {
      "name": "get_approved_patterns",
      "description": "Patrones de código aprobados en el proyecto"
    }
  ]
}

Ejemplos de MCPs en Producción (Diciembre 2025):

• Serena MCP — toolkit completo para agentes de código (búsqueda semántica, edición inteligente). Se integra con Claude Code y funciona con sub-agents
• Google Cloud Security MCP — conecta personas de SOC con runbooks de seguridad
• Shortcut MCP — integra gestión de proyectos con contexto de agentes

Beneficio: El agente no necesita releer todo nuevamente — accede vía llamada de herramienta, ahorrando 60-80% de tokens.

7. Novedad: Agentes Paralelos en Cursor 2.0

Qué Cambió (Octubre 2025)

Cursor 2.0 introdujo hasta 8 agentes simultáneos usando git worktrees o máquinas remotas:

Agente 1 (Composer model, worktree-1): Refactoring de backend
Agente 2 (Composer model, worktree-2): Componentes de frontend
Agente 3 (GPT-4 Codex, worktree-3): Tests E2E

Cada worktree es un clon aislado del mismo repositorio — los cambios no entran en conflicto. Comparas los 3 resultados y eliges el mejor.

Implicación práctica:

• Tareas complejas resueltas 2-3x más rápido
• Comparación de resultados para problemas difíciles (múltiples modelos atacando el mismo problema)
• Git worktrees gestionadas automáticamente por Cursor

8. Windsurf Cascade: Indexación Semántica

Cómo Funciona (Diciembre 2025)

Windsurf escanea previamente tu repositorio completo y crea un índice semántico en AST:

Tu código:
├── auth/
│   ├── login.py     → [función login, clase AuthService, imports]
│   ├── jwt.py       → [función encode_token, función decode_token]
├── models/
│   ├── user.py      → [clase User, validadores]
│   ├── schema.py    → [subclases Pydantic BaseModel]

Índice semántico de Windsurf:
- Entidad: "login" (función) → archivo: auth/login.py:15
- Entidad: "AuthService" (clase) → archivo: auth/login.py:42
- Dependencia: AuthService → jwt.encode_token
- Dependencia: User model → schema.py

Cuando pides "refactoriza autenticación para usar JWT", Cascade entiende la estructura sin leer archivos completos.

Ventaja sobre grep: Contexto estructural, no solo strings.

9. Compresión Intencional vs. Auto-Compactación

Patrones de Fallos en Compresión Automática

Investigación de Stanford (2024) identifica 3 patrones donde la compresión automática falla:

1. "Lost by the boundary" — información crítica en límites de chunks se pierde
2. "Lost if surprise" — información inesperada/outliers es descartada
3. "Lost along the way" — datos en el medio del contexto sufren degradación

Estrategia: Compresión Controlada con Ranks Explícitos

# Compresión Manual - Sesión #47

## Preservar (Crítico - nunca descartar)
- Decisión: Usar Row-Level Security en PostgreSQL
- Motivo: Requisito de seguridad de datos multi-tenant
- Archivo de referencia: `docs/security-design.md`
- Prioridad: 🔴 CRÍTICO

## Preservar (Importante - si hay espacio)
- Patrón de reintento con backoff exponencial y jitter
- Motivo: Prevenir thundering herd en rate limiting

## Descartar (Ya resuelto, sin relevancia futura)
- Discusiones sobre selección de ORM (resuelto con SQLAlchemy, sin alternativas)
- Debugging de sintaxis Python (problema aislado)

## Nueva Ventana de Contexto
- Comenzar nueva sesión con CLAUDE.md + progress.md + archivo de decisiones
- Sub-agent de "implementación" recibirá solo especificación enfocada

10. Selección de Modelo: El Token Más Barato es el Que No Usas

Matriz de Selección (Diciembre 2025)

Anti-Patrón

❌ Usar Opus para TODO porque "es el mejor"
❌ Usar Haiku para refactoring complejo
❌ Habilitar "thinking mode" por defecto

Cursor 2.0 permite selección automática de modelo por tarea — configura "Auto" para simple, Sonnet para moderadas, Opus raramente.

11. El Papel del Thinking Mode

Los modelos con razonamiento explícito ("thinking") pueden resolver problemas complejos, pero consumen tokens exponencialmente.

Cuándo Usar Thinking

✅ Decisiones arquitectónicas críticas (p.ej., migración de base de datos) ✅ Optimizaciones de rendimiento complejas (p.ej., algoritmo de ordenamiento distribuido) ✅ Análisis de seguridad profundo (p.ej., auditoría de criptografía)

Cuándo Evitar

❌ Refactoring simple ❌ Corrección de typos ❌ Generación de boilerplate

Regla de Oro: Thinking mode = 3-5x más tokens. Usa solo cuando la calidad lo justifique.

12. Terminología Técnica y Mejores Prácticas

Para evitar confusiones de traducción directa:

13. Monitoreo y Optimización Continua

Métricas que Importan

1. Tasa de Éxito — % de tareas completadas en primer intento
2. Tokens por Éxito — costo de cada tarea exitosa
3. Tiempo de Respuesta — latencia total (no lineal con tokens)
4. Utilización Contextual — % de ventana realmente usada

Herramientas de Observabilidad (Diciembre 2025)

• Cursor: Ver tokens/stats en UI por operación
• Windsurf: Logs detallados de recuperación + tokens en ~/.windsurf/logs
• Claude Code: Análisis retrospectivo de trazas vía Claude Dashboard
• Qodo: Métricas por agente ejecutado

Pipeline de Optimización Realista

Semana 1: Medir baseline
  Métrica: 150k tokens/tarea, 60% éxito

Semana 2: Implementar RAG inteligente
  Métrica: 80k tokens, 75% éxito

Semana 3: Agregar MCPs
  Métrica: 50k tokens, 85% éxito

Semana 4: Multi-agent (research-plan-implement)
  Métrica: 40k tokens, 90% éxito

Semana 5+: Refinamientos incrementales
  Métrica: 30k tokens, 92% éxito

14. Anti-Patrones Comunes

❌ Enviar Todo de Una Vez

# MALO
agent.run("""
    TODO: Refactoriza el módulo de autenticación.
    
    Aquí está TODO el código:
    [500 archivos adjuntos]
    
    Aquí está la documentación:
    [50 PDFs]
""")

✅ Recuperación Iterativa

# BUENO
agent.run("""
    TODO: Refactoriza el módulo de autenticación.
    
    Explora:
    1. Busca clases con 'Auth' en el nombre
    2. Identifica la función de punto de entrada
    3. Mapea dependencias
    4. Luego revisa la estructura
""")

❌ Un Agente Haciendo Todo

# MALO - contexto contaminado
agent = create_agent(
    instructions="""
        Eres un desarrollador full-stack que:
        - Escribe backends FastAPI
        - Escribe frontends React
        - Desplega con Docker
        - Escribe tests
        - Documenta todo
        - Optimiza rendimiento
    """
)

✅ Agentes Especializados

# BUENO - contexto enfocado
research_agent = SubAgent(instructions="Analiza codebase y propone arquitectura")
backend_agent = SubAgent(instructions="Implementa endpoints FastAPI")
test_agent = SubAgent(instructions="Escribe tests pytest")
review_agent = SubAgent(instructions="Revisa código para patrones y seguridad")

# Orquesta manualmente o deja que Claude Code coordine

Conclusión: Tokens como Recurso Finito

La optimización de tokens se trata fundamentalmente de tratar tokens como un recurso finito y valioso, similar a la RAM o CPU en sistemas tradicionales.

Principios aplicados por profesionales en producción en Diciembre 2025:

1. Calidad > Cantidad — contexto enfocado supera contexto abundante
2. Arquitectura Multi-Agente — divide problemas complejos en tareas especializadas
3. Compresión Intencional — controla qué se memoriza, no confíes en resúmenes automáticos
4. Búsqueda Iterativa — carga contexto bajo demanda, no todo de una vez
5. Selección Apropiada de Modelo — usa el modelo correcto para cada tarea
6. Indexación Semántica — aprovecha AST y embeddings, no grep ingenuo
7. MCPs para Memoria — accede a estado persistente vía herramientas, no contexto
8. Observabilidad — mide y optimiza continuamente
9. Sub-agents para Aislamiento — cada agente especializado, contexto propio
10. Agentes Paralelos — Cursor 2.0 permite 8 agentes simultáneos vía git worktrees

Aplicar estas técnicas no es solo sobre ahorrar tokens — se trata de construir agentes de IA que razonen mejor, entreguen código de superior calidad, y cueste menos en el proceso.

Referencias Técnicas

• Anthropic Engineering: "Effective context engineering for AI agents" (2025)
• Refine AI Case Study: "Quality Code Generation: Multi-Agent Systems and Token Dilution" (reducción 90% de tokens con multi-agent)
• Cursor 2.0 Release: "Introducing Cursor 2.0 and Composer" (Octubre 2025) — git worktrees, 8 agentes paralelos
• Windsurf: Indexación semántica basada en AST, roadmap Cascade 2.0 (revisión de código + benchmarking)
• Claude Code Documentation: Sub-agents, extensiones protocolo MCP, patrones aislamiento de contexto
• Serena MCP: Toolkit de comprensión de código semántico para agentes de código (GitHub: oraios/serena)
• HumanLayer Blog: "Writing a good CLAUDE.md" (investigación sobre seguimiento de instrucciones)
• Artículos de Investigación:
  • "Self-Organized Agents" (framework SoA)
  • "Chain of Agents" (framework CoA)
  • "Gist Token-based Context Compression" (Stanford, patrones de fallo)
  • "LLMLingua: Compressing Prompts for Accelerated Inference"