Cache miss en Claude Code: cómo evitar pagar 12,5x más tokens

TL;DR

Claude Code usa prompt cache para no cobrarte dos veces por el mismo contexto. Cuando un cache hit pasa a ser cache miss, esos tokens cuestan 12,5 veces más. Editar CLAUDE.md a mitad de sesión, cambiar de modelo o reordenar tus tools son acciones que invalidan el cache sin avisar. Aquí están las cinco causas más comunes y cómo medir tu hit rate en tiempo real.

Por qué el cache importa en tu factura mensual

Microsoft canceló sus licencias internas de Claude Code en mayo de 2026 cuando vieron que el billing por tokens se les disparaba. La causa no era el modelo, era el patrón de uso: sesiones largas con cambios constantes que reventaban el prompt cache.

Anthropic factura los tokens cacheados a un precio mucho menor que los normales. Según los precios publicados a fecha de mayo de 2026, un cache hit sobre prefix matching cuesta aproximadamente la décima parte de un token sin cache, y la escritura inicial al cache supone un sobrecoste único. En la práctica, la diferencia entre trabajar con cache caliente y romperlo continuamente es de unos 12,5x en coste real sobre los mismos tokens de contexto.

Para un desarrollador con uso intensivo (3-5 horas diarias), esto puede significar pasar de 15-25€/mes a más de 200€/mes con el mismo trabajo.

¿Qué es el prompt cache de Claude Code?

El prompt cache es el mecanismo por el que la API de Anthropic guarda un prefijo de tu conversación (system prompt, definiciones de tools, archivos cargados) durante 5 minutos. Si la siguiente petición empieza igual byte a byte, no paga el coste completo de procesar esos tokens.

Claude Code aprovecha esto automáticamente: cada turno reenvía todo el contexto previo y deja que el sistema reutilice lo que coincide desde el inicio. El cache funciona por prefix matching: si cambias un solo carácter en los primeros tokens, todo lo posterior se invalida.

Esta es la regla que casi nadie tiene clara: el cache es posicional. Modificar algo al principio del contexto invalida el resto, aunque ese resto no haya cambiado.

Las 5 acciones que rompen el cache sin que te enteres

1. Editar CLAUDE.md a mitad de sesión

El archivo CLAUDE.md se carga en los primeros tokens de la sesión. Si lo modificas mientras estás trabajando (añadir una convención, corregir un typo, ajustar instrucciones), invalidas todo el prefijo desde ese punto. La siguiente petición pagará tokens completos por todo el contexto que ya tenías cacheado.

En mi flujo de trabajo, mantengo CLAUDE.md estable durante sesiones largas y aplico cambios solo al arrancar una nueva sesión. Si necesito ajustar algo crítico, asumo el coste de un cache reset pero lo hago consciente.

2. Cambiar de modelo a media conversación

Pasar de Sonnet 4.6 a Opus 4.7 con /model en mitad de una sesión es una de las acciones más caras. El cache está vinculado al modelo: cambiar de modelo equivale a empezar de cero. Todo el contexto se recalcula a precio completo en el nuevo modelo.

El patrón sano es decidir el modelo al inicio de la tarea. Si vas a investigar y planificar, arranca con Opus; si vas a iterar código, Sonnet. Cambiar mid-task casi siempre sale más caro que terminar la tarea con el modelo equivocado.

3. Reordenar o añadir definiciones de tools/MCP servers

Las definiciones de tools (incluidos los MCP servers conectados) viven en el system prompt. Si activas un MCP server nuevo a mitad de sesión, las definiciones se insertan en el prefijo y todo lo que viene después deja de hacer match.

Para entender mejor cómo estructurar integraciones MCP estables, te recomiendo leer mi guía sobre contratos para MCP en Claude Code: el principio clave es declarar todos los servers al inicio aunque no los uses, en vez de conectarlos sobre la marcha.

4. Cargar archivos grandes en orden inconsistente

Cuando Claude Code lee archivos con la tool Read, los inyecta en el contexto en el orden en que los pides. Si en la siguiente petición lees los mismos archivos en otro orden, el cache se rompe en el punto de divergencia.

Este detalle es invisible: tú no controlas el orden directamente, pero los prompts del estilo lee X, Y, Z producen un orden distinto a revisa Y, X, Z. La regla práctica es delegar a Claude la decisión de qué leer y dejar que su propio orden se mantenga consistente entre turnos.

5. Compactar contexto manualmente con /compact

El comando /compact resume la conversación previa y reemplaza el historial original. Es útil cuando te quedas sin ventana, pero rompe el cache de todo lo anterior: el resumen es texto nuevo que no coincide con el prefijo cacheado.

Si tu tarea va a ser larga, planifica el compact al inicio de un bloque (no a mitad). Para tareas que duran días, considera estrategias de memoria persistente, en línea con lo que describo en el artículo sobre las tres capas de memoria en Claude Code.

Tabla resumen: causas, impacto y mitigación

Acción	Impacto	Mitigación
Editar CLAUDE.md	Invalida todo el prefijo	Solo entre sesiones
Cambiar modelo	Reset total del cache	Decidir modelo al inicio
Añadir MCP server	Invalida desde tools	Declarar todos al arranque
Orden de lectura inconsistente	Cache miss parcial	Delegar el orden a Claude
/compact manual	Reset de historial	Planificar al inicio del bloque

