O Claude Code oferece duas configurações que parecem "melhorar a resposta": o modelo e o nível de esforço. Mas o que elas realmente fazem na saída? E como saber se você deve usar um modelo diferente ou apenas alterar o nível de esforço?
É fácil supor que escolher um modelo maior, como o Fable, oferece uma resposta mais inteligente que o Sonnet, e que um nível de esforço maior significa apenas que o Claude pensa por mais tempo antes de responder.
A primeira suposição é verdadeira. Nossos maiores modelos são mais capazes, de acordo com benchmarks padrão da indústria.
Mas esforço significa mais do que "tempo de pensamento". O esforço controla quanto trabalho o Claude faz na sua solicitação como um todo. Isso inclui quanto tempo ele pensa, mas também:
- quantos arquivos ele lê;
- quanto ele verifica; e
- até onde ele avança em uma tarefa de várias etapas antes de consultar você.
Com esforço maior, o Claude realiza mais dessas ações (ler arquivos, executar testes, verificar novamente) antes de retornar a você. Com esforço menor, ele prefere pedir mais contexto do que gastar tokens para descobrir algo sozinho.
Como funciona a seleção do modelo
Para entender o que a configuração do modelo realmente controla, é útil começar do início, a partir do momento em que você pressiona Enter.
O Claude Code monta sua mensagem junto com o prompt do sistema, as definições de ferramentas, seu CLAUDE.md, o histórico da conversa e quaisquer arquivos no contexto. Tudo isso é enviado como uma única solicitação para a API.
Tudo o que o Claude Code tem é empacotado em uma única solicitação de API. No servidor, o texto é tokenizado antes de chegar ao modelo.
O modelo nunca vê nada disso como texto simples. A primeira coisa que acontece no servidor é a tokenização: o texto é dividido em partes, e cada parte é mapeada para um inteiro de um vocabulário fixo com o qual o modelo foi treinado. const pode ser mapeado para 1978, await pode ser mapeado para 4293. A partir daqui, seu prompt é um array de inteiros.
O tokenizador divide seu texto em partes e mapeia cada parte para um inteiro em um vocabulário fixo. Cada bloco na linha superior se torna seu ID de token (linha inferior); os IDs mostrados são ilustrativos.
O trabalho do modelo é pegar esse array e prever qual token vem em seguida. Ele faz isso calculando uma probabilidade para cada token em seu vocabulário e escolhendo entre os principais. Depois de "const x = await", um modelo bem treinado coloca alta probabilidade em "fetch" (muito provável) e quase zero em "banana" (nada provável).
A previsão do modelo é uma probabilidade para cada token em seu vocabulário. A diferença entre o palpite principal e um não relacionado é enorme.
O que transforma seus tokens de entrada nessas probabilidades são os pesos (também chamados de parâmetros): bilhões de números organizados em grandes matrizes. Para prever um token, o modelo executa sua entrada através dessas matrizes (uma longa cadeia de multiplicações de matrizes) e lê as probabilidades no final. Os pesos são onde tudo o que o modelo "sabe" reside.
Os pesos de cada modelo são definidos durante o treinamento e, no momento em que você envia solicitações, eles são somente leitura. Nada no seu prompt, no seu CLAUDE.md ou no seu contexto os altera. Se você já se deparou com a palavra inferência, é só isso: usar o modelo após o treinamento, com os pesos fixos.
Seu prompt entra, probabilidades saem. Os pesos no meio não mudam.
Tudo o que o Claude sabe sobre TypeScript, frameworks populares ou qualquer outro conhecimento geral de programação foi codificado nesses pesos durante o treinamento.
Seu prompt e contexto ainda podem direcionar a previsão. Colocar seu código real na frente do Claude é direcionamento, e funciona muito bem. No entanto, isso não adiciona nada aos pesos em si.
Se uma biblioteca não existia quando o modelo foi treinado, ela não está nos pesos. Você pode colocar a documentação no contexto e o Claude a usará, mas isso é direcionamento, não aprendizado. A resposta do Claude é influenciada apenas para aquela solicitação específica, mas o modelo subjacente não reteve nada.
Quando o Claude chama com confiança uma API que não existe (uma alucinação), são os pesos produzindo uma sequência de tokens que parece plausível a partir dos padrões de treinamento, não uma consulta com falha.
Então, o que realmente muda ao alterar o modelo? Ele troca qual conjunto de pesos congelados** lida com sua solicitação.
O modelo não gera uma resposta inteira de uma vez. Ele prevê um token, anexa-o à sequência e executa todo o cálculo novamente para obter o próximo. Uma resposta de 200 tokens são 200 passagens separadas pelos pesos. Esse loop é de onde vem a maior parte do seu tempo de espera (e do seu custo de saída).
A sequência cresce exatamente um token por etapa. O modelo relê todo o array a cada vez para prever o que vem a seguir.
A configuração do modelo decide quais pesos lidam com sua solicitação e também decide quanto custa cada token de saída.
O que ela não decide é quantos tokens são gerados. Esse número pode variar muito para o mesmo prompt, dependendo de quanto trabalho o Claude decide fazer.
Que é exatamente o que o esforço controla.
Como funciona o esforço
Enquanto o Claude Code trabalha em uma tarefa, os tokens que ele gera se enquadram em algumas categorias:
- Raciocínio: o raciocínio que você vê sendo transmitido antes e entre as ações.
- Chamadas de ferramenta: blocos estruturados nomeando uma ferramenta como Read ou Edit e seus argumentos, que o Claude Code então analisa e executa.
- Texto para você: o plano, atualizações de progresso, o resumo no final.
Todos esses são tokens de saída comuns do mesmo loop, cobrados na mesma taxa. Tokens de raciocínio, por exemplo, são gerados exatamente como os outros tokens de saída e permanecem no contexto pelo resto daquela rodada.
Quando o Claude passa a escrever código, seu raciocínio anterior faz parte da entrada, assim como um arquivo que ele leu.
Toda a saída do Claude são tokens. Raciocínio, chamadas de ferramenta e texto para você são todos gerados a partir do mesmo loop.
Então, como o esforço muda isso? O nível de esforço é enviado para o modelo como parte da solicitação, junto com seu prompt. O modelo foi treinado para entender como se comportar em cada nível de esforço, e esse comportamento aprendido está embutido nos pesos congelados.
Quando sua solicitação chega, o esforço é apenas mais uma entrada à qual o modelo responde, da mesma forma que responde ao texto do seu prompt. Ele define o quão minucioso, e quão certo, o Claude precisa estar antes de considerar a tarefa concluída. Isso é ponderado a cada rodada, e uma confiança maior requer mais tokens para ser alcançada.
Mesmo prompt, dois níveis de esforço. O caminho de alto esforço gera aproximadamente 7x mais tokens para alcançar uma resposta de maior confiança.
Em níveis de esforço mais altos, o Claude geralmente começa criando um plano, e o nível de esforço influencia a profundidade e amplitude desse plano. Mas o plano não é fixo. À medida que o Claude obtém resultados de suas ações, ele atualiza sua visão de quanto progresso fez e quão certo está do resultado acumulado.
Quando a etapa 1 de um plano de depuração de três hipóteses encontra o bug, "investigar hipóteses 2 e 3" pode não ser mais necessário. O Claude geralmente diz isso explicitamente (por exemplo, "a primeira verificação encontrou, então as verificações restantes não são necessárias") e pula adiante. Você vê isso acontecer no Claude Code quando as listas de tarefas são revisadas durante a execução.
Um esforço maior torna o Claude mais propenso a verificar novamente, como verificar a resposta que encontrou, ou ainda investigar as hipóteses que ele poderia ter pulado. No entanto, ele geralmente não inflará artificialmente o uso em uma tarefa simples só porque o nível de esforço está aumentado. "Pensar demais" é algo que nossa equipe monitora especificamente durante o treinamento do modelo, pois degrada a eficácia.
Escolhendo um nível de esforço
Para a maioria das tarefas, use o nível de esforço padrão do modelo. O padrão é o nível onde o Claude dimensiona seu uso de tokens para o que a maioria das pessoas gostaria de gastar em uma tarefa.
Pense no esforço como uma substituição manual de quão duro e por quanto tempo o Claude trabalha. Use-o deliberadamente quando você tiver uma forte preferência por minúcia ou velocidade com base no seu domínio ou no tipo de trabalho que você faz, e trate-o como uma preferência geral, não uma decisão tarefa por tarefa.
Uma observação prática após o lançamento do Opus 4.8: em nossos testes, a configuração de esforço padrão no Opus 4.8 produz melhores resultados por aproximadamente a mesma quantidade de tokens que a configuração de esforço padrão no Opus 4.7 na mesma tarefa.
O que mudar quando o Claude erra
Quando o Claude erra algo, seu primeiro instinto não deve ser mudar uma configuração. Deve ser olhar para o contexto que você deu a ele. Seu prompt é muito vago? O Claude está conectado às ferramentas certas? Ele tem as habilidades certas?
Se você está aumentando o esforço em uma tarefa que não deveria precisar dele, a correção geralmente está a montante: no seu contexto, no seu CLAUDE.md ou em como a tarefa é definida.
Mas digamos que você deu um contexto claro e o Claude ainda errou. A pergunta a se fazer é: ele não tentou o suficiente, ou ele não sabia o suficiente?
Modelo: o problema era difícil demais
Escolha um modelo maior quando o problema é genuinamente difícil, como bugs sutis, domínios desconhecidos, decisões de arquitetura. Um modelo maior é o que você quer quando o modelo menor está confiantemente errado, não importa quanto contexto você dê a ele.
Modelos maiores também são melhores em lidar com ambiguidade. Em modelos menores, instruções específicas que direcionam a execução são uma receita melhor para o sucesso.
Escolha um modelo menor quando o trabalho é rotineiro: edições que você pode descrever com precisão, alterações mecânicas, perguntas sobre código que já está no contexto. Não há razão para pagar por capacidade que a tarefa não precisa.
Se o Claude tinha todo o contexto pertinente, tentou claramente e ainda errou, esse é um sinal para escolher um modelo maior. E se você está no modelo maior e o trabalho tem sido rotineiro por um tempo, reduzir aumentará a velocidade e tipicamente reduzirá o custo sem impactar a qualidade da saída.
Esforço: Claude não tentou o suficiente
Escolha um nível de esforço maior se o Claude errou por não tentar o suficiente: pulando um arquivo, não executando os testes ou não verificando seu trabalho. Isso é mais relevante se você selecionou um nível de esforço abaixo do padrão do modelo.
O especialista, o expert e o generalista
Uma maneira que gosto de pensar sobre as duas configurações é que o Fable é um especialista que pode lidar com problemas que quase ninguém mais consegue, o Opus é o expert, e o Sonnet é um generalista muito bom. O nível de esforço decide quanto tempo qualquer um deles gasta na sua tarefa.
O Opus com esforço baixo é como ter cinco minutos com um expert que tem profunda experiência com problemas como o seu. Eles trazem conhecimento que não está em lugar nenhum no seu código-fonte; padrões que já viram antes, pegadinhas que sabem verificar, o tipo de experiência que você só obtém resolvendo muitos problemas semelhantes. Mas cinco minutos significam uma leitura rápida do seu código, não uma passagem cuidadosa por cada arquivo.
O Sonnet com esforço alto é o generalista com a tarde inteira. Eles são ótimos em programação, e vão ler tudo, executar coisas, verificar seu trabalho e acabar entendendo seu código específico a fundo.
O Fable é o especialista que você chama quando todos os outros estão travados. Mesmo com esforço baixo, eles vão perceber algo que ninguém mais perceberia. Esse reconhecimento é também o que você está pagando mais caro, então vale a pena guardá-lo para as tarefas que realmente precisam dele.
Nenhum deles é universalmente "melhor". A configuração do modelo é aproximadamente quão capaz; a configuração de esforço é aproximadamente quão minucioso. A maioria das tarefas reais precisa de um pouco de ambos.
Esforço, modelo e consumo de tokens
Então, como a seleção do modelo, o esforço e o consumo de tokens interagem? Depende da tarefa.
Em trabalho rotineiro no mesmo nível de esforço, tanto o modelo maior quanto o menor geralmente acertam. O modelo maior consome mais tokens com etapas extras de verificação, a um preço mais alto por token. É por isso que reduzir para o modelo menor em trechos rotineiros economiza dinheiro real sem perda de qualidade.
As curvas são apenas para fins de ilustração, mostradas para uma única tarefa simples o suficiente para ser realizada rapidamente por ambos os modelos. Elas não representam dados reais de benchmark.
Em trabalhos mais difíceis e de várias etapas, a equação se inverte. O modelo menor tem que se esforçar até o limite de sua capacidade, queimando iterações, enquanto o modelo maior atinge o mesmo padrão de qualidade em menos etapas.
Você está pagando mais por token pelo modelo maior, mas em tarefas que realmente desafiam o modelo menor, o custo total por tarefa pode ser menor. E mais importante: o modelo maior pode concluir tarefas que o menor não consegue, mesmo nos níveis de esforço mais altos.
Isso é mais pronunciado com o Fable. Em trabalhos longos e de várias etapas, ele se distancia ainda mais. Em nossos testes, ele concluiu trabalhos que o Opus e o Sonnet não conseguem alcançar em nenhum nível de esforço. Ele também custa mais por token, que é a outra razão para guardá-lo para o trabalho que realmente precisa dele.
As curvas são apenas para fins de ilustração, mostradas para uma única tarefa difícil o suficiente para desafiar ambos os modelos. Elas não representam dados reais de benchmark.
O ponto-chave nos gráficos acima: o esforço escolhe o quão longe o Claude está disposto a percorrer ao longo da curva. Isso não significa que o Claude precisará ir tão longe para concluir a tarefa.
Por último, o esforço molda o consumo de tokens, mas não o limita. O único limite rígido no sistema é max_tokens, que trunca uma resposta no meio do fluxo quando atingido, mas é um instrumento bruto e mais relevante para desenvolvedores de API. Controles mais suaves, como orçamentos de tarefa ou pedir ao Claude para ser breve no seu prompt, são mais úteis. Eles são orientações que o modelo é treinado para seguir (ele procurará concluir à medida que se aproxima do limite) em vez de uma parede contra a qual ele colide.
O esforço muda quanto trabalho o Claude faz. O modelo muda o que o Claude sabe.
Quando você não está satisfeito com um resultado, verifique o contexto antes de tocar em qualquer configuração: dê ao Claude um prompt claro, as ferramentas e habilidades certas e uma maneira de verificar seu próprio trabalho.
Se o Claude ainda errar, pergunte-se: ele não sabia o suficiente ou não tentou o suficiente? Não saber o suficiente é um problema de modelo, não tentar o suficiente é um problema de esforço.
Este artigo foi escrito por @lydiahallie, membro da equipe técnica do Claude Code.
