Como usar Claude Code com um teto real de esforço

Resposta rápida: como usar Claude Code com um teto de esforço

Atualize para o Claude Code 2.1.267 ou uma versão posterior. Depois, adicione "maxEffortLevel": "medium" ao arquivo de configurações correspondente às pessoas e aos projetos que devem seguir a regra. Use ~/.claude/settings.json para definir seu próprio teto global, .claude/settings.json para todos que trabalham em um repositório ou configurações gerenciadas para aplicar a política em toda a organização.

A configuração aceita low, medium, high, xhigh ou max. O valor max indica que aquela origem não impõe um teto ao esforço. Deixar a chave sem definição também significa não aplicar limite.

Pense nisso como um limitador de velocidade, não como um cartão de combustível. A configuração restringe quanto o Claude pode raciocinar em uma solicitação; ela não define uma franquia de tokens, uma cota em dólares nem o limite de uso de uma assinatura. Acompanhe esses itens separadamente com /usage, o Claude Console ou a telemetria OpenTelemetry do Claude Code.

O que maxEffortLevel realmente muda

effortLevel e maxEffortLevel cumprem funções diferentes. O nível de esforço é o valor solicitado para uma sessão ou um modelo. Já o nível máximo de esforço é a barreira que essa solicitação não pode ultrapassar.

Com o teto em medium, o desenvolvedor ainda pode escolher low ou medium. Se pedir high, xhigh ou max, a execução fica em medium. O limite também intercepta níveis solicitados por /effort, pelo seletor /model, por --effort, por CLAUDE_CODE_EFFORT_LEVEL e pelo padrão do modelo. O Claude Code aplica a regra no cliente antes de cada solicitação. Assim, a mesma política funciona quando o tráfego do modelo passa pela Anthropic, pelo Amazon Bedrock, pelo Agent Platform do Google Cloud ou pelo Microsoft Foundry.

Há uma regra crucial que passa despercebida com facilidade: prevalece o menor teto entre todos os escopos carregados. Em geral, as configurações do Claude Code seguem uma hierarquia, com as configurações gerenciadas acima das opções de linha de comando, dos arquivos do projeto e das configurações do usuário. maxEffortLevel é uma exceção restritiva. Um teto menor no projeto continua vencendo, mesmo que uma origem gerenciada ou do usuário permita mais.

Defina um teto global, uma exceção por modelo e um limite de projeto mais rígido

Primeiro, execute claude --version. Se a versão for anterior à 2.1.267, rode claude update antes de adicionar a chave.

Para aplicar um teto pessoal em todos os repositórios, inclua isto em ~/.claude/settings.json:

{
  "maxEffortLevel": "medium",
  "modelSettings": {
    "claude-sonnet-4-6": {
      "maxEffortLevel": "max"
    }
  }
}

O valor no nível superior limita todos os modelos compatíveis a medium. A entrada do Sonnet 4.6 substitui esse valor superior somente para o Sonnet e apenas dentro deste arquivo do usuário. O valor max não obriga o Sonnet a operar com esforço máximo. Ele apenas informa que essa origem específica não limita o modelo.

Agora, adicione uma regra mais rígida para um repositório em .claude/settings.json:

{
  "maxEffortLevel": "low"
}

O resultado efetivo é rigoroso de propósito:

A exceção do modelo não atravessa a regra do projeto. Ela apenas cancela o teto medium da origem do usuário para o Sonnet. Esse é o erro com maior chance de criar uma falsa impressão de que o modelo está isento de qualquer limite.

Para adotar uma política corporativa, distribua a mesma chave de nível superior por meio das configurações gerenciadas. O teto passa a valer para as pessoas cobertas por essa origem gerenciada em qualquer provedor compatível. Se uma função Enterprise também tiver um limite de esforço, o Claude Code aplicará o menor dos tetos.

Confirme o teto antes de confiar nele

Um arquivo JSON válido não prova que o limite pretendido foi o vencedor. Confirme tanto as origens carregadas quanto o nível realmente aplicado.

1. Execute /status dentro do Claude Code. A linha Setting sources confirma o carregamento de User settings, Project settings e eventuais Managed settings. Ela não mostra qual origem forneceu cada chave individualmente.
2. Execute claude doctor se alguma origem estiver ausente ou se uma chave nova parecer ignorada. O comando lista entradas de configuração rejeitadas. O schema JSON publicado pode ficar atrás de uma versão nova da CLI; portanto, um alerta do editor, sozinho, não dá o veredito.
3. Verifique o cabeçalho da sessão ao lado do nome do modelo. O Claude Code exibe ali o esforço atual e também o mostra brevemente no rodapé quando há uma mudança.
4. No repositório do exemplo, solicite /effort max. O teto low definido no projeto continua valendo. Um pedido maior não consegue elevá-lo.
5. Em frotas não interativas, examine o atributo effort em claude_code.cost.usage e claude_code.token.usage. Ele registra o nível aplicado a cada solicitação junto com o modelo e a origem da consulta.

Essa última verificação é importante no Bedrock, no Google Cloud e no Foundry. A política é aplicada pelo Claude Code antes que o provedor receba a solicitação, enquanto a telemetria revela o que o Claude Code efetivamente usou.

