Como escrever bons prompts para o Codex gerar exatamente o código que você quer

Nos capítulos anteriores você instalou o Codex, aprendeu a conduzir uma sessão e definiu quanta liberdade o agente tem para editar e executar comandos. Agora vem a habilidade que mais muda seus resultados no dia a dia: escrever o pedido. Ao fim deste capítulo você vai saber estruturar uma instrução em cinco partes, apontar para arquivos e trechos exatos, exigir um plano antes do código, quebrar tarefas grandes em etapas revisáveis, corrigir o rumo quando a resposta não serve e usar imagens como parte do pedido.

As cinco partes de um pedido eficaz

Chamamos de prompt o pedido que você escreve para o agente. Um prompt bom não é um prompt longo; é um prompt completo. Ele responde cinco perguntas, nesta ordem.

• Objetivo. O que precisa existir depois da mudança, em uma frase. Não como fazer, e sim o resultado.
• Contexto. Linguagem, framework, versão, quais arquivos estão envolvidos e onde ficam os testes. O Codex consegue descobrir muito disso sozinho lendo o repositório, mas cada informação que você dá é uma busca que ele não precisa fazer e um palpite que ele não precisa arriscar.
• Restrições. O que ele não pode fazer. Não instalar dependências novas, não mexer no esquema do banco, não alterar a assinatura pública de uma função, manter compatibilidade com uma versão antiga. Isso é o que chamo de escopo negativo, e é a parte que quase todo mundo esquece.
• Critérios de aceitação. Como saber que ficou pronto, de forma verificável. Uma rota que responde com determinado código de status, um comando de teste que passa, uma saída esperada para uma entrada específica.
• Formato esperado. Como você quer receber o trabalho. Plano antes de editar, mudanças em um único commit, diffs pequenos, explicação em três linhas no final.

O mesmo pedido, vago e preciso

Imagine uma interface de programação de aplicações, ou API, escrita em Python com FastAPI. O pedido vago costuma ser assim:

Cria um login pra minha API.

O agente vai fazer algo. Provavelmente vai inventar um arquivo novo, escolher uma biblioteca de token que talvez não esteja no projeto, criar um modelo de usuário paralelo ao que já existe e nenhum teste. Não é burrice do modelo: você não disse o que era certo, então ele preencheu as lacunas com o que é mais comum no mundo, não com o que é verdade no seu repositório.

Agora o mesmo pedido com as cinco partes:

Continue em nosso aplicativo e ...

• Ouça o áudio com a tela desligada
• Ganhe Certificado após a conclusão
• + de 5000 cursos para você explorar!

ou continue lendo abaixo...

Baixar o aplicativo

Objetivo: adicionar autenticacao por token JWT no login da API.

Contexto: Python 3.11 com FastAPI. As rotas de autenticacao ficam em
app/routers/auth.py. O modelo de usuario esta em app/models/user.py e
ja guarda a senha com hash bcrypt. Os testes usam pytest, em tests/.

Restricoes: use apenas bibliotecas que ja estao em requirements.txt.
Nao altere o esquema do banco nem os modelos existentes.
Nao mexa em app/main.py alem de registrar o router, se preciso.

Criterios de aceitacao: POST /auth/login recebe email e senha,
responde 200 com access_token quando as credenciais sao validas e
401 quando nao sao. tests/test_auth.py cobre os dois casos.
O comando pytest -q passa sem erros.

Formato: mostre o plano e espere minha confirmacao antes de editar.

A diferença aparece em várias frentes ao mesmo tempo. E, quando o assunto é autenticação, vale acrescentar aos critérios que o token tenha prazo de expiração, que a chave de assinatura venha de variável de ambiente e que a API só seja publicada sobre HTTPS: o agente não adivinha essas exigências de segurança se você não as escrever.

Aponte para arquivos e trechos, não para ideias

A forma mais rápida de dar contexto é citar caminhos. No Codex CLI, digite o símbolo de arroba e comece a escrever o nome do arquivo: aparece uma busca aproximada e o caminho é inserido no pedido. Essa é a menção de arquivo, e ela faz o agente ler aquele arquivo antes de raciocinar, em vez de procurar às cegas.

Além do arquivo inteiro, você pode restringir mais:

• Cite a função ou a classe pelo nome: na função calcular_frete de services/frete.py.
• Cite faixas de linhas: entre as linhas 40 e 75.
• Cole a mensagem de erro ou o trecho de log inteiro, sem resumir.
• No painel lateral da extensão, selecione o trecho no editor antes de escrever o pedido. A seleção vai junto e substitui qualquer descrição aproximada.

Uma frase que rende muito é pedir leitura antes de resposta: leia app/routers/auth.py e app/models/user.py antes de propor qualquer mudança e me diga o que encontrou. Se a leitura estiver errada, você descobre antes de existir um diff.

Peça o plano antes do código

Para qualquer tarefa que toque mais de um arquivo, exija o plano do agente primeiro e proíba explicitamente a edição:

