Reduzindo custos e melhorando o desempenho com a Claude Platform

Ajustar o cache de prompts, as instruções e o esforço pode reduzir o custo do Claude sem sacrificar o desempenho da aplicação.

Desempenho e custo são frequentemente vistos como uma troca: para gastar menos, você aceita resultados piores. Na prática, descobrimos que muitas aplicações que usam o Claude Platform podem reduzir custos sem abrir mão do desempenho com três correções: maximizar a taxa de acerto do cache de prompts, remover anti-padrões dos seus prompts ao atualizar para modelos Claude de fronteira e calibrar o esforço para a tarefa. Colocamos essa orientação na habilidade claude-api. Neste artigo, mostramos como o Claude Code com a habilidade claude-api pode frequentemente encontrar maneiras de reduzir custos enquanto mantém ou melhora o desempenho.

Cache de prompts

Antes do Claude gerar uma resposta, ele primeiro processa seu prompt em um estado de trabalho interno. Esta etapa, chamada de preenchimento, é a parte cara do processamento da entrada. O cache de prompts salva esse estado (o cache de chave-valor, ou KV): quando uma requisição começa com o mesmo prefixo, o Claude o lê de volta em vez de recomputá-lo. As leituras de cache são cobradas a uma fração do preço total da entrada.

Existem algumas considerações práticas para garantir o uso eficaz do cache de prompts. Primeiro, o cache de prompts está vinculado a um modelo específico. Segundo, as leituras do cache de prompts devem ser exatas em bytes no prefixo. Finalmente, o cache de prompts tem um tempo de vida limitado (TTL).

Com esses pontos em mente, aqui estão algumas dicas práticas:

• Tenha cuidado ao alterar a configuração de esforço no meio da conversa. Essas configurações são renderizadas no prompt antes do seu conteúdo, então fazem parte do prefixo em cache. Apenas com modelos Claude selecionados, incluindo Opus 5 e Fable 5.1, você pode atualizar o esforço no meio da conversa sem quebrar o cache.
• Mantenha valores voláteis fora do prefixo. Um timestamp ou ID dinâmico no prompt do sistema pode mudar entre chamadas de modelo e quebrar o cache.
• Evite definições de ferramentas que se reordenam. Ao usar a API de mensagens do Claude, o prompt é montado em uma ordem fixa com as definições de ferramentas renderizadas no topo. Qualquer alteração na definição da ferramenta quebrará o cache.
• Tenha cuidado ao bifurcar conversas. Subagentes e ramificações só compartilham o cache do pai quando o prefixo da bifurcação é idêntico em bytes, no mesmo modelo e usando o mesmo esforço.

Como corrigir

Acumulamos algumas lições para o gerenciamento do cache de prompts:

• Monitore sua taxa de acerto do cache de prompts cuidadosamente. O Claude Console e a API de diagnóstico de cache fornecem diagnósticos do cache de prompts, incluindo motivos para falhas no cache de prompts (Figura 1) e exatamente onde duas requisições divergiram.

• Adie ferramentas raramente usadas. Declare todas as suas ferramentas antecipadamente, mas marque as raramente usadas com defer_loading: elas ficam fora do prefixo em cache e são anexadas à conversa apenas quando o Claude as consulta com a pesquisa de ferramentas, preservando assim o cache.
• Aplique atualizações no prompt do sistema como mensagens. Certos modelos Claude permitem adicionar uma instrução do sistema como uma mensagem no meio da conversa, em vez de editar o prompt do sistema, o que preserva o cache.
• Organize a requisição para que a parte estável permaneça estável. Adicione o contexto estático (definições de ferramentas e o prompt do sistema) primeiro e a conversa crescente atrás deles (Figura 2).

