Reduzindo custos e melhorando o desempenho com a plataforma Claude

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 de 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 solicitação começa com o mesmo prefixo, 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.

Há 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 em todo o 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 é byte-idêntico, no mesmo modelo e usando o mesmo esforço.

Como corrigir

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

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

• Adie ferramentas raramente usadas. Declare todas as suas ferramentas antecipadamente, mas marque as raramente usadas como defer_loading: elas ficam fora do prefixo em cache e são anexadas à conversa apenas quando Claude as procura 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 solicitaçã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 a 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 interrupção do cache à medida que a conversa cresce. Com o Claude Platform, você pode definir o cache automático para aplicar o ponto de interrupção do cache ao último bloco armazenável em cache.
• Pré-aqueça o cache. Para reduzir a latência, envie uma solicitação com max_tokens: 0 e um ponto de interrupção 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 solicitação real atinge um cache aquecido.
• Não exceda o TTL do cache de prompts. O TTL de 5 minutos do cache é contado a partir do início da solicitação. Se um agente bloquear em chamadas de ferramenta ou solicitações de subagente que demorem mais de 5 minutos, o cache do pai expira antes que o resultado retorne. Em casos como este, 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 few-shot 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 solicitaçõ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 em 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 ao duplicar a consulta de pedido em cada reembolso. Os impulsionadores de ênfase ("seja extremamente minucioso") tornaram-se 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 solicitações de roteamento imediatamente. As regras de reembolso contraditórias levaram o Opus 5 a reter quatro reembolsos que eram devidos 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 de seu raciocínio e nunca a executou.

Esforço

Esforço diz ao Claude "o quão difícil trabalhar". Em esforço baixo, Claude geralmente chega a conclusões mais rápido. Em esforço alto, 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 $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 $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 $0,30 por pergunta e cerca de 61% em esforço máximo por cerca de $2,23; o último passo até o máximo adiciona cerca de meio ponto por 46% mais custo. O ganho cai dentro do ruído de execução para execução do benchmark, então você paga mais sem ganho mensurável.

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

• Assumir que maior é sempre melhor. Esforço alto pode causar excesso de pensamento. 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.
• Viesar para esforço baixo. Definido muito baixo, Claude para antes de ter evidências suficientes. Ele faz menos chamadas de ferramenta, então pode responder a partir do primeiro resultado da 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 com 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 por 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 $0,25 por milhão de tokens contra $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 de custo-desempenho plana entre os 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.

Esta 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 com Opus 4.8 em seu esforço padrão (alto). O hillclimber primeiro tentou 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 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, 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 custos holística do código da 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 descobrindo para onde seus tokens vão: a partir dos relatórios de uso e custo da sua organização, se você tiver uma chave da API 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 solicitação e estimando.

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

• LegalBench (~58% menor custo): o cost-optimize propôs armazenar em cache um prefixo compartilhado entre tarefas, definir esforço baixo e processar tarefas via 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% menor custo): Ao implementar o cache de prompts com posicionamento explícito de ponto de interrupção, o cost-optimize reduziu o gasto em 72% enquanto manteve a taxa de aprovação estável.
• OfficeQA Pro (~52% menor custo): o cost-optimize adicionou processamento em lote e cache de documentos, o que reduziu o custo de $136,20 para $64,87.
• SWE-bench Verificado (~55% menor custo): o cost-optimize descobriu que a configuração padrão já armazena em cache corretamente. As economias vieram da definição do esforço para médio e da restrição da saída do agente a apenas algumas frases concisas. As etapas medianas por tarefa foram de 29 para 17 e os tokens de prompt caíram de 75,2M para 33,7M.

Primeiros Passos

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 em 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 custos. Ele traça o gasto de tokens e então testa diferentes alavancas: aplica prompt-audit, mas também verifica maneiras de reduzir o custo via cache de prompts, processamento em lote de trabalhos não supervisionados 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, 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. 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).