Nao edite nenhum arquivo ainda. Liste em ate seis passos como voce
faria essa mudanca, dizendo quais arquivos toca em cada passo e
quais testes rodaria. Aponte tambem o que ficou ambiguo no pedido.

Esse último pedido, sobre ambiguidades, vale ouro. Em vez de o agente escolher por você, ele devolve duas ou três perguntas, e cada resposta sua vira uma restrição nova. Ler um plano de dez linhas custa meio minuto; revisar um diff errado de trezentas linhas custa meia hora.

Divida tarefas grandes em etapas revisáveis

Agentes erram mais quando o pedido cresce. A regra prática é simples: cada etapa deve caber em um diff que você consiga revisar com atenção, e deve terminar em um estado que funcione. Depois de aprovar o plano, conduza assim:

1. Peça apenas a primeira etapa e diga para parar ao terminar: implemente somente o passo um e pare para eu revisar o diff.
2. Revise, ajuste e faça o commit com Git. A árvore limpa é sua rede de segurança, como vimos no capítulo sobre modos de aprovação.
3. Siga para a etapa seguinte no mesmo diálogo, para o agente manter o contexto do que já foi feito.

Se o projeto tem migração de banco, mudança de contrato de API e ajuste de interface, essas são três etapas, nunca um pedido só.

Quando a resposta não serve: iterar, não repetir

Repetir o mesmo pedido em voz mais alta não funciona. Existem quatro movimentos úteis, do mais leve ao mais radical.

• Corrigir com precisão. Diga qual trecho está errado e por quê: na linha que monta o token você usou uma chave fixa no código; leia a chave da variável de ambiente JWT_SECRET e falhe na inicialização se ela não existir.
• Dar evidência real. Cole a saída do comando que falhou, inteira, mas antes remova senhas, tokens, chaves de API e dados pessoais, porque esse conteúdo é enviado ao modelo. O agente é muito melhor consertando com o erro na mão do que com a sua interpretação do erro.
• Estreitar o escopo. Se ele mudou o que não devia, peça para reverter e liste os arquivos permitidos: desfaça as alterações em app/main.py e mexa apenas em auth.py.
• Recomeçar limpo. Quando a conversa já acumulou tentativas erradas, volte o repositório ao último commit, abra uma nova conversa e escreva de novo o prompt, agora incorporando tudo o que você aprendeu na tentativa anterior. Atenção: voltar ao último commit descarta tudo o que não foi commitado e não há como desfazer; antes de fazer isso, guarde o que interessa com um commit temporário em outro branch ou com git stash. Um contexto poluído por caminhos errados tende a puxar o agente de volta para eles.

Imagens como parte do pedido

O Codex aceita entrada visual, e isso resolve situações em que descrever por escrito é penoso. Três usos valem o esforço:

• Captura de tela de um erro no navegador ou em um aplicativo, quando o log não conta a história inteira.
• Rascunho de interface, inclusive uma foto de desenho em papel, para gerar o componente com o layout aproximado.
• Diagrama de arquitetura ou de banco de dados, para o agente entender relações antes de escrever consultas.

No Codex CLI, você anexa a imagem ao iniciar a sessão passando o parâmetro de imagem com o caminho do arquivo, por exemplo codex -i erro.png "explique esse erro e corrija". Na extensão, basta arrastar ou colar a imagem no painel lateral. Duas dicas aumentam muito o acerto: recorte a imagem para mostrar só o que importa, o que também evita enviar tokens, e-mails e dados de clientes que aparecem na tela, e diga em palavras onde olhar, como veja o alinhamento do botão na coluna da direita. A imagem complementa o texto; ela não substitui objetivo, restrições e critérios de aceitação.

Um esqueleto para copiar

Vale manter este molde num arquivo de notas e preencher em trinta segundos antes de tarefas não triviais:

Objetivo:
Contexto: linguagem, framework, arquivos envolvidos, comando de teste
Restricoes: o que nao pode mudar, o que nao pode ser instalado
Criterios de aceitacao: comportamento verificavel e teste que deve passar
Formato: plano antes de editar, um commit, diff pequeno

Para pedidos triviais, como renomear uma variável em um arquivo, isso é excesso. Use o bom senso: quanto maior o raio da mudança, mais vale a estrutura.

Recapitulando

Um pedido eficaz tem objetivo, contexto, restrições, critérios de aceitação e formato esperado. Aponte arquivos e trechos com menções de arroba, faixas de linhas ou seleção no editor, em vez de descrições vagas. Exija o plano antes do código e peça que o agente liste ambiguidades. Divida tarefas grandes em etapas que terminem em estados funcionais e revisáveis, com commit entre elas. Quando o resultado não serve, corrija com precisão, forneça a saída real do erro, estreite o escopo ou recomece do último commit em uma conversa nova. E use capturas de tela, rascunhos e diagramas quando a imagem economizar um parágrafo de descrição.