Se você é novo no @OpenAI Codex ou em agentes de codificação em geral, este guia vai te ajudar a obter resultados melhores mais rápido. Ele cobre os hábitos essenciais que tornam o Codex mais eficaz em toda a CLI, 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ção duradoura, 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 forte com contexto e prompts 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 maior 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 relevantes para esta tarefa? Você pode mencionar certos arquivos com @ como contexto.
- Restrições: Quais padrões, arquitetura, requisitos de segurança ou convenções o Codex deve seguir?
- Concluído quando: O que deve ser verdade antes de a tarefa ser concluída, como testes passando, comportamento mudando ou um bug sendo corrigido?
Isso ajuda o Codex a permanecer no escopo, fazer menos suposições e produzir um trabalho que seja mais fácil 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
- Extra Alto para tarefas longas, agentivas e que exigem muito raciocínio
Dica para novos usuários
: A maioria das pessoas ganha velocidade mais rapidamente começando com algumas vitórias básicas, como fazer perguntas ao Codex sobre a base de código ou usá-lo para fazer uma pequena correção bem definida. Recomendo fortemente usar ditado 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 Plan: Para a maioria dos usuários, esta é a opção mais fácil e eficaz. O modo Plan permite que o Codex reúna contexto, faça perguntas esclarecedoras e construa um plano mais forte antes da implementação. Alterne com /plan ou Shift+Tab.
Peça ao Codex para te entrevistar: Se você tem uma ideia aproximada do que quer, mas não tem certeza de como descrevê-la bem, peça ao Codex para te questionar 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 Plan
3. Torne as orientações bem-sucedidas reutilizáveis com AGENTS.md
Assim 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 desejam 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 de barra /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 de modelo, esforço de raciocínio, modo sandbox, política de aprovação, perfis e configuração de 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 multiagentes 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 afrouxe as permissões apenas 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 o 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 testes 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:
Alterne o painel de diff no aplicativo Codex para
revisar alterações localmente. Clique em uma linha específica para fornecer feedback que será alimentado como contexto para a próxima rodada 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 uma branch base para revisão 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 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ê @Codex.
/review no Codex CLI
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. Isso 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 copiadas
- Você precisar de uma integração repetível entre usuários ou projetos
O Codex suporta servidores STDIO e Streamable HTTP com OAuth.
No aplicativo Codex, vá em Configurações → Servidores MCP para ver servidores personalizados e recomendados. Muitas vezes, o Codex pode ajudar a instalar os servidores necessários. Tudo que você precisa fazer é pedir. Você também pode usar o comando codex mcp add na CLI para adicionar seus servidores personalizados com um nome, URL e qualquer informação adicional.
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 depois expanda a partir daí.
Gerenciamento de servidores MCP
7. Transforme fluxos de trabalho repetidos em skills reutilizáveis
Quando um fluxo de trabalho se tornar repetível, pare de depender de prompts longos ou idas e vindas constantes. Use uma Skill para empacotar as instruções em um arquivo SKILL.md, contexto e lógica de suporte que o Codex deve aplicar de forma consistente. As skills funcionam na CLI, na extensão da IDE e no aplicativo Codex.
Mantenha cada skill bem focada em um trabalho. Comece com 2 a 3 casos de uso concretos, defina entradas e saídas claras e escreva a descrição de forma que 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 de borda de antemão. Comece com uma tarefa representativa, faça-a funcionar bem, depois 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 deveria se tornar uma skill.
Skills são especialmente úteis para trabalhos recorrentes como:
- Triagem de logs
- Elaboração de notas de versão
- Revisão de PR com base em 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
: Skills pessoais são armazenadas em
$HOME /.agents/skills, e skills de equipe compartilhadas 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 skills
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 será executado (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 worktree git 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 standup
- Executar fluxos de trabalho de análise repetíveis em um cronograma
Uma regra útil é que skills definem o método, automações definem a agenda. Se um fluxo de trabalho ainda precisa de muita direção, transforme-o em uma skill primeiro. Quando for 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, então gerenciá-las bem tem um grande impacto na qualidade.
Gerenciar várias 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, esses 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 uma nova thread preservando a transcrição original
- /compact quando a thread estiver ficando longa 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 a 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 uma thread por unidade coerente de trabalho. Se o trabalho ainda fizer parte do mesmo problema, permanecer na mesma 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 trabalho limitado da 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 ao não fornecer detalhes sobre como executar melhor os comandos de build e teste
- Pular o planejamento em tarefas de várias etapas e complexas
- Dar ao Codex permissão total no seu computador antes de entender o fluxo de trabalho
- Executar várias threads ativas nos mesmos arquivos sem usar git worktrees
- Transformar uma tarefa recorrente em 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 observar passo a passo
Lista de verificação para começar
- Dê ao Codex o objetivo, contexto, restrições e critérios de conclusão corretos
- Para tarefas difíceis, peça ao Codex para planejar primeiro
- Crie um AGENTS.md inicial
- Diga ao Codex como construir, testar, validar e revisar
- Defina padrões de configuração que correspondam ao seu fluxo de trabalho
- Adicione MCP para ferramentas externas de alto valor
- Transforme fluxos de trabalho repetidos em skills
- 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!
