Lección 03: Tokens, @-tags y Gestión de la Ventana
- La ventana de contexto de Claude Code es de 200K tokens. Cada archivo leído, cada respuesta y cada resultado de herramienta consume espacio finito.
- Los @-tags inyectan archivos directamente en el contexto sin que Claude necesite buscarlos con herramientas.
- El comando /clear reinicia la sesión sin cerrar Claude Code, liberando todo el contexto acumulado.
- Cuando el contexto se acerca al límite, Claude Code aplica compresión automática resumiendo el historial y descartando detalles antiguos.
- Los sub-agentes ejecutan tareas aisladas con su propia ventana de contexto, protegiendo el hilo principal.
La ventana de contexto es el recurso más crítico de una sesión con Claude Code. No es un detalle técnico menor: es la arquitectura invisible que determina si Claude puede resolver tu tarea o si se pierde a mitad de camino. Entender cómo se llena, cómo gestionarla y cuándo resetearla es lo que separa al usuario que obtiene resultados consistentes del que se frustra porque "Claude olvida cosas".
Anatomía de la Ventana de 200K Tokens
Claude Code opera con una ventana de contexto de 200,000 tokens. Pero esos 200K no están todos disponibles para ti. La ventana se compone de varias capas que ya ocupan espacio antes de que escribas tu primer prompt:
- System prompt (~2,000 tokens): Las instrucciones internas que definen el comportamiento de Claude Code como agente. No las ves, pero están ahí.
- CLAUDE.md (~500-2,000 tokens): Tu archivo de configuración de proyecto. Cada regla, convención y comando que defines consume contexto desde el minuto cero.
- Historial de la conversación: Cada mensaje tuyo y cada respuesta de Claude. Se acumula turno a turno.
- Resultados de herramientas: Cada archivo leído, cada búsqueda, cada ejecución de bash. Este es el consumidor principal en sesiones largas.
- Espacio de respuesta: Claude necesita tokens libres para generar su respuesta. Si el contexto está lleno, no puede responder con detalle.
Contexto = RAM de tu Sesión
Piensa en la ventana de contexto como la RAM de tu sesión. El system prompt y CLAUDE.md son el sistema operativo: siempre cargados. Los archivos que lees son programas abiertos. El historial es la memoria de trabajo. Cuando la RAM se llena, el sistema empieza a hacer swap (compresión) y el rendimiento cae.
@-tags: Inyección Directa de Contexto
Los @-tags son el mecanismo más eficiente para cargar archivos en el contexto. En lugar de pedirle a Claude que busque un archivo (lo que consume tokens en la llamada a la herramienta, la lectura y la respuesta), le das el contenido directamente:
# Inyectar un archivo específico Tu: Revisa la lógica de autenticación en @src/lib/auth.ts # Inyectar un directorio completo (lee todos los archivos) Tu: Analiza la estructura de @src/components/ # Inyectar múltiples archivos en un solo prompt Tu: Compara @src/api/users.ts con @src/api/orders.ts y unifica el manejo de errores
Cuándo usar @-tags vs dejar que Claude busque
No siempre es mejor inyectar manualmente. La decisión depende de lo que sepas sobre tu codebase:
- Usa @-tags cuando: Sabes exactamente qué archivo necesita Claude. Es más rápido y consume menos tokens que una búsqueda.
- Usa @-tags cuando: Trabajas con archivos de configuración críticos (
@tsconfig.json,@package.json,@prisma/schema.prisma). - Deja que Claude busque cuando: No sabes dónde está la implementación. Claude usa Grep y Glob que son más eficientes que cargar archivos al azar.
- Deja que Claude busque cuando: El problema puede involucrar múltiples archivos desconocidos. Claude navega el codebase mejor que tu intuición en proyectos grandes.
Coste real de los @-tags
Un @-tag inyecta el contenido completo del archivo. Un archivo de 500 líneas de TypeScript consume aproximadamente 3,000-5,000 tokens. Si inyectas un directorio con 30 archivos, puedes consumir 50,000-100,000 tokens de golpe, la mitad de tu ventana. Usa @-tags con precisión quirúrgica, no con escopeta.
/clear: Reset Estratégico
El comando /clear es tu herramienta de gestión más directa. Borra todo el historial de la conversación, liberando el contexto acumulado. Claude Code permanece abierto, tu CLAUDE.md se recarga, y empiezas con la ventana limpia.
# Escenario: llevas 45 minutos trabajando en auth # Ahora necesitas cambiar al módulo de pagos Tu: /clear > Context cleared. CLAUDE.md reloaded. > Tokens used: ~3K / 200K > Ready. # Ahora puedes trabajar en pagos con contexto limpio Tu: Necesito refactorizar el flujo de checkout en @src/payments/checkout.ts
Cuándo hacer /clear
- Cambio de tarea: Pasas de un módulo a otro completamente diferente. El contexto anterior no aporta, solo contamina.
- Después de un refactor largo: Claude ha leído y editado muchos archivos. El historial acumulado puede confundirlo con versiones antiguas del código.
- Cuando Claude empieza a "olvidar": Si notas que repite preguntas o pierde el hilo, probablemente el contexto está saturado.
- Antes de una tarea crítica: Si necesitas la máxima precisión, empieza con contexto limpio e inyecta solo lo necesario.
Compresión Automática y Sub-agentes
Cuando la ventana de contexto se acerca al límite, Claude Code no explota: aplica compresión automática. El sistema resume el historial de la conversación, manteniendo los puntos clave pero descartando detalles como diffs exactos, contenidos completos de archivos leídos hace muchos turnos, y respuestas intermedias.
La compresión es un compromiso. No pierdes el hilo general, pero sí pierdes precisión. Si le pediste a Claude que revisara un patrón específico 30 turnos atrás, después de la compresión puede no recordar los detalles exactos de lo que encontró.
Sub-agentes: Contexto Aislado
Claude Code puede lanzar sub-agentes (también llamados "tool use agents") que operan con su propia ventana de contexto independiente. Esto es crítico para tareas pesadas:
- Búsquedas extensas: Un sub-agente puede escanear 200 archivos sin contaminar tu contexto principal.
- Análisis aislados: Tareas como "revisa todos los tests que fallan" se delegan a un sub-agente que devuelve solo el resumen.
- El resultado importa, no el proceso: El sub-agente consume su propio contexto, y solo el resultado final se inyecta en el hilo principal.
No necesitas invocar sub-agentes manualmente. Claude Code los crea automáticamente cuando una operación de herramienta es lo suficientemente compleja. Tu rol es estructurar tus prompts para que Claude pueda delegar en lugar de hacer todo en el hilo principal.
# Claude lanza un sub-agente para tareas pesadas Tu: Encuentra todos los endpoints que no tienen validación de input y añade zod schemas. > [Agent] Scanning src/api/**/*.ts (47 files)... > [Agent] Found 12 endpoints without validation > [Agent] Generating zod schemas... # Solo el resumen y los cambios llegan al contexto principal > Updated 12 files. Added input validation to: > - POST /api/users (CreateUserSchema) > - PUT /api/orders/:id (UpdateOrderSchema) > - ...
Reglas Prácticas de Gestión
Después de trabajar con cientos de sesiones, estas son las reglas que mejor funcionan:
- Una tarea, un contexto. Si cambias de tema, haz
/clear. El coste de recargar contexto es menor que el coste de confundir a Claude. - @-tags para lo conocido, búsqueda para lo desconocido. No inyectes archivos "por si acaso". Cada token cuenta.
- Monitoriza la compresión. Si ves el mensaje de compresión automática, es señal de que estás forzando la sesión. Considera hacer /clear y reanudar con un prompt bien estructurado.
- CLAUDE.md compacto. Cada línea de tu CLAUDE.md consume contexto en cada sesión. Elimina lo que no sea estrictamente necesario.
- Prompts densos, no largos. Un prompt claro de 3 líneas es mejor que uno vago de 15. Menos tokens de entrada = más espacio para la respuesta.
Regla de Oro
Trata la ventana de contexto como tratarías la RAM de un servidor en producción: monitoriza el consumo, libera lo que no uses, y no cargues más de lo necesario. La eficiencia de Claude Code depende directamente de cómo gestionas este recurso finito.
Preguntas Frecuentes
Sobre gestión de contexto en Claude Code
/clear manualmente.tiktoken o la API de conteo de Anthropic para mediciones exactas./clear libera contexto y evita que Claude confunda el contexto del módulo anterior con el actual. Si trabajas en una tarea continua con dependencias entre pasos (ej: refactorizar un sistema paso a paso), mantener la sesión preserva el contexto acumulado y evita repetir explicaciones. La regla práctica: si llevas más de 30 minutos en la misma sesión y cambias de tema, haz /clear.