Guía de caché de código Claude de Anthropic para ahorrar 300 millones de tokens a la semana

Título original: Cómo los ingenieros de Anthropic realmente ahorran tokens
Autor original: Nate Herk
Traducido por: Peggy, BlockBeats

Autor original del artículo: BlockBeats

Fuente original:

Reproducción: Mars Finance

Prólogo del editor: Muchas personas al usar Claude Code sienten que el consumo de tokens es demasiado rápido y que las sesiones largas fácilmente agotan el límite. Pero desde la perspectiva de los ingenieros de Anthropic, lo que realmente afecta el costo no es cuánto código escribes, sino si el sistema puede reutilizar continuamente el contexto ya procesado.

El núcleo de este artículo es cómo ahorrar tokens mediante un mecanismo de caché. El autor ha reutilizado más de 300 millones de tokens en una semana a través de caché, alcanzando un pico de 91 millones en un solo día. Dado que el costo de los tokens en caché es solo el 10% del de los tokens de entrada normales, esto significa que 91 millones de tokens en caché equivalen aproximadamente a cobrar por 9 millones de tokens normales. La razón por la que las sesiones largas con Claude Code parecen más «duraderas» no es porque el modelo funcione gratis, sino porque se reutilizan con éxito muchas repeticiones de contexto.

La clave del prompt caching es «no interrumpir la caché». Claude Code almacena en capas las instrucciones del sistema, definiciones de herramientas, CLAUDE.md, reglas del proyecto y diálogos históricos; mientras la solicitud posterior mantenga el mismo prefijo, Claude puede leer directamente la caché en lugar de volver a procesar todo el contexto. Dentro de Anthropic también monitorean la tasa de reutilización del prompt cache, ya que no solo afecta el límite del usuario, sino que también influye directamente en el costo del servicio del modelo y en la eficiencia operativa.

Para usuarios comunes, no es necesario entender todos los detalles subyacentes, solo dominar algunos hábitos clave: no dejar que la sesión quede inactiva por más de una hora; hacer una transferencia de sesión al cambiar de tarea; evitar cambiar de modelo con frecuencia; y para documentos largos, preferir guardarlos en Projects en lugar de pegarlos repetidamente en la conversación.

Este artículo, más que ofrecer un truco para ahorrar tokens, proporciona una forma de usar Claude Code con una mentalidad más cercana a la ingeniería: gestionar el contexto como un activo, mantener la caché en uso continuo, y reducir cálculos repetidos en sesiones largas.

A continuación, el texto original:

Esta semana ahorré 300 millones de tokens, 91 millones en un solo día, y más de 300 millones en una semana.

No hice ningún cambio en la configuración. Solo fue el funcionamiento normal del prompt caching en segundo plano.

Pero cuando realmente entendí qué es la caché y cómo evitar «interrumpirla», en el mismo límite de uso, mis sesiones duraron mucho más. Por eso, aquí comparto una guía de introducción al prompt caching de Claude Code, enfocada en el 80/20, sin profundizar en detalles de la API.

TL;DR

El costo de los tokens en caché es solo el 10% del de los tokens de entrada normales. 9.1 millones de tokens en caché, el costo real equivale aproximadamente a 900,000 tokens.

La TTL del caché en la suscripción de Claude Code es de 1 hora; en la API por defecto son 5 minutos; en Sub-agent siempre son 5 minutos.

El caché se divide en tres capas: capa del sistema, capa del proyecto y capa de la conversación.

Cambiar de modelo en medio de una sesión rompe la caché, incluyendo activar el modo «opus plan».

¿Cómo se calcula el costo del caché?

Cada token en caché cuesta solo el 10% del de un token de entrada normal.

Por lo tanto, cuando mi panel muestra que en un día se usaron 91 millones de tokens en caché, en realidad solo se cobraron aproximadamente por 9 millones de tokens. Esto explica por qué, en uso prolongado de Claude Code sin caché, la sesión parece extenderse casi «gratis».

Hay dos números en el panel que vale la pena destacar:

Cache create: costo único al escribir contenido en la caché. Comienza a usarse en la siguiente interacción.
Cache read: tokens reutilizados por Claude desde la caché, como tu CLAUDE.md, definiciones de herramientas, mensajes anteriores, etc. Comparado con volver a procesar todo como entrada, cuesta 10 veces menos.

Si tu número de Cache read es alto, significa que estás aprovechando eficazmente la caché; si es bajo, estás pagando varias veces por el mismo contexto.

Thariq de Anthropic dijo una frase que me impresionó mucho: «En realidad, monitoreamos la tasa de aciertos del prompt cache; si esta baja demasiado, activamos alertas e incluso declaramos una emergencia de nivel SEV.»

También escribió un buen artículo en X. Cuando la tasa de aciertos del caché es alta, suceden cuatro cosas simultáneamente: Claude Code se siente más rápido, los costos de servicio de Anthropic bajan, tu límite de suscripción dura más, y las sesiones largas de codificación se vuelven más factibles.

Pero si la tasa de aciertos es baja, todos salen perdiendo.

Por eso, los incentivos de ambas partes son iguales: Anthropic quiere que tu tasa de aciertos sea más alta, y tú también. Lo que realmente puede perjudicarte son pequeños hábitos que parecen inofensivos pero que silenciosamente reinician la caché.

¿Cómo crece la caché en cada ronda de diálogo?

Depende del «prefix matching», es decir, «coincidencia de prefijos».

No necesitas profundizar en detalles técnicos, solo entender esto: mientras el contenido antes de cierta posición sea exactamente igual al contenido en caché, Claude puede reutilizar esa parte de tokens.

