Tokens y ventana de contexto en Claude Code: cómo gastar menos

Tiempo: unos 25 min de teoría + 10 min de práctica

Lo esencial

Los tokens son la moneda de Claude Code. Cada palabra que Claude lee o escribe cuesta tokens. Si no controlas lo que Claude lee, pagas por lo que sobra. La carga progresiva es como un mesero listo que no te trae toda la carta a la mesa, sino que primero te pregunta "¿carne o pescado?".

Conceptos clave

• El token es la unidad de medida del texto (poco más de media palabra en inglés en los modelos actuales de Claude) y la base del precio de la API
• Todo lo que Claude lee mientras trabaja gasta tokens (claude.md, workflows, herramientas)
• Carga progresiva (L1/L2/L3): leer solo lo que hace falta en este momento
• Un claude.md breve = menos tokens = cada petición más barata y más rápida

Teoría

Qué es un token, en palabras simples

🎨 Imagínalo así: los tokens son como los segundos de una llamada telefónica: no son palabras, son "pulsos" que se van gastando con cada carácter. Si hablas mucho, pagas más. Una llamada al grano sale más barata.

Un token es un pedacito de texto. No siempre es una palabra entera: a veces es parte de una palabra, a veces un signo de puntuación. Para fines prácticos: 1,000 tokens ≈ 555 palabras ≈ poco más de una página tamaño carta (texto en inglés en los modelos actuales de Claude; en modelos anteriores ≈ 750 palabras).

Por qué importa: los modelos de Claude (y todos los LLM) calculan el costo del trabajo justamente en tokens. Cada llamada a la API tiene un precio: tokens de entrada (lo que enviaste) + tokens de salida (lo que respondió el modelo).

Ejemplo: si tu claude.md pesa 2,000 tokens y corres 100 workflows al día, solo el claude.md se come 200,000 tokens de entrada al día. Con un precio de $2 por millón de tokens de entrada (Sonnet 5.5, a octubre de 2026), son $0.40 al día solo por el prompt de sistema. Reducir el claude.md a la mitad = $0.20 al día de ahorro. Precios vigentes: Lo vigente.

Qué lee Claude en cada petición

🎨 Imagínalo así: cada petición a Claude es como una mesa puesta antes de la cena. El claude.md es el mantel (siempre está), el workflow es el menú del platillo (uno a la vez), y el historial de la conversación son los platos sucios de los platillos anteriores (se van acumulando). Entre más platos, más caro sale quien lava.

Cuando corres un workflow o le escribes un mensaje al agente, Claude Code arma tras bambalinas el contexto para el modelo. Lo típico es esto:

1. claude.md: el prompt de sistema del proyecto. Se lee siempre, en cada petición.
2. El archivo del workflow: el workflow que se está ejecutando. Se lee completo.
3. Herramientas: las descripciones de las herramientas que el agente puede usar.
4. Servicios MCP: las descripciones de los MCP conectados (si hay).
5. Historial de la conversación: los mensajes anteriores de esta sesión.
6. Archivos auxiliares: solo si de verdad hacen falta (scripts, referencias).

En conjunto pueden ser de 10,000 a 50,000 tokens por petición, según qué tan complejo sea el proyecto.

Carga progresiva: tres niveles

Este es el concepto clave para usar Claude Code de forma eficiente. En vez de leer todo de golpe, el sistema lee lo mínimo necesario y profundiza solo cuando hace falta.

Nivel 1 (L1): YAML frontmatter, ~100 tokens

🎨 Imagínalo así: L1 es la portada de un libro. Lees el título, el año, el género. Si te sirve, lo bajas del estante y lo lees por dentro. Si no, lo regresas. Claude hace lo mismo con los workflows.

Cada archivo de workflow o de skill empieza con un encabezado YAML:

---
name: newsletter-generator
description: Genera un newsletter semanal sobre un tema dado
triggers: [newsletter, email-digest, weekly-summary]
---

