Prefix cache
O cache só funciona do começo do texto pra frente. Mudou um byte no início, perdeu tudo que vem depois.
Onde você esbarra nisso
Quando o fornecedor promete economia com cache e a fatura não cai. Não é mentira dele. É um carimbo de tempo, um identificador aleatório ou um campo em ordem diferente no começo do teu texto.
Conecta com
O que é
O nome já entrega a regra: é cache de prefixo, do começo. O fornecedor compara o início da tua requisição com o que ele já tem guardado, e aproveita até o ponto em que os dois textos divergem. Do primeiro caractere diferente em diante, tudo é reprocessado.
A ordem em que a requisição é montada é fixa: primeiro as ferramentas, depois a instrução de sistema, depois as mensagens. Então uma ferramenta que muda de lugar na lista invalida a instrução e a conversa inteira, mesmo que elas não tenham mudado nada.
O que muda pro teu negócio
Aqui mora uma armadilha que custa dinheiro em silêncio, e é sempre a mesma: colocar a data e hora no começo da instrução. Parece inofensivo. Só que o relógio muda a cada requisição, o prefixo nunca bate, e o cache nunca pega. Você paga preço cheio pra sempre e não recebe erro nenhum avisando.
A regra prática é uma só: o que não muda vem primeiro, o que muda vem por último.
Fontes
docs.claude.com, prompt caching.
Skill `claude-api` (cache 2026-06-24): a ordem de montagem é ferramentas, depois sistema, depois mensagens, e qualquer byte alterado no prefixo invalida tudo que vem depois. Conferir com `cache_read_input_tokens` igual a zero.
AI Coding Dictionary, verbete "Prefix cache", Matt Pocock. Ele descreve o cache como coisa do lado do fornecedor, não do teu código. Isso explica por que você não controla quando ele pega.