Como os melhores devs usam o Claude Code além do prompt

Quando estava construindo o Downshift, precisei entender melhor como o Claude Code gastava contexto e escolhia os modelos dos subagentes. Eu vinha de uma dor bem concreta: pagava o plano Pro e, em poucos dias de trabalho, já tinha esgotado o limite semanal. Queria entender o que estava consumindo tanto e onde fazia sentido otimizar.

É como trabalhar com outro dev: passar a tarefa é só o começo. A gente também combina os limites, divide o que pode andar em paralelo e confere se a entrega atende ao que foi pedido. Com agentes, precisamos ainda decidir qual modelo usar, quanto esforço dedicar e o que vale carregar na conversa.

A decisão que vale levar para o próximo projeto é esta: escolher capacidade conforme o problema e dar ao agente uma forma concreta de verificar a entrega. Vamos aplicar isso a uma correção de API, com comandos e configurações que você pode adaptar.

1. Escolha modelo e esforço antes de aumentar o prompt

Imagine que POST /pedidos recebe {"quantidade": -1} e retorna 201 Created. Neste exemplo didático, o contrato exige quantidade positiva e prevê 400 Bad Request para esse caso. Precisamos corrigir a validação e manter a criação de pedidos válidos funcionando.

Para começar, confira três coisas diferentes:

O material que inspirou este artigo destaca uma mudança específica: Opus 5.5 em medium iguala ou supera Opus 5 em high nas avaliações de código e trabalho de conhecimento da Anthropic. Carregar a configuração antiga para a versão nova pode deixar de ser uma boa escolha. Isso não é um benchmark do nosso projeto. Fonte: configuração de modelos e esforço.

Na documentação consultada em 12/11/2026, opus, sonnet e haiku resolvem para a família 5.5 na API da Anthropic. Outros provedores podem usar versões anteriores. Opus 5.5 exige Claude Code v2.1.280+, Sonnet 5.5 v2.1.284+ e Haiku 5.5 v2.1.293+. Para repetir uma comparação, registre o ID completo. Tabela por provedor.

Modelo e effort não são a mesma alavanca. O modelo define a capacidade; o esforço influencia quanto trabalho ele dedica ao turno, incluindo investigação e verificação. Mais esforço pode gerar mais tokens e espera. Não define um teto fixo de gasto. Explicação da Anthropic.

Na API do exemplo, eu usaria esta referência inicial, como hipótese para testar:

Na prática: se o teste já mostra que falta uma validação, Sonnet em medium é meu ponto de partida. Se o erro só aparece com duas requisições simultâneas, preciso investigar concorrência: aí testaria Opus, começando em medium. A incerteza da tarefa orienta a escolha.

Para abrir a sessão de implementação no terminal:

claude --model claude-sonnet-5-5 --effort medium

A escala da família 5.5 inclui low, medium, high, xhigh e max. Comece no padrão e aumente quando houver uma lacuna concreta na investigação. Para mudar, use /effort high; a seleção direta salva a preferência para o modelo. A variável CLAUDE_CODE_EFFORT_LEVEL pode prevalecer e políticas da organização podem limitar o nível. Níveis e precedência.

Um detalhe de versão: no Claude Code v2.1.311+, ultrathink tem tratamento específico e pode elevar aquele turno a xhigh nos casos suportados. think e think hard são texto comum. A afirmação de que todas essas palavras perderam efeito ficou desatualizada. Semântica atual.

2. Dê um contrato de trabalho e um mapa curto

Em vez de começar com “analise profundamente e siga todas as boas práticas”, descreva o comportamento que precisa mudar:

Tarefa: POST /pedidos aceita quantidade -1 e retorna 201.
O contrato prevê 400 para quantidade não positiva; corrija a validação.
Primeiro, escreva um teste que reproduza a falha.

Limites: preserve os campos e os status previstos no contrato.
Pedidos válidos devem continuar retornando 201.
Não altere o esquema do banco.

Pronto: o teste falha antes da correção e passa depois;
as verificações relevantes passam e o diff pode ser revisado.
Se faltar informação sobre o contrato, apresente a dúvida antes de alterá-lo.

Isso dá ao agente uma tarefa executável e permite ao revisor conferir o resultado. Para experimentar sem um repositório pronto, salve o arquivo abaixo como pedidos_test.go. Ele contém o handler e os testes e usa apenas a biblioteca padrão do Go.

package pedidos

import (
    "encoding/json"
    "net/http"
    "net/http/httptest"
    "strings"
    "testing"
)

