Até aqui você aprendeu cada peça do Codex separadamente: instalação, modos de aprovação, prompts, AGENTS.md, leitura de código, correção de bugs, refatoração, testes, automação, nuvem e MCP. Neste capítulo você vai juntar tudo em uma entrega real, do primeiro rascunho da especificação até o pull request revisado, e sair com um roteiro que pode repetir em qualquer tarefa do seu trabalho.
O projeto e a funcionalidade
Vamos trabalhar sobre a mesma API de pedidos em Python com FastAPI que apareceu nos capítulos anteriores. A estrutura é simples: uma pasta de rotas, uma pasta de serviços com as regras de negócio, uma pasta de repositórios que fala com o banco de dados e uma pasta de testes. O repositório já tem AGENTS.md na raiz, com os comandos de suíte e as convenções de código.
A funcionalidade pedida é a aplicação de cupons de desconto no fechamento do pedido. Ela é boa para um capítulo integrador porque toca em várias camadas, tem regras de negócio com casos de borda e exige migração de banco de dados. É exatamente o tipo de tarefa em que jogar um pedido solto no agente costuma dar errado.
Passo um: escrever a especificação antes de abrir o Codex
A primeira coisa que você escreve não é código nem prompt: é uma especificação curta, em um arquivo versionado. Eu costumo criar a pasta docs/tarefas e um arquivo por funcionalidade. Assim a especificação vira contexto reutilizável em todas as sessões seguintes, e não algo que você redigita.
# Cupons de desconto no fechamento do pedido
## Objetivo
Permitir que o cliente informe um codigo de cupom ao
fechar o pedido e receba o desconto correspondente.
## Regras
- Cupom tem codigo, tipo (percentual ou valor fixo),
valor, data de validade e limite de usos.
- Cupom expirado ou sem usos restantes e recusado.
- Desconto percentual nunca passa de cinquenta por cento.
- O total do pedido nunca fica negativo.
- Um pedido aceita no maximo um cupom.
## Fora de escopo
- Tela de administracao de cupons.
- Cupons por cliente ou por categoria de produto.
- Alteracao do calculo de frete.
## Critérios de aceitação
- POST em /pedidos/{id}/fechar aceita campo cupom opcional.
- Cupom invalido responde 422 com mensagem clara.
- Testes novos cobrem as cinco regras acima.
- Suite completa passa com o comando do AGENTS.md.
Note que a especificação já contém o objetivo, as restrições, o escopo negativo e critérios de aceitação verificáveis, na estrutura que você aprendeu no capítulo de prompts. A diferença é que agora ela mora no repositório.
- Ouça o áudio com a tela desligada
- Ganhe Certificado após a conclusão
- + de 5000 cursos para você explorar!
Baixar o aplicativo
Passo dois: pedir o plano e ajustá-lo
Abra o Codex CLI na raiz do projeto com a árvore do Git limpa e o sandbox em modo somente leitura. O primeiro pedido não edita nada:
Leia @docs/tarefas/cupons.md e @AGENTS.md.
Proponha um plano de implementacao em etapas pequenas,
cada uma com os arquivos que seriam tocados e como
seria verificada. Nao edite nada agora.
Ao final, liste as ambiguidades da especificacao.
O plano do agente normalmente volta com seis a oito etapas. A lista de ambiguidades é a parte mais valiosa: na minha execução, o agente perguntou se o cupom é validado no momento do fechamento ou também na visualização do carrinho, e se o limite de usos é global ou por cliente. Essas duas perguntas viraram duas linhas novas na especificação. Corrigir isso agora custa um minuto; descobrir depois custa uma reimplementação.
Ajuste também o tamanho das etapas. Se o agente propôs uma etapa chamada "implementar cupons", peça para dividi-la. Uma etapa boa cabe em um commit que você consegue revisar em poucos minutos.
Passo três: implementar em etapas revisáveis
Com o plano aprovado, mude para o modo automático e execute uma etapa por vez, com commit entre elas. Peça explicitamente para o agente parar no fim de cada etapa em vez de seguir sozinho até o fim do plano. E uma precaução antes da primeira etapa: teste a migração, principalmente o caminho de reversão, em um banco local descartável ou em uma cópia dos dados, nunca em uma base compartilhada ou de produção, porque desfazer uma migração costuma apagar colunas e os dados que estavam nelas.
| Etapa | Sandbox | Verificação | Artefato |
|---|---|---|---|
| Modelo e migração de cupom | workspace-write | migração sobe e desce | commit um |
| Repositório de cupons | workspace-write | teste unitário do repositório | commit dois |
| Regra de cálculo do desconto | workspace-write | testes das cinco regras | commit três |
| Rota de fechamento | workspace-write | teste de integração | commit quatro |
| Documentação | workspace-write | leitura humana | commit cinco |
Revise o diff de cada etapa com o comando de sessão de diferenças antes de aprovar. Duas coisas merecem atenção especial: arquivos tocados fora do escopo e dependências novas que não estavam no plano. Na etapa da regra de cálculo, o agente tentou instalar uma biblioteca de datas que o projeto não usa. Recusei e pedi para resolver com a biblioteca padrão, que já estava listada no AGENTS.md como preferida.
Passo quatro: testes e correção do que falhar
Como o comando de suíte está registrado no AGENTS.md, o agente costuma rodar os testes sozinho ao terminar cada etapa, mas isso não é garantido: peça a execução de forma explícita e confira na saída que a suíte realmente rodou, em vez de confiar no relato de que passou. Mesmo assim, peça a enumeração dos casos de borda antes de ele escrever os testes, como você aprendeu no capítulo de testes. Nesta funcionalidade os casos duvidosos foram três: cupom percentual acima do limite, cupom com valor fixo maior que o total do pedido e cupom que expira exatamente no dia do fechamento.
Na quarta etapa, dois testes de integração falharam. Aqui entra o fluxo de depuração assistida: forneci a saída completa da suíte e exigi a causa raiz com arquivo e linha antes de qualquer correção. A causa era real e interessante: o limite de usos era decrementado antes da confirmação do pagamento, então pedidos recusados consumiam cupom. Aproveite para cuidar de um caso vizinho que a suíte não pega: o consumo do limite precisa ser atômico no banco, com atualização condicional ou bloqueio da linha, senão dois fechamentos simultâneos furam o limite de usos. A primeira proposta do agente foi relaxar a asserção do teste. Recusei, porque isso é correção superficial, e pedi a correção no serviço. O teste continuou intacto, o que é o sinal que você quer ver.
Passo cinco: refatorar com a suíte verde
Só depois de a suíte inteira passar é que vale refatorar. Peça primeiro um relatório de pontos de melhoria em modo somente leitura, restrito aos arquivos da funcionalidade. No nosso caso apareceram dois itens úteis: duplicação entre o cálculo de desconto percentual e o de valor fixo, e uma função de fechamento com responsabilidades demais. Fiz as duas em commits separados, um tipo de mudança por commit, e confirmei que nenhum arquivo de teste foi alterado.
Passo seis: documentação e pull request
A documentação é uma etapa, não um extra. Pedi docstrings nas funções públicas novas, uma seção curta no README explicando o formato do cupom e uma entrada no changelog. Depois, o pull request:
Crie a branch feat/cupons-desconto, faca commit das
mudancas pendentes e abra um pull request.
A descricao deve ter: resumo em duas frases, lista de
regras implementadas, o que ficou fora de escopo e
como testar localmente.
Esse pedido só funciona com o gh instalado e autenticado, e lembre que no modo automático a rede fica bloqueada por padrão, então enviar a branch e abrir o pull request vão exigir aprovação sua. Com o pull request aberto, peça a revisão automática do Codex pelo GitHub, que depende de o aplicativo do Codex estar instalado e o repositório conectado à sua conta, direcionando o foco: regras de negócio de desconto, tratamento de erros da rota e reversibilidade da migração. A revisão apontou um detalhe que eu tinha deixado passar: o código de cupom era comparado com diferença entre maiúsculas e minúsculas. Corrigi com um pedido pontual na mesma sessão, e o teste correspondente entrou como teste de regressão.
Mantendo o contexto organizado em sessões longas
Uma entrega assim consome várias horas e muitas mensagens. Três hábitos evitam que o agente se perca:
- Uma conversa por etapa. Ao concluir e commitar uma etapa, comece conversa nova e aponte para a especificação e para o último commit. O contexto é finito, e histórico velho só atrapalha.
- A especificação como memória externa. Toda decisão tomada no meio do caminho volta para o arquivo da tarefa. Assim a conversa nova já nasce informada.
- Commits pequenos e frequentes. Eles são o seu botão de desfazer. Se uma etapa degringolar, você volta ao último commit e recomeça com um pedido melhor, sem negociar com o agente.
Quando intervir manualmente
Delegar tudo é tão ruim quanto não delegar nada. Assuma o teclado nestes casos: quando a decisão é de arquitetura ou de produto, como escolher se o cupom é validado no carrinho; quando a mudança é de uma linha e explicar levaria mais tempo que fazer; quando o agente já errou duas vezes na mesma coisa, sinal de que falta contexto que só você tem; e quando a ação envolve produção, credenciais ou dados reais de cliente. Nesses últimos, escreva você mesmo o comando e confira antes de executar.
Registrando aprendizados no AGENTS.md
Ao fechar o pull request, gaste cinco minutos promovendo para o AGENTS.md o que se repetirá. Desta entrega saíram três linhas: nunca adicionar dependência nova sem aprovação explícita; migrações de banco sempre com caminho de reversão testado; comparações de código de cupom sempre sem diferenciar maiúsculas de minúsculas, valendo só para cupons, porque senhas, tokens e chaves de API continuam sensíveis a maiúsculas e devem ser comparados em tempo constante. Cada linha dessas é um erro que o agente não vai repetir no próximo ciclo. É assim que o projeto fica mais fácil de automatizar com o tempo.
Recapitulando
O roteiro completo é este: escreva a especificação em arquivo versionado, peça plano e ambiguidades em modo somente leitura, ajuste o plano até as etapas ficarem pequenas, implemente uma etapa por commit revisando cada diff, exija testes com casos de borda enumerados, corrija falhas pela causa raiz e nunca pela asserção, refatore só com a suíte verde, documente como etapa, abra o pull request com descrição no formato pedido e peça revisão dirigida. Mantenha o contexto limpo com uma conversa por etapa, intervenha nas decisões de arquitetura, de produto e de risco, e transforme cada aprendizado em uma linha do AGENTS.md.
