# trq212-anthropic-claude-code-prompt-caching-lessons-2026-02

## Veille

Lecciones de prompt caching de Claude Code: arquitectura de caché, modo plan, compactación, optimización de costes y latencia

## Titre Article

Lessons from Building Claude Code: Prompt Caching Is Everything

## Date

2026-02

## URL

https://x.com/trq212/status/2024574133011673516

## Keywords

prompt caching, Claude Code, prefijo de caché, latencia, costes de API, modo plan, compactación, tool search, defer loading, system prompt, tasa de aciertos de caché, ventana de contexto, subagentes, arquitectura de agentes, herramientas MCP, bifurcación segura para la caché

## Authors

@trq212 (Anthropic, équipe Claude Code)

## Ton

**Perfil**: perspectiva de un ingeniero interno (equipo de Claude Code en Anthropic), registro técnico y pedagógico, nivel avanzado

**Descripción**: el autor adopta un tono estructurado y didáctico, compartiendo lecciones aprendidas "desde dentro" con una transparencia inusual sobre las decisiones arquitectónicas de Claude Code. El estilo es directo y pragmático, y alterna entre explicaciones teóricas ("el prompt caching funciona mediante coincidencia de prefijos") y anécdotas sobre errores encontrados en producción. El enfoque es el de un post-mortem técnico convertido en guía de buenas prácticas. Cada sección sigue un patrón de problema/intuición ingenua/solución real que hace accesibles conceptos contraintuitivos. El público objetivo son los desarrolladores que construyen productos agénticos sobre la API de Claude.

## Pense-betes

- **"Cache Rules Everything Around Me"**: el prompt caching es EL factor determinante de la viabilidad económica y del rendimiento de los agentes de larga duración. Todo el harness de Claude Code está construido en torno a esta restricción.
- **Prefix matching**: la caché funciona haciendo coincidir desde el inicio de la solicitud hasta puntos de control. Cualquier cambio en el prefijo invalida todo lo que sigue. Consecuencia: el orden de los elementos es crítico.
- **Orden óptimo del system prompt**: contenido estático primero, contenido dinámico al final. Para Claude Code: (1) System prompt + Herramientas (caché global) → (2) CLAUDE.MD (caché por proyecto) → (3) Contexto de sesión → (4) Mensajes de la conversación.
- **Fragilidad sorprendente**: errores sutiles rompen la caché: una marca de tiempo detallada en el system prompt, un orden no determinista de las herramientas, la actualización de parámetros de una herramienta.
- **Mensajes de sistema en lugar de modificar el prompt**: para información cambiante (fecha, archivos modificados), usar etiquetas `<system-reminder>` en el mensaje de usuario siguiente en lugar de modificar el system prompt (lo que rompería la caché).
- **Nunca cambiar de modelo en mitad de una sesión**: la caché es única por modelo. A 100k tokens de una conversación con Opus, cambiar a Haiku cuesta más que permanecer en Opus porque la caché debe reconstruirse. Solución: usar subagentes (mensaje de traspaso).
- **Nunca añadir/eliminar herramientas en mitad de una sesión**: las herramientas forman parte del prefijo cacheado. Cualquier modificación invalida la caché de toda la conversación. Es el error más común.
- **Modo plan = diseño construido en torno a la caché**: en lugar de intercambiar herramientas (por versiones de solo lectura), Claude Code conserva TODAS las herramientas y usa EnterPlanMode/ExitPlanMode como herramientas propiamente dichas + un mensaje de sistema. Ventaja adicional: el modelo puede entrar en modo plan por sí mismo sin romper la caché.
- **Tool Search = diferir en lugar de eliminar**: para decenas de herramientas MCP, en lugar de eliminarlas, se envían stubs ligeros (nombre + `defer_loading: true`). El modelo las "descubre" mediante ToolSearch. El prefijo permanece estable.
- **Compactación segura para la caché**: durante la compactación (resumen cuando la ventana de contexto está llena), usar exactamente el mismo system prompt, contexto y herramientas que la conversación principal. Solo el prompt de compactación es nuevo. De lo contrario: coste total de todos los tokens de entrada.
- **Búfer de compactación**: debe reservarse espacio en la ventana de contexto para el mensaje de compactación Y los tokens de salida del resumen.
- **Monitorizar la tasa de aciertos de caché como el uptime**: Anthropic activa alertas y declara incidencias (SEV) cuando la tasa de aciertos de caché es demasiado baja. Unos pocos puntos porcentuales de fallo de caché impactan drásticamente en los costes y la latencia.
- **Compactación disponible en la API**: basándose en las lecciones de Claude Code, la compactación se integró directamente en la API Anthropic.

## RésuméDe400mots

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.

## GrapheDeConnaissance

- Claude Code —est_basé_sur→ Prompt caching (CONCEPT, 0.98)
- Cache —est_basé_sur→ correspondance de préfixe (CONCEPT, 0.99)
- System prompt —utilise→ ordre statique puis dynamique (METHODOLOGIE, 0.97)
- Modification du system prompt —réduit→ cache de la conversation (CONCEPT, 0.98)
- System-reminder —remplace→ modification du system prompt (CONCEPT, 0.95)
- Plan mode —permet→ stabilité du cache (CONCEPT, 0.96)
- Plan mode —utilise→ EnterPlanMode/ExitPlanMode comme outils (TECHNOLOGIE, 0.95)
- Tool search —utilise→ stubs avec defer_loading (TECHNOLOGIE, 0.94)
- Changement de modèle —réduit→ cache de la session (CONCEPT, 0.97)
- Compaction —utilise→ même system prompt et outils (CONCEPT, 0.96)
- @trq212 —travaille_chez→ Anthropic (ORGANISATION, 0.95)
- Anthropic —mesure→ cache hit rate (CONCEPT, 0.93)
- Compaction —fait_partie_de→ API Anthropic (TECHNOLOGIE, 0.92)
- Ajout/retrait d'outils —réduit→ cache de la conversation (CONCEPT, 0.97)

---
Canonical: https://www.thekb.eu/es/fiches/trq212-anthropic-claude-code-prompt-caching-lessons-2026-02/