Como Claude Code usa prompt caching

Documentation Index

Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

Prompt caching torna Claude Code mais rápido e eficiente em termos de custo. Sem caching, a API reprocessaria seu histórico completo a cada turno. Com caching, ela reutiliza o que já processou e faz apenas o novo trabalho para o que mudou. Claude Code gerencia prompt caching para você, a menos que você desative-o. Ainda é útil saber como o prompt caching funciona, porque algumas ações invalidam o cache e tornam a próxima resposta mais lenta e cara enquanto ele se reconstrói. Esta página cobre quais ações são essas, por que algumas configurações aguardam uma reinicialização para serem aplicadas e como verificar o desempenho do cache quando o uso parece alto.

​

Como o cache é organizado

Cada vez que você envia uma mensagem em Claude Code, ele faz uma nova solicitação de API. O modelo não se lembra de nada entre solicitações, então Claude Code reenvia o contexto completo: o prompt do sistema, seu contexto de projeto, cada mensagem anterior e resultado de ferramenta, e sua nova mensagem. Novo conteúdo é anexado ao final, o que significa que a maior parte de cada solicitação é idêntica à anterior. Prompt caching é como a API evita reprocessar a parte que não mudou. A API faz cache correspondendo ao início de cada solicitação, chamado de prefixo, contra conteúdo que processou recentemente. Em um turno normal, o prefixo é a solicitação anterior inteira e apenas a troca mais recente é nova. A correspondência é exata, então uma mudança em qualquer lugar no prefixo recomputa tudo depois dela. Não há caching por arquivo ou por segmento. Veja como o prompt caching funciona na referência da API para o mecanismo subjacente. Para aproveitar ao máximo a correspondência de prefixo, Claude Code ordena cada solicitação para que o conteúdo que raramente muda entre turnos venha primeiro: Uma mudança na camada de conversa deixa o prompt do sistema e o contexto do projeto em cache. Uma mudança no prompt do sistema invalida tudo, porque todo o conteúdo posterior agora fica atrás de um prefixo diferente. A terceira coluna fornece gatilhos comuns em vez de uma lista exaustiva, e as seções abaixo cobrem o conjunto completo, incluindo conteúdo como estilo de saída que é fixado no início da sessão. A regra de correspondência de prefixo explica a maioria dos comportamentos nesta página. Plan mode e carregamento de skills, por exemplo, anexam suas instruções como mensagens de conversa, então o prefixo em cache permanece intacto. Duas configurações não fazem parte do texto do prompt, então não aparecem na tabela de camadas. Elas se comportam de forma diferente para caching:

• Model: o cache é codificado por modelo, então cada modelo tem seu próprio cache. Trocar modelos recomputa toda a solicitação mesmo quando o conteúdo é idêntico. Veja Trocar modelos abaixo.
• Effort level: não faz parte da chave de cache ou do prompt, então alterá-lo no meio da sessão não tem efeito no cache.

​

Onde o cache reside

O caching acontece no lado do servidor, na infraestrutura que serve seu modelo. Onde fica depende de como você se autentica:

• Chave de API, assinatura Claude ou Claude Platform on AWS: o cache reside na infraestrutura da Anthropic, acessado através da Claude API
• Bedrock ou Vertex AI: o cache reside na infraestrutura de serviço do seu provedor de nuvem
• Foundry: as solicitações são roteadas para a infraestrutura da Anthropic
• ANTHROPIC_BASE_URL personalizado ou LLM gateway: o cache reside onde suas solicitações são encaminhadas, e se o caching funciona depende do gateway

Para o que cada provedor armazena e processa, veja uso de dados. Onde quer que o cache resida, as entradas expiram após um período de inatividade, e Cache lifetime abaixo cobre o TTL e como estendê-lo.

​

Ações que invalidam o cache

Essas ações fazem com que a próxima solicitação perca parte ou todo o cache. Você vê um turno mais lento e mais caro uma única vez, após o qual o novo prefixo é armazenado em cache. A maioria delas é evitável no meio da tarefa uma vez que você sabe que têm um custo. Uma mudança de modelo ou uma reconexão de MCP pode parecer gratuita até você notar o turno mais lento que se segue.

• Trocar modelos
• Conectar ou desconectar um servidor MCP
• Negar uma ferramenta inteira
• Compactar a conversa
• Atualizar Claude Code