• Faça alterações no modelo ou esforço quando o cache de prompts já estiver quebrado. Certas operações, como compactação, já reescrevem grande parte do cache (a conversa). Esse é um bom momento para trocar de modelo ou esforço, já que você está pagando por uma falha de qualquer maneira.
• Mova o ponto de ruptura do cache à medida que a conversa cresce. Com o Claude Platform, você pode definir cache automático para aplicar o ponto de ruptura do cache ao último bloco armazenável em cache.
• Pré-aqueça o cache. Para reduzir a latência, envie uma requisição com max_tokens: 0 e um ponto de ruptura de cache explícito, usando a mesma configuração de esforço do seu tráfego real. Isso processa o prompt e o escreve no cache sem gerar nada. Se você executá-lo no início da sessão (por exemplo, enquanto um usuário está digitando), a primeira requisição real atinge um cache aquecido.
• Não exceda o TTL do cache de prompts. O TTL de 5 minutos do cache conta a partir do início da requisição. Se um agente bloquear em chamadas de ferramenta ou requisições de subagente que demorem mais de 5 minutos, o cache do pai expira antes do resultado retornar. Nesses casos, considere definir um TTL de 1 hora no prefixo.

Instruções

Os prompts podem acumular instruções que corrigem fraquezas do modelo. Essas instruções podem se desviar em relação às capacidades dos modelos Claude mais recentes. Aqui estão alguns "anti-padrões" comuns de prompting que prejudicam os modelos Claude de fronteira e podem aumentar inadvertidamente os custos:

• Rituais de verificação. Instruções como "verifique seu trabalho" ou "verifique duas vezes antes de responder" são frequentemente levadas ao pé da letra por modelos de fronteira e podem desperdiçar tokens.
• Impulsionadores de minúcia e ênfase. "Seja extremamente minucioso", "CRÍTICO: VOCÊ DEVE SEMPRE…" podem levar à verbosidade e chamadas extras de ferramentas ao trabalhar com modelos de fronteira.
• Procedimentos obrigatórios e estruturas de rascunho. Processos de etapas fixas (por exemplo, "pense passo a passo em um rascunho") ou modelos de raciocínio são rituais que os modelos de fronteira não precisam. Essa estruturação pode se sobrepor ao raciocínio nativo e usar tokens desnecessários.
• Exemplos desatualizados. Exemplos de poucas tentativas ajustados para os modos de falha de um modelo mais antigo podem ensinar um modelo de fronteira a imitar longas cadeias de raciocínio em requisições que não precisam delas.
• Regras contraditórias. Modelos de fronteira são melhores em seguir instruções. Instruções contraditórias ("sempre reembolse dentro da política" vs. "nunca emita reembolsos sem escalação") podem ser seguidas mais literalmente por modelos de fronteira, resultando em desempenho degradado.
• Configuração desatualizada. Configurações escritas para uma geração mais antiga do Claude (por exemplo, orçamentos de pensamento manuais) podem ser rejeitadas pelo Claude Platform com modelos mais novos.

Como corrigir

Atualizamos a habilidade claude-api com um novo comando que fica atento a esses anti-padrões. No Claude Code, execute /claude-api prompt-audit em seus prompts, habilidades ou descrições de ferramentas. A auditoria cobre qualquer coisa no seu diretório de trabalho, incluindo código de aplicação que chama a API do Claude e a própria configuração do Claude Code (por exemplo, CLAUDE.md ou habilidades).

Por exemplo, testamos uma migração de modelo do Opus 4.8 para o Opus 5 em um benchmark de suporte ao cliente. Começamos com um prompt limpo e plantamos um anti-padrão de cada vez (uma configuração de pensamento aposentada, um par de regras de reembolso contraditórias, um rascunho manual, "verifique duas vezes", "seja extremamente minucioso" e um procedimento obrigatório de seis etapas), resultando em seis prompts legados.

Executamos cada um no Opus 4.8, no Opus 5 com apenas o ID do modelo alterado e no Opus 5 após executar /claude-api prompt-audit uma vez por prompt (a Figura 3 mostra a média dos seis).

Com o Opus 5, os rituais de verificação ("verifique duas vezes") usam tokens desnecessários duplicando a consulta de pedido em cada reembolso. Os impulsionadores de ênfase ("seja extremamente minucioso") se tornaram dezenas de pesquisas desnecessárias na base de conhecimento.

Executar /claude-api prompt-audit removeu os anti-padrões, diminuindo os custos em 14,6% e aumentando a precisão em 5,3% em média. O custo caiu porque chamadas extras de ferramentas e raciocínio duplicado foram eliminados. A precisão aumentou por três razões. A configuração de pensamento aposentada fez a API rejeitar todas as requisições de roteamento imediatamente. As regras de reembolso contraditórias levaram o Opus 5 a reter quatro reembolsos que devia enquanto pedia ao cliente para confirmar. E o rascunho manual colidiu com o pensamento integrado do Opus 5: em três tickets, ele escreveu a chamada de ferramenta dentro do seu raciocínio e nunca a executou.

