Dominar el prompt caching, de cache miss al 80 por ciento de aciertos en 10 pasos

Los cache hits son el token más barato que vas a pagar nunca. Una lectura de caché cuesta más o menos el 10 por ciento del precio normal, una escritura de caché un 25 por ciento más. Si tienes una sesión abierta dos horas y la caché no dispara, quemas diez veces más por el mismo system prompt. Ese es el mayor generador de costes oculto en Claude Code. En este playbook repaso cómo subo el caching al 80 por ciento de aciertos en el daily driver, en mis propios scripts y en servidores MCP. Poca teoría, mucho de lo que puedes copiar ahora mismo.

1. Entiende en una frase qué hace el caching

Marcas un punto de tu prompt con cache_control. Anthropic guarda todo lo que hay hasta ese punto (tools, system, messages, en ese orden) durante 5 minutos. En la siguiente petición con el mismo prefijo recibes ese trozo como lectura de caché en vez de procesarlo de nuevo. Eso es todo.

Lo que mucha gente pasa por alto: el cache breakpoint caduca a los 5 minutos, pero se prolonga con cada acierto. Mientras vuelvas a disparar dentro de esos 5 minutos, la caché sigue caliente y sigue sin costar nada. Las pausas largas se pueden cubrir con la caché de 1 hora, sobre eso hablo enseguida.

2. Mide la caché, si no optimizas a ciegas

Cada respuesta de la API de Anthropic devuelve cuatro contadores de tokens. input_tokens es todo lo que se ha procesado de nuevo. cache_creation_input_tokens es lo que esta vez se ha escrito en la caché. cache_read_input_tokens es lo que se ha sacado de la caché. output_tokens es la respuesta.

En Claude Code, /usage lo muestra agregado por sesión. Lo que tienes que vigilar es la relación entre cache_read e input_tokens. Si está por encima de 4 a 1, vas bien. Si input_tokens está cada vez en los miles y cache_read se queda diminuto, tienes un cache buster en alguna parte, normalmente una fecha dinámica o una variable contador que se ha colado en el system prompt.

Para tus propios scripts, registra esos cuatro números por petición. Con una tabla pequeña en Postgres o un archivo JSONL basta. Sin esa medición optimizas sobre suposiciones.

3. Empieza con automatic caching, no con explicit breakpoints

Anthropic lo recomienda al principio de la documentación y yo también. Pon cache_control una sola vez en el último bloque cacheable (es decir, antes del mensaje de usuario que cambia cada vez). Ejemplo en Python,

response = client.messages.create(
    model="claude-sonnet-4-5",
    system=[
        {
            "type": "text",
            "text": SYSTEM_PROMPT,
            "cache_control": {"type": "ephemeral"}
        }
    ],
    messages=[{"role": "user", "content": user_message}]
)

Eso cubre el 80 por ciento de los casos. Solo cuando tengas capas claras que cambian con frecuencias distintas (tools rara vez, system a medias, conversación a menudo) pasas a explicit breakpoints.

4. Aplica el truco del prefijo estable, todo lo estable al principio

La caché solo funciona si el prefijo es idéntico byte a byte. Un solo carácter cambiado al principio invalida todo lo que va detrás. Así que ordena tu prompt de esta manera,

1. Primero los tools, que casi nunca cambian
2. Después el gran system prompt estático
3. Después el contexto específico del proyecto (CLAUDE.md, archivos cargados)
4. Y solo entonces, al final, el mensaje de usuario que cambia

Error clásico, un timestamp o un session ID en el system prompt. Eso mata cualquier caché. Si necesitas algo así, mételo al final en el mensaje de usuario, no en el bloque system.

5. Usa los cuatro breakpoints con cabeza, no todos a la vez

Tienes hasta cuatro marcas cache_control por petición. El reparto que tiene sentido,

• Breakpoint 1 después de los tools
• Breakpoint 2 después del system prompt estático
• Breakpoint 3 después del contexto de proyecto cargado
• Breakpoint 4 después de los últimos turnos de conversación (rolling)

Cada breakpoint cuesta una vez la prima de escritura en caché (un 25 por ciento extra). Si solo tienes una capa que sea realmente estable, no necesitas cuatro marcas. Regla práctica, mejor un buen breakpoint que cuatro a medias.

6. CLAUDE.md es tu mayor candidato a caché

Claude Code carga CLAUDE.md en el contexto al principio de cada sesión. Si ahí tienes instrucciones constantes (estilo de código, reglas de test, comandos prohibidos), eso se envía con cada una de las peticiones. Un acierto de caché reduce el coste de forma drástica.

