A doc do Codex recomenda o contrário do que quase todo mundo faz · beerandcode

Semana passada eu fiz uma coisa chata: li a documentação inteira do Codex antes de abrir o terminal.

Chata porque a doc mudou de casa e quase ninguém percebeu. O developers.openai.com/codex agora redireciona pra learn.chatgpt.com, e não foi só troca de domínio, foi reescrita pra tratar o Codex como agente que recebe tarefa, não como autocomplete que recebe Tab.

O incômodo veio depois. Em pelo menos cinco pontos, a recomendação oficial é o oposto do que eu via por aí, e do que eu mesmo estava fazendo. Não é pegadinha escondida em nota de rodapé: está escrito, de graça, na página principal.

Separei os cinco.

1. Reasoning: a doc manda usar o MENOR que resolve

A página de modelos é explícita: use o menor reasoning effort que ainda produz resultado aceitável.

O comportamento padrão que eu vejo (e que eu tinha) é o contrário: travar no máximo e esquecer que existe o seletor. A lógica parece boa, "se pensa mais, erra menos". Só que reasoning alto não é qualidade de graça: é custo e latência. Em tarefa trivial, você paga os dois e não compra nada.

Renomear variável, ajustar import, escrever teste óbvio, nada disso melhora com effort Max. Você só espera mais e paga mais pelo mesmo diff.

O caminho que a doc sugere é começar no default e calibrar pra baixo enquanto o resultado se mantém. Quase ninguém calibra pra baixo. A gente só sobe.

2. Permissão: a doc manda usar a mais restritiva que completa a tarefa

A doc de permissões define três perfis: :read-only, :workspace e :danger-full-access. O nome do terceiro já é o aviso.

A recomendação oficial é escolher o perfil mais restritivo que ainda dá conta. Análise de codebase? Read-only resolve. Feature nova? Workspace. Full access deveria ser exceção consciente.

Na prática, full access virou default, e não por decisão técnica. Por preguiça de aprovar comando. Aprovar dá trabalho, quebra o fluxo, e depois da décima vez você desliga.

Eu entendo o impulso. Mas vale saber o que você está desligando: escrita ampla altera scripts, hooks e arquivos compartilhados de forma persistente. E regra de rede com wildcard continua aberta mesmo com allowlist configurada. "Só dessa vez" acumula.

3. Modelo: existe uma escolha, e ela não é "sempre o topo de linha"

A doc separa a família GPT-5.6 em três: Sol pra trabalho ambíguo e de alto valor, Terra pro dia a dia, Luna pra tarefa repetida e bem definida.

Isso é um mapa de decisão. A maioria usa como ranking, pega o mais forte e pronto, porque "melhor é melhor".

Só que tarefa repetida e bem definida é exatamente onde o modelo mais caro rende menos. Você está pagando capacidade de lidar com ambiguidade num problema que não tem ambiguidade nenhuma.

4. Prompt: a doc diz que o primeiro não precisa ser perfeito

Literal no guia de prompting: "your first prompt doesn't need to be perfect".

O fluxo recomendado é iterar, rodou, olhou, pediu o ajuste específico na mensagem seguinte. Conversa, não invocação.

O que eu vejo é gente tratando prompt como feitiço: se o resultado veio ruim, apaga tudo, reescreve do zero e começa sessão nova. Aí joga fora todo o contexto que a sessão já tinha acumulado, o agente já sabia quais arquivos importavam, já tinha lido o teste que falha, já tinha entendido a convenção do projeto. Você reseta isso pra reescrever uma frase.

No CLI existe codex resume justamente pra recuperar sessão. É o botão que quase ninguém aperta.

5. Peça o resultado, não o passo a passo

Também literal: "start with the result, not a detailed list of steps".

Ruim:  "Abre o UserController, adiciona um método, depois cria a rota..."
Bom:   "Preciso de um endpoint GET /users/{id}/invoices que retorne as
        faturas paginadas do usuário, com teste cobrindo o caso vazio."

Microgerenciar passo a passo desperdiça justamente a habilidade que você está pagando pra usar: planejar. Se você já sabe todos os passos na ordem certa, o gargalo não era o planejamento, era digitação. Aí é outra ferramenta.

O padrão por trás dos cinco

Reparei que os cinco erros têm a mesma raiz: a gente trata o agente como oráculo, e a doc trata como subordinado.

Oráculo você invoca no modo mais potente possível, com o prompt mais bem formulado possível, e reza. Subordinado você configura: define escopo, restringe permissão, calibra esforço pro tamanho da tarefa, corrige no meio do caminho.

A segunda leitura é menos empolgante e dá mais trabalho de montar. Também é a que a documentação oficial descreve, e a que sobra quando o hype passa.

Não é que a doc tenha segredo. É que quase ninguém abre. Instalar leva trinta segundos; ler leva uma hora. A conta parece favorável até você perceber que passou três meses pagando reasoning Max pra formatar JSON.

Fica a pergunta, porque eu genuinamente não sei a resposta: quem aqui calibra reasoning pra baixo de propósito?

Eu comecei a fazer há pouco tempo e ainda não tenho medição decente do quanto economizei. Se alguém tiver número real, de custo ou de latência, eu queria muito ver.

E se você usa full access como default, sem julgamento: qual foi o momento em que você desistiu de aprovar comando?