Melhores Práticas: Além das "verdades óbvias", aquelas que realmente funcionam

📚 Navegação da Série: O artigo anterior 35 Folha de Dicas de Comandos e Configurações organizou comandos, chaves de configuração e atalhos em uma folha de dicas para colar na parede. Este artigo muda de nível — em vez de falar sobre "quais recursos existem", falaremos sobre "como combinar esses recursos para que o Codex realmente economize seu tempo". O próximo artigo 37 Resolução de Problemas Comuns abordará "o que fazer se as coisas derem errado".

Para ser sincero, quando usei o Codex pela primeira vez, fiz uma coisa bastante estúpida: li a página oficial de best-practices do início ao fim, achei que cada ponto fazia muito sentido e então... fechei a página e não mudei absolutamente nada na forma como o usava.

O problema não era eu — é que a grande maioria das chamadas melhores práticas são verdades óbvias: "escreva instruções claras", "lembre-se de testar", "faça iterações curtas" — tudo parece correto, mas não dizem o quão claro deve ser, o que testar ou quão curtas devem ser as iterações. Você concorda balançando a cabeça freneticamente, mas volta a usar da mesma forma de antes. Esse tipo de conselho genérico, na essência, apenas joga a responsabilidade de volta para você.

Portanto, neste artigo não pretendo repetir esses grandes discursos que qualquer um pode fazer. Devorei a documentação oficial de best-practices e selecionei algumas regras que realmente mudaram a minha forma de uso e que eu mesmo validei. Para cada uma delas, vou apresentar "por que fazer isso + como fazer na prática + quais problemas você enfrentará se não fizer". Mantive apenas o que é aplicável; o que parece bonito, mas não funciona na prática, foi totalmente descartado.

Para falar a verdade, a maioria dos pontos abaixo foram coisas que eu errei primeiro e sofri as consequências antes de voltar para corrigir.

Ao ler este artigo, você obterá:

Uma mentalidade para configurar o Codex como um "parceiro de equipe" e não como uma "ferramenta descartável"
O que realmente deve ser escrito no AGENTS.md (manual do projeto) e qual tamanho é útil
Um conjunto de quatro elementos para prompts: "objetivo + contexto + restrições + aceitação", basta preencher os campos
Como dividir as permissões em diferentes níveis por cenário e por qual nível os iniciantes devem começar
Por que tarefas complexas devem exigir que ele crie um plano antes de começar a codificar
Como fazer o Codex testar e revisar por conta própria, em vez de você monitorar cada passo
Como coletar uma cadeia de evidências e registros anonimizados para tarefas de produção antes de confirmar a correção
Uma tabela comparativa de "Erros Comuns ❌ / Práticas Corretas ✅" para referência direta

⚠️ Comandos, chaves de configuração e comportamentos padrão são baseados na documentação oficial do Codex; nomes de modelos e disponibilidade mudam com versões e planos, portanto, dependem do que estiver ativo no seu codex --help local, no painel /model e no arquivo ~/.codex/config.toml.

01 Primeiro, mude a mentalidade: o Codex é um parceiro para treinar, não uma ferramenta descartável

Conclusão direta: o sucesso ao usar o Codex depende, em grande parte, de como você o enxerga.

Muitas pessoas (incluindo eu no início) o tratam como uma caixa de pesquisa de "pergunta e resposta": enviam uma dúvida, pegam a resposta e vão embora, começando do zero na próxima vez. Usando assim, ele renderá no máximo 30% do seu potencial.

Analogia: O Codex é como um novo colega de equipe recém-contratado, extremamente capaz, mas que não conhece nada sobre o seu projeto. Você não espera que ele entenda tudo no primeiro dia — você precisa dar a ele um manual de integração (AGENTS.md), explicar como executar e testar o código e corrigi-lo quando ele errar para que ele se lembre da próxima vez. Quanto mais você o treinar, melhor ele trabalhará. Por outro lado, se você contratar um trabalhador temporário diferente que não te conhece todas as vezes, passará o tempo todo repetindo a mesma explicação.

