📈 El prefijo estable crece
En una conversación, system + tools + todo el historial — incluida la última respuesta del modelo — forman un prefijo estable que crece en cada turno. Solo tu próximo mensaje es realmente nuevo; todo lo anterior es idéntico a lo que ya se procesó.
Qué es
El prefijo estable es la parte del prompt que no cambia entre un turno y el siguiente: herramientas, prompt del sistema e historial acumulado. Es la «materia prima» de la caché: cuanto más grande, más tokens salen baratos.
Por qué aprenderlo
Porque eso es lo que abarata la conversación: cada respuesta que da Claude Code pasa a formar parte del prefijo estable del siguiente turno, así que el "peso" de la conversación se desplaza al lado del caché (~0,1×) en vez de cobrarse al precio completo (1×).
Conceptos clave
Prefijo = inicio idéntico que se repite turno a turno.
Solo escapa el final — tu nuevo mensaje es la única parte que no está en caché.
Orden de ensamblaje: tools → system → messages.
Crece — la respuesta del modelo se agrega al historial y hace crecer el prefijo.
La caja azul (prefijo, leído del caché) crece; la franja delgada en la parte superior (tu mensaje nuevo, escrito) se vuelve proporcionalmente más pequeña en cada turno.
🔁 Hit por turno
Con cada mensaje nuevo, solo cambia el final. La API vuelve a leer todo el prefijo del caché (lectura ≈ 0,1×) y guarda solo el bloque nuevo de ese turno. Es lo que se llama hit: el prefijo coincidió y se sirvió desde el caché.
Qué es
Hit ocurre cuando el prefijo del request coincide con una entrada ya procesada y se vuelve a leer por ~10% del precio. Cada turno de la conversación es, en la práctica, un hit grande sobre el prefijo + un write pequeño de la parte nueva.
Por qué aprenderlo
Porque explica por qué el 2.º turno en adelante cuesta mucho menos que el 1.º: la mayor parte del prompt ya está en el caché y solo se vuelve a procesar la diferencia. Es la mecánica que hace que una sesión larga no cueste una fortuna.
✓ Qué cuenta como hit
- ✓Prefijo idéntico byte por byte al request anterior.
- ✓Dentro de la ventana de TTL (el caché sigue caliente).
- ✓Solo se guarda el mensaje nuevo al final.
✗ Qué se convierte en miss
- ✗Cualquier byte diferente en medio del prefijo.
- ✗El TTL venció (terminó el tiempo de vida).
- ✗Cambiaste el modelo (el cache es por modelo).
Conceptos clave
Hit = leyó del caché (~0,1×).
Write = escribió el bloque nuevo del turno (~1,25×).
Miss = no lo encontró, procesó todo (1×).
Por turno = 1 acierto grande + 1 write pequeño.
⏱️ TTL de 5 min renovado con el uso
TTL es el tiempo de vida de la entrada en la caché. El valor predeterminado es 5 minutos, pero con un detalle importante: es renovado en cada uso.
Es decir: mientras respondas dentro de la ventana de ~5 min, el reloj se reinicia y la caché permanece caliente indefinidamente. Una conversación activa mantiene el prefijo a bajo costo sin que tengas que hacer nada especial.
Qué es
TTL (time-to-live) es el período de validez de la entrada. Cada lectura/escritura reinicia ese reloj, así que una secuencia continua de mensajes nunca deja que el caché se enfríe.
Por qué aprenderlo
Porque trabajar a un ritmo continuo literalmente cuesta menos y porque explica el costo de retomar después de una pausa larga (siguiente tema y tema 6).
Consejo práctico
También existe un TTL de 1 hora (escritura más cara, ~2×) para tráfico con pausas largas. Solo sirve cuando hay gaps > 5 min entre requests; si no, el TTL de 5 min es suficiente y cuesta menos.
Conceptos clave
TTL predeterminado = 5 min.
Se renueva con el uso — cada turno reinicia el reloj.
Conversación activa = caché siempre caliente.
TTL 1h = write ~2×, para tráfico con pausas.
📊 El % de caché SUBE en cada turno
Este es el punto que más confusión genera. El caché no es una batería que se descarga. Un turno puede marcar solo 40% de la caché — porque hubo muchas cosas nuevas (p. ej., se cargó una skill grande). Pero ese bloque nuevo se convierte en lectura barata en el próximo turno, y el porcentaje sube.
Qué es
El «% de caché» de un turno es cuánto del prompt vino del caché (read) frente a cuánto fue nuevo (write + sin caché). Como lo nuevo de hoy será lo almacenado en caché mañana, la fracción leída del caché tiende a crecer turno a turno.
Por qué aprenderlo
Porque deshace la intuición equivocada de que "el caché se acaba". Ver un 40% en un turno no es un problema: solo indica que entró algo grande, que será barato de aquí en adelante.
El nuevo bloque del turno del 40% (la skill) es exactamente lo que hace que el siguiente turno llegue a ~99%: se convirtió en una lectura barata.
Conceptos clave
| Turno | Leído de la caché | Nuevo | % de caché |
|---|---|---|---|
| ahora (skill grande) | 40k | 60k | 40% |
| siguiente (mensaje corto) | ~100k | ~1k | ~99% |
✍️ Primer mensaje = write
El primer mensaje de una conversación no hay nada que leer todavía — no existe un prefijo anterior. Entonces ella guarda el caché y paga un poco más (write ≈ 1,25× con TTL de 5 min). Es el único turno que escribe el prefijo completo.
Qué es
El write inicial es la «inversión» que paga los turnos siguientes. Grabas una vez para leer muchas veces a bajo costo.
Por qué aprenderlo
Porque evita el susto de ver el 1.º turno "caro". No es un bug ni un desperdicio: es la escritura que permite ahorrar en el resto de la sesión.
1.er turno — write
Registra tools + system + el 1.er mensaje. Pagas ~1,25× por lo que registraste. Todavía no hay nada que leer.
A partir del 2.º turno — read + pequeño write
Lee el prefijo a ~0,1× y escribe solo el mensaje nuevo. Aquí se nota el ahorro.
Conceptos clave
1.ª msg solo escribe — no lee.
Write ~1,25× (TTL 5 min).
Inversión que abarata el resto.
A partir del 2.º predomina read ~0,1×.
🧊 Una pausa larga = write en frío
Si superas los ~5 min inactivo, el TTL vence y la entrada desaparece del caché. El siguiente mensaje paga la volver a guardar — é o write frío. No es un fallo; solo significa que el caché se enfrió.
Qué es
Write en frío es la nueva escritura del prefijo después de que vence el TTL. Desde el punto de vista del costo, es como reiniciar la conversación: vuelves a pagar la escritura inicial.
Por qué aprenderlo
Porque explica por qué "retomar después del almuerzo" cuesta: fue una escritura fría, no un problema. Y señala la solución: el TTL de 1 h para flujos con pausas previsibles.
Atención
No confundas una escritura en frío con un invalidator silencioso. La escritura en frío ocurre por tiempo (TTL expiró). El silent invalidator (Ruta 2, módulo 2.3) ocurre por bytes que cambian en el prefijo, incluso con el caché caliente.
Conceptos clave
Pausa > TTL = la entrada vence.
Write en frío = vuelve a escribir el prefijo.
Fix para gaps = TTL de 1 h (write ~2×).
No es un bug — es la caché enfriándose.
Ejemplo copy-run — auditar cuánto vino del caché
Objetivo: confirmar, en una respuesta real de la API, cuánto del prompt vino de la caché — para ver con tus propios ojos cómo las lecturas baratas dominan los turnos.
Numa resposta recente da API que você tem acesso (ou num
log de <caminho do meu log de requests>), leia o objeto
`usage` e me mostre os três campos:
- cache_read_input_tokens (lido do cache, ~0,1x)
- cache_creation_input_tokens (gravado, ~1,25x)
- input_tokens (só o resto não-cacheado, 1x)
Depois calcule e me explique:
1. a SOMA dos três (= tamanho total do prompt);
2. qual % veio do cache (read / soma);
3. se este parece um 1º turno (write alto) ou um turno
posterior (read dominante).Cómo verificar: a suma de los tres campos debe coincidir con el tamaño total del prompt. En turnos posteriores de una conversación activa, cache_read_input_tokens debe ser la porción más grande y el % de caché alto (tema 4). En el 1.er turno, la porción de cache_creation_input_tokens predomina (tema 5).
Resumen del módulo
Siguiente módulo:
2.2 — Skills y herramientas: agregar vs. romper