Raciocínio alto não é padrão: é uma escolha por tarefa

Imagine duas issues na mesma fila:

Atualizar no README a documentação da variável API_TIMEOUT e rodar o verificador de links.
Descobrir por que o refresh token falha apenas depois do segundo deploy.

As duas podem ser delegadas a um agente de código. Ainda assim, seria estranho entregar a elas a mesma configuração, o mesmo limite de execução e a mesma expectativa de evidência.

Eu entendo a tentação de deixar o raciocínio sempre no nível mais alto. Parece uma escolha cautelosa: se o agente consegue pensar mais, por que pedir menos? Só que essa configuração cobra mais tokens e créditos, enquanto a parte mais importante continua sem resposta: que tipo de trabalho está sendo delegado?

Escolher o nível de raciocínio por tarefa transforma esse seletor em uma decisão de engenharia. Para um time pequeno, a decisão pode caber em poucos minutos.

O seletor não classifica a tarefa por você

Um nível alto pode ajudar quando o problema exige investigação, comparação de hipóteses ou decisões entre várias camadas do sistema. Ele não torna uma issue vaga mais clara e também não garante que a resposta esteja correta.

No agente de código do Copilot, por exemplo, o nível de raciocínio pode ser escolhido junto com o modelo no início de cada tarefa. É uma opção útil porque coloca a decisão dentro da execução concreta. O risco é transformar "alto" em padrão sem olhar para o trabalho da vez.

No primeiro exemplo, o caminho já está praticamente definido. Há um arquivo conhecido, uma alteração estreita e um comando barato para conferir o resultado. Gastar a configuração mais cara ali dificilmente acrescenta algo útil.

No segundo, nem sequer sabemos em qual camada a falha nasce. Pode haver estado inconsistente, configuração de ambiente, cache, rotação de segredo ou uma diferença no processo de deploy. Nesse caso, dar mais espaço para investigação faz sentido. Mas a investigação ainda precisa terminar em logs, uma hipótese reproduzível e um teste de regressão.

Esse é o detalhe fácil de esquecer: esforço do modelo e confiança no resultado são coisas diferentes.

Faça uma triagem curta antes de delegar

Antes de escolher o modelo ou o nível de raciocínio, eu usaria três perguntas.

1. Quanta ambiguidade existe?

Se a solução já é conhecida e o agente precisa apenas executá-la, a tarefa pede pouco espaço para exploração. Um rename local, uma correção de documentação ou uma alteração de formatação entram aqui.

Quando a issue descreve um sintoma sem causa conhecida, a ambiguidade sobe. O agente terá de localizar evidências, formular hipóteses e descartar caminhos. Isso justifica mais capacidade de raciocínio.

Uma issue vaga, porém, não deve ser confundida com uma issue difícil. "Melhore a autenticação" não merece raciocínio alto; merece uma especificação melhor.

2. Até onde uma decisão errada alcança?

Uma mudança limitada a um arquivo de documentação tem um raio pequeno. Já uma alteração que atravessa autenticação, banco, filas e deploy pode falhar longe do ponto onde o diff parece correto.

Quanto maior o alcance, mais cedo vale planejar pontos de revisão. Talvez o agente possa investigar livremente, mas precise parar antes de alterar o schema. Talvez possa preparar um patch, mas não trocar uma dependência central sem aprovação.

O nível de raciocínio ajuda na análise. O limite de atuação protege o repositório.

3. Quanto custa validar a saída?

Algumas tarefas têm um veredito barato: o lint passa, o link existe, o teste unitário cobre o comportamento. Outras dependem de reproduzir uma sequência rara, comparar desempenho ou observar o sistema em mais de um ambiente.

Quando a validação é barata e determinística, dá para trabalhar com uma rota econômica. Quando ela é cara ou incompleta, a delegação precisa reservar tempo para evidência e revisão humana. A pior combinação é usar uma configuração cara e aceitar o resultado só porque a explicação parece convincente.

Use três rotas, não uma tabela de modelos

Catálogos de modelos mudam rápido. Uma política baseada no tipo de tarefa dura mais:

Rota	Quando usar	Esforço de raciocínio	Evidência mínima
Mecânica	Mudança estreita, instrução explícita e resultado previsível	Econômico	Comando de verificação ou teste direto
Padrão	Feature pequena ou bug com hipótese clara e escopo limitado	Intermediário	Testes relevantes e revisão do diff
Escalada	Debugging incerto, arquitetura ou mudança entre camadas	Alto	Reprodução, logs, testes de regressão e ponto de revisão humana

Essas rotas não precisam virar burocracia. Elas servem para impedir que "deixa no máximo" substitua uma decisão que o time deveria tomar.

Também evitam a falsa economia. Se uma tarefa parece simples apenas porque a descrição esconde as dúvidas, baixar o esforço não resolve o problema. Primeiro reduza a ambiguidade; depois escolha a rota.

Registre a escolha na própria issue

Um template curto já deixa o contrato mais explícito:

## Objetivo
Corrigir a falha de refresh token após o segundo deploy.

## Escopo permitido
- autenticação e configuração de deploy
- sem alterar o schema do banco sem revisão

## Rota escolhida
Escalada, porque a causa ainda é desconhecida e pode atravessar camadas.

## Evidência esperada
- passos para reproduzir a falha
- logs que sustentem a causa encontrada
- teste de regressão
- resumo do diff e dos riscos restantes

## Condição de parada
Parar e pedir revisão antes de trocar dependências ou alterar o schema.

Repare que o campo mais importante não é o nome do modelo. É a relação entre a incerteza da tarefa, a liberdade concedida e a prova que o agente deve devolver.

Para a alteração no README, o mesmo template ficaria bem menor: arquivo permitido, comando de verificação e condição de parada se a variável documentada não existir no código. Não há mérito em transformar uma correção simples numa investigação.

Comentário de gatilho é botão, não especificação

Automações disparadas por comentários deixam o fluxo mais rápido. Um time pode reservar uma frase como /agent run ou @agent executar para iniciar o trabalho em uma issue ou pull request.

O comentário só deveria disparar uma tarefa que já tem objetivo, escopo e evidência esperada. Caso contrário, uma frase curta vira uma ordem cara e sem limites claros. Pior: um comentário casual pode iniciar uma execução que ninguém delimitou.

Vale separar as responsabilidades:

o corpo da issue registra o contrato;
um campo ou rótulo informa a rota escolhida;
o comentário reservado autoriza a execução.

Se o agente não encontrar os campos necessários, ele deve parar e pedir complemento. Esse comportamento costuma economizar mais do que qualquer ajuste fino no seletor de raciocínio.

Uma regra simples para a próxima issue

Na próxima delegação, não comece pelo modelo. Leia a tarefa e classifique ambiguidade, alcance e custo de validação. Em seguida, escolha a menor rota capaz de lidar com o problema e defina a evidência de acordo com o risco.

Para mudanças mecânicas, mantenha o caminho curto. Para investigação entre camadas, libere mais raciocínio e defina pontos de parada. Nos dois casos, revise o diff e cobre uma prova que possa ser conferida.

Na prática, eu deixaria o raciocínio alto para tarefas em que investigar faz parte do trabalho. Nas outras, prefiro uma rota menor e uma checagem objetiva. O custo fica previsível, e a revisão continua apoiada em algo que dá para conferir.