En L1, Claude lee solo este encabezado: nombre, descripción, disparadores. Son unos 50-150 tokens. Si la tarea no corresponde a este workflow, el archivo completo no se lee. El agente revisa todos los workflows en L1 y elige el que necesita.

Analogía: es como las fichas de un archivero: lees el título de la ficha y solo si te sirve sacas el expediente completo.

Nivel 2 (L2): el archivo de workflow completo, ~1,000–2,000 tokens

Cuando L1 coincide, Claude lee el archivo de workflow completo. Ahí están las instrucciones completas: pasos, lógica, parámetros. Pueden ser de 500 a 2,000 tokens según la complejidad del workflow.

Nivel 3 (L3): archivos auxiliares, solo si de verdad hacen falta

Si el workflow usa un script externo (helpers/parse_email.py) o un archivo con ejemplos, Claude lo lee solo cuando llega al paso que lo requiere. No antes, no siempre: solo cuando hace falta.

El principio de "solo lo necesario"

El enfoque malo: en el claude.md está escrito todo lo que alguna vez podrías querer usar: todos los roles de los agentes, todos los workflows descritos a detalle, todos los ejemplos metidos directo en el texto. Eso se lee en cada petición, incluso cuando solo necesitas escribir un correo.

El enfoque bueno: el claude.md contiene solo lo que el agente necesita para entender su rol y la estructura del proyecto. Los detalles de los workflows van en los archivos de workflow. Los ejemplos, en archivos aparte que se cargan en L3.

El comando /context: una radiografía de la ventana de contexto

🎨 Imagínalo así: /context es una radiografía. No es un simple "algo me duele", sino una imagen precisa: aquí el prompt de sistema, 3%; aquí el historial, 75%; aquí los MCP, 20%. Ves el problema y sabes dónde cortar.

El comando /context muestra un mapa del uso actual de tokens. Ejemplo de salida:

Context window usage: 225,000 / 200,000 tokens (112%)

System prompt (claude.md):     8,200 tokens  (3.6%)
MCP tool descriptions:        45,000 tokens (20.0%)
Current workflow:              2,100 tokens  (0.9%)
Conversation history:        169,700 tokens (75.4%)

Qué vemos en este ejemplo:

• Las descripciones de MCP se comen el 20% del contexto: quizá hay demasiados MCP conectados
• El historial de la conversación ocupa el 75%: es momento de hacer /clear o de empezar una conversación nueva
• La ventana de contexto está desbordada (112%): el modelo va a "olvidar" el inicio de la conversación

Es una herramienta de diagnóstico. Cuando el agente empieza a "olvidar" lo que hizo antes, lo primero que revisas es /context.

Reglas prácticas para ahorrar tokens

1. Un claude.md corto: describe el rol del agente y la estructura del proyecto, no los workflows a detalle
2. Archivos aparte para los workflows: L2 se carga solo cuando hace falta
3. Saca los ejemplos a /examples: son L3 y no se cargan en vano
4. /clear cuando la conversación se alargó: el historial suele ser el que más tokens devora
5. No conectes MCP que no necesitas: cada MCP agrega miles de tokens en descripciones de herramientas
6. YAML frontmatter en cada archivo: permite el filtro de L1

La ventana de contexto en la práctica

🎨 Imagínalo así: la ventana de contexto es como un escritorio. Puedes extender muchas hojas, pero el escritorio tiene un tamaño fijo. Cuando ya no cabe nada, las hojas viejas se caen al piso: Claude ya no las ve.

Claude tiene un límite de cuántos tokens puede ver al mismo tiempo: esa es la "ventana de contexto".

Tamaño de la ventana de contexto por modelo (a octubre de 2026)

Los identificadores exactos de los modelos para la API y los precios vigentes están en la página Lo vigente y en la documentación de Anthropic (platform.claude.com/docs/en/about-claude/models/overview).

Importante al cambiar de modelo: distintas generaciones de modelos pueden contar los tokens de forma diferente, y el mismo texto puede pesar más en un modelo nuevo. Revisa /context y el contador de tokens de la API después de cambiar de modelo, antes de planear tu presupuesto.

