En tareas largas con Claude Code, la tasa de aciertos de Prompt Cache afecta directamente el costo y la velocidad. Muchos usuarios saben que la caché puede ahorrar tokens, pero no qué acciones hacen que falle de repente.
La forma más simple de entenderlo es imaginar cada petición como una cadena de contexto de izquierda a derecha:
|
|
Cuanto más a la izquierda está un contenido, más estable debería ser y mayor es el beneficio de cachearlo. Si cambia una sección de la izquierda, todo lo que va después puede necesitar recalcularse. Si cambia algo a la derecha, el impacto suele ser menor.
Optimizar Prompt Cache en Claude Code no es magia. La regla es simple: antes de iniciar una tarea, prepara modelo, servidores MCP, Skills, CLAUDE.md y el contexto base. Una vez iniciada, cambia lo menos posible esa parte fija.
Prompt Cache no guarda texto plano
Prompt Cache no es solo una caché de cadenas de texto. En la inferencia Transformer, lo importante es el estado Key/Value calculado por las capas de atención a partir del prefijo de contexto, lo que solemos llamar KV cache.
Eso implica dos cosas:
- Si el prefijo se mantiene estable, parte del cálculo previo puede reutilizarse.
- Si cambian el modelo, las definiciones de herramientas, el prompt del sistema o los mensajes iniciales, las entradas antiguas de caché pueden dejar de coincidir.
La documentación de Anthropic resume la jerarquía de invalidación como tools -> system -> messages. Cambiar definiciones de herramientas puede invalidar toda la caché; cambios en system afectan system y messages; cambios en messages afectan sobre todo la caché de mensajes.
Claude Code añade otras fuentes de contexto como CLAUDE.md, Skills, MCP, plugins y subagents, así que es fácil romper la caché sin querer.
Asesino de caché 1: cambiar de modelo a mitad de tarea
Cambiar de modelo es una de las operaciones más caras.
Prompt Cache está aislada por modelo. Opus, Sonnet y Haiku tienen arquitecturas y pesos distintos, así que el KV cache calculado desde el mismo texto no es intercambiable. Si construyes un contexto largo en Opus y luego cambias a Sonnet, Sonnet no puede reutilizar la caché de Opus.
Esto produce un resultado poco intuitivo: cambiar a un modelo más barato a mitad de tarea puede hacer inútil la caché acumulada. El contexto que podría leerse a precio de cache read quizá tenga que escribirse y calcularse de nuevo.
Un patrón más estable:
- Mantén la conversación principal en un solo modelo.
- Usa un subagent para tareas laterales que puedan ejecutarse con un modelo más barato.
- Deja que el agente lateral busque, explore o resuma, y devuelva un resultado breve a la conversación principal.
Así el prefijo largo de la conversación principal se mantiene estable y la caché acierta con más consistencia.
Asesino de caché 2: añadir MCP o recargar plugins a mitad de tarea
MCP proporciona herramientas a Claude Code. Al añadir un servidor MCP, cambia la lista de herramientas, y las definiciones de herramientas están en el extremo izquierdo de la cadena de contexto.
Desde la perspectiva de Prompt Cache, cuando cambia la lista de herramientas, system y messages pueden necesitar recalcularse. Si usas muchos MCP, las definiciones de herramientas pueden ocupar muchos tokens, y el costo de invalidación se nota.
Un detalle importante: Claude Code suele leer la configuración MCP al iniciar la sesión. Cambiar configuración durante la sesión no siempre afecta de inmediato. Los momentos peligrosos son reiniciar, hacer resume, recargar plugins o reconstruir la lista de herramientas.
Recomendaciones:
- Instala los MCP necesarios antes de iniciar una tarea larga.
- Evita descubrir a mitad de trabajo que falta una herramienta y recargar.
- Reduce los MCP habilitados por defecto cuando sea posible.
- No mantengas servidores MCP raramente usados siempre activos.
Las definiciones de herramientas estables son la base de una Prompt Cache estable.
Asesino de caché 3: editar CLAUDE.md durante la sesión
CLAUDE.md es el archivo de memoria de proyecto de Claude Code. Sirve para comandos de build, tests, convenciones de arquitectura, estilo de código y restricciones del proyecto.
Es útil, pero también entra en el contexto. La ayuda de Claude explica que CLAUDE.md se lee al iniciar la sesión y se entrega como mensaje de usuario. También se beneficia de Prompt Cache: la primera petición paga el precio completo de entrada, y las siguientes pueden usar el precio menor de cache read si la caché sigue válida.
El problema es que CLAUDE.md se identifica por contenido. Si cambias el archivo, la caché antigua deja de coincidir.
Por eso conviene no editar CLAUDE.md con frecuencia durante tareas largas. Mejor:
- Revisa si
CLAUDE.mdes suficiente antes de empezar. - Coloca reglas estables en el archivo e instrucciones temporales en la conversación.
- No edites la memoria de largo plazo por una necesidad puntual.
- Si debes cambiarlo, trata la siguiente fase como una nueva sesión o etapa.
CLAUDE.md debería ser guía estable de proyecto, no un borrador temporal que cambia cada ronda.
Asesino de caché 4: instalar o actualizar Skills a mitad de tarea
Skills también forman parte del contexto. Instalar una Skill nueva, actualizar una Skill o cambiar la lista de Skills cambia lo que se inyecta en la sesión.
Estos cambios suelen aplicarse al recargar, reanudar o abrir una nueva sesión. Cuando messages se reconstruye, las entradas antiguas de caché pueden dejar de servir.
La recomendación es similar a MCP:
- Decide qué Skills necesitas antes de empezar.
- Mantén estable el conjunto de Skills para tareas similares.
- Evita instalar Skills en mitad de una tarea larga.
- Si instalas una Skill nueva, trátalo como inicio de una nueva etapa.
Para flujos repetibles como producción de contenido, review, despliegue o traducción, mantener un conjunto fijo de Skills ayuda a estabilizar la estructura del contexto.
Asesino de caché 5: estar inactivo más allá del TTL
Prompt Cache no dura para siempre. Un TTL común está en el orden de minutos, y la documentación relacionada con Claude Code suele hablar de una ventana cercana a cinco minutos. Pasado el TTL, incluso la misma petición puede requerir reconstruir la caché.
Esto explica una sensación común en tareas largas: todo iba rápido y barato, sales por un café, vuelves y el costo de tokens sube otra vez.
Es fácil que ocurra. Lees la salida de Claude Code, inspeccionas archivos, ejecutas tests o piensas el siguiente paso. Cinco minutos pasan rápido.
Si tu entorno lo permite, puedes pedir un TTL de una hora antes de tareas largas:
|
|
En Windows PowerShell:
|
|
Las escrituras de caché de una hora suelen costar más que las de cinco minutos. No siempre conviene para tareas cortas, pero en bases de código grandes, conversaciones largas y trabajos complejos de varias etapas, puede ser más barato que sufrir expiraciones repetidas.
Un flujo de Claude Code que ahorra tokens
Un flujo más estable sería:
- Elegir el modelo antes de empezar y evitar cambios frecuentes.
- Habilitar los MCP necesarios y desactivar los que no usarás.
- Mantener
CLAUDE.mdbreve, estable y centrado en reglas duraderas. - Preparar por adelantado las Skills necesarias.
- En tareas complejas, considerar TTL de una hora.
- Dividir la tarea en fases, pero mantener estable la estructura de contexto dentro de cada fase.
- Usar subagents o sesiones separadas para exploraciones laterales, sin alterar la conversación principal.
El objetivo no es eliminar todos los fallos de caché. Es evitar los fallos caros y fáciles de pasar por alto.
Regla rápida
Hazte esta pregunta:
¿Esta operación cambia el modelo, las definiciones de herramientas, el contexto del sistema o los mensajes fijos del inicio de la sesión?
Si la respuesta es sí, probablemente afecte a Prompt Cache. Cuanto más a la izquierda esté en la cadena de contexto, mayor será el impacto.
Operaciones comunes:
- Cambiar modelo: alto riesgo, cachés aisladas por modelo.
- Añadir MCP o recargar plugins: alto riesgo, cambia la lista de herramientas.
- Editar
CLAUDE.md: riesgo medio-alto, cambia la memoria del proyecto. - Instalar Skills: riesgo medio-alto, cambia el contexto inyectado.
- Continuar una conversación normal: bajo riesgo, principalmente añade messages.
- Superar el TTL en inactividad: alto riesgo, la caché del servidor expira.
Resumen
Optimizar Prompt Cache en Claude Code consiste en mantener estable el prefijo de la sesión.
No cambies modelos sin necesidad. No instales MCP y Skills a mitad de trabajo. No uses CLAUDE.md como borrador temporal. En tareas complejas, considera un TTL más largo. Con estas bases estables, el costo en tokens y la velocidad de respuesta se vuelven mucho más predecibles.
La frase práctica es: configura antes de empezar, cambia menos después.