Primeiros passos com o Codex: Melhores práticas para obter melhores resultados

Se você é novo no @OpenAI Codex ou em agentes de codificação em geral, este guia vai ajudar você a obter resultados melhores mais rapidamente. Ele aborda os hábitos essenciais que tornam o Codex mais eficaz na CLI, nas extensões de IDE e no aplicativo Codex, desde prompts e planejamento até validação, MCP, skills e automações.

O Codex funciona melhor quando você o trata menos como um assistente pontual e mais como um colega de equipe que você configura e melhora ao longo do tempo.

Um modelo mental útil é: comece com o contexto de tarefa certo, use o AGENTS.md para orientações duradouras, configure o Codex para corresponder ao seu fluxo de trabalho, conecte sistemas externos com MCP, transforme trabalhos repetitivos em skills e automatize fluxos de trabalho estáveis.

1. Configure o Codex para um primeiro uso robusto com contexto e prompting claros

O Codex já é forte o suficiente para ser útil mesmo quando seu prompt não é perfeito. Muitas vezes você pode dar a ele um problema difícil com configuração mínima e ainda assim obter um resultado sólido. Um prompt claro não é obrigatório para obter valor, mas torna os resultados mais confiáveis, especialmente em bases de código maiores ou tarefas de alto risco.

Se você trabalha em um repositório grande ou complexo, o maior ganho geralmente é dar ao Codex o contexto de tarefa certo e uma estrutura clara para o que você deseja fazer.

Um bom padrão é incluir quatro coisas no seu prompt:

• Objetivo: O que você está tentando mudar ou construir?
• Contexto: Quais arquivos, pastas, docs, exemplos ou erros são importantes para esta tarefa? Você pode usar @ para mencionar certos arquivos como contexto.
• Restrições: Quais padrões, arquitetura, requisitos de segurança ou convenções o Codex deve seguir?
• Pronto quando: O que deve ser verdade antes da tarefa ser concluída, como testes passando, comportamento mudando ou um bug sendo corrigido?

Isso ajuda o Codex a manter o escopo, fazer menos suposições e produzir trabalhos que são mais fáceis de revisar e validar.

Escolha um nível de raciocínio com base na dificuldade da tarefa e teste o que funciona melhor para o seu fluxo de trabalho. Diferentes usuários e tarefas se beneficiam de configurações diferentes.

• Baixo para tarefas mais rápidas e bem definidas
• Médio ou Alto para mudanças mais complexas ou depuração
• Muito Alto para tarefas longas, com agente e que exigem muito raciocínio

Dica para novos usuários

: A maioria das pessoas ganha velocidade mais rápido começando com algumas pequenas vitórias básicas, como fazer perguntas ao Codex sobre a base de código ou usá-lo para fazer uma pequena correção com escopo definido. Recomendo fortemente usar a ditadura por voz no aplicativo Codex para acelerar as iterações.

Esforços de raciocínio do Codex

2. Reduza erros em tarefas difíceis fazendo o Codex planejar primeiro

Se a tarefa for complexa, ambígua ou difícil de descrever claramente, peça ao Codex para planejar antes de começar a codificar.

Existem algumas boas maneiras de fazer isso:

Usar o Modo de Planejamento: Para a maioria dos usuários, esta é a opção mais fácil e eficaz. O Modo de Planejamento permite que o Codex reúna contexto, faça perguntas esclarecedoras e construa um plano mais forte antes da implementação. Ative com /plan ou Shift+Tab.

Peça ao Codex para entrevistá-lo: Se você tem uma ideia geral do que quer, mas não tem certeza de como descrevê-la bem, peça ao Codex para questioná-lo primeiro. Diga a ele para desafiar suas suposições e transformar a ideia vaga em algo concreto antes de escrever código.

Use um modelo PLANS.md: Para fluxos de trabalho mais avançados, você pode configurar o Codex para seguir um modelo PLANS.md ou de plano de execução para trabalhos mais longos ou com várias etapas. Para mais detalhes, confira nosso guia de planos de execução.

Modo de Planejamento

3. Torne as orientações bem-sucedidas reutilizáveis com o AGENTS.md

Depois que um padrão de prompt funciona, o próximo passo é parar de repeti-lo manualmente. É aí que entra o AGENTS.md.

Pense no AGENTS.md como um README para agentes. É um formato simples e aberto que é carregado automaticamente no contexto e é o melhor lugar para codificar como você e sua equipe querem que o Codex funcione em um repositório.