Há uma frase na documentação oficial com a qual concordo plenamente: Em vez de tratar o Codex como um assistente descartável, trate-o como um parceiro que você configura e aprimora continuamente. Todas as práticas deste artigo giram essencialmente em torno disso — transformar coisas temporárias e repetitivas em configurações permanentes.

Meu próprio ponto de virada foi no início de 2026. Antes disso, toda vez que eu abria uma nova conversa, tinha que digitar novamente: "este projeto usa pnpm em vez de npm", "os testes rodam com pnpm test", "as mensagens de commit devem ser em chinês". Eu digitava isso sete ou oito vezes por dia. Até que um dia me cansei e coloquei tudo isso no AGENTS.md. O mundo instantaneamente se acalmou — e percebi que estava usando a forma mais tola de interagir com uma ferramenta tão inteligente.

💡 Resumo em uma frase: Tratar o Codex como um parceiro de equipe que você treina continuamente, e não como uma ferramenta descartável, é a base de todas as melhores práticas.

02 Escreva o `AGENTS.md` corretamente: faça-o trabalhar automaticamente "com contexto"

Por que fazer isso. Este arquivo é o remédio para o problema mencionado na seção anterior. O AGENTS.md é um manual colocado no projeto que o Codex lê automaticamente para o contexto toda vez que inicia, sem que você precise mencioná-lo manualmente com @. Coisas que precisam ser repetitivas em um projeto são escritas uma vez e valem para sempre.

Analogia: O AGENTS.md é um README para a IA. Um README comum é escrito para humanos, dizendo o que o projeto faz e como executá-lo; o AGENTS.md is escrito para o Codex, informando as regras, as zonas de perigo e os "critérios de aceitação".

Como fazer. A documentação oficial sugere que um bom AGENTS.md cubra estas áreas, bastando listá-las:

Onde estão a estrutura do projeto e os diretórios importantes
Como executar o projeto
Quais comandos usar para build, testes e lint
Convenções de engenharia e requisitos para abrir PRs
Restrições e lines vermelhas de "nunca fazer"
Quais são os critérios de aceitação e como validá-los

A maneira mais rápida de começar é digitar /init no CLI, o que criará um esqueleto inicial do AGENTS.md no diretório atual. Mas não o use sem modificações — o que é gerado é apenas um modelo; você precisa adaptá-lo para refletir a realidade do seu projeto.

O AGENTS.md também pode ser estruturado em camadas: o que está em ~/.codex/ é o seu padrão pessoal; o que está na raiz do projeto são as regras compartilhadas da equipe; e o que está nos subdiretórios são regras locais. Quanto mais próximo do diretório atual, maior a prioridade de execução.

Exemplo negativo (que eu realmente vivenciei). No começo, eu cometia o erro inverso: escrevia uma série de instruções de uso único, como "não altere o banco de dados desta vez" ou "altere apenas este arquivo desta vez", no AGENTS.md. Como resultado, o arquivo ficou enorme e cheio de regras desatualizadas, o que acabou confundindo o Codex ao lê-lo. Depois disso, aprendi a lição —

Requisitos de uso único vão nos prompts; regras duradouras vão no AGENTS.md. Curto e preciso é melhor do que longo e vago.

A documentação oficial traz um hábito muito útil que vale a pena copiar: quando o Codex cometer o mesmo erro pela segunda vez, peça para ele fazer uma retrospectiva e adicionar a lição aprendida no AGENTS.md. Dessa forma, o seu manual é construído a partir de problemas reais vivenciados na prática, e não apenas de ideias abstratas.

💡 Resumo em uma frase: Consolide as "regras permanentes" no AGENTS.md. Algo curto, preciso e real funciona muito melhor do que uma longa lista de palavras vazias.

03 Prompts não dependem de inspiração: use o modelo de quatro partes (objetivo + contexto + restrições + aceitação)

