10 boas práticas para usar o Codex (direto da documentação oficial)

Todo mundo instalou o Codex. Pouca gente leu a documentação.

E ela mudou — de endereço e de filosofia. A doc oficial saiu do developers.openai.com e hoje vive em learn.chatgpt.com, reescrita pra era em que o Codex é agente que recebe tarefa, não autocomplete que recebe tab.

Fiz a varredura completa: prompting, permissões, modelos, skills, cloud, changelog. Este post condensa as 10 boas práticas que a própria OpenAI recomenda — cada uma com fonte e com o jeito de aplicar hoje no seu fluxo.

TL;DR

• O que é: as 10 práticas recomendadas na doc oficial do Codex, destrinchadas com exemplo prático.
• Stack: Codex CLI, extensão de IDE (VS Code, Cursor, Windsurf, JetBrains, Xcode), app desktop e Codex cloud.
• Custo/Acesso: incluso nos planos pagos do ChatGPT (Plus/Pro e superiores).
• Link útil: learn.chatgpt.com/docs.

O contexto: a doc do Codex mudou de casa (e de filosofia)

Se você guardou o link antigo, ele redireciona: developers.openai.com/codex agora aponta pra learn.chatgpt.com. Não foi só mudança de domínio. A doc nova organiza o Codex como um agente com quatro superfícies: o CLI no terminal, a extensão de IDE, o app desktop do ChatGPT (integração que chegou em julho, segundo o changelog) e o Codex cloud, que roda tarefas em ambientes isolados enquanto sua máquina fica livre.

Por baixo, a família GPT-5.6 em três sabores — Sol, Terra e Luna — mais níveis de reasoning que vão de Low a Max. A mensagem implícita da doc inteira: o gargalo não é o modelo, é como você configura contexto, permissão e verificação em volta dele.

Doc lida é metade do caminho. A outra metade é ver essas práticas rodando em projeto de verdade, com alguém do lado pra revisar o que você montou — e é exatamente esse ambiente que o Clã Beer and Code oferece, toda semana, ao vivo.

As 10 boas práticas do Codex

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

A primeira orientação do guia de prompting é literal: "start with the result, not a detailed list of steps". Descreva o que precisa existir no final — comportamento, formato, restrição — e deixe o agente decidir o caminho. Micro-gerenciar passo a passo desperdiça a principal habilidade do modelo: planejar.

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."

Se quiser levar o prompt-como-contrato adiante, a gente já destrinchou como usar goals no Codex CLI pra guiar o agente sem microgerenciar.

2. Dê o contexto que muda a resposta

A doc recomenda anexar tudo que altera o resultado: arquivos, screenshots, links — e liberar busca na web quando o problema envolve informação recente. Contexto que você não deu é contexto que o modelo vai inventar. Na extensão de IDE, referencie arquivos abertos e seleções direto no compositor em vez de reexplicar o problema.

3. Não persiga o prompt perfeito

Também literal na doc: "your first prompt doesn't need to be perfect". O fluxo recomendado é iterar — rodou, olhou, pediu o ajuste específico na mensagem seguinte. Recomeçar do zero a cada tentativa joga fora o contexto que a sessão já acumulou. No CLI, codex resume recupera sessões antigas justamente pra isso.

4. Trate o AGENTS.md como documentação viva

O AGENTS.md é onde vivem as instruções persistentes do projeto: convenções, comandos de build, o que o agente nunca deve tocar. Rode /init pra gerar o primeiro. A hierarquia é global → repositório → diretório, com o mais específico vencendo. Regra de ouro: toda correção que você repete pro Codex duas vezes é candidata a virar linha no AGENTS.md — e só entra ali o que ele não consegue inferir lendo o código.

5. Rode com a permissão mais restritiva que resolve

A doc de permissões define três perfis: :read-only (só inspeção), :workspace (escrita dentro do workspace) e :danger-full-access — o nome já é o aviso. A recomendação oficial: escolha o perfil mais restritivo que ainda completa a tarefa. Análise de codebase? Read-only. Feature? Workspace. Full access é exceção consciente, nunca default por preguiça de aprovar comando.

6. Escolha modelo e reasoning pelo tamanho do problema