​

Trocar modelos

Cada modelo tem seu próprio cache. Trocar com /model significa que a próxima solicitação lê todo o histórico de conversa sem acertos de cache, mesmo que o conteúdo seja idêntico. A configuração de modelo opusplan resolve para Opus durante o modo de plano e Sonnet durante a execução, então cada alternância de modo de plano é uma mudança de modelo e inicia um cache novo.

​

Conectar ou desconectar um servidor MCP

As definições de ferramentas ficam na camada de prompt do sistema, então o cache se invalida quando o conjunto de ferramentas MCP disponíveis para Claude muda entre turnos. A causa mais comum é um servidor MCP se conectando ou desconectando no meio da sessão, o que pode acontecer sem nenhuma ação da sua parte: o processo de um servidor stdio sai, uma sessão HTTP expira ou um servidor se reconecta automaticamente após uma falha transitória. Um servidor conectado também pode enviar uma atualização de ferramenta dinâmica que muda sua lista de ferramentas. Editar sua configuração de MCP não muda o cache por si só. A nova configuração entra em vigor apenas após uma reinicialização, que é quando o servidor se conecta ou desconecta. Busca de ferramentas MCP reduz quanto cada ferramenta contribui para o prefixo adiando definições completas de ferramentas, mas o conjunto de nomes de ferramentas ainda precisa permanecer estável para o cache permanecer válido.

​

Negar uma ferramenta inteira

Adicionar um nome de ferramenta simples como Bash ou WebFetch como uma regra de negação remove essa ferramenta do contexto de Claude completamente. As definições de ferramentas ficam na camada de prompt do sistema, então adicionar ou remover uma dessas regras no meio da sessão invalida o cache da mesma forma que um servidor MCP se conectando ou desconectando faz. A mudança entra em vigor no próximo turno, quer você a adicione através de /permissions ou editando um arquivo de configurações diretamente. Apenas um nome de ferramenta simples, ou a forma equivalente Bash(*), tem esse efeito. Regras de negação com escopo como Bash(rm *), e todas as regras de permissão e pergunta, não mudam quais ferramentas Claude vê. Claude Code as verifica quando Claude tenta fazer uma chamada, deixando o prefixo intacto.

​

Compactar a conversa

Compactação substitui seu histórico de mensagens por um resumo. Por design, isso invalida a camada de conversa, já que a próxima solicitação tem um histórico novo e mais curto que não compartilha um prefixo com o antigo. Claude Code reutiliza a camada de prompt do sistema e recarrega o contexto do projeto do disco, que acerta o cache apenas se CLAUDE.md e memória não mudaram desde o início da sessão. Para produzir o resumo, Claude Code envia uma solicitação única com o mesmo prompt do sistema, ferramentas e histórico que sua conversa, mais uma instrução de resumo anexada como uma mensagem de usuário final. Como compartilha seu prefixo, essa solicitação lê o cache existente em vez de reprocessar o histórico completo. A maior parte do tempo de compactação vai para gerar o resumo, não para um acerto de cache perdido. O turno que se segue reconstrói o cache de conversa apenas para o resumo muito mais curto, então o turno pós-compactação não é a parte lenta.

​

Atualizar Claude Code

Uma nova versão de Claude Code normalmente atualiza o prompt do sistema ou definições de ferramentas, então a primeira solicitação após uma atualização reconstrói o cache do início. Auto-update baixa novas versões em segundo plano, mas as aplica no próximo lançamento, nunca no meio da sessão, então você vê isso como um primeiro turno sem cache após reiniciar em vez de uma surpresa durante uma sessão. Defina DISABLE_AUTOUPDATER=1 para controlar quando as atualizações se aplicam.

​

Ações que mantêm o cache

Essas ações ou anexam ao final da conversa ou não tocam a solicitação. Algumas delas, como editar CLAUDE.md ou alterar o estilo de saída, também são o motivo pelo qual uma mudança de configuração aguarda uma reinicialização para ser aplicada.

• Editar arquivos em seu repositório
• Editar CLAUDE.md no meio da sessão
• Alterar estilo de saída
• Alterar modo de permissão
• Invocar skills e comandos
• Executar /recap
• Rewind da conversa
• Spawning de um subagent

​

Editar arquivos em seu repositório