Avalie qualidade e custo em trilhas separadas

Não adote um teto medium ou low apenas porque o nome parece econômico. Escolha uma tarefa rotineira que a equipe já conheça e compare execuções equivalentes.

Um bom cenário de teste é um repositório pequeno com um teste de parser falhando. Mantenha iguais o modelo, o commit, o prompt, as permissões e o acesso a ferramentas em cada execução. A tarefa deve ser a mesma: corrigir o caso extremo, adicionar um teste de regressão, rodar a suíte e informar os arquivos alterados. Execute primeiro a linha de base sem teto, restaure o cenário limpo e então rode a condição limitada.

Avalie o resultado antes de olhar para o custo:

A métrica de decisão é o custo por tarefa aprovada, não a quantidade de tokens por resposta. Uma execução com esforço menor que exige uma segunda revisão ou rodada de correções pode custar mais do que uma execução limpa com esforço maior. A mesma lógica vale para a comparação mais ampla dos níveis de esforço do Claude, mas a nova configuração torna o limite superior escolhido obrigatório no Claude Code.

Sete situações em que um teto de esforço compensa

Estes casos de uso estão ordenados de acordo com quem obtém o retorno operacional mais evidente.

1. Equipes de plataforma que controlam tarefas rotineiras

Uma equipe de plataforma responsável por 20 ou 200 desenvolvedores pode definir medium nas configurações gerenciadas, manter os níveis inferiores disponíveis e reservar mudanças de política para exceções comprovadas por métricas. O ganho não se resume a gastar menos tokens. Trata-se de manter um limite padrão consistente entre notebooks, sessões de IDE e rotas de provedores de nuvem, o que torna úteis as comparações de custo e qualidade.

2. Responsáveis por FinOps com Claude Code cobrado via API

Uma liderança de FinOps pode combinar um teto gerenciado com dados de OpenTelemetry agrupados por effort, modelo, equipe e centro de custo. O fluxo é simples: observar a linha de base sem limite, introduzir o teto em um grupo piloto e comparar o custo por tarefa aprovada. Assim, discussões subjetivas sobre qual nível de esforço parece caro dão lugar a um relatório vinculado ao trabalho entregue.

3. Empresas que usam Bedrock, Google Cloud ou Foundry

Uma empresa regulada talvez encaminhe os modelos pela nuvem escolhida por motivos de aquisição ou controle de dados. Como o cliente do Claude Code aplica maxEffortLevel antes de cada solicitação, a organização consegue manter uma única política de esforço entre esses provedores. O benefício é ter a mesma política em todos eles sem esperar que cada console ofereça um controle equivalente.

4. Responsáveis por CI que executam correções repetitivas

Uma equipe que aciona o Claude Code para atualizar dependências, corrigir formatação, manter testes ou alterar documentação pode limitar esses repositórios a low ou medium. O nível exato deve vir dos cenários de teste das tarefas, mas, quando a qualidade se sustenta, o teto impede que uma flag, skill ou padrão do modelo eleve uma automação rotineira a um modo de raciocínio mais profundo.

5. Responsáveis por monorepos que separam trabalho rotineiro e complexo

Quem mantém um monorepo pode usar um teto pessoal medium, versionar um limite compartilhado menor em um repositório de documentação ou código gerado e deixar um repositório de sistemas mais complexo com o limite mais amplo. Cada repositório carrega sua própria fronteira. Assim, a política de custos acompanha o trabalho, sem depender de que cada desenvolvedor se lembre de um comando.

6. Consultorias que alternam entre repositórios de clientes

Um consultor pode adotar um teto pessoal medium como base e permitir que cada repositório de cliente imponha uma configuração compartilhada mais rígida. Isso reduz a divergência de configurações quando o mesmo notebook circula entre um site de conteúdo pequeno, uma aplicação madura e um contrato de manutenção sensível a custos. O arquivo do projeto também documenta o modo operacional esperado para a próxima pessoa.

7. Staff engineers que preservam uma exceção restrita por modelo

Um staff engineer pode isentar um modelo do teto global de uma origem por meio de modelSettings e, ao mesmo tempo, manter outro limite mais baixo em um repositório crítico para a segurança. O modelo ganha espaço onde a origem permite, sem que a exceção se transforme em desvio universal. O benefício é uma isenção precisa que continua subordinada a políticas mais rígidas do projeto ou da organização.

O que vale a pena construir em torno desse recurso

1. Gate de regressão de esforço, a oportunidade mais forte

Crie uma verificação de CLI e CI que execute a suíte de tarefas aprovadas de um repositório nos níveis de esforço permitidos. Depois, apresente taxa de aprovação, falhas de revisão, duração, tokens e custo. Equipes de plataforma de engenharia pagariam por isso porque o teto cria uma pergunta imediata sobre qualidade: até onde o esforço das tarefas rotineiras pode cair antes que o trabalho de correção elimine a economia?

