- En productos de agentes de larga ejecución, el prompt caching es una tecnología clave que reutiliza el cómputo de round trips anteriores para reducir de forma drástica la latencia y el costo, y toda la arquitectura de Claude Code fue diseñada alrededor de esto
- Como el caché funciona con coincidencia por prefijo, el diseño del orden —poner el contenido estático al frente y el dinámico al final— determina el costo y el rendimiento
- Si se cambian herramientas o el modelo a mitad de la sesión, el caché se invalida, por lo que es esencial un diseño alternativo que use stubs ligeros y herramientas para transición de estado en lugar de eliminar herramientas
- El trabajo de compactación (resumen y reducción) que se realiza al exceder la ventana de contexto también debe compartir el prefijo en caché de la conversación padre para evitar una explosión de costos
- La tasa de aciertos del caché debe monitorearse como el uptime, y hasta unos pocos puntos porcentuales de fallos de caché pueden tener un impacto serio en costo y latencia, por lo que deben tratarse como incidentes
- “Cache Rules Everything Around Me” también aplica tal cual a los agentes
- Gracias al prompt caching, es posible construir productos de agentes de larga duración como Claude Code
- Reutiliza el cálculo de round trips anteriores para reducir en gran medida la latency y el cost
Cómo funciona el prompt caching y cómo ubicar el system prompt
- El prompt caching funciona mediante coincidencia por prefijo (Prefix), y la API almacena en caché todo el contenido desde el inicio de la solicitud hasta cada punto de interrupción
cache_control
- La clave es maximizar el prefijo compartido entre solicitudes, y para eso hay que colocar primero el contenido estático y después el dinámico
- El orden en Claude Code es:
- System prompt estático y herramientas (caché global)
- Claude.MD (caché dentro del proyecto)
- Contexto de sesión (caché dentro de la sesión)
- Mensajes de la conversación
- Este orden es sorprendentemente frágil, y puede invalidarse el caché por cosas como:
inserción de timestamps detallados en el system prompt estático,
mezcla no determinística del orden de las herramientas,
actualización de parámetros de herramientas
Estrategia de actualización usando system messages
- Hay situaciones en las que la información dentro del prompt se vuelve obsoleta, como cambios en la hora o modificaciones de archivos del usuario
- Actualizar el prompt directamente puede provocar un cache miss y aumentar el costo para el usuario
- En su lugar, se usa el método de entregar la actualización como mensaje en el siguiente turno
- Claude Code inserta la información actualizada en el siguiente user message o tool result con la etiqueta
<system-reminder>
- Por ejemplo, puede dar una actualización de tiempo como “ahora es Wednesday”
- Usar system messages de esta manera permite conservar el caché
Por qué no se debe cambiar de modelo a mitad de la sesión
- El prompt cache es único por modelo, por lo que el cálculo de costos del caché puede no coincidir con la intuición
- Ejemplo: si en una conversación de 100k tokens con Opus cambias a Haiku para una pregunta simple, hay que reconstruir desde cero el caché para Haiku, así que puede salir más caro que responder con Opus
- Si es necesario cambiar de modelo, la mejor opción es usar subagentes, donde Opus prepara y entrega un mensaje de "handoff" al otro modelo
- El agente Explore de Claude Code usa este enfoque cuando trabaja con Haiku
No agregues ni elimines herramientas a mitad de la sesión
- Cambiar el conjunto de herramientas es una de las causas más comunes de invalidación del caché
- Como las herramientas son parte del prefijo almacenado, agregar o quitar una sola herramienta invalida el caché de toda la conversación
-
Plan Mode — diseño centrado en el caché
- Enfoque intuitivo: cuando el usuario entra en plan mode, dejar solo herramientas de solo lectura → destruye el caché
- Diseño real: incluir siempre todas las herramientas en la solicitud e implementar EnterPlanMode y ExitPlanMode como herramientas
- Al entrar en plan mode, se pasan instrucciones mediante un system message: explorar únicamente la base de código, no editar archivos y llamar a ExitPlanMode al terminar
- La definición de herramientas nunca cambia
- Ventaja adicional: como EnterPlanMode es una herramienta que el modelo puede invocar directamente, puede entrar de forma autónoma en plan mode al detectar un problema difícil sin destruir el caché
-
Tool Search — carga diferida en vez de eliminación
- Claude Code puede cargar decenas de herramientas MCP; incluirlas todas eleva el costo, pero quitarlas destruye el caché
- Solución: enfoque defer_loading, donde en lugar de eliminar herramientas se envían stubs ligeros que solo incluyen el nombre (
defer_loading: true)
- Si el modelo las necesita, carga el esquema completo mediante la herramienta ToolSearch
- Como siempre existen los mismos stubs en el mismo orden, el prefijo almacenado se mantiene estable
- Esto puede simplificarse mediante la función de tool search de la API
Forking de contexto — compactación (Compaction)
- Cuando se excede la ventana de contexto, se realiza una compactación para resumir la conversación e iniciar una nueva sesión
- Una implementación intuitiva (generar el resumen con una llamada API separada, sin el mismo system prompt ni las mismas herramientas) no coincide en nada con el prefijo en caché de la conversación principal, así que se paga el costo completo por todos los tokens de entrada
-
Solución de Cache-Safe Forking
- Al ejecutar la compactación, se usan el mismo system prompt, contexto de usuario, contexto del sistema y definiciones de herramientas que en la conversación padre
- Se colocan primero los mensajes de la conversación padre y al final se agrega el prompt de compactación como un nuevo mensaje de usuario
- Desde la perspectiva de la API, esta solicitud se ve casi igual que la última solicitud del padre, por lo que puede reutilizar el prefijo almacenado, y los únicos tokens nuevos son los del prompt de compactación
- Dentro de la ventana de contexto hay que reservar un "buffer de compactación" para el mensaje compacto y los tokens de salida del resumen
- Con base en este patrón, Anthropic integró directamente una función de compactación en la API para que los desarrolladores puedan aplicarla ellos mismos
Resumen de las lecciones clave
- El prompt caching funciona por coincidencia de prefijo, y cualquier cambio en cualquier punto del prefijo invalida todo el caché posterior → hay que diseñar todo el sistema alrededor de esta restricción
- En lugar de cambiar el system prompt, insertar system messages durante la conversación es más favorable para conservar el caché
- No cambies herramientas ni modelos en medio de la conversación → modela las transiciones de estado como herramientas y usa carga diferida en vez de eliminar herramientas
- La tasa de aciertos del caché debe monitorearse como el uptime, y hasta unos pocos puntos porcentuales de fallos de caché tienen un efecto dramático en costo y latencia
- Los trabajos de fork (compactación, resumen, ejecución de skills) deben compartir el prefijo del padre para que haya cache hits
- Si vas a construir un agente, debes diseñarlo alrededor del prompt caching desde el primer día
5 comentarios
La clave parece ser el cambio de la ingeniería de prompts a la ingeniería de contexto y, en la práctica, la respuesta parece ser la "separación de responsabilidades".
Gestionar la personalidad, las reglas de comportamiento y la memoria en archivos distintos ayuda a reducir el context rot. Cargar solo los archivos necesarios, en lugar de usar un prompt monolítico, es mucho más favorable para el attention budget. Por eso parece que OpenClaw (o frameworks similares) gestionan por separado la personalidad (
SOUL.md), las reglas de comportamiento (AGENTS.md) y la memoria (MEMORY.md).Ah, con razón Opus tiene un precio por token tan alto.
Me pregunto si habrá alguna reseña sobre la diferencia en la gestión de contexto entre Antigravity y Claude Code.
Aunque usen el mismo modelo Opus, seguro que hay diferencias. :)
Es un artículo que de verdad ayuda mucho.
Lectores reales:
Personas que están creando “agentes de larga ejecución” como Claude Code
(en especial ingenieros de producto/plataforma e ingenieros de infraestructura de LLM)
¿A quién le sirve más?
✅ 1) Equipos que crean productos de agentes de IA
✅ 2) Ingenieros que optimizan costo/latencia de LLM
✅ 3) Personas que conectan montones de herramientas MCP
En cambio, el usuario general casi no lo va a leer
No es un texto del tipo “cómo escribir buenos prompts”
Sino sobre “cómo hay que tratar los prompts a nivel de arquitectura de producto”
Resumen en una línea
Es un texto para quienes convierten los LLM no en un “chat”, sino en un “sistema de producción”.
Prácticamente no es diferente de optimizar capas de Docker.