Katas Prefix Caching

Qué certifica

Esta kata certifica que una política de prompt caching distingue almacenamiento automático y breakpoints explícitos, conserva un prefijo idéntico en el orden tools -> system -> messages, y demuestra lecturas o escrituras con usage. El caching cambia reutilización, latencia y costo; no reduce los tokens que ocupan la ventana de contexto. [DOC]

Frontera

Usa esta kata para diseñar y revisar la forma del prefijo y sus breakpoints. La autoridad de campos, modelos, proveedores y compatibilidad pertenece a claude-api-context-management; Redis, cachés HTTP y almacenamiento durable están fuera de alcance. [CONFIG]

Contrato

1. Automático: cache_control en el nivel superior mueve el breakpoint al último bloque elegible en cada solicitud. Si ese bloque no es elegible, la API retrocede al elegible más cercano; si no encuentra ninguno, omite el caching. [DOC]
2. Explícito: cache_control: {"type": "ephemeral"} en un bloque escribe exactamente el prefijo que termina allí. Úsalo al final del contenido estable, no sobre timestamps, IDs de solicitud ni otro sufijo volátil. [DOC]
3. Composición: automático y explícito pueden combinarse, pero hay hasta cuatro espacios totales y el automático consume uno. Cuatro breakpoints explícitos más automático producen HTTP 400. [DOC]
4. TTL: el valor predeterminado es 5 minutos; ttl: "1h" selecciona una hora. Si se mezclan, los breakpoints de una hora deben aparecer antes que los de cinco minutos. Un TTL diferente en el mismo último bloque automático/explícito produce HTTP 400. [DOC]
5. Retroceso: cada breakpoint busca como máximo 20 posiciones, incluida la propia. El retroceso encuentra entradas que solicitudes anteriores escribieron; no descubre ni escribe automáticamente un prefijo estable que nunca tuvo breakpoint. [DOC]
6. Invalidación: cambiar contenido en o antes de un breakpoint cambia su hash. La jerarquía es tools -> system -> messages: cambiar un nivel invalida ese nivel y los posteriores según el contrato documentado. [DOC]
7. Uso: verifica cache_creation_input_tokens, cache_read_input_tokens e input_tokens. El total de entrada es la suma de los tres; valores de cache en cero no prueban que el prompt fuese elegible o almacenado. [DOC]
8. Mínimo cacheable: cada modelo tiene una longitud mínima de prompt cacheable (1024 tokens en la mayoría; 2048 en algunos modelos del tier rápido). Un prefijo por debajo del piso NO se cachea y NO produce error: cache_creation_input_tokens queda en 0. Es la causa más frecuente de "breakpoint puesto, cero escrituras". Verifica el piso contra la tabla vigente de modelos del vendor. [DOC]

Procedimiento

1. Separa prefijo estable y sufijo variable; conserva serialización y orden deterministas. [CONFIG]
2. Elige automático para conversaciones crecientes simples y explícito cuando distintas secciones cambian con frecuencias distintas o la ventana de retroceso necesita anclas. [DOC]
3. Declara TTL y cuenta los espacios de breakpoint antes de enviar la solicitud. [DOC]
4. Ejecuta una solicitud de escritura y otra de lectura dentro del TTL; compara usage sin asumir hit por configuración. [DOC][CONFIG]
5. Falla cerrado ante orden de TTL inválido, más de cuatro espacios, prefijo variable, prefijo estable por debajo del mínimo cacheable del modelo sin reconocerlo, ausencia de evidencia en usage o afirmaciones de que caching libera ventana. [CONFIG]

Escenarios de certificación

• Positivo: prefijo estable, breakpoint elegible, segunda solicitud dentro del TTL y cache_read_input_tokens > 0. [DOC]
• Error/adversarial: automático con cuatro breakpoints explícitos, TTL conflictivo, contenido variable antes del breakpoint, entrada previa fuera de las 20 posiciones o afirmación de hit con usage en cero. [DOC][CONFIG]

Cuándo activar

Activa esta skill para prompt caching automático o explícito, prefijos estáticos, TTL, breakpoints, retroceso, invalidación o interpretación de usage. [CONFIG]

Skills relacionadas

• claude-api-context-management
• katas-context-dilution-mitigation
• katas-persistent-scratchpad
• katas-multipass-prompt-chaining

Packet

Capas del packet, cargables bajo demanda (disciplina ICM: una capa por vez, nunca todas juntas): knowledge/ cuerpo de conocimiento · prompts/ prompts listos · examples/ salida de ejemplo · agents/ subagentes del packet · templates/ plantilla de output.