Prompt caching en Claude Code: por qué tu siguiente turno va lento y dispara el consumo (y cómo evitarlo)

TL;DR A veces una sesión se vuelve astronómicamente más lenta y dispara el consumo, y al principio no sabes por qué. Casi siempre es la caché. Claude Code cachea el prefijo de cada petición de forma automática; ciertos cambios a mitad de sesión lo invalidan y el siguiente turno reprocesa toda la conversación a precio completo. La regla de oro: elige modelo y effort al arrancar y no los toques a mitad de tarea.

Claude Code gestiona el prompt caching por ti, así que no es algo que configures. Es algo que conviene no romper sin querer. Saber qué lo invalida es la diferencia entre una sesión fluida y una que de repente se arrastra.

Cómo funciona la caché

En cada turno el modelo no recuerda nada del anterior, así que Claude Code reenvía todo el contexto (system prompt, tu CLAUDE.md, todos los mensajes previos) y añade lo nuevo al final. La API cachea por prefijo: compara el principio de tu petición con lo que ya procesó. El match es exacto, así que un cambio en cualquier punto del prefijo recomputa todo lo que viene detrás. No hay caché por archivo ni por fragmento.

Para aprovecharlo, Claude Code ordena la petición de lo más estable a lo más cambiante:

Un cambio en la conversación deja intactas las dos capas de arriba. Un cambio en el system prompt invalida todo. Y hay dos cosas que ni siquiera son texto pero también forman parte de la clave de caché: el modelo y el effort level. Cambiar cualquiera de los dos arranca una caché nueva desde cero.

Cómo se ve

# Caché sana (lo normal)
cache_read_input_tokens:      48.231   ← se reutiliza, ~10% del precio de input
cache_creation_input_tokens:     412   ← solo lo nuevo de este turno

# El turno después de cambiar de modelo a mitad de sesión
cache_read_input_tokens:           0   ← cero aciertos
cache_creation_input_tokens:  48.643   ← reprocesa TODO a precio completo

Una lectura cacheada cuesta ~10% del precio de input (según la doc oficial). Un fallo de caché paga el precio completo: por eso ese turno va lento y consume del orden de 10× más en input.

Ese 10% dejó de ser universal el 1 de septiembre de 2026: en Fable 5.1 y Mythos 5.1 la lectura cacheada cuesta el 2,5% del input, la cuarta parte. En el resto de modelos de Claude sigue siendo el 10%. Lo que no cambia en ninguno es el fallo de caché, que se paga entero.

Las tres categorías que tienes que distinguir

1. Lo que rompe la caché (evítalo a mitad de tarea)

• Cambiar de modelo con /model (y el toggle de plan mode con opusplan, que es un cambio de modelo encubierto).
• Cambiar el effort con /effort. Claude Code te pide confirmación precisamente porque sabe que penaliza, pero solo mientras la caché sigue caliente: si ya ha expirado no hay nada que perder, así que cambia sin preguntarte. Lo mismo vale para /model.
• Activar fast mode.
• Denegar una herramienta entera (Bash o WebFetch a secas; las reglas con ámbito como Bash(rm *) y todas las de allow/ask no rompen nada).
• Actualizar Claude Code y retomar una sesión larga: el primer turno reprocesa toda la historia, suele ser la petición que más consume de toda la sesión.

2. Lo que resetea la caché por diseño, pero apenas penaliza (no lo temas)

• /compact: invalida solo la capa de conversación. El resumen se genera leyendo la caché y el turno siguiente reconstruye una historia mucho más corta, así que no es la parte lenta. Ojo, eso vale mientras la caché siga viva: si compactas después de una pausa larga esa misma petición reprocesa el historial entero a precio completo, y por eso conviene compactar antes de levantarte de la mesa y no al volver. En consumo apenas penaliza, pero no todas tus instrucciones vuelven igual: qué sobrevive a /compact.
• /clear: empiezas de cero a propósito.
• /rewind: trunca a un prefijo que ya estaba cacheado, así que abandonas un camino sin reconstruir la caché, a diferencia de /compact, que construye una nueva.

