📈 O prefixo estável cresce
Numa conversa, system + tools + todo o histórico — inclusive a última resposta do modelo — formam um prefixo estável que cresce a cada turno. Só a sua próxima mensagem é realmente nova; tudo que veio antes é idêntico ao que já foi processado.
O que é
O prefixo estável é a fatia do prompt que não muda entre um turno e o seguinte: ferramentas, prompt de sistema e o histórico acumulado. Ele é a "matéria-prima" do cache — quanto maior, mais tokens saem baratos.
Por que aprender
Porque é isso que torna a conversa barata: cada resposta que o Claude Code dá vira parte do prefixo estável do próximo turno, então o "peso" da conversa migra para o lado do cache (~0,1×) em vez do preço cheio (1×).
Conceitos-chave
Prefixo = começo idêntico que se repete turno a turno.
Só o fim escapa — sua nova mensagem é a única parte não-cacheada.
Ordem de montagem: tools → system → messages.
Cresce — a resposta do modelo entra no histórico e engorda o prefixo.
A caixa azul (prefixo, lido do cache) cresce; a faixa fina no topo (sua nova mensagem, gravada) fica proporcionalmente menor a cada turno.
🔁 Hit por turno
A cada mensagem nova, só o final muda. A API relê todo o prefixo do cache (leitura ≈ 0,1×) e grava apenas o bloco novo daquele turno. É o que se chama hit: o prefixo bateu e foi servido do cache.
O que é
Hit é quando o prefixo do request casa com uma entrada já processada e é lido de volta a ~10% do preço. Cada turno da conversa é, na prática, um grande hit sobre o prefixo + um pequeno write da parte nova.
Por que aprender
Porque explica por que o 2º turno em diante é muito mais barato que o 1º: o grosso do prompt já está no cache e só a diferença é reprocessada. É a mecânica que faz uma sessão longa não custar uma fortuna.
✓ O que conta como hit
- ✓Prefixo idêntico byte a byte ao request anterior.
- ✓Dentro da janela de TTL (cache ainda quente).
- ✓Só a nova mensagem no fim é gravada.
✗ O que vira miss
- ✗Qualquer byte diferente no meio do prefixo.
- ✗TTL expirou (passou o tempo de vida).
- ✗Trocou o modelo (cache é por modelo).
Conceitos-chave
Hit = leu do cache (~0,1×).
Write = gravou o bloco novo do turno (~1,25×).
Miss = não achou, processou cheio (1×).
Por turno = 1 grande hit + 1 pequeno write.
⏱️ TTL de 5 min renovado por uso
TTL é o tempo de vida da entrada no cache. O padrão é 5 minutos, mas com um detalhe importante: ele é renovado a cada uso.
Ou seja: enquanto você responde dentro da janela de ~5 min, o relógio reinicia e o cache permanece quente indefinidamente. Uma conversa ativa mantém o prefixo barato sem que você faça nada de especial.
O que é
TTL (time-to-live) é a validade da entrada. Cada leitura/gravação reinicia esse relógio, então uma sequência contínua de mensagens nunca deixa o cache esfriar.
Por que aprender
Porque trabalhar em ritmo contínuo é literalmente mais barato — e porque explica o custo da retomada depois de uma pausa longa (próximo tópico e tópico 6).
Dica prática
Existe também um TTL de 1 hora (write mais caro, ~2×) para tráfego com pausas longas. Vale só quando há gaps > 5 min entre requests — senão o TTL de 5 min já dá conta e sai mais barato.
Conceitos-chave
TTL padrão = 5 min.
Renova por uso — cada turno reinicia o relógio.
Conversa ativa = cache sempre quente.
TTL 1h = write ~2×, para tráfego com pausas.
📊 A % de cache SOBE a cada turno
Este é o ponto que mais gera confusão. O cache não é uma bateria que descarrega. Um turno pode marcar apenas 40% de cache — porque teve muita coisa nova (ex.: uma skill grande carregada). Mas esse bloco novo vira read barato no próximo turno, e a porcentagem sobe.
O que é
A "% de cache" de um turno é quanto do prompt veio do cache (read) versus quanto foi novo (write + não-cacheado). Como o novo de hoje é o cacheado de amanhã, a fração lida do cache tende a crescer turno a turno.
Por que aprender
Porque desfaz a intuição errada de que "o cache acaba". Ver 40% num turno não é problema — é só sinal de que entrou algo grande, que ficará barato daqui pra frente.
O bloco novo do turno de 40% (a skill) é exatamente o que faz o próximo turno chegar a ~99%: virou leitura barata.
Conceitos-chave
| Turno | Lido do cache | Novo | % cache |
|---|---|---|---|
| agora (skill grande) | 40k | 60k | 40% |
| próximo (msg curta) | ~100k | ~1k | ~99% |
✍️ Primeira mensagem = write
A primeira mensagem de uma conversa não tem o que ler ainda — não existe prefixo anterior. Então ela grava o cache e paga um pouco mais (write ≈ 1,25× com TTL de 5 min). É o único turno que grava o prefixo inteiro.
O que é
O write inicial é o "investimento" que paga os turnos seguintes. Você grava uma vez para ler barato muitas vezes.
Por que aprender
Porque evita o susto de ver o 1º turno "caro". Não é um bug nem desperdício: é a gravação que habilita a economia do resto da sessão.
1º turno — write
Grava tools + system + a 1ª mensagem. Paga ~1,25× sobre o que gravou. Nada a ler ainda.
2º turno em diante — read + pequeno write
Lê o prefixo a ~0,1× e grava só a nova mensagem. Aqui a economia aparece.
Conceitos-chave
1ª msg só grava — não lê.
Write ~1,25× (TTL 5 min).
Investimento que barateia o resto.
A partir do 2º predomina read ~0,1×.
🧊 Pausa longa = write frio
Se você passar dos ~5 min parado, o TTL expira e a entrada some do cache. A próxima mensagem paga a gravação de novo — é o write frio. Não é falha; é só o cache tendo esfriado.
O que é
Write frio é a regravação do prefixo depois que o TTL expirou. Do ponto de vista do custo, é como reiniciar a conversa: paga o write inicial mais uma vez.
Por que aprender
Porque explica por que "retomar depois do almoço" custa: foi um write frio, não um problema. E aponta a solução — o TTL de 1 h para fluxos com pausas previsíveis.
Atenção
Não confunda write frio com silent invalidator. O write frio acontece por tempo (TTL expirou). O silent invalidator (Trilha 2, módulo 2.3) acontece por bytes que mudam no prefixo, mesmo com o cache quente.
Conceitos-chave
Pausa > TTL = entrada expira.
Write frio = regrava o prefixo.
Fix p/ gaps = TTL de 1 h (write ~2×).
Não é bug — é o cache esfriando.
Exemplo copy-run — auditar quanto veio do cache
Objetivo: confirmar, numa resposta real da API, quanto do prompt veio do cache — para ver com os próprios olhos o read barato dominando os turnos.
Numa resposta recente da API que você tem acesso (ou num
log de <caminho do meu log de requests>), leia o objeto
`usage` e me mostre os três campos:
- cache_read_input_tokens (lido do cache, ~0,1x)
- cache_creation_input_tokens (gravado, ~1,25x)
- input_tokens (só o resto não-cacheado, 1x)
Depois calcule e me explique:
1. a SOMA dos três (= tamanho total do prompt);
2. qual % veio do cache (read / soma);
3. se este parece um 1º turno (write alto) ou um turno
posterior (read dominante).Como verificar: a soma dos três campos deve bater com o tamanho total do prompt. Em turnos posteriores de uma conversa quente, cache_read_input_tokens deve ser a maior fatia e a % de cache alta (tópico 4). No 1º turno, a fatia de cache_creation_input_tokens domina (tópico 5).
Resumo do módulo
Próximo módulo:
2.2 — Skills e ferramentas: anexar vs quebrar