🧩 O que é prompt caching
Uma ideia só, montada peça por peça: a API reprocessa tudo toda vez, o cache guarda o começo estável, e o começo é reconhecido por casamento de prefixo — os bytes exatos até um ponto de corte. Cada termo é definido na 1ª vez que aparece.
🔁 O problema: reprocessar tudo toda vez
Toda a economia do prompt caching começa entendendo uma dor: a API do Claude é stateless. A cada mensagem que você manda, o modelo recebe a conversa inteira de novo — e processa tudo do zero. Numa conversa longa, isso é caro e lento.
Novo aqui? Dois termos primeiro
- stateless — "sem estado". A API não guarda a conversa entre chamadas; quem guarda o histórico é o cliente (o Claude Code), que reenvia tudo a cada turno.
- prompt de sistema — o texto de instruções que vem antes da conversa (quem o modelo é, o que pode fazer). É estável e vai sempre na frente.
Ilustração: a barra cresce a cada turno porque tudo que já foi dito é reenviado. É esse trabalho repetido que o cache elimina.
O que é
Como a API não guarda a conversa, o cliente reenvia o pacote completo — prompt de sistema, definição das ferramentas e todo o histórico — a cada requisição. O modelo então reprocessa esse pacote inteiro antes de responder.
Por que aprender
Sem sentir essa dor, o cache parece mágica sem propósito. Depois de entender o reprocessamento, cada peça do curso vira "ah, é isso que ele evita".
Conceitos-chave
♻️ A ideia: reaproveitar o prefixo
Repare uma coisa: o começo da conversa quase não muda. O prompt de sistema é o mesmo, as ferramentas são as mesmas, e o histórico já dito continua exatamente igual. Só o fim cresce, com a mensagem nova. O prompt caching aproveita isso: guarda esse começo estável — o prefixo — já processado, e o reaproveita em vez de reprocessar.
Novo aqui? O que é "prefixo"
prefixo = o pedaço do começo do prompt que se repete igual a cada turno. Pense na conversa como um texto que só cresce no fim: o prefixo é a parte de cima que já está congelada.
Como o reaproveitamento se desenrola
Turno 1 — o prefixo é processado e guardado
A primeira vez não tem o que reaproveitar: o modelo processa o prefixo e o grava no cache (paga um pouco mais por isso).
Turno 2 — o prefixo é reaproveitado
O começo é idêntico, então o modelo lê o prefixo já processado do cache (barato) e só processa a mensagem nova do fim.
Turno N — o prefixo só cresce e continua barato
A cada turno o prefixo reaproveitado fica maior (a resposta anterior também entra nele), mas continua sendo lido barato do cache.
O que é
Prompt caching é guardar o começo estável da conversa já processado e reaproveitá-lo a cada turno, em vez de reprocessá-lo do zero.
Por que aprender
É a virada de chave da economia: você paga uma vez pelo que não muda e, depois, só uma fração por relê-lo.
Conceitos-chave
🧩 O invariante: casamento de prefixo
Aqui está o invariante que explica tudo no resto do curso. O cache reconhece o prefixo por casamento de prefixo: a chave são os bytes exatos do prompt até um ponto de corte. Um único byte diferente no meio invalida o cache dali pra frente.
Ilustração: o cache é um casamento por prefixo, não por "parecido". Ele casa enquanto os bytes forem idênticos; no primeiro byte diferente, tudo à direita vira processamento cheio.
✓ Mantém o prefixo (casa)
- ✓Prompt de sistema idêntico, byte a byte
- ✓Mesma lista de ferramentas, na mesma ordem
- ✓Só adicionar conteúdo novo no fim
✗ Quebra o prefixo (invalida)
- ✗Trocar uma palavra no meio do system
- ✗Injetar data/hora ou um id que muda toda vez
- ✗Reordenar as ferramentas entre requisições
O que é
A chave do cache é a sequência exata de bytes do prompt até o ponto de corte. Enquanto os bytes casarem, é hit; no primeiro byte diferente, o resto é reprocessado.
Por que aprender
Porque quase todo "por que meu cache não bateu?" é um byte que mudou no prefixo. Este invariante é a lente para diagnosticar tudo depois.
Conceitos-chave
📚 A ordem: tools → system → messages
Se o cache é casamento de prefixo, então onde cada coisa fica no prompt importa muito. O prompt é sempre montado nesta ordem: tools (as ferramentas), depois system (o prompt de sistema), depois messages (o histórico da conversa). Coisa estável vai no começo; coisa que muda a cada requisição vai no fim.
Novo aqui? "posição 0" e "breakpoint"
- posição 0 — o comecinho absoluto do prompt. As ferramentas ficam ali; por isso mexer nelas é o que mais quebra cache.
- breakpoint — a marca que diz "o cache vai até aqui". Um breakpoint no fim do
systemguarda tools + system juntos.
Ilustração: como tools e system ficam antes do corte, eles são o pedaço mais barato de manter quente. As mensagens, que mudam sempre, ficam depois — onde variar não custa o cache.
[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)O que é
A regra de montagem do prompt: primeiro as ferramentas, depois o sistema, depois as mensagens. Um breakpoint ao fim do sistema cacheia tudo que veio antes dele.
Por que aprender
Saber a ordem diz onde colocar o que é estável (começo) e o que varia (fim) — a decisão de arquitetura que mais protege o cache.
Conceitos-chave
🎯 Hit, miss e write
Três palavras aparecem o tempo todo — inclusive nos números que você vai ler no próximo módulo. Hit é quando o cache foi lido (barato). Write é quando o cache foi gravado (um leve prêmio). Miss é quando não achou nada e processou tudo cheio. A 1ª mensagem grava; as seguintes leem.
Ilustração: o caminho feliz é write uma vez e hit em todos os turnos seguintes. Miss é o estado que você quer evitar — e o próximo módulo mostra como enxergá-lo nos números.
✓ Leva a hit
- ✓Continuar a mesma conversa dentro da janela do cache
- ✓Prefixo idêntico ao de um turno anterior
✗ Leva a miss / write frio
- ✗Primeiro turno de uma conversa nova (não há o que ler)
- ✗Prefixo alterado — o cache antigo não casa mais
O que é
Os três desfechos de uma requisição em relação ao cache: leu (hit), gravou (write) ou processou cheio (miss).
Por que aprender
É o vocabulário que você vai ver nos campos de usage e usar para diagnosticar se a economia está acontecendo.
Conceitos-chave
✂️ Breakpoint (cache_control)
Falta uma peça: como o sistema sabe até onde cachear? Pela marca cache_control,
o breakpoint — que diz "cacheie até aqui". No Claude Code isso é
automático: você não marca à mão, mas entender o conceito explica por que trechos curtos não cacheiam.
Novo aqui? "token" e "TTL"
- token — o pedacinho de texto que o modelo conta (mais ou menos uma sílaba/palavra curta). Preço e tamanho são medidos em tokens.
- TTL — "time to live", o tempo de vida da entrada no cache. Você vê isso a fundo no 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 cacheAs regras do breakpoint
- Máximo 4 por requisição — você não pode marcar quantos cortes quiser.
- Prefixo mínimo ~1024–4096 tokens (varia por modelo) — abaixo disso não cacheia.
- Falha silenciosa — se o trecho é curto demais, não cacheia e não dá erro: você só não vê a economia.
Dica prática
No Claude Code você não gerencia breakpoints — a ferramenta os coloca por você. O que fica no seu controle é não quebrar o prefixo (o resto do curso é sobre isso). Guarde o conceito; use a atenção para o que realmente muda.
O que é
O breakpoint (cache_control) é a marca que define até onde o prefixo será cacheado, com limite de 4 por requisição e um tamanho mínimo de prefixo.
Por que aprender
Explica por que prompts curtos parecem "não cachear" e por que, no Claude Code, você não precisa marcar nada — mas precisa entender o mecanismo.
Conceitos-chave
Resumo do módulo
Próximo módulo
1.2 — Termos e economia: os três campos de usage, o TTL e a conta de quando o cache paga.