Um bom AGENTS.md geralmente cobre:

• Layout do repositório e diretórios importantes
• Como executar o projeto
• Comandos de build, teste e lint
• Convenções de engenharia e expectativas de PR
• Restrições e regras de "não fazer"
• O que significa "pronto" e como verificar o trabalho

O comando /init na CLI é o comando de início rápido para criar um AGENTS.md inicial no diretório atual. É um ótimo ponto de partida, mas você deve editar o resultado para corresponder à forma como sua equipe realmente constrói, testa, revisa e entrega código.

Você pode criar arquivos AGENTS.md em vários níveis: um AGENTS.md global para padrões pessoais que fica em ~/.codex, um arquivo no nível do repositório para padrões compartilhados e arquivos mais específicos em subdiretórios para regras locais. Se houver um arquivo mais específico mais próximo do seu diretório atual, essa orientação prevalece.

Mantenha-o prático. Um AGENTS.md curto e preciso é mais útil do que um arquivo longo cheio de regras vagas. Comece com o básico e adicione novas regras somente depois de notar erros repetidos.

Se o AGENTS.md começar a ficar muito grande, mantenha o arquivo principal conciso e faça referência a arquivos markdown específicos da tarefa para coisas como planejamento, revisão de código ou arquitetura.

Dica

: Quando o Codex cometer o mesmo erro duas vezes, peça a ele uma retrospectiva e atualize o AGENTS.md. As orientações permanecem práticas e baseadas em atritos reais.

Site do AGENTS.md

4. Obtenha um comportamento mais consistente configurando o Codex para corresponder ao seu fluxo de trabalho

A configuração é uma das principais maneiras de fazer o Codex se comportar de forma mais consistente entre sessões e superfícies. Por exemplo, você pode definir padrões para escolha do modelo, esforço de raciocínio, modo sandbox, política de aprovação, perfis e configuração do MCP.

Um bom padrão inicial é:

• Manter padrões pessoais em ~/.codex/config.toml (Configurações → Configuração → Abrir config.toml no aplicativo Codex)
• Manter o comportamento específico do repositório em .codex/config.toml
• Usar substituições de linha de comando apenas para situações pontuais (se você usar a CLI)

O Config.toml é onde você define preferências duradouras, como servidores MCP, perfis, configuração de multiagente e recursos experimentais. Você pode editá-lo diretamente ou pedir ao Codex para atualizá-lo para você.

O Codex vem com sandboxing em nível de sistema operacional e tem dois controles principais que você pode gerenciar. O modo de aprovação determina quando o Codex pede sua permissão para executar um comando e o modo sandbox determina se o Codex pode ler ou escrever no diretório e quais arquivos o agente pode acessar.

Se você é completamente novo em agentes de codificação, a recomendação é começar de forma conservadora com permissões padrão. Mantenha a aprovação e o sandbox restritos por padrão e só afrouxe as permissões para repositórios confiáveis ou fluxos de trabalho específicos quando a necessidade ficar clara.

Observe que a CLI, a IDE e o aplicativo Codex compartilham as mesmas camadas de configuração. Saiba mais em nossa página de documentação de configuração de exemplo.

Dica

: Configure o Codex para seu ambiente real desde o início. Muitos problemas de qualidade são, na verdade, problemas de configuração, como diretório de trabalho errado, falta de permissão de escrita, padrões de modelo errados ou falta de ferramentas e conectores.

5. Melhore a confiabilidade fazendo o Codex testar, validar e revisar o trabalho

Não pare de pedir ao Codex para fazer uma alteração. Peça a ele para criar testes quando necessário, executar as verificações relevantes, validar o resultado e revisar o trabalho antes de você aceitá-lo.

O Codex pode fazer esse loop para você, mas apenas se ele souber como é o "bom". Essa orientação pode vir do prompt ou do AGENTS.md.

Isso pode incluir:

• Escrever ou atualizar testes para a alteração
• Executar os conjuntos de teste corretos
• Verificar lint, formatação ou verificações de tipo
• Confirmar que o comportamento final corresponde à solicitação
• Revisar o diff em busca de bugs, regressões ou padrões arriscados

Dica:

Ative o painel de diff no aplicativo Codex para

revisar alterações diretamente localmente. Clique em uma linha específica para fornecer feedback que será usado como contexto na próxima interação do Codex.

Uma opção útil aqui é o comando de barra /review, que oferece várias maneiras diferentes de revisar o código:

