El diseño de cache que reduce un 90% los costes de la API de Claude Code

Ayer tenía trabajo urgente en producción. A mitad de sesión, el prompt cache se rompió. La factura de la API de esa única hora fue más alta que la de los tres días anteriores juntos.

El momento no podía ser más irónico. Esa misma tarde, Thariq (quien construyó Claude Code en Anthropic) y Lance Martin, también de Anthropic, publicaron sendos artículos sobre el diseño del prompt caching. Al leer sus explicaciones, comprendí que mi cache había sido frágil por diseño, no por casualidad.

Esto es lo que extraje de ambos artículos, filtrado por el dolor de producción que acababa de vivir.

El orden lo es todo cuando se trabaja con prefijos

El prompt caching en la API de Anthropic funciona haciendo coincidir el inicio de la petición token a token. En el momento en que un solo carácter difiere de la versión en cache, todo lo que viene después se convierte en un cache miss. Sin coincidencias parciales, sin saltos.

El equipo de Claude Code trata el orden del prompt como si fuera infraestructura. El system prompt estático va primero. Después, CLAUDE.md. Luego el contexto de sesión. Los mensajes de conversación van al final, porque cambian en cada turno. Este ordenamiento garantiza que el prefijo estable y costoso se guarde en cache y se reutilice en cada petición de la sesión.

Los tokens en cache cuestan el 10% de los tokens de entrada normales. Esa diferencia explica por qué un cache roto se siente como una subida de precio del 1000%.

Mi error fue incrustar una marca de tiempo en el system prompt. Cada petición generaba una nueva marca de tiempo, lo que significaba que los primeros tokens eran distintos cada vez. Nada de lo que venía después podía guardarse en cache. Un simple log de depuración en el sitio equivocado y estaba pagando el precio completo por más de 100.000 tokens por petición.

El equipo de Claude Code también informó de que el orden no determinista en las definiciones de herramientas provoca cache misses. Si tus herramientas se serializan en un orden diferente entre peticiones, el cache se rompe en ese punto aunque las propias herramientas no hayan cambiado.

Propaga los cambios a través de mensajes, no editando el system prompt

Cuando el contexto cambia a mitad de sesión (se modifica un archivo, se actualiza la hora, cambia un modo), el instinto es actualizar el system prompt. No lo hagáis. Cualquier edición al system prompt invalida el prefijo completo que había en cache.

Claude Code resuelve esto dejando el system prompt intacto después de la primera petición. El contexto que ha cambiado se incluye en el siguiente mensaje del usuario, envuelto en una etiqueta system-reminder. El modelo lo procesa de la misma manera, pero el prefijo en cache permanece intacto.

Plan Mode es un buen ejemplo. Cambiar a Plan Mode podría suponer intercambiar definiciones de herramientas, lo que rompería el cache. En su lugar, Claude Code lo implementa como una llamada a herramienta (EnterPlanMode) que el propio modelo puede invocar. El conjunto de herramientas nunca cambia. Cuando el modelo detecta un problema difícil, puede entrar en Plan Mode por su cuenta sin modificar el system prompt.

La misma lógica se aplica al cambio de modelo. Cambiar de modelo a mitad de conversación rompe el cache por completo. Claude Code evita esto ejecutando diferentes modelos como subagentes en contextos separados, manteniendo intacto el cache de la conversación principal.

Ocultar herramientas en lugar de eliminarlas

Los servidores MCP pueden cargar decenas de herramientas. Incluirlas todas en cada petición es costoso. Pero eliminar herramientas entre peticiones rompe el cache porque las definiciones de herramientas forman parte del prefijo en cache.

La solución del equipo de Claude Code: defer_loading. En lugar de incluir los esquemas completos de las herramientas, insertan stubs ligeros que contienen únicamente el nombre de la herramienta y un flag defer_loading: true. Los stubs se mantienen siempre en el mismo orden, lo que garantiza que el prefijo del cache sea idéntico. Cuando el modelo realmente necesita el esquema completo de una herramienta, llama a ToolSearch para cargarlo bajo demanda.

Este patrón está disponible hoy en la API de Anthropic. Podéis implementar el mismo enfoque de stubs y búsqueda en vuestros propios agentes.

peakji, de Manus, afirmó que la tasa de aciertos del cache es la métrica más decisiva para los agentes en producción. Después de ayer, estoy completamente de acuerdo.

La compresión de contexto tiene una trampa de cache

Cuando una conversación llena la ventana de contexto, necesitas comprimir: resumir el historial y continuar con una versión reducida. El enfoque obvio es llamar a la API con un prompt de resumen. Pero si esa llamada de resumen usa un system prompt distinto o definiciones de herramientas diferentes, no coincidirá con el cache existente. Acabas procesando una conversación completa de más de 100.000 tokens sin ningún beneficio del cache, justo en el momento en que los costes son más elevados.

Claude Code soluciona esto reutilizando el system prompt y las definiciones de herramientas exactas de la conversación principal para la llamada de compresión. Solo cambia el último mensaje del usuario, que pasa a ser una instrucción de compresión. El prefijo en cache de la conversación principal sigue coincidiendo, así que solo pagas el precio completo por el nuevo mensaje y la salida del resumen.

Anthropic desde entonces ha incorporado este patrón en la API como funcionalidad de compactación. También lanzaron el auto-caching, donde configurar cache_control una vez en el cuerpo de la petición gestiona automáticamente los puntos de ruptura del cache.

La tasa de aciertos del cache como métrica operacional

El equipo de Claude Code monitoriza la tasa de aciertos del cache igual que los equipos de operaciones monitorizan el uptime. Cuando el número cae, lo tratan como un incidente.

Ese enfoque cambió la forma en que pienso sobre el diseño de prompts. Cada edición al system prompt, cada reordenamiento de herramientas, cada cambio de modelo a mitad de sesión es un posible incidente. El token más barato es el que acierta en cache, y ayer aprendí a la fuerza lo caro que puede ser lo contrario.