func novoHandler(criar func()) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        var pedido struct {
            Quantidade int `json:"quantidade"`
        }
        if err := json.NewDecoder(r.Body).Decode(&pedido); err != nil {
            http.Error(w, "JSON inválido", http.StatusBadRequest)
            return
        }
        // Correção: rejeitar antes do efeito colateral.
        if pedido.Quantidade <= 0 {
            http.Error(w, "quantidade deve ser positiva", http.StatusBadRequest)
            return
        }
        criar()
        w.WriteHeader(http.StatusCreated)
    })
}

func TestCriarPedido(t *testing.T) {
    casos := []struct {
        nome, corpo      string
        status, criacoes int
    }{
        {"negativa", `{"quantidade":-1}`, 400, 0},
        {"zero", `{"quantidade":0}`, 400, 0},
        {"positiva", `{"quantidade":1}`, 201, 1},
    }
    for _, caso := range casos {
        t.Run(caso.nome, func(t *testing.T) {
            criadas := 0
            handler := novoHandler(func() { criadas++ })
            req := httptest.NewRequest(http.MethodPost, "/pedidos",
                strings.NewReader(caso.corpo))
            req.Header.Set("Content-Type", "application/json")
            res := httptest.NewRecorder()
            handler.ServeHTTP(res, req)
            if res.Code != caso.status {
                t.Errorf("status: esperado %d, recebido %d", caso.status, res.Code)
            }
            if criadas != caso.criacoes {
                t.Errorf("criações: esperado %d, recebido %d", caso.criacoes, criadas)
            }
        })
    }
}

Execute no diretório onde salvou o arquivo:

go test -v pedidos_test.go

Para reproduzir o bug, remova temporariamente o bloco if pedido.Quantidade <= 0 e repita o comando. Os casos negativo e zero falham: recebem 201 e criam um pedido. Restaure a validação e rode novamente: os três casos passam. O teste confere tanto o status quanto o efeito colateral; devolver 400 depois de criar o pedido não resolveria o problema.

Conferi esse ciclo localmente para o artigo: sem a validação, dois casos falharam; com ela, os três passaram. É uma demonstração de comportamento HTTP, sem banco, autenticação ou servidor de produção. Em uma API real, mantenha os demais campos válidos para a falha acontecer pelo motivo que está testando.

O CLAUDE.md complementa esse pedido com o que vale para o projeto: comando de testes, convenções próprias e caminhos das regras. Não precisa recontar o funcionamento de Go ou copiar toda a documentação. A recomendação oficial é mantê-lo abaixo de 200 linhas. Imports @ carregam conteúdo; dividir um documento usando imports não elimina seu custo de contexto. Use ponteiros e regras por caminho quando fizer sentido. Memória e regras.

O Plan Mode continua útil para explorar uma mudança ampla antes de editar. Ele controla a etapa de trabalho e as ferramentas disponíveis; não aumenta o effort. Para esse bug delimitado, eu começaria pelo teste. Boas práticas.

3. Separe a pesquisa quando ela atrapalhar a correção

Se descobrir os consumidores exigir ler dezenas de arquivos, essa exploração pode ocupar a conversa inteira. Um subagente consegue pesquisar em contexto separado e devolver as evidências relevantes. Para uma busca curta, abrir outro agente pode acrescentar mais coordenação do que benefício.

Uma definição didática em .claude/agents/contratos-api.md:

---
name: contratos-api
description: Investiga consumidores de endpoints sem editar arquivos.
tools: Read, Grep, Glob
model: haiku
effort: medium
---
Identifique campos, status e consumidores do endpoint solicitado.
Retorne arquivo e linha de cada evidência e declare as lacunas.

Peça: “Use contratos-api para investigar os consumidores deste endpoint; retorne o contrato observado e o que não conseguiu confirmar.”

Um retorno útil nesse cenário seria: “O contrato prevê 400 para quantidade não positiva e 201 para pedido válido. Localizei o consumidor web, mas não confirmei o comportamento do aplicativo mobile.” É uma resposta ilustrativa; numa execução real, ela precisa trazer arquivo e linha das evidências. Essa lacuna deve continuar visível na revisão.

Aqui, a escolha do modelo é explícita e as ferramentas permitem apenas leitura. O alias acompanha o provedor; fixe o ID completo quando precisar reproduzir um teste. O subagente também consome cota: preservar a conversa principal não significa eliminar esse consumo. Configuração de subagentes.

Também não suponha que o effort será sempre herdado. Sem configuração própria, no mesmo modelo ele acompanha a seleção da sessão; em outro modelo, essa seleção não se aplica. Declare effort quando precisar controlar essa escolha e confira o modelo em /tasks. Regras de esforço.

4. Faça o agente demonstrar que terminou

