Se você está começando a usar o Codex ou agentes de programação em geral, este guia vai ajudar você a obter melhores resultados em menos tempo. Ele apresenta práticas para usar o Codex de forma mais eficaz na CLI, na extensão para IDE e no aplicativo ChatGPT para desktop. Os temas incluem a elaboração de prompts, planejamento, validação, MCP, habilidades e tarefas agendadas.
O Codex funciona melhor quando você o trata como um colega de equipe com quem vai ajustando a forma de trabalhar ao longo do tempo, em vez de recorrer a ele apenas para pedidos isolados.
Comece fornecendo o contexto adequado para a tarefa. Use AGENTS.md para registrar orientações que continuam válidas entre tarefas, configure o Codex de acordo com seu fluxo de trabalho, conecte sistemas externos com MCP, transforme atividades recorrentes em habilidades e automatize fluxos de trabalho estáveis.
Como começar bem com contexto e prompts
O Codex pode ajudar mesmo quando seu prompt é impreciso. Muitas vezes, basta apresentar um problema difícil, com pouca preparação, para obter um bom resultado. Você já pode aproveitar o Codex dessa forma, mas escrever prompts claros torna os resultados mais confiáveis, principalmente em bases de código maiores ou em tarefas nas quais um erro teria consequências mais sérias.
Se você trabalha em um repositório grande ou complexo, o que mais ajuda é dar ao Codex o contexto relevante para a tarefa e explicar de forma organizada o que precisa ser feito.
Procure incluir quatro elementos no prompt:
- Objetivo: O que você quer mudar ou criar?
- Contexto: Quais arquivos, pastas, documentos, exemplos ou erros são relevantes para a tarefa? Você pode mencionar arquivos específicos com @ para incluí-los no contexto.
- Restrições: Quais padrões, decisões de arquitetura, requisitos de segurança ou convenções o Codex deve seguir?
- Critérios de conclusão: Como verificar se a tarefa está concluída? Por exemplo, os testes passam, o comportamento mudou ou não é mais possível reproduzir o bug?
Esses quatro elementos ajudam o Codex a respeitar o escopo da tarefa, fazer menos suposições e entregar um trabalho mais fácil de revisar.
Use o GPT-6.1 Sol quando ele estiver disponível na sua conta e no cliente que você usa. Comece com o esforço de raciocínio padrão do cliente. Para o GPT-6 Luna, comece com Alto. Para o GPT-6 Astra, comece com Leve (low na configuração). Ajuste o nível de acordo com a tarefa e o resultado. Consulte Modelos para ver os níveis de raciocínio disponíveis.
- Baixo para tarefas rápidas e de escopo bem definido
- Médio ou Alto para alterações mais complexas ou depuração
- Extra alto para tarefas longas com agentes de IA que exigem raciocínio intenso
Para fornecer contexto mais rapidamente, experimente o ditado por voz no aplicativo ChatGPT para desktop. Dite o que você quer que o Codex faça em vez de digitar.
Planeje antes de começar tarefas difíceis
Se a tarefa for complexa, ambígua ou difícil de descrever com clareza, peça ao Codex que faça um plano antes de começar a programar.
Algumas abordagens funcionam bem:
Use o Modo Planejar: Para a maioria das pessoas, essa é a opção mais fácil e eficaz. No Modo Planejar, o Codex pode reunir contexto, fazer perguntas para esclarecer dúvidas e elaborar um plano mais sólido antes da implementação. Use /plan ou Shift+Tab para alternar entre os modos.
Peça ao Codex que entreviste você: Se você tem uma ideia geral do que quer, mas ainda não sabe explicá-la bem, peça ao Codex que comece fazendo perguntas. Peça que questione suas suposições e ajude a transformar a ideia em uma proposta concreta antes de escrever código.
Use um modelo de PLANS.md: Para fluxos de trabalho mais avançados, você pode configurar o Codex para seguir um PLANS.md ou um modelo de plano de execução em tarefas demoradas ou com várias etapas. Para saber mais, consulte o guia de planos de execução.
Reutilize orientações com AGENTS.md
Quando uma forma de escrever prompts funciona bem, o próximo passo é aproveitar as mesmas orientações sem precisar repeti-las manualmente. É para isso que serve o AGENTS.md.
Pense no AGENTS.md como um README de formato aberto para agentes. O Codex carrega esse arquivo automaticamente no contexto. É o melhor lugar para registrar como você e sua equipe querem que o Codex trabalhe no repositório.
Um bom AGENTS.md descreve:
- A estrutura do repositório e os diretórios importantes
- Como executar o projeto
- Os comandos de build, teste e lint
- As convenções de engenharia e o que se espera de um PR
- As restrições e o que o agente não deve fazer
- Os critérios de conclusão e como verificar o trabalho
Na CLI, o comando de barra /init cria a estrutura inicial de um AGENTS.md no diretório atual. Use o arquivo como ponto de partida e edite o conteúdo para refletir como sua equipe faz o build, testa, revisa e entrega código na prática.
Você pode criar arquivos AGENTS.md em diferentes níveis: um AGENTS.md global em ~/.codex para suas preferências pessoais, um arquivo na raiz do repositório para os padrões da equipe e arquivos em subdiretórios para regras locais. Se houver um arquivo mais específico e mais próximo do diretório atual, as orientações dele têm prioridade.
Mantenha as orientações práticas. Um AGENTS.md curto e preciso é mais útil do que um arquivo longo cheio de regras vagas. Comece pelo básico e só acrescente regras quando perceber que um erro se repete.
Se o AGENTS.md começar a ficar extenso demais, mantenha o arquivo principal conciso e inclua referências a arquivos Markdown específicos para atividades como planejamento, revisão de código ou definição de arquitetura.
Quando o Codex cometer o mesmo erro duas vezes, peça a ele uma retrospectiva e use o resultado para atualizar o AGENTS.md. Assim, as orientações continuam práticas e refletem dificuldades reais.
Configure o Codex para manter um comportamento consistente
A configuração é uma das principais formas de manter o comportamento do Codex consistente entre sessões e interfaces. Você pode definir, por exemplo, o modelo padrão, o esforço de raciocínio, o modo de sandbox, a política de aprovação, os perfis e a configuração do MCP.
Para começar:
- Salve suas preferências pessoais em
~/.codex/config.toml(Configurações > Configuração > Abrir config.toml no aplicativo ChatGPT para desktop) - Defina o comportamento específico do repositório em
.codex/config.toml - Se usar a CLI, substitua configurações pela linha de comando apenas em situações pontuais
config.toml é o arquivo em que você define preferências persistentes, como servidores MCP, configuração de múltiplos agentes e sinalizadores de recursos. Para substituir configurações de perfis específicos, use arquivos $CODEX_HOME/profile-name.config.toml separados.
O Codex inclui um ambiente isolado no nível do sistema operacional e oferece dois controles principais. O modo de aprovação determina quando o Codex pede sua permissão para executar um comando. O modo de sandbox determina se o Codex pode ler ou gravar no diretório e quais arquivos o agente pode acessar.
Se você está começando a usar agentes de programação, use as permissões padrão. Mantenha regras restritivas de aprovação e de acesso ao ambiente isolado por padrão. Amplie as permissões apenas para repositórios confiáveis ou fluxos de trabalho específicos, quando a necessidade estiver clara.
A CLI, a extensão para IDE e o aplicativo ChatGPT para desktop usam as mesmas camadas de configuração. Saiba mais na página de exemplo de configuração.
Desde o início, configure o Codex para o ambiente em que você trabalha. Muitos problemas de qualidade vêm da configuração, como um diretório de trabalho incorreto, falta de permissão de gravação, escolha inadequada do modelo padrão ou ausência de ferramentas e conectores.
Aumente a confiabilidade com testes e revisão
Além de pedir ao Codex que faça uma alteração, peça que crie testes quando necessário, execute as verificações relevantes, confirme o resultado e revise o trabalho antes de você aceitá-lo.
O Codex pode cuidar de todo esse processo, desde que saiba o que caracteriza um bom resultado. Você pode informar esses critérios no prompt ou no AGENTS.md.
As orientações podem incluir:
- Escrever ou atualizar testes para a alteração
- Executar as suítes de testes adequadas
- Verificar o lint, a formatação ou os tipos
- Confirmar que o comportamento final corresponde ao pedido
- Examinar o diff em busca de bugs, regressões ou padrões de risco
Abra o painel de diff no aplicativo ChatGPT para desktop para revisar as alterações diretamente no ambiente local. Clique em uma linha específica para deixar um comentário. O Codex receberá esse comentário como contexto na próxima interação.
O comando de barra /review oferece várias opções para revisar código:
- Comparar as alterações com uma branch base, como na revisão de um PR
- Revisar alterações que ainda não foram incluídas em um commit
- Revisar um commit
- Usar instruções de revisão personalizadas
Se sua equipe tem um arquivo code_review.md e inclui uma referência a ele no AGENTS.md, o Codex também pode seguir essas orientações durante a revisão. Essa prática ajuda a manter a consistência das revisões entre repositórios e entre as pessoas que contribuem com o código.
O Codex pode fazer mais do que gerar código. Com as instruções adequadas, ele também ajuda a testar, verificar e revisar o código.
Se você usa o GitHub Cloud, pode configurar o Codex para fazer revisões de código nos seus PRs. Na OpenAI, o Codex revisa 100% dos PRs. Você pode ativar as revisões automáticas ou solicitar uma revisão mencionando @Codex.
Use servidores MCP para obter contexto externo
Use servidores MCP quando o contexto de que o Codex precisa estiver fora do repositório. Com o MCP, o Codex se conecta às ferramentas e aos sistemas que você já usa, sem que você precise copiar e colar informações atualizadas nos prompts a cada pedido.
O Model Context Protocol, ou MCP, é um padrão aberto para conectar o Codex a ferramentas e sistemas externos.
Use o 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 no prompt
- Você precisar de uma integração que possa reutilizar com diferentes usuários ou projetos
O Codex oferece suporte a servidores STDIO e a servidores Streamable HTTP com OAuth.
No aplicativo ChatGPT para desktop, acesse Configurações > Servidores MCP para ver os servidores personalizados e recomendados. Em muitos casos, o Codex pode ajudar você a instalar os servidores de que precisa. Basta pedir. Você também pode usar o comando codex mcp add na CLI para adicionar servidores personalizados, informando o nome, a URL e outros detalhes.
Adicione ferramentas apenas quando elas viabilizarem um fluxo de trabalho concreto. Evite conectar de uma vez todas as ferramentas que você usa. Comece com uma ou duas que eliminem uma sequência de passos manuais que você repete com frequência. Depois, amplie a integração.
Transforme tarefas recorrentes em habilidades
Quando você já consegue repetir um fluxo de trabalho, pode dispensar os prompts longos e as várias rodadas de mensagens. Use uma habilidade para reunir as instruções em um arquivo SKILL.md, junto com o contexto e a lógica de apoio que o Codex deve aplicar de forma consistente. As habilidades funcionam na CLI, na extensão para IDE e no aplicativo ChatGPT para desktop.
Dedique cada habilidade a uma única atividade. Comece com 2 a 3 casos de uso concretos, defina claramente as entradas e saídas e explique na descrição o que a habilidade faz e quando usá-la. Inclua frases que as pessoas realmente usariam para pedir essa atividade.
Evite tentar prever todos os casos excepcionais logo de início. Comece com uma tarefa representativa. Quando ela funcionar bem, transforme o fluxo de trabalho em uma habilidade e continue a aperfeiçoá-la. Inclua scripts ou recursos adicionais apenas quando aumentarem a confiabilidade.
Se você vive reutilizando o mesmo prompt ou corrigindo o mesmo fluxo de trabalho, provavelmente vale a pena criar uma habilidade.
As habilidades são especialmente úteis para atividades recorrentes como:
- Fazer a triagem de logs
- Redigir notas de versão
- Revisar PRs com uma lista de verificação
- Planejar migrações
- Resumir dados de telemetria ou incidentes
- Seguir procedimentos habituais de depuração
A habilidade $skill-creator é o melhor ponto de partida para montar a primeira versão de uma habilidade. Mantenha essa versão no ambiente local enquanto faz ajustes. Quando estiver pronta para compartilhar com mais pessoas, distribua a habilidade como um plugin. A descrição é uma das partes mais importantes da habilidade. Ela deve explicar o que a habilidade faz e quando usá-la.
As habilidades pessoais ficam em $HOME/.agents/skills. As habilidades compartilhadas pela equipe podem ser versionadas em .agents/skills no repositório. Isso é especialmente útil para quem está entrando na equipe.
Use tarefas agendadas para atividades recorrentes
Quando um fluxo de trabalho estiver estável, você pode agendar sua execução pelo Codex em segundo plano. No aplicativo ChatGPT para desktop, as tarefas agendadas permitem escolher o projeto, o prompt, a frequência e o ambiente de execução para atividades recorrentes.
Crie uma tarefa agendada na página Agendadas. Escolha o projeto, o prompt e a frequência. Defina se a tarefa será executada em uma árvore de trabalho dedicada do Git ou no seu ambiente local. O prompt pode acionar habilidades. Saiba mais sobre as árvores de trabalho do Git.
Algumas atividades que vale a pena agendar:
- Resumir commits recentes
- Procurar possíveis bugs
- Redigir notas de versão
- Verificar falhas de CI
- Preparar resumos para as reuniões diárias da equipe
- Executar análises recorrentes em intervalos definidos
As habilidades definem como executar o trabalho, e as tarefas agendadas definem quando executá-lo. Se um fluxo de trabalho ainda exige muita orientação, transforme-o primeiro em uma habilidade. Quando os resultados forem previsíveis, agendar a execução pode economizar tempo.
Além de executar atividades, use tarefas agendadas para avaliar e manter seus fluxos de trabalho. Revise chats recentes, resuma dificuldades recorrentes e aprimore os prompts, as instruções ou a configuração do fluxo ao longo do tempo.
Organize chats de longa duração
Os chats acumulam contexto, decisões e ações ao longo do tempo. A forma como você os organiza influencia bastante a qualidade dos resultados.
No aplicativo ChatGPT para desktop, você pode fixar chats e criar árvores de trabalho. Se você usa a CLI, estes comandos de barra são especialmente úteis:
/experimentalpara ativar ou desativar recursos experimentais e adicioná-los aoconfig.toml/resumepara retomar um chat salvo/forkpara criar um chat preservando o histórico original/compactpara resumir o contexto anterior quando o chat ficar longo. O Codex também compacta chats automaticamente/subagentspara alternar entre as conversas dos subagentes no chat atual/themepara escolher um tema de realce de sintaxe/appspara usar os aplicativos do ChatGPT diretamente no Codex/statuspara consultar o estado atual da sessão
Use um chat para cada conjunto de tarefas com um objetivo comum. Se você ainda está resolvendo o mesmo problema, em geral é melhor continuar no mesmo chat para preservar a linha de raciocínio. Faça um fork apenas quando o trabalho realmente se dividir em frentes distintas.
Use os fluxos de trabalho com subagentes do Codex para delegar tarefas de escopo delimitado a partir da conversa principal. Mantenha o agente principal concentrado no problema central e use subagentes para atividades como exploração, testes ou triagem.
Erros comuns
Ao começar a usar o Codex, evite estes erros:
- Sobrecarregar o prompt com regras permanentes em vez de registrá-las no
AGENTS.mdou em uma habilidade - Deixar o agente sem meios de verificar o próprio trabalho por falta de instruções claras sobre como executar os comandos de build e teste
- Pular o planejamento em tarefas complexas ou com várias etapas
- Dar ao Codex acesso completo ao computador antes de entender o fluxo de trabalho
- Executar tarefas simultâneas nos mesmos arquivos sem usar árvores de trabalho do Git
- Agendar uma tarefa recorrente antes de conseguir executá-la manualmente de forma confiável
- Acompanhar cada passo do Codex em vez de deixá-lo trabalhar em paralelo com você
- Usar um único chat para o projeto inteiro em vez de dedicar um chat a cada resultado que você quer alcançar. Com o tempo, o excesso de contexto prejudica os resultados