O conteúdo do arquivo entra em contexto apenas quando Claude o lê, e as leituras se anexam à conversa. Editar um arquivo que Claude leu anteriormente não muda retroativamente a leitura anterior no histórico. Em vez disso, Claude Code anexa um <system-reminder> observando que o arquivo mudou, e Claude o relê se necessário.

​

Editar CLAUDE.md no meio da sessão

Seus arquivos CLAUDE.md de raiz de projeto e nível de usuário são lidos uma vez no início da sessão e mantidos na memória. Editá-los no meio da sessão não invalida o cache, mas a edição também não se aplica. Claude continua trabalhando com a versão que foi carregada no início da sessão. O novo conteúdo carrega no próximo /clear, /compact ou reinicialização. Arquivos CLAUDE.md aninhados em subdiretórios e regras com frontmatter paths: carregam depois, quando Claude primeiro lê um arquivo correspondente. Editar um antes de carregar tem efeito. Depois de carregar, o conteúdo faz parte do histórico de conversa, então uma edição no meio da sessão não muda retroativamente.

​

Alterar estilo de saída

Estilo de saída faz parte do prompt do sistema, que Claude Code lê uma vez no início da sessão. Alterá-lo via /config ou a configuração outputStyle no meio da sessão não invalida o cache, mas a mudança também não se aplica. Claude continua usando o estilo que foi carregado no início da sessão. O novo estilo carrega no próximo /clear ou reinicialização.

​

Alterar modo de permissão

Alternar entre modos de permissão, como de padrão para aceitar edições, não muda o prompt do sistema ou definições de ferramentas, então mudanças de modo são seguras para cache. A exceção é o modo de plano com a configuração de modelo opusplan, que alterna o modelo entre Opus e Sonnet conforme você entra ou sai do modo de plano. Isso torna a alternância de modo uma mudança de modelo.

​

Invocar skills e comandos

Skills e comandos injetam suas instruções como mensagens de usuário no ponto de invocação. Nada anterior na conversa muda.

​

Executar /recap

/recap gera um resumo para exibição em seu terminal. Ao contrário de /compact, ele anexa o resumo como saída de comando em vez de substituir seu histórico de mensagens, então o prefixo em cache permanece intacto.

​

Rewind da conversa

/rewind trunca sua conversa de volta para um turno anterior. O histórico restante é o mesmo conteúdo do qual o cache foi construído naquele ponto, e as camadas de prompt do sistema e contexto do projeto não mudam, então a próxima solicitação acerta a entrada de cache anterior. Cada turno desde então leu através desse prefixo, que manteve a entrada aquecida mesmo se o turno original foi há mais tempo do que o TTL. Restaurar checkpoints de arquivo junto com a conversa não tem efeito separado no cache. O conteúdo do arquivo entra em contexto apenas quando Claude o lê, o mesmo que editar arquivos em seu repositório.

​

Cache lifetime

Prefixos em cache expiram após um período de inatividade. Cada solicitação que acerta o cache redefine o temporizador, então o cache permanece aquecido enquanto você continua trabalhando. Após um intervalo longo o suficiente, a próxima solicitação recomputa a entrada completa e reestabelece o cache, o que é por que o primeiro turno de volta após se afastar pode ser notavelmente mais lento. O tempo de vida (TTL) controla quanto tempo um intervalo o cache sobrevive. A API oferece dois: um TTL de cinco minutos e um TTL de uma hora que mantém o cache aquecido através de pausas mais longas, mas cobra gravações de cache a uma taxa mais alta. Claude Code escolhe o TTL para você com base em como você se autentica, e você pode substituí-lo com variáveis de ambiente.

​

Em uma assinatura Claude

Em uma assinatura Claude, Claude Code solicita o TTL de uma hora automaticamente. O uso é incluído em seu plano em vez de ser cobrado por token, então o TTL mais longo não custa nada extra e apenas afeta quanto tempo seu cache permanece aquecido. Se você ultrapassou o limite de uso do seu plano e Claude Code está usando créditos de uso, você é cobrado por esse uso, então Claude Code automaticamente reduz o TTL para cinco minutos.

​

Em uma chave de API ou provedor de terceiros

