🌱 Fundamentos e termos
Antes de mexer em nada, entenda o que o prompt caching é e o vocabulário que o cerca. Aqui você sai sabendo por que o cache existe, o que é hit, miss, write e TTL, e por que uma conversa longa pode custar ~10% em vez de 100%. Cada termo técnico é definido na primeira vez que aparece — sem pré-requisito de API.
Ilustração: o começo da conversa (o prefixo) é montado
sempre na ordem tools → system → histórico. Ele é processado uma vez, gravado
no cache e, depois, apenas relido a cada turno — barato. É essa a máquina inteira que a Trilha 1
desmonta peça por peça.
Mapa da trilha
Conteúdo detalhado
🧩 O que é prompt caching
Do problema do reprocessamento à ideia do prefixo: hit, miss, write, a ordem
tools → system → messages e o breakpoint. Cada termo definido na 1ª aparição.
A API do Claude é stateless — não guarda a conversa. A cada mensagem você reenvia tudo: prompt de sistema, ferramentas e histórico inteiro.
É a dor que o cache resolve. Sem entender o reprocessamento, o resto não faz sentido.
stateless · prompt de sistema · reenviar a conversa inteira · custo e latência que crescem por turno.
O começo da conversa é estável e se repete a cada turno. O cache guarda esse começo já processado e o reaproveita, em vez de reprocessar.
É a virada de chave: pagar uma vez pelo que não muda, em vez de pagar todo turno.
prefixo estável · processado uma vez · reaproveitamento · o que muda fica no fim.
A chave do cache são os bytes exatos até o ponto de corte. Um único byte diferente no meio invalida tudo dali pra frente.
Explica todo "por que meu cache não bateu?". É o invariante que rege a trilha inteira.
prefixo · bytes exatos · ponto de corte · invalidação a partir do byte que muda.
O prompt é montado nessa ordem. Um breakpoint no fim do system cacheia tools + system juntos.
Saber a ordem diz o que colocar no começo (estável) e o que deixar no fim (muda).
ordem de montagem · posição 0 = tools · coisa estável no começo · coisa volátil no fim.
Hit = leu do cache (barato). Write = gravou no cache (leve prêmio). Miss = não achou, processou cheio. A 1ª mensagem grava; as seguintes leem.
É o vocabulário que você vai ler nos campos de usage e usar pra diagnosticar.
hit · miss · write · 1ª mensagem grava, próximas leem.
A marca que diz "cacheie até aqui". Máx. 4 por requisição; prefixo mínimo ~1024–4096 tokens (varia por modelo) — abaixo disso não cacheia e não dá erro.
No Claude Code é automático, mas entender o conceito explica por que trechos curtos não cacheiam.
cache_control · máx. 4 breakpoints · mínimo cacheável · automático no Claude Code.
💸 Termos e economia
Os três campos de usage, o TTL de 5 min e 1 h, os custos relativos
e o cálculo de break-even. A economia real, sem mistério.
Tokens servidos do cache neste turno. Custam ~0,1× do preço de input.
É o campo que prova que o cache bateu. Zero repetindo o mesmo prefixo = tem problema.
leitura do cache · ~0,1× · sinal de hit.
Tokens gravados no cache neste turno. Custam ~1,25× (TTL 5 min) ou ~2× (TTL 1 h).
É o "prêmio" que você paga uma vez pra ler barato depois. Ver isso alto o tempo todo é sinal de cache que nunca lê.
gravação · ~1,25× / ~2× · pago uma vez por bloco novo.
Só a parte NÃO cacheada, preço cheio (1×). O total do prompt = soma dos três campos.
Pegadinha: se o agente rodou horas e input_tokens mostra pouco, o resto veio do cache — olhe a SOMA dos três.
parte não-cacheada · 1× · total = soma dos três.
TTL = tempo de vida da entrada no cache. Padrão 5 min, renovado a cada uso. Existe opção de 1 h (write ~2×) pra tráfego com pausas longas.
Explica por que uma conversa ativa fica "quente" e uma pausa longa te faz pagar write de novo.
TTL · 5 min renovável · 1 h mais caro · conversa ativa mantém quente.
read ~0,1× · write 5 min ~1,25× · write 1 h ~2× · não-cacheado 1×. Numa conversa longa, o grosso do input sai a ~10%.
São os quatro números que explicam qualquer conta de economia do curso.
tabela de custos · read barato · write com prêmio · cheio como referência.
Com TTL 5 min, 2 requisições já pagam o write (1,25× + 0,1× = 1,35× vs 2× sem cache). Com 1 h, precisa ~3.
Ensina a NÃO cachear prefixo que muda todo request (só paga write, nunca lê).
ponto de equilíbrio · 2 reqs (5 min) / ~3 (1 h) · não cachear o que muda sempre.