O sinal de demanda é especialmente comercial. ai code review registra uma estimativa de 1,300 buscas por mês nos EUA e CPC de $62.38. A menor versão vendável seria um executor local acompanhado de uma verificação no GitHub, capaz de comparar dois perfis de esforço no mesmo cenário limpo e bloquear uma mudança de política quando testes obrigatórios ou regras de revisão apresentarem regressão.

O obstáculo está no benchmark. Uma pontuação genérica de programação é fácil de copiar e tem pouca relação com o repositório do comprador. A parte defensável é formada pelo conjunto privado de tarefas, pelos critérios de revisão e pelo histórico da equipe ao longo das atualizações dos modelos. Sem esses dados, o produto vira apenas mais um dashboard.

2. Linter de políticas de esforço do Claude Code

Crie um inspetor de políticas somente leitura que reúna origens do usuário, compartilhadas do projeto, locais do projeto, de linha de comando e gerenciadas em uma única tabela de tetos por modelo. Equipes de plataforma e segurança poderiam usá-lo para detectar uma exceção max tratada por engano como global, um limite inferior do projeto que vence sem ser percebido ou uma frota que ainda roda uma versão anterior à 2.1.267.

claude code soma uma estimativa de 550,000 buscas mensais nos EUA, e entre as perguntas encontradas está “Qual nível de esforço devo usar no Claude Code?”. Esse volume é amplo, não necessariamente pronto para compra, mas a confusão de configuração é objetiva. Um MVP precisa apenas descobrir as origens, detectar a versão, validar o JSON e explicar qual é o menor teto vencedor.

O obstáculo é o risco de plataforma. A Anthropic pode adicionar um inspetor nativo das configurações efetivas. Para ser duradouro, o produto precisaria oferecer alertas de desvio de política, inventário da frota e evidências para auditoria, não apenas uma tela de configurações mais bonita.

3. Monitor de custos do Claude Code sensível ao esforço

Crie um dashboard específico de OpenTelemetry que combine o atributo effort aplicado com tokens, custo, modelo, origem da consulta, repositório e verificações de qualidade em implantações da Anthropic e de provedores de nuvem. Equipes de FinOps e experiência do desenvolvedor pagariam pela conexão entre política e resultado, não por mais um totalizador de tokens.

llm observability registra uma estimativa de 590 buscas por mês nos EUA e CPC de $37.45. Os preços existentes confirmam que há verba: o Agent Observability da Datadog começa grátis para 40,000 spans de LLM, enquanto o Pro parte de $160 por mês para 100,000 spans. Um MVP focado poderia incluir uma predefinição do coletor OpenTelemetry, um inventário de tetos e três visualizações: esforço aplicado, custo por tarefa aprovada e regressões após uma mudança de modelo ou política.

O obstáculo está na concorrência e na causalidade. Fornecedores de observabilidade já coletam tokens e custos, e uma conta menor depois da adoção do teto não prova que ele foi a causa. O produto precisa de avaliações equivalentes ou evidências de pontos de mudança para conquistar confiança.

O gate de regressão de esforço é a melhor das três opções. A demanda está mais próxima de uma decisão de engenharia que recebe orçamento, e o histórico privado de avaliações ganha valor toda vez que a Anthropic altera um modelo ou a calibração de esforço.

O que o teto não resolve

Um teto de esforço não garante uma conta menor. O esforço afeta os tokens de saída, o comportamento das ferramentas e o raciocínio, mas a escolha do modelo, o tamanho da base de código, o comportamento do cache e a automação paralela também pesam. Assinantes dos planos Claude Max e Pro já têm o uso incluído, portanto o custo de sessão exibido por /usage não corresponde à cobrança deles.

Ele também não torna low seguro para todas as tarefas de programação. A Anthropic recomenda expressamente testar a carga de trabalho, e um mesmo nome de esforço recebe calibrações diferentes entre modelos. Uma execução medium em um modelo não representa uma quantidade fixa de raciocínio que possa ser comparada mecanicamente com medium em outro.

O teto não cria um desvio absoluto para um modelo. Uma entrada max específica por modelo remove apenas o limite superior da mesma origem. Outra origem ainda pode impor um teto menor, e o limite de esforço da organização pode ser ainda mais baixo.

Por fim, /status confirma quais arquivos foram carregados, não qual arquivo venceu para cada chave. Em automações, o atributo de telemetria effort aplicado é o registro mais confiável.

O que fazer na segunda-feira

Na próxima semana, escolha uma tarefa rotineira de um repositório. Registre uma linha de base sem teto, adicione um limite medium no nível do usuário, inclua a exceção documentada para o Sonnet e depois defina low no arquivo compartilhado do projeto. Confirme as origens carregadas e o esforço mostrado no cabeçalho da sessão, repita a tarefa a partir do mesmo cenário limpo e compare a qualidade de aceitação antes do custo indicado por /usage. Se a qualidade se mantiver, leve o teto testado ao escopo compartilhado ou gerenciado apropriado. Se houver falha, aumente ou remova o limite mais rígido para essa carga de trabalho e preserve as evidências.

Se você quer uma política de esforço, um gate de avaliação e telemetria de custos ajustados ao fluxo de engenharia, conheça os sistemas de IA em produção.