⚙️ Como funciona tecnicamente
Prompt caching não é mágica — é um mecanismo bem definido no servidor da Anthropic. Entender cada detalhe técnico é pré-requisito para usá-lo com disciplina e não quebrá-lo sem querer.
🔬O mecanismo em 5 pontos
- 1.Prefixo exato é armazenado em cache no servidor. "Exato" significa byte a byte: um espaço a mais invalida.
- 2.TTL padrão: 5 minutos. Opcional: 1 hora (sem beta header desde 2025).
- 3.Escrita: 1,25× input (TTL 5 min) ou 2× (TTL 1h). Cobrada apenas na primeira chamada.
- 4.Leitura: 0,1× input — ou seja, 90% de desconto.
- 5.Cache é por modelo. Trocar de Sonnet para Opus invalida.
Fluxo de uma chamada com cache
Preço oficial do cache por operação (Anthropic)
| Operação | TTL 5 min | TTL 1 h | Desconto vs. input |
|---|---|---|---|
| Escrever (cache write) | 1,25× | 2,0× | +25% ou +100% |
| Ler (cache read) | 0,1× | 0,1× | −90% |
| Sem cache | 1,0× | 1,0× | baseline |
Break-even: precisa ler o cache ≥ 3× para compensar a escrita de 5 min; ≥ 11× para compensar a de 1h.
⚠️Cache é por modelo
Este é o ponto que mais gente esquece. Se você começa em Sonnet, chegou no 15º turno e muda para Opus "porque tem um bug difícil" — você re-escreve todo o prefixo no cache do Opus. Nenhuma da leitura anterior é aproveitada. Escolha o modelo no início e mantenha.
💰 90% de desconto em números
Teoria é bonita, mas número vende. Vamos ver a conta completa de uma sessão realista — 50k tokens de base, 20 turnos, Sonnet 4.6.
Sessão de 50k tokens × 20 turnos — comparativo
| Cenário | Cálculo | Total input | Custo |
|---|---|---|---|
| Sem cache | 50k × 20 × US$3/1M | 1,0M tokens | US$ 3,00 |
| Com cache (5min) | 50k × 1,25 + 50k × 19 × 0,1 | 50k write + 95k read | US$ 0,48 |
| Diferença | mesmo trabalho | — | 6,25× |
Base: Sonnet 4.6 (US$ 3/1M input). Cálculo cache: 1× write a 1,25× + 19× read a 0,1×.
❌ Sem cache
✅ Com cache bem usado
Mesma sessão. Mesmo resultado. 1/6 do custo.
💡O efeito composto
Em uma equipe de 5 devs rodando 40 sessões/semana, essa diferença vira ~US$ 500/mês de economia só com cache automático. Fazer bem, com estrutura correta, pode multiplicar por 2 ou 3 esse número.
🏗️ Estrutura: estático primeiro
Cache só funciona com prefixo exato. A estratégia é organizar o prompt como uma pirâmide: o que nunca muda no topo, o que muda sempre na base. Qualquer mudança invalida tudo a partir daquele ponto.
Pirâmide de cache — do mais estático ao mais volátil
📜A regra de ouro
Não edite arquivos do CLAUDE.md ou skills no meio da sessão.
Parece óbvio depois de dito, mas é a causa #1 de cache quebrado na prática. Quer refinar seu CLAUDE.md? Termine a sessão, edite, abra nova. A economia vale a disciplina.
✓ Hábitos que protegem o cache
- ✓CLAUDE.md curto e estável — edite entre sessões
- ✓Leia arquivos no início da sessão, não espalhado
- ✓Manter MCPs fixos durante a sessão
- ✓Escolha o modelo no início e mantenha
- ✓Skills definidas de antemão
✗ Ações que quebram o cache
- ✗Editar CLAUDE.md durante a sessão
- ✗Ativar/desativar MCPs em runtime
- ✗Timestamp dinâmico no system
- ✗Reordenar arquivos entre turnos
- ✗Trocar modelo no meio
🎯 Cache checkpoints (até 4 por chamada)
A API da Anthropic aceita até 4 pontos de cache explícitos por chamada via cache_control. O Claude Code faz isso automaticamente, mas se você usar a API direto (SDK, projeto próprio), dominar isso é crítico.
📐Como funciona
- •Cada bloco marcado com
cache_control: {"type": "ephemeral"}é um ponto de cache. - •Máximo de 4 pontos por request.
- •O servidor armazena o conteúdo até aquele ponto. Modificações depois não afetam o cache antes.
- •Claude Code marca checkpoints automaticamente em: system, CLAUDE.md, cada message block.
Exemplo de request JSON com 3 checkpoints
POST /v1/messages{
"model": "claude-opus-4-7",
"max_tokens": 4096,
"system": [
{
"type": "text",
"text": "Você é um especialista em engenharia de software...",
"cache_control": {"type": "ephemeral"} // checkpoint 1
}
],
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "<CLAUDE.md>\n...regras do projeto...\n</CLAUDE.md>",
"cache_control": {"type": "ephemeral"} // checkpoint 2
},
{
"type": "text",
"text": "<arquivos>\n...conteúdo de 5 arquivos fixos...\n</arquivos>",
"cache_control": {"type": "ephemeral"} // checkpoint 3
},
{
"type": "text",
"text": "Analise o código acima e sugira melhorias."
// sem cache — é a pergunta atual
}
]
}
]
}💡Onde colocar os 4 checkpoints
- 1.Após o system prompt — cacheia a identidade do agente
- 2.Após o CLAUDE.md / documentação — cacheia as regras do projeto
- 3.Após os arquivos fixos do código — cacheia o código que não muda
- 4.Após o histórico até o penúltimo turno — cacheia a conversa consolidada
A mensagem nova (pergunta atual) sempre fica fora dos checkpoints — ela muda a cada request por definição.
Claude Code vs. API direta
Faz tudo automaticamente. Você só precisa manter o prefixo estável. É o caminho padrão.
Você controla cada cache_control. Mais poder, mais responsabilidade. Use se estiver construindo sistema próprio.
⚠️ O que invalida o cache (lista completa)
Você pode estar pagando preço cheio sem saber. Essa é a lista definitiva das armadilhas — se reconhecer qualquer uma, corrija.
Editar CLAUDE.md no meio da sessão
Qualquer edição (até um espaço extra) invalida o cache a partir do CLAUDE.md em diante. Você paga preço cheio do ponto de alteração para frente.
→ Planeje edições entre sessões. Pense em CLAUDE.md como configuração "imutável durante run".
Ativar/desativar MCPs em runtime
Cada MCP contribui com definições de tools no system. Adicionar ou remover reestrutura o prefixo.
→ Defina MCPs ativos antes de abrir a sessão. Use perfis (.mcp.json) por projeto.
Adicionar timestamp dinâmico no system
Se seu system prompt tem "Data atual: 2026-04-21 14:35:22", o prefixo muda a cada chamada — cache 100% quebrado.
→ Conteúdo dinâmico vai na mensagem atual, não no system.
Mudar ordem de arquivos entre turnos
Se no turno 5 você anexa [A, B, C] e no turno 6 anexa [B, A, C] — ordem diferente = prefixo diferente = cache miss.
→ Ordem consistente. Automatize com helper se precisar.
Trocar modelo (Sonnet → Opus)
Cache é por modelo. A mudança force re-escrita completa do prefixo.
→ Escolha o modelo no início. Se precisar de Opus para parte difícil, use subagente separado.
TTL expirado (5 min sem atividade)
Parou para almoçar? 30 min depois o cache de 5min já era. Próxima mensagem reescreve tudo.
→ Em sessões com pausas longas, considere TTL de 1h (se a API direta aceitar; Claude Code padrão é 5min).
🔍Como diagnosticar
Na API direta, a resposta inclui cache_creation_input_tokens e cache_read_input_tokens. Se o primeiro está alto em cada chamada, algo está invalidando.
No Claude Code, use /cost para ver o ratio de cache hit/miss da sessão.
📊 ROI em projetos reais
Um caso concreto vale mais que dez tabelas abstratas. Esta é uma equipe real (5 devs, projeto Next.js médio, ~30 sessões/semana) que mediu antes e depois de otimizar o cache.
Perfil do projeto
Custo mensal — antes × depois
| Categoria | Antes | Depois | Redução |
|---|---|---|---|
| Input acumulado | US$ 620 | US$ 85 | −86% |
| Cache write | US$ 0 | US$ 22 | + (investimento) |
| Cache read | US$ 0 | US$ 11 | + (economia) |
| Output | US$ 230 | US$ 22 | −90% |
| TOTAL | US$ 850 | US$ 140 | −83,5% |
Valores médios mensais do 3º mês após a otimização, comparados com o 2º mês antes.
🔧O que eles mudaram
- 1.CLAUDE.md congelado — reduziram de 450 para 180 linhas e proibiram edição em runtime
- 2.MCPs enxutos — de 12 servidores ativos para 4 críticos
- 3.Modelo fixo por sessão — Sonnet default; Opus só em sessões específicas separadas
- 4.Ciclos mais curtos — limite de 25 turnos por sessão + handoff estruturado
- 5.Subagentes Haiku — tarefas repetitivas (docs, formatação) migraram para Haiku
Com 1 tarde de refactor de CLAUDE.md + disciplina de ciclos. Mesmo volume de trabalho.
🎯Aplique no seu projeto
Se sua equipe gasta mais de US$ 300/mês com Claude Code, uma tarde de auditoria provavelmente paga 2–3 meses de custo. Use o Módulo 6.3 como guia operacional.
📋Resumo do Módulo
Próximo módulo:
6.2 — 🎭 Orquestração Multi-Modelo
Opus planeja, Haiku executa. Economia de até 80% distribuindo trabalho pelo modelo certo.