Cómo medir tu hit rate en tiempo real

Anthropic devuelve métricas de cache en cada respuesta de la API. Claude Code las expone en el statusline y en los logs. Para inspeccionar los headers manualmente desde un script Python:

# Mide cache_read vs cache_creation para detectar miss rates altos
import anthropic

client = anthropic.Anthropic()
response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    system=[{
        "type": "text",
        "text": "Eres un asistente tecnico. Responde en espanol.",
        "cache_control": {"type": "ephemeral"}
    }],
    messages=[{"role": "user", "content": "Hola"}]
)

usage = response.usage
print(f"Cache read: {usage.cache_read_input_tokens}")
print(f"Cache write: {usage.cache_creation_input_tokens}")
print(f"Tokens nuevos: {usage.input_tokens}")

La métrica clave es la ratio cache_read_input_tokens / (cache_read + input_tokens). Por debajo del 70% tienes un problema de invalidación. Por encima del 90% estás optimizado.

En Producción

Cuando trabajas en proyectos reales con Claude Code, estas son las consideraciones extra que importan:

TTL del cache es de 5 minutos. Si dejas la sesión idle más tiempo, el cache expira y la siguiente petición paga completo. Para tareas pausadas, considera cerrar sesión y reabrirla con CLAUDE.md actualizado en vez de mantener una sesión zombie.
El cache es por endpoint y región. Si tu cliente cambia de región (algo que no suele pasar pero ocurre con failovers), pierdes el cache.
Coste real vs coste percibido. El dashboard de Anthropic muestra tokens, no eficiencia de cache. Calcula tu hit rate manualmente al menos una vez por semana para detectar drift.
Equipos pequeños: en proyectos de 2-3 personas, una convención compartida sobre cuándo se permite tocar CLAUDE.md ahorra fácilmente 30-40% del coste mensual.

Si trabajas con varios agentes (Claude Code, Codex, Gemini), recuerda que el cache no se comparte entre proveedores. Cada uno tiene su propia estrategia y métricas.

Errores Comunes y Depuración

Error: Factura disparada sin cambios aparentes en el uso. Causa: alguien del equipo modificó CLAUDE.md y nadie reinició sesiones. Solución: versionar CLAUDE.md en git y avisar al equipo antes de cualquier cambio.
Error: Hit rate del 30% en sesiones cortas. Causa: Claude Code está leyendo archivos en orden distinto cada turno porque el prompt es ambiguo. Solución: dar instrucciones claras sobre alcance y dejar que Claude planifique la lectura.
Error: Cache miss tras cambiar de Sonnet a Opus. Causa: esperado, el cache es por modelo. Solución: evitar el cambio de modelo a media tarea; si es imprescindible, asume el coste como parte de la planificación.
Error: Tokens marcados como cache write pero nunca cache read. Causa: sesiones demasiado cortas o pausas mayores de 5 minutos entre turnos. Solución: trabajar en bloques continuos o usar cache_control: {"type": "ephemeral", "ttl": "1h"} donde aplique.

Preguntas Frecuentes

¿El prompt cache de Claude Code es lo mismo que el cache de OpenAI?

No exactamente. Anthropic usa cache opt-in con cache_control explícito y soporta hasta 4 breakpoints por petición. OpenAI tiene cache automático sin control granular. En la práctica, el de Anthropic es más predecible si sabes lo que haces, pero exige diseñar bien la jerarquía de tu system prompt.

¿Merece la pena pagar el cache write si solo voy a hacer un par de peticiones?

No. La escritura al cache tiene un sobrecoste único de aproximadamente 1,25x el precio de un token normal. Si haces menos de 3-4 turnos con el mismo prefijo, sale más caro escribir al cache que pagar tokens normales. Por eso Claude Code aplica cache solo a partir de cierto umbral de contexto.

¿Puedo extender el TTL del cache más allá de 5 minutos?

Sí, Anthropic ofrece un TTL extendido de 1 hora (configurable con cache_control: {"type": "ephemeral", "ttl": "1h"}) que tiene un sobrecoste mayor en la escritura pero compensa para sesiones largas con pausas. A fecha de mayo de 2026, esta opción está disponible para clientes con uso intensivo.

Cierre

El cache de Claude Code es probablemente la palanca más importante para controlar coste en proyectos reales, y la menos visible. Entender que es posicional, que es por modelo y que cualquier edición al prefijo lo invalida cambia cómo organizas tus sesiones. Mantén CLAUDE.md estable, decide el modelo al inicio, declara todos los MCP servers al arranque y mide tu hit rate al menos una vez por semana.

El siguiente paso natural es decidir qué meter en ese CLAUDE.md estable y qué dejar fuera. Si quieres profundizar en arquitectura de contexto, el artículo sobre cómo la config pesa más que el modelo es el complemento directo, y el de separación de responsabilidades aplica también aquí: separa lo estable de lo cambiante.

¿Has medido alguna vez tu hit rate de cache? Cuéntamelo en los comentarios o en Twitter @sergiomarquezp_. En el próximo post veremos cómo automatizar la medición con un hook que avise cuando el hit rate baje del 70%.