• Revisar em relação a um branch base para revisão no estilo PR
• Revisar alterações não commitadas
• Revisar um commit
• Usar instruções de revisão personalizadas

Se você e sua equipe tiverem um arquivo code_review.md que é referenciado no AGENTS.md, o Codex pode seguir essa orientação durante a revisão também. Este é um padrão forte para equipes que desejam que o comportamento de revisão permaneça consistente entre repositórios e contribuidores.

O Codex não deve apenas gerar código. Com as instruções certas, ele também pode ajudar a testá-lo, validá-lo e revisá-lo.

Se você usa o GitHub Cloud, pode configurar facilmente o Codex para executar revisões de código para seus PRs. Nós fazemos o Codex revisar 100% dos PRs na OpenAI. Você tem a opção de ativar revisões automáticas ou fazer o Codex revisar reativamente quando você mencionar @Codex.

/review na CLI do Codex

6. Traga ferramentas externas e contexto ao vivo para o Codex com MCPs

Use MCPs quando o contexto que o Codex precisa estiver fora do repositório. Ele permite que o Codex se conecte às ferramentas e sistemas que você já usa, para que você não precise ficar copiando e colando informações ao vivo nos prompts.

O Model Context Protocol, ou MCP, é um padrão aberto para conectar o Codex a ferramentas e sistemas externos.

Use MCP quando:

• O contexto necessário estiver fora do repositório
• Os dados mudarem com frequência
• Você quiser que o Codex use uma ferramenta em vez de depender de instruções coladas
• Você precisar de uma integração repetível entre usuários ou projetos

O Codex suporta servidores STDIO e HTTP Streamable com OAuth.

No aplicativo Codex, vá para Configurações → Servidores MCP para ver servidores personalizados e recomendados. Muitas vezes, o Codex pode ajudá-lo a instalar os servidores necessários. Tudo o que você precisa fazer é perguntar. Você também pode usar o comando codex mcp add na CLI para adicionar seus servidores personalizados com um nome, URL e informações adicionais.

Dica

: Adicione ferramentas apenas quando elas desbloquearem um fluxo de trabalho real. Não comece conectando todas as ferramentas que você usa. Comece com uma ou duas ferramentas que claramente removam um loop manual que você já faz com frequência e, em seguida, expanda a partir daí.

Gerenciamento de servidor MCP

7. Transforme fluxos de trabalho repetitivos em skills reutilizáveis

Quando um fluxo de trabalho se torna repetitivo, pare de depender de prompts longos ou de idas e vindas frequentes. Use uma Skill para empacotar as instruções em um arquivo SKILL.md, contexto e lógica de suporte que o Codex deve aplicar consistentemente. As Skills funcionam na CLI, na extensão da IDE e no aplicativo Codex.

Mantenha cada skill com escopo restrito a um trabalho. Comece com 2 a 3 casos de uso concretos, defina entradas e saídas claras e escreva a descrição de modo que ela diga claramente o que a skill faz e quando usá-la. Inclua os tipos de frases de gatilho que um usuário realmente diria.

Não tente cobrir todos os casos extremos de antemão. Comece com uma tarefa representativa, faça-a funcionar bem, transforme esse fluxo de trabalho em uma skill e melhore a partir daí. Inclua scripts ou ativos extras apenas quando eles melhorarem significativamente a confiabilidade.

Uma boa regra prática: se você continua reutilizando o mesmo prompt ou corrigindo o mesmo fluxo de trabalho, provavelmente ele deveria se tornar uma skill.

As skills são especialmente úteis para trabalhos recorrentes como:

• Triagem de logs
• Elaboração de notas de versão
• Revisão de PR contra uma lista de verificação
• Planejamento de migração
• Resumos de telemetria ou incidentes
• Fluxos de depuração padrão

A skill $skill-creator é o melhor lugar para começar a criar a primeira versão de uma skill e usar a skill $skill-installer para instalá-la localmente. Uma das partes mais importantes de uma skill é a descrição. Ela deve dizer claramente o que a skill faz e quando usá-la.

Dica

: As skills pessoais são armazenadas em

$HOME /.agents/skills, e as skills compartilhadas da equipe podem ser verificadas em .agents/skills dentro de um repositório. Isso é especialmente útil para integrar novos membros da equipe.

Criação e instalação de skill

Interface de skills do aplicativo Codex

8. Economize tempo em trabalhos recorrentes com automações

