Este artículo técnico del equipo de Claude Code en Anthropic revela cómo el prompt caching constituye el fundamento arquitectónico de Claude Code, lo que hace económicamente viable un producto agéntico con sesiones de larga duración. El principio fundamental: la caché funciona mediante coincidencia de prefijos (prefix matching), donde cualquier modificación del prefijo invalida todo lo que sigue. Esta única restricción determina el diseño de todo el sistema.
La arquitectura del system prompt sigue un orden estricto: primero el contenido estático y las herramientas (caché global), luego CLAUDE.MD (caché por proyecto), el contexto de sesión y, finalmente, los mensajes de la conversación. Esta jerarquía maximiza el uso compartido de la caché entre sesiones. El equipo descubrió que este orden es sorprendentemente frágil: basta con una simple marca de tiempo, un orden no determinista de las herramientas o la actualización de parámetros de una herramienta para romper la caché.
De su experiencia surgen varias reglas contraintuitivas. Primero, nunca modificar el system prompt para información cambiante (fecha, archivos modificados), sino usar etiquetas <system-reminder> en los mensajes posteriores. Segundo, nunca cambiar de modelo en mitad de una sesión: a 100k tokens de una conversación con Opus, usar Haiku para una pregunta simple resulta más costoso porque la caché debe reconstruirse por completo. La solución: subagentes con un mensaje de traspaso (handoff). Tercero, nunca añadir ni eliminar herramientas, ya que forman parte del prefijo cacheado.
El modo plan ilustra perfectamente un diseño condicionado por la caché. En lugar de reemplazar las herramientas por versiones de solo lectura (lo que rompería la caché), Claude Code conserva todas las herramientas y usa EnterPlanMode/ExitPlanMode como herramientas adicionales, junto con un mensaje de sistema explicativo. Este diseño permite que el modelo entre en modo plan por sí mismo sin romper la caché. Tool search aplica el mismo principio: en lugar de eliminar las herramientas MCP no utilizadas, se mantienen stubs ligeros con defer_loading: true que conservan la estabilidad del prefijo.
La compactación (resumen cuando se supera la ventana de contexto) presenta escollos importantes. La implementación ingenua, mediante una llamada API separada (system prompt distinto, sin herramientas), incurre en el coste total de todos los tokens. La solución: usar exactamente los mismos parámetros que la conversación principal para reutilizar el prefijo cacheado, pagando únicamente los tokens del prompt de compactación.
El artículo concluye que la tasa de aciertos de caché (cache hit rate) debe monitorizarse como el uptime, con alertas e incidencias declaradas cuando desciende. Estos patrones ya están integrados directamente en la API Anthropic, lo que permite a cualquier desarrollador de agentes beneficiarse de estas optimizaciones.