Em uma chave de API, Bedrock, Vertex, Foundry ou Claude Platform on AWS, você paga as taxas por token, então o TTL permanece nos cinco minutos mais baratos por padrão. Para optar pelo TTL de uma hora, defina ENABLE_PROMPT_CACHING_1H=1. No Bedrock, suporte a prompt caching, comprimento mínimo de prefixo armazenável em cache e disponibilidade de TTL de uma hora variam por modelo. Se as contagens de tokens de cache permanecerem em zero, verifique modelos, regiões e limites suportados na documentação do Bedrock.

​

Substituir o TTL

Defina FORCE_PROMPT_CACHING_5M=1 para forçar o TTL de cinco minutos independentemente da autenticação. Isso é útil quando você está depurando o comportamento do cache, comparando os dois TTLs ou substituindo um ENABLE_PROMPT_CACHING_1H definido em configurações gerenciadas.

​

Escopo do cache

Em Claude Code, o cache é efetivamente limitado a uma máquina e diretório. O prompt do sistema incorpora o diretório de trabalho, plataforma, shell, versão do SO e caminhos de memória automática, então duas sessões em diretórios diferentes constroem prefixos diferentes e perdem o cache uma da outra. Isso inclui worktrees do mesmo repositório, já que cada worktree tem seu próprio diretório de trabalho. Sessões que você executa em paralelo no mesmo diretório constroem prefixos correspondentes e leem o cache uma da outra. Sessões sequenciais compartilham o prefixo apenas quando o snapshot de status git na inicialização corresponde, já que o prompt do sistema também captura branch e commits recentes. O cache de API subjacente é mais amplo. Os caches são isolados entre organizações e, em alguns provedores, entre workspaces dentro de uma organização. Dentro desses limites, quaisquer duas solicitações com o mesmo modelo e prefixo leem o mesmo cache. Para chamadores do Agent SDK executando frotas de processos automatizados, veja melhorar prompt caching entre usuários e máquinas para suprimir as seções por máquina do prompt do sistema e compartilhar o cache entre máquinas.

​

Verificar desempenho do cache

O desempenho do cache aparece como duas contagens de tokens que a API relata em cada resposta. A forma mais direta de observá-los ao vivo é um script de statusline que lê o objeto current_usage: Uma alta proporção de leitura para criação significa que o caching está funcionando bem. Se a criação permanecer alta turno após turno, algo está mudando em seu prefixo. A seção ações que invalidam o cache lista as causas usuais. Para visibilidade em toda uma organização, o exportador OpenTelemetry relata tokens de leitura e criação de cache por usuário e sessão. Veja Monitorar uso para a referência de métrica e atributo de evento.

​

Subagents e o cache

Um subagent inicia sua própria conversa com seu próprio prompt do sistema e conjunto de ferramentas, separado do pai. Ele constrói seu próprio cache, começando sem acertos de cache em sua primeira chamada e aquecendo através de seus próprios turnos. Subagents usam o TTL de cinco minutos mesmo em uma assinatura, já que o TTL automático de uma hora se aplica à conversa principal. O cache do pai não é afetado. Do lado do pai, a chamada e resultado do subagent se anexam à conversa, deixando o prefixo do pai intacto. Um fork, por contraste, herda o prompt do sistema, ferramentas e histórico de conversa do pai exatamente, então sua primeira solicitação lê o cache do pai. A chamada de resumo de compactação descrita em Compactar a conversa usa a mesma abordagem de compartilhamento de prefixo.

​

Desabilitar prompt caching

Desabilitar caching é ocasionalmente útil ao depurar comportamento de caching com um modelo ou provedor específico. Para desativá-lo, defina uma dessas variáveis de ambiente como 1: Para definir a política de caching em toda uma organização, coloque qualquer uma dessas ou as variáveis de TTL no bloco env de configurações gerenciadas. Para uso normal, deixe o caching habilitado.

​

Recursos relacionados

• Lições de construir Claude Code: Prompt caching é tudo: a lógica de design para modo de plano, carregamento de ferramentas adiado e compactação
• Explorar a janela de contexto: o que carrega em contexto e quando
• Reduzir uso de tokens: estratégias além de caching para gerenciar tamanho de contexto
• Rastrear e reduzir custos: rastreamento de tokens de cache e configuração de TTL para chamadores do Agent SDK
• Prompt caching: o mecanismo de API subjacente, breakpoints e preços