🧩 Qué es el prompt caching
Una sola idea, armada pieza por pieza: la API vuelve a procesarlo todo cada vez, el cache guarda el comienzo estable, y el comienzo se reconoce por coincidencia de prefijo — los bytes exactos hasta un punto de corte. Cada término se define la primera vez que aparece.
🔁 El problema: reprocesar todo cada vez
Todo el ahorro del prompt caching empieza por entender un problema: la API de Claude es stateless. Cada mensaje que envías hace que el modelo reciba la conversación completa de nuevo — y procesa todo desde cero. En una conversación larga, esto es caro y lento.
¿Nuevo por aquí? Primero, dos términos
- stateless — «sin estado». La API no guarda la conversación entre llamadas; quien conserva el historial es el cliente (Claude Code), que lo vuelve a enviar todo en cada turno.
- prompt de sistema — el texto de instrucciones que viene antes de la conversación (quién es el modelo, qué puede hacer). Es estable y siempre va al principio.
Ilustración: la barra crece en cada turno porque se vuelve a enviar todo lo que ya se dijo. Ese trabajo repetido es lo que elimina el caché.
Qué es
Como la API no guarda la conversación, el cliente reenvía el paquete completo —el prompt del sistema, la definición de las herramientas y todo el historial— en cada solicitud. Luego, el modelo vuelve a procesar todo ese paquete antes de responder.
Por qué aprenderlo
Sin sentir ese dolor, el caché parece magia sin propósito. Después de entender el reprocesamiento, cada pieza del curso se convierte en «ah, esto es lo que evita».
Conceptos clave
♻️ La idea: reutilizar el prefijo
Fíjate en algo: el comienzo de la conversación casi no cambia. El prompt de sistema es el mismo, las herramientas siguen siendo las mismas y el historial ya escrito continúa exactamente igual. Solo el fin crece, con el mensaje nuevo. El prompt caching aprovecha esto: guarda ese comienzo estable — el prefijo — ya procesado, y lo reutiliza en vez de reprocesarlo.
¿Nuevo por aquí? ¿Qué es un «prefijo»?
prefijo = el fragmento del inicio del prompt que se repite igual en cada turno. Piensa en la conversación como un texto que solo crece al final: el prefijo es la parte de arriba que ya está congelada.
Cómo funciona la reutilización
Turno 1 — el prefijo se procesa y se guarda
La primera vez no hay nada que reutilizar: el modelo procesa el prefijo y el guarda en el caché (pagas un poco más por eso).
Turno 2 — se reutiliza el prefijo
El comienzo es idéntico, así que el modelo lee el prefijo ya procesado del caché (barato) y solo procesa el mensaje nuevo del final.
Turno N — el prefijo solo crece y sigue siendo barato
En cada turno, el prefijo reutilizado es más grande (la respuesta anterior también se incluye), pero se sigue leyendo del caché a bajo costo.
Qué es
El prompt caching consiste en guardar el inicio estable de la conversación ya procesado y reutilizarlo en cada turno, en lugar de volver a procesarlo desde cero.
Por qué aprenderlo
Es el cambio clave para ahorrar: pagas una vez por lo que no cambia y, después, solo una fracción por volver a leerlo.
Conceptos clave
🧩 El invariante: coincidencia de prefijo
Aquí está el invariante que explica todo en el resto del curso. El caché reconoce el prefijo por coincidencia de prefijo: la clave son los bytes exactos del prompt hasta un punto de corte. Un solo byte diferente en medio invalida el caché a partir de ahí.
Ilustración: el caché es una coincidencia por prefijo, no por «parecido». Coincide mientras los bytes sean idénticos; ante el primer byte diferente, todo lo que sigue pasa a procesarse por completo.
✓ Mantiene el prefijo (coincide)
- ✓Prompt de sistema idéntico, byte por byte
- ✓La misma lista de herramientas, en el mismo orden
- ✓Solo agregar contenido nuevo al final
✗ Rompe el prefijo (lo invalida)
- ✗Cambiar una palabra en medio del system
- ✗Inyectar fecha/hora o un id que cambia cada vez
- ✗Reordenar las herramientas entre solicitudes
Qué es
La clave del caché es la secuencia exacta de bytes del prompt hasta el punto de corte. Mientras los bytes coincidan, es un hit; ante el primer byte diferente, el resto se vuelve a procesar.
Por qué aprenderlo
Porque casi todo "¿por qué no funcionó mi caché?" se debe a que cambió un byte del prefijo. Este invariante es la lente para diagnosticar todo lo demás.
Conceptos clave
📚 El orden: tools → system → messages
Si el caché es un emparejamiento de prefijos, entonces dónde cada cosa que queda en el prompt importa mucho. El prompt siempre se monta en este orden: tools (las herramientas), después system (el prompt de sistema), después messages (el historial de la conversación). Lo estable va al comienzo; lo que cambia en cada solicitud va al final.
¿Nuevo por aquí? «posición 0» y «breakpoint»
- posición 0 — el comienzo absoluto del prompt. Las herramientas están ahí; por eso, modificarlas es lo que más rompe la caché.
- breakpoint — la marca que indica «la caché llega hasta aquí». Un punto de corte al final del
systemguarda tools + system juntos.
Ilustración: cómo tools e system quedan antes del corte, son la parte más barata de mantener caliente. Los mensajes, que cambian siempre, quedan después, donde variar no cuesta el caché.
[1] tools → definição das ferramentas (posição 0, estável)
[2] system → prompt de sistema (estável)
── cache_control (breakpoint) ── ← cacheia [1]+[2]
[3] messages → histórico + mensagem nova (cresce no fim)Qué es
La regla para armar el prompt: primero las herramientas, luego el sistema y después los mensajes. Un breakpoint al final del sistema cachea todo lo que vino antes.
Por qué aprenderlo
Saber el orden indica dónde poner lo que es estable (al principio) y lo que varía (al final): la decisión de arquitectura que más protege el caché.
Conceptos clave
🎯 Hit, miss y write
Tres palabras aparecen todo el tiempo — incluso en los números que vas a leer en el próximo módulo. Hit es cuando se leyó desde la caché (barato). Write es cuando se guardó en la caché (un pequeño costo adicional). Miss es cuando no encontró nada y procesó todo desde cero. El primer mensaje se guarda; los siguientes lo leen.
Ilustración: el camino ideal es escribir una vez y obtener un hit en todos los turnos siguientes. Un miss es el estado que quieres evitar — y el próximo módulo muestra cómo detectarlo en los números.
✓ Genera un hit
- ✓Continuar la misma conversación dentro de la ventana del caché
- ✓Prefijo idéntico al de un turno anterior
✗ Genera un miss / write en frío
- ✗Primer turno de una conversación nueva (no hay nada que leer)
- ✗Prefijo alterado: el caché anterior ya no coincide
Qué es
Los tres desenlaces de una solicitud en relación con la caché: leyó (hit), guardó (write) o procesó todo (miss).
Por qué aprenderlo
Es el vocabulario que verás en los campos de usage y usar para diagnosticar si se está logrando el ahorro.
Conceptos clave
✂️ Punto de corte (cache_control)
Falta una pieza: ¿cómo sabe el sistema hasta dónde usar el caché? Por la marca cache_control,
o breakpoint — que dice «guarda en caché hasta aquí». En Claude Code esto es
automático: no lo marcas manualmente, pero entender el concepto explica por qué los fragmentos cortos no se guardan en caché.
¿Nuevo por aquí? «token» y «TTL»
- token — el fragmento de texto que cuenta el modelo (más o menos una sílaba o palabra corta). El precio y el tamaño se miden en tokens.
- TTL — «time to live», el tiempo de vida de la entrada en la caché. Lo verás en detalle en el Módulo 1.2.
system: "Você é um assistente… (instruções estáveis)"
▲ cache_control: { type: "ephemeral" } ← breakpoint aqui
messages: [ …histórico…, {nova mensagem} ] ← fora do cacheLas reglas del breakpoint
- Máximo 4 por solicitud — no puedes marcar tantos cortes como quieras.
- Prefijo mínimo ~1024–4096 tokens (varía según el modelo): por debajo de ese valor no se guarda en caché.
- Falla silenciosa — si el fragmento es demasiado corto, no se guarda en caché y no da error: simplemente no ves el ahorro.
Consejo práctico
En Claude Code no administras los breakpoints: la herramienta los coloca por ti. Lo que sí está bajo tu control es no romper el prefijo (el resto del curso trata sobre eso). Conserva el concepto; usa tu atención para lo que realmente cambia.
Qué es
El breakpoint (cache_control) es la marca que define hasta dónde se guardará en caché el prefijo, con un límite de 4 por request y un tamaño mínimo de prefijo.
Por qué aprenderlo
Explica por qué los prompts cortos parecen «no usar el caché» y por qué, en Claude Code, no tienes que marcar nada, pero sí entender el mecanismo.
Conceptos clave
Resumen del módulo
Siguiente módulo
1.2 — Términos y ahorro: los tres campos de usage, el TTL y el cálculo de cuándo se amortiza el caché.