Corrigir um bug com análise, correção e revisão

O cenário

Na loja-api, o cupom PRIMEIRA (desconto da primeira compra) dá desconto em dobro quando o carrinho tem dois itens ou mais. Os testes atuais passam, porque não existe teste de cupom. A correção vai ser feita em três etapas, cada uma com seu agente, seu terminal e seu papel:

Você entra em dois momentos: num pedido de permissão e na aprovação final. O resto os agentes fazem em sequência.

Veja no vídeo

VÍDEO 10 · 2:35

Uma operação de correção com vários agentes. Um bug corrigido do começo ao fim por três agentes: análise, correção confirmada pelo npm test e revisão com a minha aprovação. Legendas e transcrição ↗

Antes de começar

1. Cadastre C:\demo\loja-api e confira que npm test passa num PowerShell do projeto.
2. Confira a verificação do projeto no cartão: Verificação: npm test · detectado. Se não aparecer, abra o menu ··· do cartão, escolha Verificação, informe npm test, use Testar agora e Salvar. Veja Verificação.
3. Em Ferramentas → Regras e papéis…, crie três regras em Deste projeto: "Responda sempre em português do Brasil.", "Não altere package.json sem avisar antes." e "Toda mudança em src vem com um teste." Veja Regras.
4. Tenha o Claude Code e o Codex instalados e autenticados.

Monte o fluxo

As três etapas são criadas pela + Nova etapa, com Só planejar, para nada começar antes de você conferir o conjunto.

Etapa 1: análise

1. Com loja-api selecionado, clique em + Nova etapa, no topo.

2. Em O que precisa ser feito?, escreva:

   Investigue por que o cupom PRIMEIRA dá desconto em dobro em carrinhos com mais de um item. Grave a causa, o plano e um caso que reproduz em ANALISE.md. Não altere código.

3. Executa: Claude Code. Em Onde esta etapa roda, Novo terminal.
4. Abra Mais opções. Em Papel (regras), escolha analista. Em Como esta etapa termina e a próxima começa?, escolha Automática.
5. Em Ao criar, escolha Só planejar e confirme.

A análise grava o resultado num arquivo porque o Codex não enxerga a conversa do Claude Code. O arquivo é a passagem entre os dois.

Etapa 2: correção

1. Clique de novo em + Nova etapa. Com um fluxo planejado, o diálogo abre para acrescentar ao fluxo, depois da etapa 1.

2. Tarefa:

   Leia ANALISE.md, corrija a causa e acrescente um teste que reproduz o caso. Rode npm test.

3. Executa: Codex CLI, Novo terminal, começando depois da etapa 1.
4. Em Mais opções: papel implementador e Automática com verificação. Em Conferir com um comando (opcional), use o do projeto (npm test), que aprova quando terminar com sucesso (0).
5. Só planejar e confirme.

Etapa 3: revisão

1. + Nova etapa outra vez: Executa: Claude Code, Novo terminal, depois da etapa 2.

2. Tarefa:

   Revise o diff desta correção e grave até três achados em REVISAO.md, com arquivo e linha. Responda só com os achados.

3. Em Mais opções: papel revisor e Com sua aprovação.
4. Só planejar e confirme.

Ampliar captura ↗

Antes de executar, abra o Fluxo e leia os três cartões: o agente e o papel de cada um (por exemplo Codex CLI · implementador), terminal próprio, a linha Começa: e a linha Pronta: (Automática, Automática com verificação com npm test passar, Com sua aprovação). Em Regras deste projeto · 3, confira as regras que valem para as três etapas.

Execute e acompanhe

1. Clique em Executar fluxo e volte para a Grade. Os terminais das etapas abrem; só o da análise recebe a instrução agora.
2. O analista lê src/cupom.cjs e src/carrinho.cjs. Quando quiser gravar o ANALISE.md, a CLI pede permissão. O pedido aparece em quatro lugares: no rótulo do painel, no cartão do projeto (aguardando você), na aba Atenção e no rodapé (1 aguardando).
3. Na Atenção, clique em Ver pedido. O diálogo Pedido de permissão mostra o terminal, o projeto, a etapa e o comando pedido. Responda com Permitir, Recusar ou Ir ao terminal.
4. Com a análise pronta, a correção começa sozinha. Passe para o Foco e clique na miniatura do Codex para acompanhar.
5. O Codex lê a análise, altera o cálculo do desconto em src/cupom.cjs, acrescenta o teste dos dois itens e roda npm test.
6. A etapa 2 só fica pronta porque npm test passou. Na aba Etapas, Ver resultado mostra o comando, a saída e o veredito.

Ampliar captura ↗

Ampliar captura ↗

Revise e aprove

1. O revisor lê o diff e grava os achados em REVISAO.md.
2. Quando ele termina, a etapa aparece na Atenção como precisando de você. Abra Revisar a entrega e leia os achados.
3. Se estiver tudo certo, clique em Aprovar e continuar. Se algo precisar mudar, use Devolver para correção… com uma instrução clara; a correção volta para o implementador.
4. Na aba Etapas, abra Instruções enviadas e o registro para ver o horário de cada entrega, aviso e aprovação.

O que conferir no fim

• git status --short mostra src/cupom.cjs alterado, o teste novo, ANALISE.md e REVISAO.md.
• npm test passa num terminal seu, fora do agente.
• O diff faz só o que a análise propôs. Use Revisar alterações no resultado para ler o diff pela tela, ou o seu editor.

Variações

• Sem o Codex. Use o Claude Code nas três etapas. Para a correção, um terminal novo dá uma conversa limpa; o mesmo terminal da análise continua a conversa com o contexto que ela já tem.
• Correção num worktree. Se outra tarefa está mexendo na mesma pasta, crie a etapa de correção numa cópia isolada (Mais opções, pasta em um worktree novo). Lembre que o worktree nasce sem dependências instaladas. Veja Worktrees.
• Sem aprovação. Para tarefas pequenas, a revisão pode ser automática. Para mudanças em produção, mantenha a aprovação.