Na nossa API, uma entrega útil mostra três evidências: o teste reproduziu o problema, passou após a correção e as verificações relevantes foram executadas sobre o código final. “Revise duas vezes” não define nenhuma dessas provas.

Para continuar automaticamente até uma condição de término, /goal aceita um objetivo como:

/goal Corrigir o endpoint e incluir o teste de regressão.
Prova: executar as verificações do projeto e trazer à conversa
os comandos, códigos de saída e resumo dos resultados.
Preservar contrato público e esquema do banco.
Após 15 turnos, parar e relatar o bloqueio se não houver prova.

O avaliador de /goal lê a conversa; não abre arquivos nem executa comandos por conta própria. Por isso, a prova precisa aparecer no histórico. O limite de turnos escrito no objetivo é interpretado pelo avaliador, não um teto rígido de execução. O recurso também consome tokens e não muda as permissões. Funcionamento de /goal.

Na revisão, eu pediria: o nome dos testes executados, o resultado antes e depois e se o código mudou após a última execução. Isso permite conferir a entrega sem aceitar um “agora funciona” como prova.

Limites críticos precisam de controles além do texto. Um hook de comando PreToolUse pode bloquear uma chamada antes da execução com código de saída 2 e explicar o motivo em stderr. Sua eficácia depende das ações que ele consegue identificar e interceptar; um filtro de comandos não protege sozinho todos os acessos ao banco. Contrato dos hooks.

É a aplicação prática de guias e sensores em harness engineering, por Birgitta Böckeler: instruções orientam; controles e verificações dão retorno sobre o que aconteceu.

Como conferir consumo sem confundir tokens com a conta

Ao concluir uma tentativa, abra /usage. O bloco de sessão apresenta tokens por modelo, incluindo entrada, saída, leitura e escrita de cache, além de duração e custo estimado. No Pro, o valor em dólares não é uma cobrança adicional: a tela também mostra os limites do plano. Para faturamento de API, confira o provedor. Referência de consumo.

Na comparação, salve uma linha por tentativa:

tarefa | modelo/versão | effort | passou? | tokens por categoria |
custo estimado | duração | tentativas | intervenção humana

Use o mesmo estado inicial do código, prompt, testes, skills e ferramentas. Abra sessões novas, alterne a ordem das configurações e registre o estado do cache; não compare uma sessão já aquecida com outra fria como se fossem equivalentes. Repita os casos antes de concluir que houve ganho.

Inclua as falhas na conta: some o consumo de todas as tentativas de uma configuração e divida pelas entregas aceitas. Se nenhuma passou, não há custo por entrega aceita a reportar. Mantenha tokens de cache separados: um token lido do cache e um token de saída não têm o mesmo preço. A ocupação da janela de contexto também não representa todo o consumo acumulado.

O que essa comparação mostrou no Downshift

Foi essa distinção que precisei levar para o Downshift. No estudo de 21/10/2026, a bateria teve 46 execuções com tarefas mecânicas e delegação obrigatória:

O relatório registra 24,1% menos tokens por execução aceita, contando as falhas no consumo do grupo. O compactador estava desligado nos dois grupos comparados; essa diferença é do experimento de roteamento. O intervalo de 95% foi amplo: de 2,1% a 46,7%. Mais de 98% dos tokens eram de cache. Portanto, esse percentual não significa a mesma redução na fatura ou aumento do limite semanal do Pro.

É um resultado histórico do roteamento usado naquele experimento, anterior à mudança de arquitetura O8, como ressalva o README atual. Não comprova o efeito da implementação atual, nem se estende a tarefas gerais. O aprendizado aplicável aqui é medir a entrega aceita e identificar de onde vem a diferença antes de anunciar economia.

Para uma skill que já existe, compare tarefas equivalentes com e sem ela. O estudo independente skill-placebo, com 450 execuções no Opus 5.5, reforça esse cuidado: nenhum dos nove pacotes demonstrou custo menor que a condição sem skill naquela amostra. Isso não decide o valor da sua skill; mostra por que precisamos medir.

O ganho que eu buscaria é conseguir responder, ao revisar a entrega: por que usamos essa capacidade, o que o agente pôde fazer e qual evidência mostra que a mudança funciona? Com essas respostas, fica mais fácil ajustar o consumo sem trocar qualidade por uma sessão aparentemente barata.

Referências

• Vídeo que inspirou a seleção dos temas — IA em 6 minutos.
• Modelos, versões e esforço e explicação do mecanismo.
• Memória e CLAUDE.md, boas práticas e subagentes.
• Hooks, /goal e medição de consumo.
• Downshift: estudo controlado de tarefas mecânicas, 21/10/2026.
• Skill-placebo: método e resultados.
• Harness engineering — Birgitta Böckeler.