Una sesión completamente nueva generalmente funciona así:

Según la documentación de Claude Code, una sesión nueva suele seguir este flujo:

Primera ronda: sin caché. Las instrucciones del sistema, el contexto del proyecto (como CLAUDE.md, memoria, reglas) y tu primer mensaje se procesan y almacenan en caché.

Segunda ronda: todo lo de la primera ronda ya está en caché. Claude solo procesa tu nueva respuesta y el siguiente mensaje. El costo de esta ronda será mucho menor.

Tercera ronda: igual. La conversación previa sigue en caché, solo se procesa la interacción más reciente.

La caché en sí misma tiene tres capas:

De Thariq en su artículo en X:

Capa del sistema (System layer): incluye instrucciones básicas, definiciones de herramientas (read, write, bash, grep, glob) y estilos de salida. Es la caché global.

Capa del proyecto (Project layer): incluye CLAUDE.md, memoria, reglas del proyecto. Se cachea por proyecto.

Capa de la conversación (Conversation): incluye respuestas y mensajes, que crecen con cada ronda.

Si en medio de la sesión cambian el contenido de la capa del sistema o del proyecto, todo debe volver a cachearse desde cero. Esa es la operación más «costosa». Imagina: ya llevas 16 mensajes, y de repente cambias las instrucciones del sistema o pasas una hora sin hablar, entonces todos los tokens desde el primero deben volver a procesarse.

Confusión entre 1 hora y 5 minutos

Este es el error más común.

Claude Code suscripción: TTL por defecto de 1 hora.
API de Claude: TTL por defecto de 5 minutos. Puedes pagar más para subirlo a 1 hora.
Sub-agent en cualquier plan: siempre 5 minutos.

Chat en la web de Claude.ai: no hay una documentación oficial clara. Podría ser igual que la suscripción, pero no lo he confirmado.

Hace unos meses, muchos se quejaron de que el límite de Claude se agotaba muy rápido. Pensaron que Anthropic había bajado silenciosamente el TTL de 1 hora a 5 minutos sin avisar. Pero no fue así; el TTL de Claude Code sigue siendo 1 hora.

El problema es que la documentación de Claude Code y la API están separadas, y en realidad son cosas distintas, lo que genera confusión.

Si usas mucho Sub-agent o la API, ese número de 5 minutos importa mucho. Pero para el 95% de usuarios de Claude Code, lo que importa de verdad es esa ventana de 1 hora.

Tres hábitos para cubrir al 95% de los usuarios

Estas son las prácticas que considero más útiles en el uso diario:

No dejes la sesión inactiva por más de una hora

Si pasaste más de una hora sin interactuar, la mayoría del contenido en caché ya expiró. La próxima respuesta que envíes reconstruirá la caché. En ese caso, en lugar de reactivar una sesión «enfriada», es mejor hacer una transferencia clara y empezar una nueva, generalmente más barato.

Al cambiar de tarea, reinicia directamente

/compact o /clear rompen la caché, así que es mejor usarlos para resetear de verdad.

Yo mismo creé una habilidad de transferencia de sesión, para reemplazar /compact. Resume lo que hemos hecho, las decisiones pendientes, los archivos importantes y dónde continuar. Luego ejecuto /clear y pego ese resumen, y puedo seguir sin interrupciones.

El comando compact a veces es lento. Este método de transferencia suele completarse en menos de un minuto.

En Claude.ai, para documentos largos, mejor guardarlos en Projects

El mecanismo de caché en Claude.ai no está muy documentado oficialmente, pero Projects claramente usa una optimización distinta a los hilos normales. Por eso, si vas a pegar documentos grandes, mejor colócalos en un Project en lugar de en la conversación.

¿Y qué cosas pueden romper la caché sin aviso?

Varias acciones pueden reiniciar toda la caché sin que te des cuenta:

Cambiar de modelo: porque la caché depende del prefijo, y cada modelo tiene su propia caché. Cambiar de modelo hace que la próxima solicitud lea toda la historia desde cero, sin caché.

Modo «Opus plan»: este modo usa Opus en la planificación y Sonnet en la ejecución. Lo recomendé en algunos videos de optimización de tokens, y tiene su razón. Pero hay que entender que cada cambio de plan en realidad es un cambio de modelo, y eso implica reconstruir la caché. A largo plazo, ayuda a extender el límite, pero debes saber qué pasa en el fondo.

Editar CLAUDE.md en medio de la sesión: esto no tiene efecto inmediato, se aplica solo en el próximo reinicio. La caché en curso no se ve afectada.

Mi panel de tokens gratuito

La captura que mostré antes proviene de un panel de tokens.

Es un repositorio simple en GitHub. Le das el enlace a Claude Code, y él lo despliega localmente en localhost, leyendo todos tus registros pasados en lugar de empezar desde cero. Así, puedes ver diariamente inputs, outputs, creación y lectura de caché.

Pero ojo: ese panel solo mide tokens en tu dispositivo local. Si cambias de PC a portátil, los números no serán exactamente iguales. Cada dispositivo tiene su propia vista de estadísticas.

Resumen

Prompt caching es un tema muy profundo. La publicación de Thariq es más completa, si quieres una visión global, vale la pena leerla.

Pero no necesitas entender todos los detalles para beneficiarte. Solo domina el 80/20: los tokens en caché son 10 veces más baratos que los tokens normales; la TTL de Claude Code es 1 hora; cambiar de modelo rompe la caché; hacer transferencias claras entre tareas suele ser más barato que dejar que una sesión vieja «expira» y seguir.