- Em produtos de agentes de longa execução, o cache de prompt é a tecnologia central que reduz drasticamente latência e custo ao reutilizar o processamento de round-trips anteriores, e toda a arquitetura do Claude Code foi projetada em torno disso
- Como o cache funciona por correspondência de prefixo, o design da ordem — colocar conteúdo estático antes e conteúdo dinâmico depois — determina custo e desempenho
- Se ferramentas ou o modelo forem alterados no meio da sessão, o cache é invalidado, então um design alternativo com stubs leves e ferramentas de transição de estado é essencial, em vez de remover ferramentas
- Até o trabalho de compactação (redução por resumo) executado quando a janela de contexto é excedida precisa compartilhar o prefixo em cache da conversa pai para evitar explosão de custos
- A taxa de acerto do cache deve ser monitorada como uptime, e até alguns poucos pontos percentuais de cache miss podem ter impacto grave em custo e latência, devendo ser tratados como incidente
- “Cache Rules Everything Around Me” também se aplica integralmente a agentes
- O cache de prompt (prompt caching) é o que torna viável um produto de agentes de longa duração como o Claude Code
- Reutilizar o processamento de round-trips anteriores reduz bastante latency e cost
Como o cache de prompt funciona e como posicionar o prompt de sistema
- O cache de prompt funciona por correspondência de prefixo (Prefix), e a API armazena em cache todo o conteúdo desde o início da requisição até cada ponto de interrupção
cache_control
- O ponto-chave é maximizar o prefixo compartilhado entre requisições e, para isso, é preciso colocar conteúdo estático primeiro e conteúdo dinâmico depois
- A ordem usada no Claude Code:
- Prompt de sistema estático e ferramentas (cache global)
- Claude.MD (cache dentro do projeto)
- Contexto da sessão (cache dentro da sessão)
- Mensagens da conversa
- Essa ordem é surpreendentemente frágil, e pode haver invalidação do cache por motivos como:
inserção de timestamps detalhados no prompt de sistema estático,
embaralhamento não determinístico da ordem das ferramentas,
atualização dos parâmetros das ferramentas
Estratégia de atualização usando mensagens de sistema
- Há situações em que informações dentro do prompt ficam desatualizadas, como mudanças na informação de horário ou alterações de arquivos feitas pelo usuário
- Atualizar o prompt diretamente leva a cache miss, o que pode aumentar o custo para o usuário
- Em vez disso, usa-se a estratégia de enviar a atualização como mensagem no turno seguinte
- O Claude Code insere informações atualizadas com a tag
<system-reminder> na próxima user message ou no próximo resultado de ferramenta
- Por exemplo, fornece uma atualização de tempo como “agora é Wednesday”
- Assim, ao usar system messages, é possível preservar o cache
Por que não se deve mudar de modelo no meio da sessão
- O cache de prompt é único por modelo, então o cálculo de custo do cache pode ser diferente do que a intuição sugere
- Exemplo: em uma conversa de 100k tokens com Opus, se você trocar para Haiku para responder uma pergunta simples, será necessário reconstruir do zero o cache para Haiku; por isso, pode sair mais caro do que responder com o próprio Opus
- Se for necessário trocar de modelo, a melhor abordagem é via subagente, em que o Opus prepara e envia uma mensagem de "handoff" para outro modelo
- O agente Explore do Claude Code usa essa abordagem ao trabalhar com Haiku
Não adicionar nem remover ferramentas no meio da sessão
- Alterar o conjunto de ferramentas é uma das causas mais comuns de invalidação do cache
- Como as ferramentas fazem parte do prefixo em cache, adicionar ou remover uma única ferramenta invalida o cache da conversa inteira
-
Plan Mode — design centrado no cache
- Abordagem intuitiva: quando o usuário entra em plan mode, deixar apenas ferramentas de leitura → destrói o cache
- Design real: incluir sempre todas as ferramentas na requisição e implementar EnterPlanMode e ExitPlanMode como ferramentas
- Ao entrar em plan mode, instruções são passadas por mensagem de sistema: apenas explorar o codebase, não editar arquivos, e chamar ExitPlanMode ao terminar
- As definições das ferramentas nunca mudam
- Benefício adicional: como EnterPlanMode é uma ferramenta que o modelo pode chamar diretamente, ele também pode entrar autonomamente em plan mode ao detectar um problema difícil, sem destruir o cache
-
Tool Search — carregamento tardio em vez de remoção
- O Claude Code pode carregar dezenas de ferramentas MCP; incluir todas eleva o custo, mas removê-las destrói o cache
- Solução: abordagem defer_loading, enviando stubs leves contendo apenas o nome da ferramenta, em vez de removê-la (
defer_loading: true)
- Quando necessário, o modelo carrega o schema completo por meio da ferramenta ToolSearch
- Como o mesmo stub existe sempre na mesma ordem, o prefixo em cache permanece estável
- Isso pode ser simplificado com a funcionalidade de tool search da API
Fork de contexto — compactação (Compaction)
- Quando a janela de contexto é excedida, faz-se uma compactação para resumir a conversa e iniciar uma nova sessão
- Uma implementação intuitiva (gerar o resumo com uma chamada de API separada, sem o mesmo prompt de sistema e sem as mesmas ferramentas) não coincide em nada com o prefixo em cache da conversa principal, o que faz com que todos os tokens de entrada sejam cobrados integralmente
-
Solução de Cache-Safe Forking
- Ao executar a compactação, usar o mesmo prompt de sistema, contexto do usuário, contexto do sistema e definições de ferramentas da conversa pai
- Colocar as mensagens da conversa pai antes e adicionar o prompt de compactação no final como uma nova mensagem do usuário
- Do ponto de vista da API, essa requisição parece quase idêntica à última requisição da conversa pai, então é possível reutilizar o prefixo em cache, e os únicos novos tokens são os do prompt de compactação
- É necessário garantir, dentro da janela de contexto, um “buffer de compactação” para a mensagem compactada e para os tokens de saída do resumo
- Com base nesse padrão, a Anthropic incorporou diretamente à API uma funcionalidade de compactação, para que desenvolvedores possam aplicá-la diretamente
Resumo das lições principais
- O cache de prompt funciona por correspondência de prefixo; se houver qualquer mudança em qualquer ponto do prefixo, todo o cache dali em diante é invalidado → o sistema inteiro deve ser projetado em torno dessa restrição
- Em vez de alterar o prompt de sistema, inserir mensagens de sistema durante a conversa é mais favorável para preservar o cache
- Não mude ferramentas nem modelo no meio da conversa → modele transições de estado como ferramentas e use carregamento tardio em vez de remover ferramentas
- A taxa de acerto do cache deve ser monitorada como uptime, porque até alguns poucos pontos percentuais de cache miss têm impacto dramático em custo e latência
- Trabalhos de fork (compactação, resumo, execução de skill) precisam compartilhar o prefixo do pai para que o cache possa acertar
- Se você vai construir um agente, precisa projetá-lo com cache de prompt no centro desde o primeiro dia
5 comentários
A chave parece ser a mudança de engenharia de prompt para engenharia de contexto e, na prática, a resposta parece ser a "separação de responsabilidades".
Gerenciar persona, regras de comportamento e memória em arquivos separados é eficaz para reduzir o context rot. Em comparação com um prompt monolítico, carregar apenas os arquivos necessários é muito mais vantajoso para o orçamento de atenção. Por isso, OpenClaw (ou frameworks semelhantes) parecem gerenciar separadamente a persona (
SOUL.md), as regras de comportamento (AGENTS.md) e a memória (MEMORY.md).Ah, então é por isso que o preço por token do Opus é tão caro.
Fiquei curioso para saber se existe alguma análise sobre a diferença no gerenciamento de contexto entre o Antigravity e o Claude Code.
Mesmo sendo o mesmo modelo Opus, com certeza deve haver diferenças. :)
Texto realmente muito útil.
Leitor ideal:
Pessoas que estão criando “agentes de longa execução” como o Claude Code
(especialmente engenheiros de produto/plataforma e engenheiros de infraestrutura de LLM)
Para quem isso é mais útil?
✅ 1) Times que criam produtos de agentes de IA
✅ 2) Engenheiros que otimizam custo/latência de LLM
✅ 3) Pessoas que conectam um monte de ferramentas MCP
Por outro lado, usuários em geral quase não vão ler isso
Não é um texto do tipo “como escrever bons prompts”
É sobre “como tratar prompts no nível da arquitetura do produto”
Resumo em uma linha
É um texto para quem transforma LLM em um “sistema de produção”, e não apenas em “chat”.
Parece não ser diferente de otimização de camadas do Docker.