Como escrever Prompts: Falando diretamente ao coração do Codex
📚 Navegação da Série: Anterior 12 · Comandos de barra e atalhos ensina você a colocar os dedos no lugar certo na conversa —
/para mudar de modo, limpar o contexto, ver o status, agora que você já conhece as teclas. Esta parte muda de nível: agora que você sabe onde apertar, sua boca também precisa saber o que falar. Para a mesma necessidade, se você falar de forma adequada ou não, o trabalho feito pelo Codex será completamente diferente.
Dizem que 'se uma ferramenta de programação de IA é forte ou não, depende do modelo' — eu tenho que discordar disso.
Para ser sincero e direto: com o mesmo GPT-5 e o mesmo repositório, quem sabe propor necessidades resolve em três frases, enquanto quem não sabe fica indo e voltando por cinco rodadas e ainda termina com raiva. O modelo já é forte o suficiente; na maioria das vezes, o que te trava não é a mente dele, é a frase que você entrega a ele. Se você enviar um 'conserte este bug' cuja quantidade de informação é quase zero, ele só poderá adivinhar — qual arquivo, qual erro, como alterar, tudo depende de suposições. Se adivinhar errado, você olha para a tela cheia de diffs e resmunga 'este AI não serve', mas quem realmente não serviu não foi ele.
Eu caí em uma armadilha dessas no ano passado. Um serviço Node reportou 500, e eu enviei um simples 'a API de login caiu, conserte', sem nem anexar os logs. O Codex procurou por um tempo, escolheu um bug que ele achou que era, alterou três arquivos e nenhum deles era a verdadeira causa raiz — o erro real estava em uma variável de ambiente que eu não mencionei, e ele simplesmente não sabia que ela existia. Só então percebi completamente: o teto do Codex é, em grande parte, limitado pela minha própria forma de perguntar.
Portanto, esta parte não ensina você a memorizar modelos, mas a entender uma coisa: o que o Codex realmente precisa saber para não se desviar. Quando você entender isso claramente, os prompts surgirão naturalmente.
Ao ler esta parte, você obterá:
- Uma tabela comparativa 'Pergunta Ruim vs. Pergunta Boa' para seguir e reduzir imediatamente a taxa de retrabalho
- Um framework de 'quatro elementos' para descrever necessidades: Objetivo, Escopo, Restrições e Validação — o Codex vai adivinhar o que estiver faltando
- Como dividir tarefas grandes em passos pequenos que o Codex consiga digerir e você consiga revisar
- O método oficial de usar
/goal(Modo Objetivo) para fixar os critérios de aceitação como 'não terminar até atingir o objetivo' (requer ativação prévia defeatures.goals, detalhes no passo 05) - Um experimento prático de 'uma necessidade, duas formas de falar' para ver a diferença com os próprios olhos
⚠️ As menções abaixo a comandos específicos, parâmetros e comportamentos padrão são baseadas na documentação oficial do Codex; nomes de modelos e textos de interface que mudam com as versões devem seguir o que for exibido localmente, pois esta parte não os fixa.
01 O que torna uma pergunta ruim tão ruim
Olhando de perto para aquele erro no início. A frase 'a API de login caiu, conserte', do ponto de vista do Codex, tem uma falta absurda de informações:
- Qual API de login? Ele terá que vasculhar o projeto todo.
- Como ela caiu? Que erro reportou? Sob quais condições é reproduzido? Ele não sabe nada disso.
- Qual é o comportamento correto esperado? Ele só pode adivinhar com base em 'como um login geralmente deveria funcionar'.
Como explicado em 06 · Executando a primeira tarefa, o trabalho do Codex é um loop de agente (agent loop) — chama o modelo, lê arquivos, altera arquivos, executa comandos, girando em 'pensar → fazer → observar'. A frase oficial diz que ele 'executa comandos de terminal em um loop, altera código, roda checagens e tenta validar seu próprio trabalho'. Mas por mais inteligente que seja esse loop, se o que você insere no primeiro passo 'pensar' for lixo, todo o resto do ciclo rodará no vazio na direção errada.
Analogia: Preencher o endereço de entrega. Se você fizer um pedido e apenas escrever 'entregar naquele condomínio', o entregador terá que rodar de prédio em prédio, provavelmente entregará errado e ainda terá que te ligar. Mude para 'Condomínio XX, Bloco 8, Entrada 2, Apto 1503, há uma sapateira verde na porta', e ele entregará de olhos fechados. Quanto mais preciso o endereço, menos o entregador se perde; quanto mais vaga for a frase que você joga, mais ele terá que adivinhar, e maior será a chance de errar. O mesmo vale para propor necessidades ao Codex — a precisão do 'endereço' que você fornece determina diretamente se ele vai se perder ou não.
Vejamos a abordagem de comparação enfatizada repetidamente na documentação oficial, organizada em uma tabela (coluna esquerda ruim, coluna direita boa):
| Cenário | ❌ Pergunta Ruim | ✅ Pergunta Boa |
|---|---|---|
| Corrigir bug | 「A API de login caiu, conserte」 | 「Usuários relatam que, após a expiração da sessão, chamar POST /api/login retorna 500. Escreva primeiro um teste de falha reproduzível, localize a lógica de atualização de token em src/auth/ e depois corrija. Por fim, execute o teste para confirmar que ficou verde」 |
| Escrever testes | 「Adicione testes para parser.py」 | 「Escreva testes para parse_date em parser.py, cobrindo os casos limite de string vazia e formato inválido. Não use mocks e execute pytest para confirmar que passou」 |
| Adicionar recurso | 「Adicione uma função de exportação」 | 「Veja primeiro como export_csv existente em report.py foi escrito, e adicione export_json seguindo o mesmo padrão. Não introduza novas dependências além das bibliotecas já instaladas」 |
| Ler código | 「Por que este módulo foi escrito assim」 | 「Verifique o histórico do git do módulo transform e resuma como sua interface evoluiu passo a passo até o estado atual」 |
Estude os detalhes. Perguntas boas se concentram em uma coisa: entregar ao Codex, com antecedência, o que ele teria que adivinhar. Ele não precisa adivinhar, e consequentemente não se desvia.
💡 Resumo em uma frase: Perguntas ruins são ruins porque 'o Codex precisa adivinhar todas as lacunas de informação'; perguntas boas são aquelas em que você diz antecipadamente o que ele teria que adivinhar.
02 O checklist de quatro elementos para descrever necessidades: Objetivo / Escopo / Restrições / Validação
Na seção anterior dissemos 'entregar antecipadamente o que ele teria que adivinhar', mas o que exatamente devemos entregar? Não vá por intuição, apenas decore um framework — Objetivo, Escopo, Restrições e Validação (os quatro elementos). Este é um checklist que criei após resumir inúmeros retrabalhos: passe por ele mentalmente antes de cada necessidade. O que estiver faltando, o Codex decidirá por você.
Analogia: A 'ordem de serviço' entregue ao mestre de obras. Um mestre de obras experiente confirmará quatro coisas com você antes de começar: qual o resultado final desejado (Objetivo), quais cômodos alterar e quais não tocar (Escopo), quais regras seguir, por exemplo, não quebrar paredes estruturais (Restrições) e como inspecionar ao concluir (Validação). Com os quatro definidos, ele faz o serviço e finaliza sozinho; se faltar um, ele terá que tomar a decisão por conta própria, o que provavelmente não será do seu agrado. Propor necessidades ao Codex é entregar essa ordem de serviço a ele.
Vamos detalhar o que são esses quatro elementos e o que acontece se faltarem:
| Elemento | Pergunta que responde | Como fornecer | O que acontece se faltar |
|---|---|---|---|
| Objetivo (Goal) | O que deve ser feito | 「Fazer listas vazias retornarem 0」「Alterar exportação para o formato JSON」 | Ele adivinha o que você quer, e a direção depende de sorte |
| Escopo (Scope) | O que alterar, o que não alterar | Especificar arquivos/funções: 「Alterar apenas average em stats.py」 | Ele procura agulha no palheiro pelo projeto todo e altera outras coisas por engano |
| Restrições (Constraint) | O que não deve ser tocado ou regras | 「Não adicione bibliotecas novas」「Mantenha compatibilidade com versões anteriores」「Não altere migrations/」 | Ele segue suas próprias preferências, e o resultado final pode não te agradar |
| Validação (Verification) | Como determinar o sucesso | 「Escrever dois casos de teste e executar」「Código de saída do build ser 0」 | Ele para ao 'achar que está bom', e os erros sobram para você encontrar |
Desses quatro, a 'Validação' é a mais fácil de esquecer pelos iniciantes, mas é a que mais precisa ser adicionada — o documento oficial destaca isso especificamente:
O Codex entrega melhor qualidade quando consegue validar seu próprio trabalho. Inclua os passos para reproduzir o problema, a forma de validar o recurso, o lint a ser executado e as verificações pré-commit.
Por que a validação é tão crucial? Porque, sem verificações executáveis, 'parecer concluído' é o único sinal de término para o Codex. Se você não der um critério, ele para com base em seu 'sentimento', e a responsabilidade de inspecionar sobra para você, tendo que caçar cada erro pessoalmente. Mas uma vez que você fornece a ele uma verificação que gera 'passou / falhou' — um conjunto de casos de teste, um comando de lint, um código de saída do build — este loop se fecha sozinho: ele faz → roda a verificação → olha o resultado → se não passar, continua corrigindo, sem você precisar ficar vigiando.
Eu mesmo agora uso o 'disparo de quatro elementos' para minhas necessidades. No mês passado, ao adicionar validação de e-mail a um projeto Python, eu disse o seguinte:
No src/validators.py, adicione uma função validate_email (Objetivo).
Altere apenas este arquivo, não toque em mais nada (Escopo).
Implemente usando a biblioteca padrão re, não introduza bibliotecas de terceiros (Restrições).
Após escrever, adicione três testes: user@example.com deve ser verdadeiro, invalid deve ser falso e user@.com deve ser falso,
execute pytest para confirmar que todos passaram (Validação).Com os quatro elementos prontos, o Codex acertou de primeira — localizou o arquivo, escreveu a função, adicionou os três testes, executou e me mostrou o resultado verde. Ele não precisou adivinhar nenhum passo, porque eu defini exatamente 'o que fazer, o que alterar, o que usar e como considerar um sucesso'.
💡 Resumo em uma frase: Antes de propor necessidades, passe mentalmente pelo checklist de quatro elementos 'Objetivo / Escopo / Restrições / Validação'. O que estiver faltando, o Codex decidirá por você; a 'Validação' é a que mais precisa ser adicionada — fornecendo verificações que geram passou / falhou, o loop se fecha sozinho.
03 Escopo e Restrições: O que puder ser colado, não descreva
Nos quatro elementos, 'Escopo' e 'Restrições' muitas vezes não precisam de longas descrições. Basta colar o material diretamente diante dele — esta seção é dedicada a explicar como colar, pois é o truque mais prático no dia a dia.
A ideia central é: Tudo o que puder ser 'colado', evite 'descrever'. O Codex ler materiais brutos é sempre mais preciso do que ler a sua interpretação de segunda mão deles.
Primeiro, coloque os arquivos relevantes diretamente no contexto. O documento oficial diz claramente em «Prompting»: ao enviar necessidades, traga o contexto que o Codex pode usar, como referências a arquivos e imagens. A forma mais direta é mencionar os caminhos dos arquivos na necessidade:
Consulte a definição de tipo em src/types/user.ts e adicione anotações de tipo ao UserServiceIsso é dez mil vezes mais confiável do que 'há um arquivo de tipo de usuário no projeto, procure por ele'. A extensão da IDE traz um benefício gratuito aqui: a documentação oficial explica claramente — a extensão da IDE traz automaticamente a lista de arquivos abertos atualmente e o intervalo de texto selecionado como contexto. Em outras palavras, no VS Code, onde quer que seu cursor esteja selecionando linhas, o Codex saberá que você está falando daquelas linhas, sem você precisar descrevê-las.
Analogia: Pen drive USB vs. dizer uma localização aproximada para ele procurar. Mencionar o arquivo ou deixar a IDE trazer o contexto automaticamente é como plugar um 'pen drive de dados' diretamente na mesa de trabalho do Codex — plugou, usou, e as informações que ele precisa aparecem em um segundo. Se você apenas jogar um 'os dados estão mais ou menos em algum armário do terceiro andar, procure aí', ele ainda terá que vasculhar a sala de arquivos inteira, e se procurar errado, perderá ainda mais tempo. (A metáfora da porta USB do MCP na seção 02 Conceitos básicos refere-se a 'plugar capacidades externas'; aqui é 'plugar dados', o mesmo conceito em dois usos diferentes.)
Segundo, cole o erro inteiro diretamente, não resuma. Vale a pena treinar isso para se tornar memória muscular — ao encontrar um traceback, não resuma como 'deu erro de ponteiro nulo', cole a pilha de execução inteira como ela é:
Ocorreu este erro ao executar os testes, me ajude a localizar a causa:
TypeError: Cannot read properties of null (reading 'userId')
at getUserProfile (src/services/user.ts:42:18)
at async ProfileController.getProfile (src/controllers/profile.ts:15:20)Por que colar tudo? Porque na pilha já constam o nome do arquivo, o número da linha e a cadeia de chamadas, e o Codex pode se localizar com precisão a partir de user.ts:42. Se você resumir, estará removendo todas essas coordenadas cruciais, e ele terá que adivinhar do zero novamente.
Terceiro, para problemas de UI / visuais, envie imagens diretamente. O Codex suporta entrada de imagens — você pode colar ou arrastar imagens diretamente para a área de conversa na interface; o CLI também aceita imagens (consulte os parâmetros específicos na documentação oficial). Telas de design, capturas de tela com erros, diagramas de arquitetura: enviar imagens é sempre mais preciso do que descrever em texto 'mova o botão um pouco para a esquerda'.
Vamos comparar 'o material que você quer dar' com 'como fornecer':
| Material que você quer dar | ❌ Descrever com palavras | ✅ Alimentar diretamente |
|---|---|---|
| O conteúdo de um arquivo | 「Há um arquivo no projeto que lida com autenticação」 | Mencione src/auth/session.ts na necessidade |
| O código que você está olhando | 「Aquela lógica lá」 | Selecione na IDE, e a extensão trará automaticamente para o contexto |
| Um erro | 「Deu um erro de undefined」 | Cole o traceback completo exatamente como está |
| Um problema de UI | 「A posição do botão está errada」 | Cole diretamente a captura de tela / design |
💡 Resumo em uma frase: Na maioria das vezes, escopo e restrições não precisam de descrições longas — mencione os arquivos, selecione na IDE, cole o erro completo, envie capturas de tela. Tudo o que puder ser colado, evite descrever, pois o Codex lê materiais brutos de forma muito mais precisa do que a sua interpretação.
04 Como dividir tarefas grandes: Deixando-as digeríveis para o Codex e revisáveis para você
Os quatro elementos resolvem 'como explicar uma necessidade de forma clara'. Mais alguns trabalhos são grandes por natureza — 'implementar um sistema completo de autenticação de usuários', 'migrar todo o projeto de JavaScript para TypeScript' — se você jogar isso de uma vez, o Codex tentará abraçar o mundo e acabará se desviando em algum canto que você não está vendo, e quando você notar, ele já terá alterado uma montanha de coisas.
A atitude oficial sobre esse tipo de trabalho é muito clara:
O Codex se sai melhor quando você divide trabalhos complexos em passos menores e mais focados. Tarefas menores são mais fáceis de testar para o Codex e mais fáceis de revisar para você. Se não tiver certeza de como dividir, peça diretamente para o Codex sugerir um plano (plan).
Isso tem dois significados importantes para memorizar. Primeiro: dividir em passos menores não é apenas para o Codex, mas também para você — passos pequenos facilitam a execução de testes para ele e a revisão de diffs para você; com alterações de dezenas de linhas por vez, basta uma olhada rápida para saber se está certo. Se forem centenas de linhas abrangendo oito arquivos de uma vez, você não conseguirá revisar de verdade (meu erro no início foi exatamente aceitar tudo sem conseguir revisar). Segundo: não sabe como dividir? Não force, deixe o Codex criar um plano primeiro — isso se conecta com a recomendação da seção 06: 'para trabalhos grandes, peça um plano primeiro, não o deixe sair alterando tudo logo de cara'.
Analogia: Comer um boi inteiro não é possível de uma vez. Mesmo a maior das fomes exige cortar a comida em pedaços pequenos — um pedaço de cada vez, mastigando e engolindo, e se algum pedaço estiver ruim, você cospe na hora. Tentar engolir tudo de uma vez vai te engasgar e você nem saberá onde travou. Dividir tarefas grandes em passos pequenos é cortar esse boi em pedaços — cada pedaço deve ser pequeno o suficiente para que qualquer problema seja visto imediatamente, garantindo a segurança.
Como dividir? Aqui está uma forma que você pode copiar para um 'sistema de autenticação', sinta a granularidade:
Tarefa grande: Implementar um sistema de autenticação de usuários completo
Dividir em passos menores, entregando um de cada vez:
Passo 1: Projetar a estrutura de dados de autenticação (tabela de usuários + tabela de tokens), primeiro me dê o plano para confirmar
Passo 2: Implementar a funcionalidade de registro (criptografia bcrypt da senha), adicionar testes e executar
Passo 3: Implementar a funcionalidade de login (emissão de JWT), adicionar testes e executar
Passo 4: Implementar o middleware de verificação de token, adicionar testes e executar
Passo 5: Implementar a funcionalidade de logout, adicionar testes e executarObserve dois pontos importantes nessa divisão: primeiro, cada passo traz sua própria 'validação' (adicionar testes e executar) — isso é a aplicação do elemento 'Validação' dos quatro elementos em cada pequeno passo; segundo, o Passo 1 cria o plano antes de agir — a estrutura de dados afeta todo o projeto, se a direção estiver errada, tudo o que vier depois será desperdiçado. Deixe-o apresentar o projeto primeiro para você revisar; o custo de ajustar duas linhas é muito menor do que reconstruir a parede depois de pronta.
Quando você não souber como dividir, o Codex tem dois modos internos para te ajudar, como mencionado na seção 07, e aqui explicamos a divisão de tarefas entre eles:
/plan(Modo Plano): Permite ao Codex explorar e propor soluções primeiro, criando um plano de execução antes de iniciar a implementação. Indicado para quando 'eu mesmo não tenho certeza de como abordar este trabalho' — deixe-o listar os passos primeiro, e você autoriza o início quando estiver satisfeito.- Uma simples frase 'não altere ainda': Se não quiser mudar de modo, adicione uma restrição na conversa normal — 'primeiro me diga quais arquivos serão alterados e sua abordagem, mas não altere nenhum código neste passo'.
Que tipo de trabalho deve ser dividido ou planejado com /plan, e o que não precisa disso? Aqui está uma referência:
| Tarefa | Como lidar |
|---|---|
| Corrigir erro de digitação, adicionar uma linha de log, renomear variável | Faça diretamente. Se a alteração de diff puder ser explicada em uma frase, não divida nem planeje |
| Adicionar validação a uma única função, criar um teste | Necessidade única + quatro elementos, resolvido em um passo |
| Abrange múltiplos arquivos, envolve código desconhecido, afeta muitas partes | Use /plan primeiro para criar o plano, revise e libere passo a passo |
| 「Implementar todo o sistema XX」「Migração/refatoração geral」 | Divida em 5 a 8 pequenos passos com validações próprias e execute gradualmente |
A regra prática mais útil é: 'Consigo descrever em uma frase como será o diff após esta alteração?' Se sim, faça diretamente; se travar, significa que o trabalho é complexo, então divida e deixe-o listar o plano primeiro. Passar por /plan para corrigir apenas um erro de digitação é pura burocracia desnecessária.
💡 Resumo em uma frase: Não tente engolir tarefas grandes de uma vez — divida-as em partes pequenas, com validações próprias e fáceis de revisar; se não souber como dividir, deixe o Codex propor o plano primeiro usando
/plan; por outro lado, para tarefas simples que podem ser descritas em uma frase, faça diretamente sem planejar.
05 Fixando os critérios de aceitação: Modo Objetivo /goal
Na seção 02 dissemos que a 'Validação' é o elemento mais importante a ser adicionado, mas a validação descrita em perguntas normais tem um limite: ela só cuida 'desta rodada' — o Codex executa a verificação nesta rodada e, se falhar, ele pode devolver o controle a você, esperando que você peça novamente. Se você deseja que ele 'não desista até atingir o critério, corrigindo rodada após rodada por conta própria', o Codex tem um modo específico para isso — o Modo Objetivo (Goal mode).
Primeiro, vejamos a diferença em relação às perguntas normais. Definir critérios de aceitação em perguntas normais é como dizer 'execute uma vez e veja'; com /goal, o critério é fixado como o objetivo de toda a tarefa. A documentação oficial diz de forma muito clara:
Ao definir um objetivo, o texto do objetivo serve tanto como prompt inicial quanto como critério de conclusão. O Codex usa isso para decidir o que fazer a seguir e se a tarefa foi concluída.
Em outras palavras, o objetivo que você fornece é tanto 'o que fazer' quanto 'o que define que terminou' — o Codex compara o resultado com ele a cada execução; se não atingir, ele continua tentando, e só para quando for alcançado. É ideal para trabalhos longos com muitos passos, que exigem uma definição clara de conclusão que ele possa checar durante a execução.
Como usar? Digite /goal na conversa, seguido do seu objetivo. O segredo é escrever o objetivo de forma que o 'Codex consiga julgar por si mesmo se funcionou ou não' — a exigência oficial é que um bom objetivo deve conter entregas específicas, métricas quantificáveis ou critérios testáveis. Veja dois exemplos oficiais:
/goal Migrar este repositório de JavaScript para TypeScript, exigindo que compile com sucesso no modo strict e não apresente tipos any explícitos/goal Reduzir o tempo de interação (TTI) da página inicial para menos de 1 segundoPercebeu? 'compilar com sucesso no modo strict, sem any', 'TTI abaixo de 1 segundo' — todos esses são critérios claros de 'sim / não'. Se você escrever algo como 'código de alta qualidade' ou 'melhor experiência', que não podem ser julgados objetivamente, o modo objetivo não conseguirá finalizar por você, pois não saberá determinar se deu certo.
Alguns detalhes práticos sobre /goal para não cometer erros:
/goalnão aparece na lista? É necessário ativar a chave do recurso primeiro. O método oficial é: adicione a seção[features]comgoals = trueno arquivo~/.codex/config.toml, ou execute diretamentecodex features enable goals(você também pode pedir para o Codex rodar isso para você).
# ~/.codex/config.toml
[features]
goals = true- Não sabe como definir o objetivo logo de início? Sugestão oficial: se o objetivo for difícil de definir no começo, use
/planprimeiro para o Codex te ajudar a organizá-lo antes de transformá-lo em objetivo; você pode inclusive pedir para ele fazer uma 'entrevista' com você para ajudar a formular um objetivo com critérios de sucesso claros. - O objetivo pode mudar de rumo durante a execução. Não fica travado após definir — você pode enviar mensagens no meio do caminho para adicionar restrições ('mude para usar esta biblioteca', 'não siga por esse caminho'); se quiser ver o progresso sem interromper a tarefa principal, use a conversa lateral (side chat) para pedir um relatório.
- Medo de perder a conexão em tarefas longas? Alerta oficial: para objetivos que demoram muito para executar, pause antes de desconectar da rede e retome ou edite quando voltar ao normal.
Colocando a validação de perguntas normais e /goal lado a lado, fica fácil saber quando usar cada um:
| Validação em perguntas normais | Modo Objetivo /goal | |
|---|---|---|
| Duração | Apenas nesta rodada; após executar, pode te devolver o controle | Toda a tarefa; não desiste até atingir o objetivo |
| Ideal para | Necessidades únicas, tarefas de um ou dois passos | Tarefas longas com muitos passos que precisam de definição de conclusão clara |
| Como escrever o critério | 「Escrever dois testes e executar」 | Escrever como um 'sim / não' quantificável e testável |
| Precisa de chave de ativação | Não | Precisa de features.goals = true |
💡 Resumo em uma frase: Se quiser que o Codex 'não pare até dar certo, corrigindo rodada após rodada até atingir o critério', use o Modo Objetivo
/goal— o objetivo deve ser escrito como um padrão quantificável de 'sim / não' que ele possa avaliar sozinho; se não souber definir o objetivo, use/planprimeiro e lembre-se de ativarfeatures.goals.
06 Mão na massa: Uma mesma necessidade, duas formas de falar
Ouvir teorias não basta, vamos fazer um pequeno experimento para ver a diferença com os próprios olhos. Você só precisa de um arquivo de teste de três linhas, sem depender do seu projeto atual.
Esclarecimento sobre diferenças de plataforma: O comando para criar pastas
mkdirpode ser usado diretamente no Mac / Linux; no Windows, usemkdir/cdnormalmente, e para criar o arquivostats.py, basta criar um novo arquivo no Bloco de Notas, colar as duas linhas e salvá-lo.
Passo 1: Criar o arquivo de teste com uma 'armadilha' (Mac / Linux)
mkdir prompt-demo
cd prompt-demo
echo 'def average(nums):
return sum(nums) / len(nums)' > stats.pyEsta função tem uma armadilha: se uma lista vazia [] for passada, len(nums) será 0, causando um erro de 'divisão por zero'. Vamos usar isso como nosso campo de testes.
Passo 2: Iniciar o Codex no diretório do projeto
codexResultado esperado: A interface interativa do Codex aparecerá, com o campo de entrada e o cursor na parte inferior. (Se não iniciar ou pedir login, volte ao passo 03 Instalação e login.)
⚠️ Certifique-se de iniciar o
codexdentro do diretórioprompt-demo, não no desktop ou na pasta pessoal — o Codex usa a pasta atual como área de trabalho e lerá de onde for iniciado.
Passo 3: Primeiro use a 'pergunta ruim' para ver como ele adivinha
@stats.py me ajude a alterar esta funçãoResultado esperado: O Codex provavelmente 'adivinhará' o que você quer fazer — talvez adicione anotações de tipo ou documentação, mas ele não sabe que sua real preocupação é a quebra com a lista vazia, e a direção dependerá da sorte. Esse é o preço da falta de 'Objetivo / Validação': ele está decidindo por você.
Passo 4: Mude para a 'pergunta boa' — com todos os quatro elementos
A função average em @stats.py tem um bug: ela quebra por divisão por zero ao receber uma lista vazia.
O comportamento esperado é retornar 0 para listas vazias (Objetivo).
Altere apenas esta função, não mexa em mais nada (Escopo); implemente usando apenas Python puro, sem importar bibliotecas (Restrições).
Corrija para mim e adicione testes: average([]) deve retornar 0 e average([2, 4]) deve retornar 3,
execute-os ao concluir para confirmar que passaram (Validação).Resultado esperado: Desta vez, os passos do Codex serão muito claros — localiza a verificação de lista vazia → adiciona o retorno de 0 → escreve os dois casos de teste solicitados → executa os testes de fato → mostra o resultado de sucesso verde para você. Ele não precisa adivinhar nada do que você quer, porque você definiu exatamente 'o que fazer, o que alterar, o que usar e como medir o sucesso'.
Passo 5: Sair e verificar se as alterações foram salvas
Saia do Codex (use a tecla indicada na interface) e volte ao terminal para verificar o arquivo:
cat stats.py(No Windows PowerShell, use type stats.py)
Resultado esperado: O arquivo stats.py conterá a lógica de tratamento para a lista vazia (algo como if not nums: return 0). Isso corresponde ao que você pediu no Passo 4 = você pegou o jeito de 'falar de forma clara'.
Colocando as duas perguntas lado a lado, a diferença é evidente:
| Passo 3 ❌ Pergunta Ruim | Passo 4 ✅ Pergunta Boa | |
|---|---|---|
| Objetivo | Não mencionado, ele adivinha | Retornar 0 para lista vazia, definido |
| Escopo | Não mencionado, ele adivinha no arquivo | Mencionou a função average |
| Restrições | Não mencionado, livre para importar | Python puro, sem bibliotecas |
| Validação | Sem critérios, para ao 'achar' que acabou | Dois casos de teste + executar |
| Sua experiência | Olhando o diff sem entender por que não era o que queria | Ele segue seu roteiro e resolve de primeira |
💡 Resumo em uma frase: Com o mesmo arquivo e o mesmo bug, a pergunta ruim faz o Codex decidir por você, enquanto a pergunta boa define exatamente 'Objetivo / Escopo / Restrições / Validação' — executar esses dois passos na prática mostra a diferença de forma muito mais direta do que ler sobre ela dez vezes.
07 Uma imagem para fechar: Do pedido à entrega
Vamos organizar a lógica desta seção em uma imagem — a trajetória de uma necessidade desde que sai da sua boca até o Codex concluir o trabalho segue este ciclo:
Preste atenção em duas ramificações cruciais nesta imagem: uma é 'é grande?' — tarefas grandes devem ser divididas e planejadas com /plan primeiro, sem tentar abraçar tudo de uma vez; a outra é 'há uma validação executável?' — fornecendo uma checagem de sucesso/falha, o loop se fecha sozinho; sem ela, ele para com base em impressões e a inspeção final volta para você. Seguir essas duas ramificações corretamente garante o sucesso da parceria com o Codex.
💡 Resumo em uma frase: O caminho correto para uma necessidade é 'tarefa grande dividida /
/plan→ quatro elementos claros → validação executável para fechar o loop → revisar diff para aplicar'; o que te trava nunca é o modelo não ser forte o suficiente, é se você seguiu esses passos adequadamente.
08 Resumo
Esta seção ensinou uma única coisa: como explicar suas necessidades para que o Codex as receba com precisão.
Para fechar, se não conseguir decorar tudo, lembre-se desta tabela:
| Técnica | Em uma frase | Como aplicar |
|---|---|---|
| Quatro elementos | Objetivo / Escopo / Restrições / Validação; ele decide por conta própria o que faltar | 「Altere average (Escopo), retorne 0 para lista vazia (Objetivo), sem bibliotecas (Restrições), adicione dois testes e execute (Validação)」 |
| Cole, não descreva | Forneça o material diretamente | Mencione caminhos de arquivos, selecione na IDE, cole erros completos, envie capturas de tela |
| Divida tarefas grandes | Não tente engolir tudo; divida em partes com validações próprias | Se não souber como dividir, use /plan para propor um plano e libere os passos após revisar |
| Fixe os critérios | Não o deixe parar até atingir o objetivo | Use /goal + critérios quantificáveis de 'sim / não' (ative features.goals antes) |
Agora você é capaz de: traduzir uma necessidade vaga de 'me ajude a alterar' em instruções precisas que o Codex consegue executar — definindo Objetivo, Escopo, Restrições e Validação, colando os dados diretamente, dividindo tarefas complexas e usando /goal quando for necessário rigor absoluto. Esta forma de se comunicar é a sua base para qualquer operação futura com o Codex — não importa as funcionalidades disponíveis, se o pedido for ruim, o resultado também será.
Pensando pelo caminho inverso: se 'falar de forma clara' é tão importante, você precisa repetir regras regras recorrentes (como 'nunca importe novas bibliotecas' ou 'testes devem ficar na pasta
tests/') em todas as perguntas? Existe uma forma de fazer o Codex 'lembrar' disso sem precisar repetir? (Dica: o arquivo 11 · AGENTS.md já traz a resposta.)
A próxima seção 14 · Fluxos de trabalho comuns — enquanto esta ensinou as regras gerais de 'como falar com clareza', a próxima mostrará como aplicá-las em atividades frequentes e específicas: explorar códigos novos, corrigir bugs, refatorar, escrever testes... Cada uma com um roteiro pronto para você seguir. Agora que você tem as regras, vamos aos golpes.