🌱 Fundamentos y términos
Antes de modificar nada, entiende qué es el prompt caching y el vocabulario relacionado. Al terminar, sabrás por qué existe la caché, qué son hit, miss, write y TTL, y por qué una conversación larga puede costar ~10% en vez de 100%. Cada término técnico se define la primera vez que aparece, sin requisitos previos de API.
Ilustración: el comienzo de la conversación (el prefijo) se construye
siempre en el orden tools → system → histórico. Se procesa una vez, se guarda
en el caché y, después, solo releído en cada turno: barato. Toda esta máquina es la que la Ruta 1
desarma pieza por pieza.
Mapa de la ruta
Contenido detallado
🧩 Qué es el prompt caching
Del problema del reprocesamiento a la idea del prefijo: hit, miss, write, el orden
tools → system → messages y el breakpoint. Cada término se define en su primera aparición.
La API de Claude es stateless — no guarda la conversación. Con cada mensaje vuelves a enviar todo: el prompt del sistema, las herramientas y todo el historial.
Es el problema que resuelve la caché. Sin entender el reprocesamiento, lo demás no tiene sentido.
stateless · prompt de sistema · reenviar toda la conversación · costo y latencia que crecen en cada turno.
El comienzo de la conversación es estable y se repite en cada turno. La caché guarda ese comienzo ya procesado y lo reutiliza, en vez de volver a procesarlo.
Es el cambio clave: pagar una vez por lo que no cambia, en vez de pagar en cada turno.
prefijo estable · procesado una vez · reutilización · lo que cambia queda al final.
La clave del caché son los bytes exactos hasta el punto de corte. Un solo byte diferente en medio invalida todo lo que viene después.
Explica todo «¿por qué no se activó mi caché?». Es el invariante que rige toda la ruta.
prefijo · bytes exactos · punto de corte · invalidación desde el byte que cambia.
El prompt se construye en este orden. Un breakpoint al final del system guarda en caché tools + system juntos.
Saber el orden indica qué poner al principio (estable) y qué dejar al final (cambia).
orden de montaje · posición 0 = tools · cosa estable al principio · cosa volátil al final.
Hit = leyó de la caché (barato). Write = registró en la caché (ligera bonificación). Miss = no lo encontró, procesó todo. El 1.er mensaje registra; los siguientes leen.
Es el vocabulario que leerás en los campos de usage y usar para diagnosticar.
hit · miss · write · el 1.er mensaje guarda; los siguientes leen.
La marca que indica «cachea hasta aquí». Máx. 4 por solicitud; prefijo mínimo de ~1024–4096 tokens (varía según el modelo): por debajo de ese límite no se cachea y no se produce ningún error.
En Claude Code es automático, pero entender el concepto explica por qué los fragmentos cortos no se almacenan en caché.
cache_control · máx. 4 breakpoints · mínimo cacheable · automático en Claude Code.
💸 Términos y ahorro
Los tres campos de usage, el TTL de 5 min y 1 h, los costos relativos
y el cálculo del punto de equilibrio. El ahorro real, sin misterio.
Tokens servidos desde la caché en este turno. Cuestan ~0,1× del precio de input.
Es el campo que prueba que la caché funcionó. Si se repite cero con el mismo prefijo, hay un problema.
lectura de la caché · ~0,1× · señal de hit.
Tokens guardados en la caché en este turno. Cuestan ~1,25× (TTL 5 min) o ~2× (TTL 1 h).
Es el «premio» que pagas una vez para leer a bajo costo después. Si lo ves alto todo el tiempo, es señal de que la caché nunca lee.
guardado · ~1,25× / ~2× · se paga una vez por cada bloque nuevo.
Solo la parte NO almacenada en caché, a precio completo (1×). El total del prompt = suma de los tres campos.
Trampa: si el agente estuvo funcionando durante horas y input_tokens muestra poco, el resto vino de la caché: mira la SUMA de los tres.
parte sin caché · 1× · total = suma de los tres.
TTL = tiempo de vida de la entrada en caché. Valor predeterminado: 5 min, renovado con cada uso. Hay una opción de 1 h (write ~2×) para tráfico con pausas largas.
Explica por qué una conversación activa se mantiene «caliente» y una pausa larga hace que tengas que pagar otra escritura.
TTL · 5 min renovable · 1 h más caro · la conversación activa mantiene la caché caliente.
leer ~0,1× · escribir 5 min ~1,25× · escribir 1 h ~2× · sin caché 1×. En una conversación larga, la mayor parte de la entrada sale a ~10%.
Son los cuatro números que explican cualquier cálculo de ahorro del curso.
tabla de costos · read barato · write con recargo · lleno como referencia.
Con TTL de 5 min, 2 solicitudes ya amortizan la escritura (1,25× + 0,1× = 1,35× frente a 2× sin caché). Con 1 h, se necesitan ~3.
Enseña a NO cachear un prefijo que cambia en cada request (solo pagas el write, nunca lo lees).
punto de equilibrio · 2 reqs (5 min) / ~3 (1 h) · no almacenes en caché lo que cambia siempre.