Por que fazer isso. O artigo anterior sobre a folha de dicas já mencionou a escrita de prompts, aqui trago apenas uma estrutura pronta para copiar. O Codex é muito poderoso hoje e consegue entregar resultados mesmo com prompts mal escritos; contudo, em projetos grandes ou de alto risco, se o prompt for confuso, ele terá que adivinhar e, se adivinhar errado, você terá retrabalho.

A "fórmula padrão para bons prompts" recomendada oficialmente é um conjunto de quatro partes, que eu utilizo como um exercício de preenchimento de lacunas:

Elemento	O que ele responde	O que acontece se não preencher
Objetivo (Goal)	O que você realmente quer alterar ou criar	Ele perde o foco e faz um monte de coisas que você não pediu
Contexto (Context)	Quais arquivos, erros ou exemplos estão relacionados (você pode mencionar arquivos com @)	Ele procura no lugar errado e faz caminhos desnecessários
Restrições (Constraints)	Quais padrões, arquiteturas ou requisitos de segurança devem ser seguidos	Ele segue seus próprios hábitos e bagunça todo o estilo
Aceitação (Done when)	Quais condições determinam que o trabalho está concluído	Ele acha que "se rodar está bom" e entrega, deixando os bugs para você

Como fazer. Você não precisa escrever cada prompt como se fosse um contrato. Mas para qualquer tarefa que seja minimamente complexa ou que você queira evitar retrabalho, passe mentalmente (ou escreva diretamente) por essas quatro partes antes de enviar: o que eu quero que ele faça, onde estão os arquivos relacionados, o que não deve ser tocado e o que define a conclusão da tarefa.

Analogia: Esse modelo de quatro partes funciona como as instruções para uma equipe de reforma. Você não diria apenas "deixe a cozinha mais bonita" e esperaria que começassem a trabalhar — você precisa especificar o estilo desejado (objetivo), onde estão as plantas e esquemas elétricos/hidráulicos (contexto), quais paredes estruturais não podem ser demolidas (restrições) e que, na entrega, as luzes funcionem, a água corra e os armários fiquem firmes (aceitação). Quanto mais detalhada a instrução, menor o retrabalho.

O item que eu mais esquecia era a aceitação. Antigamente, eu pedia ao Codex para alterar a validação de um formulário dizendo apenas "adicione uma validação de formato de celular", sem dizer "garanta que a validação de e-mail existente continue funcionando e que os testes relacionados passem". Ele adicionou rapidamente a validação de celular, mas acabou quebrando a lógica do e-mail. Só percebi isso ao rodar os testes antes de subir para produção. Desde então, a seção "Done when" tornou-se obrigatória para mim.

💡 Resumo em uma frase: Não dependa de inspiração para prompts. Siga a estrutura de quatro campos "objetivo + contexto + restrições + aceitação" e nunca se esqueça da aceitação.

04 Para tarefas complexas, crie um plano antes de agir

Por que fazer isso. Quando uma tarefa é complexa ou vaga, se você pedir para escrever código direto, ele terá que adivinhar suas intenções enquanto digita, e você só perceberá que o rumo estava errado muito tarde. Pedir para ele criar um plano primeiro é como ter uma oportunidade barata de "ajuste de rumo" antes de começar a codificar.

Analogia: É como ver a planta antes de construir uma casa. Ninguém manda a equipe levantar as paredes sem um desenho — ter que demolir paredes tortas é doloroso. O plano é esse desenho, apenas algumas linhas de texto, mas muito mais barato do que refazer um bloco inteiro de código.

Como fazer. A documentação oficial traz algumas abordagens, que listei por ordem de facilidade de uso:

Use o modo Plan (mais recomendado): Use o /plan no CLI ou alterne pressionando Shift+Tab. Ele coletará o contexto primeiro, fará perguntas para esclarecer dúvidas e entregará um plano mais consistente. Depois que você aprovar, ele começará a trabalhar.
Peça para ele fazer perguntas a você: Se você mesmo não tiver clareza do que quer, peça para ele "não escrever código ainda, mas me questionar e transformar essa ideia vaga em uma proposta concreta".
Use o modelo PLANS.md: Um método mais avançado para permitir que tarefas longas e de várias etapas sigam um modelo de plano de execução (consulte o guia oficial de planos de execução para mais detalhes).

Exemplo negativo. A documentação oficial lista claramente "pular o planejamento em tarefas complexas de várias etapas" como um erro comum, e eu sei bem disso por experiência própria. No ano passado, pedi ao Codex para me ajudar a migrar um módulo de callbacks para async/await. Para poupar tempo, não pedi um plano e disse apenas "altere como achar melhor". Ele fez a alteração, mas no meio do caminho resolveu "otimizar" por conta própria uma lógica global de tratamento de erros. Toda a alteração virou uma bagunça e, na hora do review, fiquei tonto olhando para aquele diff. No fim das contas, precisei dar um git reset e começar de novo — desta vez usei o /plan primeiro, pedindo para listar "quais arquivos alterar, o que alterar em cada arquivo e o que não tocar de jeito nenhum". Após confirmar, deixei que ele fizesse o trabalho, e passou de primeira.

💡 Resumo em uma frase: Quanto mais complexa ou vaga for a tarefa, mais importante é usar o /plan para desenhar um plano e alinha o rumo antes de deixá-lo programar.

05 Níveis de permissão: rigoroso por padrão, flexibilizado gradualmente por cenário

Por que fazer isso. O Codex vem com uma sandbox integrada no nível do sistema operacional e possui dois controles cruciais: o modo de aprovação (approval mode), que controla se ele deve perguntar antes de executar comandos, e o modo sandbox (sandbox mode), que controla se ele pode ler/escrever em diretórios e quais arquivos pode acessar. Dar permissão total logo de início é como entregar o volante e o acelerador simultaneamente a um motorista iniciante cujo comportamento você ainda não conhece.

Analogia: É como configurar permissões para um estagiário recém-chegado. No primeiro dia, você dá apenas acesso para leitura de código e execução de testes locais; conforme ganha confiança, libera gradativamente a alteração de arquivos e conexão ao banco de dados. Ninguém entrega a chave do ambiente de produção a um novato no primeiro dia.

Como fazer. A recomendação oficial é bem direta:

Iniciantes devem começar com as permissões padrão, mantendo a aprovação e a sandbox restritas.
Depois de entender um fluxo de trabalho específico e quando precisar de mais agilidade, flexibilize as permissões apenas para repositórios confiáveis ou cenários específicos, em vez de liberar tudo de uma vez.

Cenário	Nível sugerido	Motivo
Iniciantes / Projetos desconhecidos	Padrão (perguntar antes de agir, sandbox restrita)	Segurança: entenda o que ele vai fazer antes de aprovar
Repositórios confiáveis próprios / Tarefas repetitivas	Aprovação moderadamente flexibilizada	Reduz a frustração de ter que clicar em "aprovar" o tempo todo
Scripts desconhecidos / Código de terceiros	Máxima restrição	Evita a execução de comandos inesperados

A documentação oficial lista "dar permissão total de acesso ao computador ao Codex antes de entender o fluxo de trabalho" como um erro comum. Minha própria lição não foi um desastre completo, mas serviu de alerta: houve uma época em que, cansado de confirmar tudo, flexibilizei demais a aprovação. Como resultado, durante uma refatoração ele executou um comando de limpeza que eu não analisei detalhadamente e acabou apagando alguns arquivos temporários que eu ainda precisava usar — não foi uma catástrofe, mas me deu um susto. Economizar esses poucos segundos de confirmação simplesmente não vale o risco.

💡 Resumo em uma frase: Mantenha as permissões restritas por padrão e entenda o que ele fará antes de liberar; flexibilize gradualmente apenas para cenários confiáveis, e nunca libere tudo de uma vez para poupar tempo.