Esforço

Esforço diz ao Claude "o quão difícil trabalhar". Em esforço baixo, o Claude geralmente chega a conclusões mais rápido. Em esforço alto, o Claude delibera, verifica e explora alternativas antes de responder.

O custo versus desempenho entre níveis de esforço em um único modelo pode variar. Por exemplo, o Claude Fable 5 pontua 11,5% em esforço baixo por US$ 5,35 por tarefa no FrontierCode Diamond (as 50 tarefas mais difíceis). Em esforço máximo, o Fable 5 obtém 30,9% por US$ 19,00 por tarefa; mudar o esforço aumenta a pontuação cerca de 2,7x (+19 pontos) por cerca de 3,5x o custo (Figura 4).

No Claude Fable 5.1, o Humanity's Last Exam (sem ferramentas) mostra uma curva íngreme com um último passo decrescente. Ele pontua cerca de 53% em esforço baixo por cerca de US$ 0,30 por pergunta e cerca de 61% em esforço máximo por cerca de US$ 2,23; o último passo até o máximo adiciona cerca de meio ponto por 46% mais custo. O ganho fica dentro do ruído de execução para execução do benchmark, então você paga mais por nenhum ganho mensurável.

O esforço pode ser mal calibrado em qualquer direção:

• Assumir que mais alto é sempre melhor. Esforço alto pode causar excesso de pensamento. O Claude gasta mais tempo deliberando do que a tarefa justifica, o que adiciona custo e latência, e pode degradar a qualidade da resposta. A deliberação só ajuda enquanto ainda há evidências a serem encontradas.
• Tendenciar para esforço baixo. Definido muito baixo, o Claude para antes de ter evidências suficientes. Ele faz menos chamadas de ferramentas, então pode responder a partir do primeiro resultado de pesquisa em vez do terceiro. Ele pensa menos em etapas difíceis e pula a verificação que normalmente executaria por conta própria. A resposta parece completa, mas é construída com informações parciais.

Como corrigir

Existem algumas maneiras úteis de calibrar o esforço:

• Teste modelos mais fortes em esforço mais baixo. Um modelo mais forte em esforço baixo pode ser mais barato do que um modelo mais fraco trabalhando duro (esforço alto). Por exemplo, no CursorBench 3.2, o Claude Fable 5.1 em esforço baixo corresponde ao desempenho do Fable 5 em esforço alto a um terço do custo (Figura 5). Duas coisas tornam o modelo mais novo mais barato: em esforço baixo, ele faz menos trabalho por tarefa, e as leituras de cache de prompt do Fable 5.1 são precificadas em US$ 0,25 por milhão de tokens contra US$ 1,00 do Fable 5. Mesmo aos preços do Fable 5, o Fable 5.1 em esforço baixo custaria cerca de 40% menos.

• Entenda a forma da sua tarefa. Medir o desempenho da aplicação em uma varredura de níveis de esforço é uma maneira útil de entender a troca custo-desempenho para sua tarefa específica. Em uma avaliação não saturada, uma curva plana de custo-desempenho entre níveis de esforço sugere que a tarefa não é limitada pelo poder de computação do pensamento; aumentar o esforço não é benéfico.

Essa calibração geralmente envolve executar uma avaliação entre modelos e níveis de esforço. No Claude Code, /claude-api hillclimb realiza essa busca para você: ele divide sua avaliação em conjuntos de treino e teste, propõe mudanças de configuração e lê exemplos de treino com falha para corrigir o que encontra.

Executamos isso em um benchmark de suporte ao cliente, começando do Opus 4.8 em seu esforço padrão (alto). O hillclimber primeiro tentou o Opus 5 em esforço baixo, aplicando prompt-audit para remover rituais obrigatórios de chamada de ferramenta, etapas de rascunho e regras contraditórias. Isso superou a linha de base do Opus 4.8 com 98,9% de precisão no treino e reduziu o custo para 2,6 centavos por ticket (Figura 6).