Qué cambió para octubre de 2026:

• 1M de tokens de contexto en Fable 5.1, Opus 5.5 y Sonnet 5.5; Haiku 4.5 tiene una ventana de 200,000
• Los modelos viejos (Haiku 3.5, Sonnet 4, Opus 4, Opus 4.1) se retiraron de la Claude API
• Haiku 4.5 podría retirarse de la API no antes del 15/10/2026: sigue la página de model deprecations

Cuando la ventana se desborda, pasa una de dos cosas: la petición no pasa, o Claude "olvida" el inicio de la conversación (el modelo solo ve los últimos N tokens). En sesiones largas de desarrollo es algo normal: se resuelve con /clear o /compact.

Importante: /clear borra el historial de la conversación, no los archivos del proyecto. Tus workflows y tu código siguen ahí.

/compact es la opción más suave: comprime el historial y conserva las decisiones clave y el contexto. Usa /compact cuando quieras seguir trabajando y /clear cuando cambies a otra tarea.

Práctica

Tarea: auditoría de tokens de tu proyecto

1. Abre en Claude Code el proyecto de la lección Claude.md: el prompt de sistema de tu proyecto
2. Escribe el comando /context
3. Estudia la salida: ¿qué se come más tokens?
4. Si el claude.md ocupa más de 3,000 tokens, busca qué puedes sacar a archivos aparte
5. Revisa los MCP conectados: ¿de verdad usas todos?
6. Después de optimizar, vuelve a correr /context y compara

Pregunta para reflexionar: si tu proyecto crece a 50 workflows, ¿qué tan importante será la arquitectura L1/L2/L3?

Herramientas y recursos

• /context: muestra cómo se reparten los tokens en la sesión actual
• /clear: borra el historial de la conversación (no los archivos)
• /compact: comprime el historial de forma inteligente y conserva las decisiones clave
• /usage: límites del plan, costo y estadísticas de la sesión (antes el comando se llamaba /cost)
• YAML frontmatter en los workflows: permite la carga progresiva de L1
• Claude Pricing: precios vigentes de los planes; los precios por token de cada modelo están en la página Lo vigente
• Claude Console: administración de claves de API y del uso
• tiktoken: biblioteca de Python para contar tokens (es de OpenAI, pero sirve para estimar)
• Anthropic SDK: conteo exacto de tokens con la Token Counting API (el método client.messages.count_tokens())

Errores comunes

Error 1: ignorar /context Llevas 3 horas trabajando y el agente empieza a "trabarse": olvida instrucciones, se repite. La causa: el contexto está lleno al 90%. El hábito: revisa /context cada 30-40 minutos.

Error 2: todo en CLAUDE.md Todas las reglas, todos los ejemplos, todas las plantillas en un solo archivo de 5,000 tokens. Eso se lee en cada petición. Saca los ejemplos a archivos aparte y usa la carga L2/L3.

Error 3: no usar /compact Mucha gente solo conoce /clear. Pero /clear borra todo el contexto y tienes que volver a explicar la tarea. /compact conserva lo esencial y libera buena parte del contexto. Usa /compact con anticipación, antes de que la ventana se llene, y /clear cuando cambies de tarea.

Lecciones relacionadas

• Comandos integrados de Claude Code: la lista completa de comandos, incluidos /compact, /clear y /usage
• Context Rot y 28 técnicas contra la degradación: manejo avanzado del contexto

Ideas clave

Los tokens son dinero. Cada palabra que Claude lee o escribe cuesta. Entenderlo te convierte en un arquitecto ahorrativo y no en uno derrochador.

La carga progresiva L1/L2/L3 no es un detalle técnico, es un principio de diseño. Arma tu proyecto para que Claude lea solo lo que necesita en este momento.

/context es una radiografía. Cuando algo va lento o sale caro, córrelo primero.

Siguiente lección

→ Context Rot y 28 técnicas contra la degradación: qué hacer cuando el contexto "se echó a perder". Los comandos /clear, /context y otros se explican en la lección Comandos integrados de Claude Code.