Lo que tienes que evitar son los datos dinámicos en CLAUDE.md. Nada de Today is 2026-05-26, ningún contador de estado, ningún "la última sesión fue ...". Eso se resuelve con elegancia mediante un sub-skill: trae la fecha dinámica como salida de un slash command o de una tool, no la escribas de forma estática en el archivo.

7. Mantén finas las definiciones de tools, están en el prefijo de la caché

Las definiciones de tools MCP acaban en tools y con eso al principio del todo. Un servidor MCP con 80 tools mete 15.000 tokens en cada petición, para volver a cachearlos cada vez. Eso está bien mientras necesites esos tools de forma permanente.

Pero si los necesitas poco, desactiva el servidor en .mcp.json y enciéndelo solo cuando toque. O usa el patrón pickMcp si estás construyendo tu propio agente, así cada agente recibe solo los tools que de verdad necesita. El playbook tool-sprawl-vermeiden entra más a fondo en eso.

8. La caché de 1 hora para pausas largas, pero de forma consciente

Además del valor por defecto de 5 minutos, Anthropic ofrece una caché de 1 hora. Se activa con,

{"type": "ephemeral", "ttl": "1h"}

Cuesta más al escribir y merece la pena cuando tienes sesiones en las que te ausentas un rato (reunión, comida). Mi patrón, la caché de 1h solo para la capa realmente estable (tools más el system prompt global). El valor por defecto de 5 minutos para todo lo demás. Si sé que vuelvo al portátil en 90 minutos, me ahorro reconstruir todo el system prompt.

Si arrancas cada sesión de cero y siempre estás en el flow, deja fuera la caché de 1h. La prima del 25 por ciento sobre la escritura no sale a cuenta cuando la caché se mantiene caliente de todos modos.

9. Usa las cache diagnostics cuando el acierto no llega

Anthropic tiene las cache diagnostics en beta. Envías dos peticiones seguidas y la API te dice en qué punto ha divergido el prefijo. Vale oro cuando no entiendes por qué la caché no dispara.

Se activa con la cabecera beta anthropic-beta: prompt-caching-diagnostics-2025-XX-XX (el número de versión exacto míralo en la documentación actual, va cambiando). En la respuesta recibes entonces un campo adicional con el punto de divergencia.

Si las diagnostics muestran que la divergencia está ya en el token 50, es muy probable que tengas una cabecera dinámica o un timestamp en el prefijo. Si diverge recién en el token 8000, ahí vive probablemente la salida de tu última tool.

10. Mi patrón de daily driver, una rutina concreta

Así es mi sesión de Claude Code, optimizada en cuanto a caching.

Al arrancar pulso /usage para ver dónde estoy. CLAUDE.md es estático (sin fecha, sin contadores). Mi configuración MCP tiene exactamente los cinco servidores que necesito en esta sesión, el resto está desactivado.

Corre la primera petición, cache_creation_input_tokens está alto (unos 20.000), cache_read es cero. Normal, la primera petición escribe la caché. Segunda petición, cache_read salta a 20.000 y input_tokens son solo los pocos cientos del nuevo input de usuario. Ese es el punto en el que sé que todo va bien.

Tras 90 minutos de pausa llega mi reinicio de caché. En vez de procesar otra vez 20.000 tokens uso /resume y un breakpoint de 1h sobre la capa de tools. La caché se mantiene caliente y volver a entrar cuesta más o menos la mitad.

Cambio de tema, pulso /clear y me voy a una sesión nueva. La caché se descarta, pero eso ahorra en la hora siguiente más de lo que cuesta la reconstrucción puntual. Una caché sucia con contexto irrelevante es más cara que una limpia.

Qué viene después

Cuando el caching está resuelto, las siguientes palancas están en claude-code-cost-controls-für-daily-driver (enrutado de modelos, /compact, límites de gasto) y en context-window-managen-claude-code. Quien construya sus propios scripts debería volcar el patrón de logging de caché en una tabla de Postgres y evaluar al cabo de dos semanas qué prefijos dan aciertos de verdad. Ahí suele estar el último 20 por ciento de optimización.

Source

• platform.claude.com/docs/en/build-with-claude/prompt-caching (oficial, consultado 2026-05-26)
• platform.claude.com/docs/de/build-with-claude/prompt-caching (espejo en alemán, consultado 2026-05-26)
• code.claude.com/docs/en/costs (oficial, para la mecánica de /usage, consultado 2026-04-27)