06 Faça-o se autovalidar: testar, checar e revisar, em vez de apenas "terminar de escrever"

Por que fazer isso. Esta é, na minha opinião, a dica mais valiosa de todas. Não deixe o Codex parar assim que terminar de escrever o código — peça para ele já criar os testes correspondentes, rodar as verificações necessárias e revisar o diff antes de entregar para você. Se fizer isso corretamente, você economizará ciclos cansativos de "ele escreve, você testa, dá erro, pede para ele corrigir".

Mas há um pré-requisito: ele precisa saber o que define um trabalho "bom". De onde vem essa métrica? Ou é fornecida no prompt, ou está escrita no AGENTS.md (o que nos traz de volta à seção 02).

Como fazer. O ciclo de autoverificação sugerido oficialmente inclui as seguintes etapas, que você pode incluir diretamente em suas instruções:

Criar ou atualizar testes para a alteração atual
Executar a suíte de testes correspondente
Executar lint, formatação e verificação de tipos
Confirmar se o comportamento final atende exatamente aos requisitos
Revisar o diff para encontrar bugs, regressões ou códigos perigosos

No CLI, o comando /review é extremamente valioso para esta seção: ele permite revisar as alterações comparando com a branch base no estilo de um PR, revisar alterações não commitadas, revisar um commit específico ou seguir instruções personalizadas. Se sua equipe possui um arquivo code_review.md referenciado no AGENTS.md, o Codex seguirá exatamente esse padrão durante o review — isso garante que o critério de revisão seja unificado em equipes colaborativas.

Exemplo negativo. A documentação oficial lista "não deixar o agent ver o resultado de seu trabalho" (ou seja, não informar como rodar comandos de build e testes) como um erro comum. Tive uma experiência típica disso: pedi para ele alterar uma função de processamento de dados e não pedi para rodar os testes. Ele garantiu que estava "concluído e com a lógica correta", e eu acreditei. O resultado foi que o código lançou uma exceção em um caso de borda — ele simplesmente não teve a chance de perceber isso porque não pedi para rodar o teste. Depois disso, criei um hábito: sempre que houver mudança de lógica, incluo no final do prompt a frase "após alterar, execute <测试命令> e me avise quando tudo passar". Uma instrução simples que evita a maior parte do retrabalho.

💡 Resumo em uma frase: Deixe o Codex testar, checar e revisar tudo antes de entregar o trabalho, desde que você forneça o critério do que é "bom" no prompt ou no AGENTS.md.

07 Para tarefas de produção, colete a cadeia de evidências antes de corrigir

Por que fazer isso. O desenvolvimento local de recursos pode contar com a validação de testes. No entanto, falhas em produção exigem respostas a perguntas difíceis: qual foi o sintoma original visto pelo usuário? Como você o reproduz? Qual linha de log corresponde a essa requisição? A correção foi validada simulando o mesmo fluxo de usuário?

Hoje, eu escrevo esta regra nas normas do projeto: colete evidências primeiro, faça o diagnóstico depois e só então aplique a correção. O Codex consegue buscar no código seguindo pistas, mas se você simplesmente disser "corrija isso para mim", ele assumirá a causa mais provável como a real e considerará a tarefa concluída se os testes locais passarem. Para incidentes de produção, essas duas suposições não são suficientes.

Como fazer. Primeiro, instrua-o a não alterar nenhum código e focar apenas na coleta de evidências. O prompt pode ser escrito assim:

text

先不要改代码。请按证据链排查这个线上问题：

1. 复现用户路径，记录请求方式、状态码、关键响应摘要和时间。
2. 查对应时间段的应用日志，只摘出相关错误行。
3. 找到涉及的配置、路由、任务或数据表，但不要修改生产状态。
4. 给出「已验证事实 / 待确认假设 / 下一步验证」三段结论。
5. 输出时脱敏，隐藏 token、私有访问链接、邮箱、手机号、订单号和内部地址。

