Mejores prácticas para el almacenamiento en caché de prompts

Un conjunto de prácticas numeradas y accionables para obtener valor fiable y continuo del almacenamiento en caché de prompts de Claude, que cubre dónde colocar los puntos de interrupción, cómo elegir un TTL y cómo evitar los fallos silenciosos que borran silenciosamente los ahorros.

Cómo usar esta lista

• Trátalas como valores predeterminados, no como reglas absolutas: desvíate deliberadamente cuando tu carga de trabajo tenga una razón genuina.
• El Grupo A cubre la colocación de puntos de interrupción, el Grupo B cubre las decisiones de TTL y costes, el Grupo C cubre la evitación de fallos silenciosos y el Grupo D cubre la monitorización y verificación.
• Revisa esta lista cada vez que añadas un nuevo campo a un prompt del sistema o a un esquema de herramientas, ya que ese es el punto más común en el que una configuración previamente correcta se degrada.
• Empareja estas prácticas con las páginas explicativas y de cómo hacer más detalladas en "Relacionado" para entender el razonamiento detrás de cada una.

A - Colocación de puntos de interrupción

• Ordena el contenido por estabilidad, no por conveniencia. Coloca el contenido más estable (esquemas de herramientas, documentos de referencia largos, instrucciones del sistema) primero, y el contenido más volátil (la pregunta del usuario en vivo, una marca de tiempo, un ID de sesión) al final, después de cualquier punto de interrupción.
• Recuerda el orden fijo de las solicitudes: herramientas, luego sistema, luego mensajes. La cobertura de un punto de interrupción está determinada por este orden, independientemente de cómo organices los argumentos de palabras clave en tu llamada de Python.
• Usa dos puntos de interrupción cuando las herramientas y el prompt del sistema cambien a diferentes ritmos. Un punto de interrupción en la última definición de herramienta y un segundo en el prompt del sistema permiten que una edición del prompt del sistema evite invalidar un catálogo de herramientas estable, y viceversa.
• Nunca apliques cache_control a un prompt del sistema de cadena simple. cache_control requiere la forma de lista de bloques de contenido de system; una cadena simple no tiene dónde adjuntarlo.
• En bucles de agente multivuelta, mueve el punto de interrupción hacia adelante en cada turno. Colócalo en el último mensaje del historial de conversación en crecimiento y elimínalo de los mensajes anteriores, de modo que la caché siga cubriendo "todo lo establecido hasta ahora".

B - Decisiones de TTL y costes

• Por defecto, usa el TTL de 5 minutos a menos que tengas una razón específica para 1 hora. Tiene un multiplicador de coste de escritura menor y se adapta a la mayoría de las cargas de trabajo interactivas y de ráfaga.
• Usa el TTL de 1 hora para sesiones con brechas reales entre llamadas. Las sesiones de agente de larga duración, la revisión humana en el bucle o los trabajos por lotes infrecuentes distribuidos durante una hora se benefician de no consumir repetidamente el coste de escritura.
• Recuerda que ambos TTL son efímeros y se actualizan en cada acceso. Un flujo constante de solicitudes dentro de la ventana mantiene una entrada activa mucho más allá de su TTL nominal; no necesitas "mantenerla activa" manualmente.
• Evalúa el coste de escritura frente al recuento de lecturas esperado antes de comprometerte con un TTL. Un prefijo reutilizado solo una o dos veces rara vez recupera el coste de escritura de ningún TTL; un prefijo reutilizado docenas de veces casi siempre lo hace.
• Verifica las suposiciones de precios con la documentación actual, no con la memoria. Los multiplicadores de escritura y lectura de la caché cambian independientemente de los lanzamientos de modelos; confirma los números exactos en platform.claude.com/docs antes de presupuestar una carga de trabajo.

C - Evitar fallos silenciosos

• Nunca incrustes una marca de tiempo, UUID o ID de solicitud antes de un punto de interrupción. Estos son los invalidadores silenciosos más comunes: mueve cualquier cosa por solicitud a messages, después del punto de interrupción, en su lugar.
• Serializa el contenido JSON y de diccionario de forma determinista. Pasa siempre sort_keys=True (o un orden de claves fijo equivalente) para cualquier diccionario que termine dentro de un segmento de prompt con caché.
• Construye el contenido con caché a partir de una función compartida, no de literales en línea dispersos. Centralizar la construcción del prompt del sistema y del esquema de herramientas evita que pequeñas diferencias accidentales se filtren entre los sitios de llamada.
• Audita también el contenido de prompts de terceros y generados por frameworks. Un generador de esquemas de herramientas o una biblioteca de plantillas de prompts puede incrustar contenido volátil tan fácilmente como tu propio código; comprueba la carga útil serializada final, no solo lo que escribiste a mano.
• Trata un fallo de caché deliberado (por ejemplo, después de recortar el historial de conversación) como esperado, no como un error. Presupuesta el coste de reescritura único en lugar de intentar evitarlo por completo cuando el historial realmente necesita cambiar.

D - Monitorización y verificación

• Comprueba usage.cache_read_input_tokens y cache_creation_input_tokens en cada respuesta, no solo durante la configuración. El almacenamiento en caché falla silenciosamente (un fallo nunca genera un error), por lo que la monitorización continua es la única forma de detectar una regresión en producción.
• Prueba con al menos dos llamadas consecutivas antes de concluir que el almacenamiento en caché no funciona. La primera llamada a cualquier prefijo es siempre una escritura, nunca un acierto; eso es esperado, no un fallo.
• Utiliza la beta de diagnósticos de caché para la investigación específica de un fallo confirmado. Pasar diagnostics.previous_message_id te proporciona un cache_miss_reason directamente desde la API en lugar de requerir una diferencia manual.
• Etiqueta las métricas de caché por endpoint o prompt, no solo en agregado. Una caída en la tasa de aciertos general puede ocultar el hecho de que solo un prefijo específico comenzó a fallar; el etiquetado por prompt aísla la regresión real.
• Compara dos prefijos supuestamente idénticos mediante programación al investigar, nunca a simple vista. Un solo carácter diferente en un prompt de varios miles de tokens es prácticamente invisible a la inspección manual.

Preguntas frecuentes

Relacionado

• Cómo funciona realmente la coincidencia de prefijos del almacenamiento en caché de prompts - el mecanismo detrás de cada práctica de esta lista.
• Colocación de puntos de interrupción cache_control en prompts del sistema y herramientas - el detalle completo detrás del Grupo A.
• Depuración de invalidadores de caché silenciosos en prompts largos - el detalle completo detrás del Grupo C.
• Verificación de aciertos de caché con cache_read_input_tokens - el detalle completo detrás del Grupo D.

Versiones de la pila: Escrito contra la línea de modelos Claude actual a partir de ~junio de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (el predeterminado) y Claude Haiku 4.5 - y el SDK oficial de Python anthropic (última versión 0.x). Los nombres de los modelos, las versiones del SDK y los precios cambian rápidamente; verifica los detalles actuales en platform.claude.com/docs antes de confiar en ellos.