Em seguida, ele desceu para o Sonnet 5 em esforço baixo, que era ainda mais barato a 1 centavo por ticket, mas a precisão caiu para 88,9%. Lendo os tickets de treino com falha, o Claude adicionou regras de roteamento e uma referência cruzada de limite de reembolso ao prompt, trazendo o Sonnet 5 de volta para 98,9% pelo mesmo custo.

Nos 14 tickets retidos que a busca nunca viu, a configuração final pontuou 90,5% contra os 78,6% da configuração original, a cerca de um quinto do custo.

Automatizando a redução de custos

Cache de prompts, instruções e esforço são alavancas comuns para reduzir custos. Nossa documentação cobre ainda mais. Para executar uma auditoria de custo holística do código de aplicação que usa a API do Claude, adicionamos /claude-api cost-optimize: ele traça para onde vai seu gasto, aplica reduções de custo e, se você fornecer uma avaliação, mostra como as economias se equilibram com o desempenho.

O cost-optimize começa encontrando para onde vão seus tokens: a partir dos relatórios de uso e custo da sua organização, se você tiver uma chave da API de Admin do Claude, a partir do objeto de uso em cada resposta da API, se sua aplicação o registrar, ou, na falta de ambos, lendo seu código de construção de requisição e estimando.

Ele então classifica as economias disponíveis, começando com o cache de prompts, aparando o que cada requisição carrega (incluindo um prompt-audit), limitando a saída e processamento em lote de trabalho não supervisionado. Se você fornecer uma avaliação, ele vai além e calcula custo e desempenho entre níveis de esforço e escolhas de modelo. Executamos isso em quatro benchmarks públicos com o Sonnet 5 como linha de base (Figura 7):

• LegalBench (~58% de custo menor): o cost-optimize propôs armazenar em cache um prefixo compartilhado entre tarefas, definir esforço baixo e processar tarefas via a API de Lote. Os tokens de pensamento caíram de 102.779 para 8.284 e a taxa de aprovação permaneceu dentro do ruído, e o custo caiu ~58%.
• tau2-bench varejo (~73% de custo menor): Ao implementar o cache de prompts com posicionamento explícito do ponto de ruptura, o cost-optimize reduziu o gasto em 72% enquanto manteve a taxa de aprovação estável.
• OfficeQA Pro (~52% de custo menor): o cost-optimize adicionou processamento em lote e cache de documentos, o que reduziu o custo de US$ 136,20 para US$ 64,87.
• SWE-bench Verificado (~55% de custo menor): o cost-optimize descobriu que a configuração padrão já armazena em cache corretamente. As economias vieram de definir o esforço para médio e restringir a saída do agente a apenas algumas frases concisas. O número mediano de etapas por tarefa foi de 29 para 17 e os tokens de prompt caíram de 75,2M para 33,7M.

Começando

Comece com /claude-api prompt-audit quando você tiver migrado para um modelo Claude de fronteira e quiser verificar seus prompts existentes. Ele escaneia os prompts, habilidades e descrições de ferramentas no seu diretório de trabalho. Isso pode ser código de aplicação que chama a API do Claude ou a configuração do Claude Code (CLAUDE.md, habilidades). Ele remove anti-padrões comuns que prejudicam modelos de fronteira.

Recorra a /claude-api cost-optimize quando sua aplicação usar a API do Claude e você quiser uma auditoria de custo. Ele traça o gasto de tokens e então testa diferentes alavancas: aplica prompt-audit, mas também verifica maneiras de reduzir custo via cache de prompts, processamento em lote de trabalho não supervisionado ou limitação da saída. Se você fornecer uma avaliação, ele mede as trocas de esforço e seleção de modelo.

Finalmente, use /claude-api hillclimb para uma busca sobre custo e desempenho. Dada uma avaliação, o Claude a divide em conjuntos de treino e teste, então propõe atualizações para sua aplicação que visam reduzir o custo enquanto mantêm o desempenho da linha de base. O Claude lê os casos de treino com falha para guiar a busca, e a configuração final é pontuada no conjunto de teste retido.

Para saber mais:

• Veja nossa documentação aqui
• Veja nosso livro de receitas de redução de custos aqui
• Veja a habilidade claude-api aqui; a habilidade também está integrada ao Claude Code
• Veja este artigo no Blog do Claude aqui

Escrito por Lance Martin (@RLanceMartin), Brad Abrams (@brada), Isabella He (@IsabellaKHe) e Ben Lehrburger (@benlehrburger).