Esse texto puxa o Codex de volta da ideia de "corrigir diretamente" para "provar primeiro". O diagnóstico final fornecido por ele precisa ser rastreável a partir das evidências: qual requisição falhou, qual linha de log gerou o erro, qual configuração participou desse fluxo e qual ação será tomada a seguir para refutar as hipóteses.

Eu coloco uma regra de longo prazo no AGENTS.md, específica para este tipo de tarefa:

## 线上问题处理

- 先复现原问题，记录状态码、关键响应摘要、日志时间和验证路径。
- 未经确认，不要改生产数据、权限、可见性、计费、通知或工单状态。
- 输出内容必须脱敏，不要贴 token、用户信息、私有链接、密钥、完整 IP 或订单号。
- 修复后必须用原用户路径复查；本地测试通过不等于线上恢复。
- 如果不能复查，说明缺哪条证据、为什么缺、下一步谁能补。

Essas poucas regras parecem diretrizes de operações e são muito adequadas para o Codex. Ao ler "após a correção, reavalie seguindo o fluxo de usuário original", ele não considerará a tarefa concluída apenas rodando um teste unitário; ao ler "sem confirmação prévia, não altere dados de produção", ele parará para perguntar se encontrar uma operação que possa afetar o estado do usuário.

A anonimização deve manter as informações úteis para diagnóstico. Se você apagar todas as evidências ao anonimizar, no final restará apenas "falha em alguma API", e ninguém mais conseguirá investigar. Preserve a estrutura e oculte os valores confidenciais:

Informação original	Formato utilizável após a anonimização
`https://example.com/private/path?token=secret_value`	`https://example.com/private/path?token=<token>`
`user@example.com`	`<user-email>`
`order_20260201_123456`	`<order-id>`
`Authorization: Bearer ...`	`Authorization: Bearer <redacted>`
`2026-02-01 14:03:22 status=500`	Preservar a hora original e o código de status

Horários, códigos de status, tipos de erro e padrões de rotas geralmente podem ser mantidos; valores que identificam diretamente usuários, contas, chaves e ativos internos devem ser ocultados. Dessa forma, as pessoas podem analisar com base nas evidências, sem expor informações confidenciais em PRs, Issues ou chats públicos.

Como aceitar. O critério de aceitação para tarefas de produção deve retornar ao fluxo original. Se uma API quebrou, faça uma nova chamada para a mesma API e registre o novo código de status e resumo da resposta; se uma página quebrou, use o navegador para simular as ações do usuário; se uma fila ou tarefa agendada quebrou, verifique o log e as saídas da próxima execução. Caso as permissões do ambiente sejam insuficientes, não escreva de forma vaga "não foi possível validar", mas especifique claramente: falta de acesso a produção, falta de conta de teste, falta de webhook externo ou necessidade de confirmação do usuário.

💡 Resumo em uma frase: Em tarefas de produção, não deixe o Codex adivinhar as causas de início, peça a cadeia de evidências primeiro; após corrigir, reavalie a partir do fluxo de usuário original, anonimizando valores sensíveis, mas preservando o código de status, horários e padrões de erros.

08 Divida tarefas pesadas para sub-agents: uma thread executa apenas uma tarefa por vez

Por que fazer isso. Uma sessão (session) não é apenas um histórico de chat; ela é uma thread de trabalho que acumula contexto continuamente. Quanto mais longa a thread e mais misturado o conteúdo, menor a qualidade das respostas. Portanto, como gerenciar threads afeta diretamente o resultado final.

Analogia: É como organizar sua mesa de trabalho. Se sua mesa estiver cheia de documentos de três projetos diferentes ao mesmo tempo, você será mais lento e confuso ao procurar coisas e tomar decisões. Uma mesa limpa com apenas um trabalho em andamento oferece a maior eficiência. A thread do Codex é a mesa de trabalho dele.