Quando um fluxo de trabalho estiver estável, você pode agendar o Codex para executá-lo em segundo plano para você. No aplicativo Codex, as automações permitem que você escolha o projeto, o prompt, a cadência e o ambiente de execução para uma tarefa recorrente.

Quando uma tarefa se tornar repetitiva para você, você pode criar facilmente uma automação na guia Automações no aplicativo Codex. Você pode escolher em qual projeto ela será executada, o prompt que ela executará (você pode invocar skills) e a cadência com que será executada. Você também pode escolher se a automação será executada em uma git worktree dedicada ou em seu ambiente local. Saiba mais sobre git worktrees.

Bons candidatos incluem:

• Resumir commits recentes
• Escanear possíveis bugs
• Elaborar notas de versão
• Verificar falhas de CI
• Produzir resumos de daily
• Executar fluxos de trabalho de análise repetíveis em um cronograma

Uma regra útil é que as skills definem o método, as automações definem o cronograma. Se um fluxo de trabalho ainda precisa de muita direção, transforme-o em uma skill primeiro. Quando se tornar previsível, a automação se torna um multiplicador de força.

Dica

: Use automações para reflexão e manutenção, não apenas para execução. Revise sessões recentes, resuma atritos repetidos e melhore prompts, instruções ou a configuração do fluxo de trabalho ao longo do tempo.

Criação de automação no aplicativo Codex

9. Mantenha-se organizado em trabalhos de longa duração com controles de sessão

As sessões do Codex não são apenas histórico de chat. Elas são threads de trabalho que acumulam contexto, decisões e ações ao longo do tempo, portanto, gerenciá-las bem tem um grande impacto na qualidade.

Gerenciar vários threads é mais fácil na interface do aplicativo Codex com a capacidade de fixar threads e criar worktrees. Mas se você estiver usando a CLI, estes comandos de barra são especialmente úteis:

• /experimental para ativar/desativar recursos experimentais e adicionar ao seu config.toml
• /resume para retomar uma conversa salva
• /fork para criar um novo thread preservando o transcript original
• /compact quando o thread estiver ficando longo e você quiser uma versão resumida do contexto anterior. Observe que o Codex compacta automaticamente as conversas para você
• /agent quando você estiver executando vários agentes e quiser alternar entre o thread do agente ativo
• /theme para escolher um tema de destaque de sintaxe
• /apps para usar aplicativos ChatGPT diretamente no Codex
• /status para inspecionar o estado atual da sessão

Mantenha um thread por unidade de trabalho coerente. Se o trabalho ainda fizer parte do mesmo problema, permanecer no mesmo thread geralmente é melhor porque preserva o rastro de raciocínio. Crie um fork apenas quando o trabalho realmente divergir.

Dica

:

Use os fluxos de trabalho

multiagente do Codex para delegar trabalhos com escopo definido do thread principal. Mantenha o agente principal focado no problema central e use subagentes para tarefas como exploração, testes ou triagem.

10. Erros comuns a evitar

Alguns erros comuns a evitar ao usar o Codex pela primeira vez:

• Sobrecarregar o prompt com regras duradouras em vez de movê-las para o AGENTS.md ou uma skill
• Não deixar o agente ver seu trabalho, não fornecendo detalhes sobre a melhor forma de executar comandos de build e teste
• Pular o planejamento em tarefas complexas e com várias etapas
• Dar ao Codex permissão total para seu computador antes que o fluxo de trabalho seja compreendido
• Executar vários threads ativos nos mesmos arquivos sem usar git worktrees
• Transformar uma tarefa recorrente em uma automação antes que ela seja confiável manualmente
• Usar o Codex em paralelo com seu próprio trabalho em vez de tratá-lo como algo que você precisa acompanhar passo a passo

Checklist para começar

1. Dê ao Codex o objetivo, contexto, restrições e critério de "pronto quando" corretos
2. Para tarefas difíceis, peça ao Codex para planejar primeiro
3. Crie um AGENTS.md inicial
4. Diga ao Codex como construir, testar, validar e revisar
5. Defina padrões de configuração que correspondam ao seu fluxo de trabalho
6. Adicione MCP para ferramentas externas de alto valor
7. Transforme fluxos de trabalho repetitivos em skills
8. Use automações quando um fluxo de trabalho estiver estável

Quanto mais você transformar seu fluxo de trabalho, padrões e contexto em algo que o Codex possa usar, mais verá o que o agente pode realmente fazer. Comece hoje!