El Diseño de Cache que Reduce los Costos de la API de Claude Code en un 90%

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

El momento fue casi cómico. Esa misma noche, Thariq (quien construyó Claude Code en Anthropic) y Lance Martin de Anthropic publicaron posts sobre el diseño del prompt caching. Al leer sus explicaciones, me di cuenta de que mi cache había sido frágil por diseño, no por accidente.

Acá comparto lo que extraje de ambos posts, filtrado por el dolor de producción que acababa de vivir.

El prefijo importa: el orden lo es todo

El prompt caching en la API de Anthropic funciona comparando desde el inicio de la solicitud, token por token. En el momento en que un solo carácter difiere de la versión cacheada, todo lo que viene después se convierte en un cache miss. Sin coincidencias parciales. Sin saltar hacia adelante.

El equipo de Claude Code trata el orden de los prompts como infraestructura. El system prompt estático va primero. Luego CLAUDE.md. Después el contexto de la sesión. Los mensajes de la conversación van al final, porque cambian en cada turno. Este orden asegura que el prefijo costoso y estable se cachee y se reutilice en cada solicitud dentro de una sesión.

Los tokens cacheados cuestan el 10% de los tokens de entrada regulares. Esa diferencia explica por qué un cache roto se siente como un aumento de precio de 10x.

Mi error fue incrustar un timestamp en el system prompt. Cada solicitud generaba un nuevo timestamp, lo que significaba que los primeros tokens diferían en cada llamada. Nada de lo que venía después podía cachearse. Un log de debug en el lugar equivocado, y terminé pagando el precio completo por más de 100K tokens por solicitud.

El equipo de Claude Code también reportó que el orden no determinístico de las definiciones de herramientas provoca cache misses. Si las herramientas se serializan en un orden diferente entre solicitudes, el cache se rompe en ese punto aunque las herramientas en sí no hayan cambiado.

Envíen actualizaciones por 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 hagan. Cada edición al system prompt invalida todo el prefijo cacheado.

Claude Code maneja esto dejando el system prompt intacto después de la primera solicitud. El contexto que cambió se incluye en el siguiente mensaje del usuario, dentro de una etiqueta system-reminder. El modelo lo lee de la misma manera, pero el prefijo del cache se mantiene intacto.

Plan Mode es un buen ejemplo. Cambiar a Plan Mode podría implicar reemplazar definiciones de herramientas, lo que rompería el cache. En cambio, Claude Code lo implementa como una llamada a herramienta (EnterPlanMode) que el modelo puede invocar por sí mismo. El conjunto de herramientas nunca cambia. Cuando el modelo detecta un problema complejo, puede entrar a Plan Mode por su cuenta sin ninguna modificación al system prompt.

La misma lógica aplica al cambio de modelos. 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.

Oculten herramientas en lugar de eliminarlas

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

La solución del equipo de Claude Code: defer_loading. En lugar de incluir los esquemas completos de las herramientas, insertan stubs livianos que contienen solo el nombre de la herramienta y una bandera defer_loading: true. Los stubs siempre aparecen en el mismo orden, manteniendo el prefijo del cache idéntico. Cuando el modelo realmente necesita el esquema completo de una herramienta, llama a una herramienta ToolSearch para cargarlo bajo demanda.

Este patrón ya está disponible en la API de Anthropic. Pueden implementar el mismo enfoque de stub-and-search en sus propios agentes.

peakji de Manus calificó la tasa de aciertos del cache como la métrica más decisiva para agentes en producción. Después de ayer, estoy de acuerdo.

La compresión de contexto tiene una trampa con el cache

Cuando una conversación llena la ventana de contexto, necesitan comprimir: resumir el historial y continuar en una forma reducida. El enfoque obvio es llamar a la API con un prompt de resumen. Pero si esa llamada de resumen usa un system prompt diferente o definiciones de herramientas distintas, no va a coincidir con el cache existente. Terminan procesando toda la conversación de 100K tokens o más sin ningún beneficio del cache, justo en el momento en que los costos son más altos.

Claude Code resuelve esto reutilizando el system prompt exacto y las definiciones de herramientas de la conversación principal para la llamada de compresión. Solo el mensaje final del usuario cambia a una instrucción de compresión. El prefijo cacheado de la conversación principal sigue coincidiendo, así que solo pagan el precio completo por el nuevo mensaje y el resumen de salida.

Anthropic ha incorporado este patrón en la API como una funcionalidad de compaction. También lanzaron auto-caching, donde configurar cache_control una vez en el cuerpo de la solicitud gestiona los breakpoints del cache automáticamente.

La tasa de aciertos del cache como métrica operacional

El equipo de Claude Code monitorea la tasa de aciertos del cache de la misma manera en que los equipos de operaciones monitorean el uptime. Cuando el número baja, 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í exactamente cuán costosa es la alternativa.