Como fazer (dois pontos):

Primeiro, uma thread faz apenas um trabalho contínuo. O significado original do guia é: enquanto for o mesmo problema, permaneça na mesma thread — ela preserva a linha de raciocínio completa. Só quando o trabalho realmente se ramificar é que você deve usar /fork para iniciar uma nova thread. Em outras palavras, divida as threads por tarefas, não por projetos — o antipadrão a ser evitado é usar "uma única thread do início ao fim para todo o projeto", o que infla o contexto e piora as respostas.

Segundo, delegue tarefas isoladas com escopo definido para sub-agents (subagent). Deixe a thread principal focada no problema central e delegue tarefas como explorar código, escrever testes ou fazer triagem (que podem ser concluídas de forma independente e têm entregas claras) para sub-agents, evitando que poluam a atenção da thread principal.

Alguns comandos práticos para gerenciar threads (sujeitos ao que estiver ativo no seu codex --help local):

/resume: Continua uma conversa salva anteriormente
/fork: Inicia uma nova thread mantendo o histórico original
/compact: Comprime o contexto antigo em um resumo quando a thread fica longa (o Codex também faz isso automaticamente)
/status: Verifica o status da sessão atual

Minha rotina atual é "uma thread para cada tarefa" e arquivar a thread após a conclusão. Essa mudança parece pequena, mas desde que deixei de usar "uma única thread mestre para todo o projeto", as respostas do Codex raramente "se misturam" — antigamente, ele costumava poluir as decisões atuais trazendo contextos de outras demandas de três dias atrás.

💡 Resumo em uma frase: Uma thread para apenas uma tarefa; divida trabalhos pesados ou secundários para sub-agents, evitando inflar o contexto.

09 Guia de início rápido: uma tabela comparativa de "Erros Comuns ❌ / Práticas Corretas ✅"

A documentação oficial encerra com uma lista de "erros comuns", resumindo a essência das oito seções anteriores. Consolidei isso em uma tabela comparativa para que você possa fazer uma autoverificação — se identificar algum ponto à esquerda, ajuste conforme a recomendação à direita.

❌ Erro comum observado	✅ Prática correta
Colocar regras permanentes de forma bagunçada no prompt	Mover regras permanentes para o `AGENTS.md` ou skill; manter no prompt apenas requisitos temporários
Não informar como rodar comandos de build e testes	Descrever claramente no `AGENTS.md` como executar e testar, permitindo que ele veja os resultados
Escrever código diretamente em tarefas complexas de várias etapas, sem planejar	Usar `/plan` em tarefas complexas para desenhar o plano e alinhar o rumo antes de codificar
Conceder permissões totais antes de entender o fluxo de trabalho	Adotar restrição por padrão e flexibilizar gradualmente por cenários confiáveis
Usar apenas uma única thread do início ao fim do projeto	Usar uma thread por tarefa e criar novas com `/fork` apenas quando houver ramificações
Alterar os mesmos arquivos em várias threads sem usar o git worktree	Usar o git worktree para abrir áreas de trabalho independentes para threads paralelas, evitando conflitos
Automatizar tarefas que ainda não estão estáveis	Executar manualmente até estabilizar e depois considerar transformar em um skill ou automação
Ficar observando passo a passo e não conseguir fazer outras coisas	Deixar rodando em paralelo e focar nas suas próprias tarefas
Tentar corrigir problemas de produção antes de reproduzi-los	Registrar primeiro os sintomas originais, status de requisição, horários dos logs e hipóteses a testar
Declarar o problema de produção resolvido logo após os testes locais passarem	Reavaliar a partir do fluxo original do usuário, registrando os novos códigos de status, comportamentos da página ou logs de tarefas
Colar logs, links e dados de usuário originais em PRs públicos	Anonimizar valores sensíveis, mas manter horários, códigos de status, tipos de erro e padrões de rotas