A página de modelos é direta: Sol pra trabalho ambíguo e de alto valor, Terra pro dia a dia, Luna pra tarefa repetida e bem definida. E use o menor reasoning effort que produz resultado aceitável — Max em tarefa trivial é fatura maior e resposta mais lenta, sem ganho. Comece no default (Sol, effort médio) e calibre pelo que a tarefa pede, via /model.

7. Vire skill tudo que você repete

Skills empacotam um workflow — instruções, templates, exemplos — em algo reutilizável que o Codex reconhece sozinho. O caminho oficial: pegue uma tarefa focada e repetitiva, descreva o fluxo pro $skill-creator, teste com caso real, compartilhe com o time. É conhecimento tácito virando artefato versionável. Plugins entram quando a skill precisa de serviço externo via MCP.

8. Delegue o que é longo pro cloud

Tarefa que vai levar uma hora não precisa da sua máquina — nem de você olhando. O Codex cloud roda tarefas em ambientes isolados e paralelos, integrado ao GitHub. A boa prática da doc: configure o ambiente do repositório (dependências, setup, variáveis) antes de delegar. Agente em ambiente que não builda produz PR que não builda.

9. Checkpoint de git antes, /review depois

A doc da IDE recomenda criar pontos de controle git antes e depois de cada tarefa — reverter vira git reset, não arqueologia. E antes de commitar, /review (ou codex review contra a branch base) faz o agente inspecionar o próprio diff atrás de problemas. Não substitui o seu olho: organiza o que chega até ele.

10. Automatize o repetitivo — codex exec e scheduled tasks

codex exec roda o Codex em modo não-interativo, pronto pra script e CI. E o changelog de julho trouxe scheduled tasks — trabalho recorrente rodando sozinho, local ou em worktrees — e o Record & Replay, que converte uma demonstração sua em skill. Triagem de issue, atualização de changelog, verificação de dependência: se acontece toda semana, não precisa de você toda semana.

Limitações e pontos de atenção

danger-full-access é o que o nome diz. Perfil com escrita ampla altera scripts, hooks e arquivos compartilhados de forma persistente — e regra de rede com wildcard continua aberta mesmo com allowlist. Use quando for intencional, nunca como atalho.

Reasoning alto não é qualidade grátis. É custo e latência. A própria doc manda calibrar pra baixo sempre que o resultado se mantém.

Revisão humana continua obrigatória. /review organiza o diff, cloud abre o PR — mas quem faz merge é você. Nenhuma página da doc promete o contrário, e desconfie de quem promete.

Docs em movimento. A migração pra learn.chatgpt.com é recente e feature nova chega todo mês. Confira o changelog antes de assumir que algo não existe.

FAQ rápido

O Codex CLI é pago? O CLI é open source, mas o uso consome os limites do seu plano ChatGPT (Plus/Pro e superiores). Instalação: curl -fsSL https://chatgpt.com/codex/install.sh | sh.

Funciona no Cursor e no JetBrains? Sim. A extensão cobre VS Code e derivados (Cursor, Windsurf) e tem integração nativa com JetBrains e Xcode.

AGENTS.md vale pro cloud também? Vale. O arquivo vive no repositório, então qualquer superfície que clone o repo — incluindo os ambientes do Codex cloud — lê as mesmas instruções. É o motivo de ele ser a camada de personalização mais durável.

Qual a diferença entre skill e plugin? Skill é workflow empacotado (instruções + recursos) pra uma tarefa focada. Plugin é o pacote instalável que pode combinar skills e conectores MCP — use quando precisar de ferramenta externa, não só de instrução.

Conclusão

As 10 práticas cabem numa frase: diga o resultado, dê contexto, persista o que se repete (AGENTS.md, skills), restrinja o que é perigoso (permissões), calibre o que é caro (modelo, reasoning) e verifique tudo (git, /review). Nada disso é segredo — está publicado, de graça, na doc oficial. A diferença é quem aplica.

A provocação: com scheduled tasks e Record & Replay, o Codex está deixando de ser ferramenta que você abre e virando um colega assíncrono que trabalha enquanto você dorme. Quem estruturar repositório, permissão e verificação primeiro colhe primeiro. E se você quer comparar o outro lado do ringue, veja como o manifesto da HumanLayer critica as "fábricas de software" — a discussão de harness vale pros dois agentes.