3. Lo que es seguro siempre

• Editar archivos, invocar skills y comandos, /recap, cambiar de modo de permisos, lanzar subagentes.
• Delegar con /fork: el fork hereda tu prefijo, así que su primera petición reusa tu caché en vez de pagarla de cero (más barato que un subagente normal).
• Cambiar de carpeta con /cd: mueve la sesión pero añade el CLAUDE.md de la nueva carpeta como mensaje en vez de reescribir el system prompt, así que el prefijo aguanta.
• Editar CLAUDE.md o el output style a mitad de sesión no rompe la caché, pero tampoco se aplica: Claude sigue con la versión que cargó al arrancar hasta el próximo /clear o reinicio.

Si vas a cambiar de modelo de todas formas, el orden importa: compacta antes y no después, para que el reproceso obligatorio caiga sobre un historial ya corto. Ese movimiento, y cuándo merece la pena bajar de un modelo a otro, en Sonnet 5, Opus 5 y Fable 5.

Sobre MCP y plugins: por defecto, en Opus y Sonnet, las tools de MCP van diferidas con Tool Search y conectar o desconectar un servidor no toca la caché. Solo la rompe cuando las tools se cargan en el prefijo (Haiku, Vertex, un gateway propio, o alwaysLoad). En el caso normal, tranquilo.

Comprueba si tu caché está sana

Los dos números viven en el objeto current_usage que la API devuelve en cada respuesta, y lo más cómodo es leerlos desde un script de statusline:

• cache_read_input_tokens: tokens servidos desde caché (a ~10% del input).
• cache_creation_input_tokens: tokens escritos a la caché este turno.

Mucha lectura y poca creación significa que la caché trabaja a tu favor. Si la creación se mantiene alta turno tras turno, algo en tu prefijo está cambiando: repasa la lista de arriba. Para saber qué proporción es normal, medí esos dos contadores en tres sesiones enteras y la lectura salía entre 16 y 61 veces la creación.

Estira la caché si trabajas a ratos (TTL)

La caché expira tras un rato de inactividad, y cada acierto reinicia el contador. Cuánto aguanta ese rato no es un número único: depende de qué petición sea y de cómo pagues.

Dos matices que no aparecen en ninguna pantalla. El primero: en cuanto pasas del uso incluido del plan y entras en usage credits, tu conversación principal baja sola a cinco minutos, porque a partir de ahí la facturan. El segundo: la petición que genera un resumen vive en la fila de abajo, así que hereda cinco minutos aunque tú tengas una hora.

Si quieres fijar la TTL tú, hay un mando por fila. promptCacheTtl (o la variable CLAUDE_CODE_PROMPT_CACHE_TTL) manda sobre la conversación principal, y subagentPromptCacheTtl (o CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL) sobre el resto. Ambos aceptan 5m o 1h y nada más. Por encima de todos, FORCE_PROMPT_CACHING_5M=1 fuerza cinco minutos en las dos filas, que es lo que quieres si estás depurando. Y ENABLE_PROMPT_CACHING_1H=1 sigue siendo el atajo para pedir la hora en ambas.

Esto es la otra cara de 10 hábitos para ahorrar tokens: ahí reduces el tamaño del contexto; aquí evitas pagarlo dos veces. Falta el tercer lado, cuánto de tu consumo es ese contexto reenviado turno tras turno con la caché sana, y eso está medido en por qué Claude Code consume tantos tokens. Y si quieres ver el gasto real, /usage y /stats te lo cuentan. Y para entender qué te corta de verdad, cómo funcionan tus límites de uso.

Documentación oficial: How Claude Code uses prompt caching

Requisitos: mantener la cabecera de fast mode entre toggles necesita Claude Code v2.1.86+. Los ajustes promptCacheTtl y subagentPromptCacheTtl, y sus dos variables de entorno, necesitan v2.1.242+. Las variables ENABLE_PROMPT_CACHING_1H, FORCE_PROMPT_CACHING_5M y DISABLE_PROMPT_CACHING van en el bloque env de los settings.