Como seguir as orientações. Não olhe para esta tabela apenas uma vez. Minha recomendação é: na próxima vez em que achar que o uso do Codex está "difícil ou com muito retrabalho", volte aqui e compare com a coluna da esquerda. É muito provável que encontre qual ponto não foi bem executado. Nenhum desses erros me foi contado — eu mesmo bati a cabeça na parede em cada um deles para aprender.

💡 Resumo em uma frase: Use esta tabela comparativa para autoverificação. Ajustar o que estiver errado na coluna da esquerda conforme a recomendação da direita é muito mais eficaz do que decorar qualquer lema de "melhores práticas".

10 Resumo

Este artigo não trouxe verdades óbvias, mas sim oito práticas que eu mesmo validei e que podem mudar diretamente sua forma de uso:

Mudar a mentalidade: Tratar o Codex como um parceiro de equipe sob treinamento contínuo é a base de tudo.
Escrever o AGENTS.md: Consolide as regras permanentes nele — mantenha-o curto, preciso e real.
Modelo de quatro partes de prompts: Objetivo + contexto + restrições + aceitação. Siga o modelo e nunca se esqueça da aceitação.
Planejar antes de codificar: Use o /plan em tarefas complexas. Não abra mão dessa oportunidade barata de correção de rota.
Níveis de permissão: Restrito por padrão; entenda o que ele fará antes de aprovar.
Faça-o se autovalidar: Peça para testar, checar e revisar tudo junto, desde que informe a ele o critério do que é "bom".
Investigar incidentes primeiro: Reprodução, logs, código de status, anonimização e reavaliação pelo fluxo original. Não pule etapas.
Gerenciar threads: Uma thread para apenas uma tarefa; delegue tarefas pesadas para sub-agents.

Agora você deve conseguir: Ao receber qualquer tarefa do Codex, instintivamente pensar — esta tarefa precisa de um plano primeiro? Preenchi todas as quatro partes do prompt? As regras no AGENTS.md são suficientes? Preciso pedir para ele fazer autoverificação? Qual nível de permissão usar? Preciso coletar a cadeia de evidências primeiro? Transformar isso em memória muscular fará com que sua colaboração com o Codex passe de "tentativa e erro" a um processo "organizado".

No próximo artigo [37 Resolução de Problemas Comuns], conversaremos sobre algo mais prático: por mais que siga as regras, sempre haverá momentos em que o Codex cometerá falhas — erros de comandos, alterações quebradas, falhas de conexão ou comportamentos anormais. Enfrentar problemas não é terrível; terrível é não saber por onde começar a investigar. Fica uma pequena reflexão: a maior parte das práticas explicadas aqui como "planejar com /plan primeiro, testar com frequência e dar passos curtos" serve, na verdade, para prevenir problemas. Mas e se o problema realmente ocorrer, onde você deve olhar primeiro? O próximo artigo trará um roteiro passo a passo para investigação.

Melhores Práticas: Além das "verdades óbvias", aquelas que realmente funcionam ​

01 Primeiro, mude a mentalidade: o Codex é um parceiro para treinar, não uma ferramenta descartável ​

02 Escreva o AGENTS.md corretamente: faça-o trabalhar automaticamente "com contexto" ​

03 Prompts não dependem de inspiração: use o modelo de quatro partes (objetivo + contexto + restrições + aceitação) ​

04 Para tarefas complexas, crie um plano antes de agir ​

05 Níveis de permissão: rigoroso por padrão, flexibilizado gradualmente por cenário ​

06 Faça-o se autovalidar: testar, checar e revisar, em vez de apenas "terminar de escrever" ​

07 Para tarefas de produção, colete a cadeia de evidências antes de corrigir ​

08 Divida tarefas pesadas para sub-agents: uma thread executa apenas uma tarefa por vez ​

09 Guia de início rápido: uma tabela comparativa de "Erros Comuns ❌ / Práticas Corretas ✅" ​

10 Resumo ​

Leituras Recomendadas ​