De los cambios que trajo la versión 2.1.257 de Claude Code, hay cuatro que no aparecerán en ningún titular y que probablemente sean los que más dinero devuelven: cuatro escenarios en los que la caché de prompts se estaba perdiendo sin que nada lo indicara. Merece la pena mirarlos juntos, porque los cuatro son casos de libro del mismo mecanismo, y entender ese mecanismo sirve tanto si usas Claude Code como si construyes contra la API por tu cuenta.
La razón por la que esto importa tanto ahora es aritmética. Con Claude Fable 5.1, una lectura de caché cuesta 0,25 dólares por millón de tokens: un 0,025 del precio base de entrada, cuando en el resto de modelos ronda el 0,1. Cuanto más barato es el acierto, más caro resulta el fallo en términos relativos. Una caché que no acierta ya no es una optimización desaprovechada: es la diferencia entre pagar una fracción y pagar el precio completo, turno tras turno.
Un prefijo, y cualquier byte lo rompe
Todo el comportamiento de la caché se deduce de una sola regla: es una coincidencia de prefijo, y un cambio en cualquier punto del prefijo invalida todo lo que viene después. La clave de caché sale de los bytes exactos del prompt renderizado hasta cada punto de corte. Un byte distinto en la posición N tira la caché de todos los puntos de corte a partir de N.
Y el orden de renderizado es siempre el mismo: primero tools, después system, después messages. Ese orden explica por qué unos cambios son catastróficos y otros inocuos. Tocar la lista de herramientas afecta a la posición cero, así que invalida absolutamente todo. Editar el system invalida toda la conversación que venga detrás. Añadir un mensaje al final no invalida nada de lo anterior.
Un fallo de caché no lanza ningún error. La petición funciona, la respuesta llega y lo único que cambia es la factura.
Los cuatro fallos, y qué regla rompía cada uno
Leídos con esa regla en la mano, los cuatro arreglos de la 2.1.257 se explican solos:
- Remote Control conectándose a mitad de sesión reenviaba la definición de la herramienta Bash. Las herramientas se renderizan en la posición cero: cambiar una a mitad de conversación invalida el prefijo entero. Un fallo de caché completo por conectarse desde otro sitio.
- Las sesiones con un modelo advisor configurado perdían la caché en todas las peticiones de fondo —compactación,
/recap, sugerencias de prompt— y reenviaban la conversación entera sin cachear cada vez. Es el caso clásico de la operación derivada: si el proceso que se bifurca no reconstruye exactamente el mismosystem, las mismastoolsy el mismo modelo, no acierta el prefijo del padre. Además las cachés son por modelo, así que una petición auxiliar contra otro modelo nunca reutiliza nada. - Las sesiones largas con muchas capturas fallaban la caché en cada turno una vez las imágenes superaban el tope de tamaño por petición. Aquí lo que cambiaba era el contenido del propio prefijo, y con él la clave.
/forkrompía la caché de la conversación original porque el briefing del worktree entraba como cambio en el prompt de sistema. Ahora llega como mensaje. Es exactamente la misma solución que recomienda la documentación para las instrucciones que aparecen a mitad de conversación: no toques elsystem, que está delante de todo; añade el contenido detrás del historial ya cacheado.
Ese último punto tiene una versión que puedes aplicar hoy en tu propio código. En los modelos que lo admiten, una instrucción de operador a mitad de conversación se envía como un mensaje con role: "system" dentro de messages, no editando el system de primer nivel. El efecto en la caché es enorme —el prefijo queda intacto— y además es el canal no falsificable, frente a colar la instrucción como texto dentro de un turno de usuario.
Cuándo compensa cachear y cuándo es un recargo
Cachear no es gratis: la escritura cuesta 1,25 veces el precio base con el TTL de 5 minutos y el doble con el de 1 hora. De ahí salen los umbrales. Con 5 minutos, dos peticiones ya salen a cuenta. Con una hora, hacen falta al menos tres. Y si el prompt cambia desde el principio en cada petición, sencillamente no hay prefijo reutilizable: poner un punto de corte solo paga la prima de escritura sin llegar a leer nunca.
Sobre el TTL, la regla es más simple de lo que parece y depende de una sola cosa: el hueco entre el inicio de dos peticiones que comparten prefijo. Por debajo de cinco minutos, el TTL corto se refresca solo en cada lectura y es estrictamente más barato. Entre cinco y sesenta minutos es la única ventana donde la escritura al doble de precio se amortiza. Por encima de la hora, ninguno de los dos ayuda.
💡 En Fable 5.1, el keep-alive gana al TTL de una hora
Como la lectura es tan barata en este modelo, para huecos de entre cinco y sesenta minutos suele salir más a cuenta quedarse en el TTL corto y, mientras hay pausa, reenviar la petición anterior con max_tokens: 0 justo antes de que la entrada caduque. Esa petición refresca el temporizador y solo factura una lectura de caché barata, sin tokens de salida. Sale mejor que pagar la escritura al doble, salvo que tus pausas se acerquen habitualmente a la hora.
Dos detalles más que cuestan dinero cuando se ignoran. El mínimo cacheable depende del modelo y no es progresivo: son 512 tokens en Fable 5.1 y en Opus 5, pero 4.096 en Opus 4.6 o Haiku 4.5. Un prompt de 3.000 tokens cachea en unos y silenciosamente no cachea en otros, sin error alguno. Y hay un máximo de cuatro puntos de corte por petición.
Cómo comprobar que tu caché sigue viva
Aquí está la parte accionable, y es la que casi nadie hace. La respuesta de la API trae en usage tres campos que son la única fuente de verdad: cache_creation_input_tokens (lo que has escrito en caché, pagando la prima), cache_read_input_tokens (lo servido desde caché) e input_tokens, que —esto sorprende a mucha gente— es solo el resto no cacheado, no el total. El tamaño real del prompt es la suma de los tres.
Si cache_read_input_tokens es cero entre peticiones repetidas con el mismo prefijo, hay un invalidador silencioso. Los sospechosos habituales son siempre los mismos: una fecha o una hora interpolada en el prompt de sistema, un identificador por petición, una serialización de JSON que no ordena las claves de forma determinista, o una lista de herramientas que cambia de orden.
Y una advertencia que la documentación subraya y que encaja con lo que le pasó a Claude Code: el fallo de caché más caro en producción es una regresión, no una mala implementación inicial. Lo típico es que el caching funcione el día que se escribe y que meses después un cambio en el ensamblado del prompt lo rompa sin que nadie se entere, porque nada falla. Por eso la recomendación no es mirarlo una vez al montarlo, sino dejar una comprobación permanente: un test que afirme que una segunda petición idéntica devuelve cache_read_input_tokens mayor que cero.
Lo que esto significa para tus automatizaciones
Si tienes flujos que llaman a Claude desde n8n o desde cualquier orquestador, la lectura práctica es directa. Todo lo estable —las instrucciones, los ejemplos, el contexto del proyecto— va delante y sin variar un byte entre ejecuciones. Todo lo volátil —la fecha, el identificador de la ejecución, la pregunta concreta— va al final, detrás del último punto de corte. Y si tu nodo mete la fecha de hoy en la cabecera del prompt de sistema porque parecía lo natural, ahí tienes, con casi total seguridad, tu caché al cero por ciento.
La conclusión general vale más allá de la caché: los fallos que no producen errores son los que más duran. Claude Code tenía cuatro y han hecho falta meses y un release de más de cien entradas para cerrarlos. En tu propio código no hay nadie publicando ese changelog, así que la comprobación tendrás que dejarla puesta tú.
