Peça ao Codex que investigue um único incidente de escopo delimitado em um ambiente de nuvem já preparado. O objetivo é entregar material que um engenheiro possa revisar: uma explicação fundamentada, um teste de regressão que falhe antes da correção, um patch restrito ao defeito e evidências dos testes executados.

Esse fluxo funciona bem quando a situação já está estabilizada e resta entender e corrigir um defeito na aplicação. Se as evidências disponíveis não permitirem determinar a causa, um relato claro da investigação e do próximo passo para o diagnóstico já é um resultado útil.

Prepare o ambiente e o material do incidente

1. No aplicativo para web ou desktop, escolha Trabalhar em > Nuvem e selecione um ambiente publicado.

2. Para criar um ambiente, selecione Criar ambiente, escolha os repositórios do GitHub e peça ao Codex que prepare o ambiente de execução, as dependências e os serviços de teste isolados.

3. Revise o relatório de configuração, resolva as falhas nas verificações e selecione Publicar antes de iniciar uma nova tarefa.

• Siga o guia atualizado de ambientes de nuvem.
• Mantenha as orientações do repositório no arquivo AGENTS.md.

Se as dependências ou a configuração dos serviços mudarem, edite o ambiente reutilizável, teste-o e selecione Republicar. Em seguida, valide o ambiente atualizado em uma nova tarefa.

Atualizar o repositório não executa novamente os comandos de instalação e inicialização. As tarefas existentes mantêm seu próprio estado.

Configure separadamente os destinos de rede necessários e as credenciais de teste. Permitir conexões com um destino não concede acesso ao serviço.

Confirme que a cópia de trabalho afetada, as dependências, as verificações e o banco de dados descartável de teste funcionam na nova tarefa. Registre o commit inicial e os resultados de referência dos testes.

Reúna tudo o que for necessário para a investigação inicial. Coloque o material do incidente, já sem dados sensíveis, no repositório ou disponibilize os arquivos para a tarefa. Antes de começar, um engenheiro deve reunir e conferir o seguinte material:

Não inclua tokens de acesso, payloads de clientes ou dados pessoais no material.

A integração com um serviço de monitoramento é opcional. Se usar uma, conceda acesso somente leitura ao projeto e ao período relevantes. O fluxo baseado em arquivos dispensa essa integração. As instruções do repositório devem manter as credenciais de teste separadas da configuração de produção.

Execute o prompt inicial

Use o prompt inicial desta página e substitua os marcadores pelo ID do incidente, pelo repositório e pelo caminho dos arquivos do incidente. O primeiro resultado deve relacionar as evidências ao código afetado, explicar o que é possível reproduzir e identificar as informações que faltam.

Peça ao Codex que prossiga com a implementação somente quando as evidências indicarem um defeito no código. Caso contrário, revise a investigação e forneça as informações que faltam. Uma explicação plausível, uma alteração recente no código ou um teste que passou em outra versão não bastam para determinar a causa.

Exemplo: uma nova tentativa de entrega de um webhook cria um pedido duplicado

Use o exemplo executável do incidente para praticar a investigação. Ele inclui os arquivos do incidente já preparados, um handler com um defeito reproduzível, o handler corrigido e testes com PostgreSQL.

O serviço recebe um webhook order.created, grava um pedido e registra que processou o evento. Durante um incidente, uma nova tentativa de entrega parece criar um segundo pedido. A equipe já estabilizou o serviço e quer revisar um patch.

O exemplo usa JavaScript, o executor de testes do Node.js e PostgreSQL. A fixture descartável contém uma tabela event_receipts com colunas de identificação que não admitem valores nulos e uma restrição de unicidade não postergável sobre (provider, account_id, event_id).

O schema permite reservar o evento inserindo seu recibo antes que o pedido exista. Ele também mantém a impressão digital do payload canônico, necessária para detectar reutilizações conflitantes da mesma chave de evento.

Se a aplicação exigir uma chave estrangeira do pedido no momento da reserva ou não mantiver essa evidência de conflito, interrompa o trabalho para decidir separadamente como tratar o schema ou o desenho da solução.

Registre nas evidências o ambiente de execução exato, as dependências fixadas no arquivo de lock, a versão do PostgreSQL, o nível de isolamento das transações e o schema dos recibos. A fixture disponível para download fixa as versões Node.js 24.19.0, PostgreSQL 17.6 e pg 8.23.1.

Para usar a configuração do Compose fornecida, prepare um ambiente com o daemon do Docker em funcionamento e verifique a saída de docker info antes de publicar o ambiente. O banco de dados aceita apenas credenciais públicas de teste e escuta somente na interface de loopback local. Ao adaptar o teste, use o mecanismo de banco de dados e as configurações relevantes da sua aplicação.

O exemplo pressupõe o nível de isolamento READ COMMITTED do PostgreSQL, IDs de evento estáveis fornecidos pelo provedor e retenção dos recibos por todo o período em que o provedor pode repetir uma tentativa ou reenviar um evento.

O handler corrigido grava o recibo e o pedido na mesma transação do banco de dados. A fixture provisiona um banco de dados descartável e uma tabela delivery_holds para simular o procedimento de quarentena de uma fila existente. Essa tabela faz parte da infraestrutura de teste e não representa uma proposta de migração da aplicação.

A correção da aplicação não acrescenta filas, serviços de banco de dados, migrações de schema ou integrações de monitoramento. Se essas premissas não se aplicarem, interrompa o trabalho e reveja o escopo.

Execute o exemplo

Extraia o ZIP, abra o diretório extraído e use o Docker com o Compose:

docker compose -p codex-incident-rehearsal up -d --wait postgres
docker compose -p codex-incident-rehearsal run --rm runner node main.mjs baseline
docker compose -p codex-incident-rehearsal run --rm runner node main.mjs regression
docker compose -p codex-incident-rehearsal run --rm runner
docker compose -p codex-incident-rehearsal down --volumes

O comando de referência deve terminar com o código 1. Na nova tentativa, a asserção encontra dois pedidos e um recibo em vez de um de cada. O comando de regressão executa a mesma asserção com o handler corrigido e deve terminar com o código 0.

O último comando de teste cobre todos os cenários, incluindo conexões independentes, disputa por bloqueios no banco de dados e quarentena de pedidos legados sem recibo.

Se a sua instalação fornecer docker-compose, use essa grafia no lugar de docker compose. Execute os comandos em sequência. A suíte reinicializa apenas o schema identificado como seu schema de teste.

Examine o handler da transação

O trecho a seguir vem do arquivo main.mjs disponível para download. Depois de extrair o ZIP, execute os arquivos completos, que incluem os testes e a configuração da fixture.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39async function fixed(client, input, hook = async (_boundary) => {}) {
  await assertNotHeld(client, input);
  await hook("beforeClaim");
  await client.query("BEGIN ISOLATION LEVEL READ COMMITTED");
  let committed = false;
  try {
    const claimed = await client.query(
      `INSERT INTO event_receipts(provider, account_id, event_id, payload_fingerprint)
       VALUES ($1,$2,$3,$4)
       ON CONFLICT (provider, account_id, event_id) DO NOTHING RETURNING event_id`,
      [...key(input), fingerprint(input)]
    );
    trace("receipt-claim-result", client, input, {
      inserted: claimed.rowCount === 1,
    });
    if (claimed.rowCount === 1) {
      await hook("afterClaim");
      await writeOrder(client, input);
      await hook("afterOrder");
    } else {
      // A new READ COMMITTED statement sees the winner after its commit.
      await checkReceipt(client, input);
    }
    await client.query("COMMIT");
    committed = true;
    trace("transaction-committed", client, input);
    await hook("afterCommit");
    trace("acknowledged", client, input, acknowledgment);
    return acknowledgment;
  } catch (error) {
    if (!committed) {
      await client.query("ROLLBACK");
      trace("transaction-rolled-back-no-ack", client, input);
    } else {
      trace("committed-response-lost-no-ack", client, input);
    }
    throw error;
  }
}

1. Forneça um conjunto enxuto de arquivos

Use estes arquivos como modelo para organizar o material:

incidents/INC-DEMO-014/incident.md
incidents/INC-DEMO-014/logs.ndjson
incidents/INC-DEMO-014/release.json
incidents/INC-DEMO-014/order-created.sanitized.json

Neste cenário, release.json identifica a versão do exemplo pelo SHA 4a1c9e7d2b6f8a0c3d5e7f9012a4b6c8d0e2f413, implantada em 2026-09-22T11:58:00Z. O incidente ocorreu no intervalo 12:03:00Z–12:05:00Z do mesmo dia. O material relata dois pedidos internos associados a um único evento do provedor. Ao preparar seu próprio material, inclua as contagens confirmadas do impacto e indique quais números são estimativas.

Os logs sem dados sensíveis contêm as seguintes observações correlacionadas:

Mantenha o mesmo ID de evento entre as entregas e use IDs de requisição e de rastreamento distintos para cada entrega. Um identificador específico da requisição ocultaria a relação entre a nova tentativa e o evento original.

2. Rastreie as evidências e teste a hipótese

O relatório do incidente sugere que uma avalanche de novas tentativas causou a duplicação. O Codex deve tratar essa explicação como hipótese. Observar duas entregas não comprova uma avalanche, e novas tentativas são uma condição normal que o handler de um webhook precisa tolerar.

Ao examinar o código afetado do exemplo, é possível identificar esta sequência: consultar o recibo, confirmar a transação do pedido e depois gravar o recibo em outra transação. O intervalo entre as duas confirmações oferece uma explicação mais consistente. Se o worker falhar nesse intervalo, o pedido pode ficar sem recibo, permitindo que uma nova tentativa crie outro pedido. Duas entregas simultâneas também podem passar pela verificação separada antes que qualquer uma delas grave seu recibo.

Peça ao Codex que acompanhe o fluxo do handler real, identifique os limites das transações e cite as linhas relevantes. Ele deve confirmar que a versão indicada no material corresponde ao código testado ou explicar como testar outro commit limita a conclusão.

3. Reproduza o defeito antes de alterar o handler

Adicione um teste de regressão usando o webhook do exemplo e o banco de dados PostgreSQL isolado. No handler original, insira um hook de falha exclusivo para testes imediatamente após a gravação do pedido e antes da gravação do recibo.

Confira os limites reais das transações para confirmar que, nesse ponto, a transação do pedido original já foi efetivada. Repita a entrega com o mesmo provedor, a mesma conta e o mesmo evento. Use uma asserção que exija exatamente um pedido e um recibo correspondente. Na implementação fornecida com o defeito, essa asserção deve falhar ao encontrar dois pedidos.

Após a correção, acione o hook correspondente depois da instrução que grava o pedido, mas antes da confirmação da transação compartilhada. A tentativa que falhar deve deixar zero pedidos e zero recibos.

Repita a entrega e verifique pela asserção que há um de cada. Mantenha a mesma asserção de negócio nas duas revisões e registre a posição do hook em cada uma.

Execute o novo teste primeiro na implementação original. Para o defeito introduzido neste exemplo, a falha esperada é encontrar dois pedidos em vez de um. Salve o comando, o commit inicial, o código de saída e a saída da asserção. Se essa falha não ocorrer, investigue a divergência antes de editar o handler.

Injetar uma exceção permite testar o comportamento transacional da aplicação. Registre que o teste não reproduz todas as possíveis falhas do host, da rede ou do banco de dados.

4. Faça a menor correção justificada pelas evidências

Para este defeito específico, reserve o evento inserindo o recibo e grave o pedido na mesma transação, usando uma única conexão com o banco de dados. Use a chave única existente com INSERT ... ON CONFLICT (provider, account_id, event_id) DO NOTHING RETURNING ....

Somente a entrega que inserir o recibo poderá gravar o pedido. Envie a resposta de sucesso somente após o commit. Se a transação falhar, o rollback desfará as duas gravações. Não capture um erro de unicidade para continuar usando uma transação abortada.

Uma entrega concorrente pode precisar aguardar a primeira transação. Se a primeira efetuar o commit, a segunda tentativa de reserva não inserirá nada. Execute um novo SELECT em READ COMMITTED, confira a identidade armazenada do evento e verifique se o payload atende à política definida. Retorne a resposta já prevista para duplicatas, sem gravar outro pedido.

Se a primeira transação fizer rollback, a entrega concorrente poderá reservar e processar o evento. Se faltar o recibo após uma inserção ignorada, houver conflito de identidade ou ocorrer um erro transitório no banco de dados, siga o fluxo documentado de nova tentativa ou erro. Não retorne uma resposta de sucesso sem fundamento.

Com níveis de isolamento mais rigorosos, falhas de serialização exigem seguir a política do repositório para repetir a transação inteira com um número limitado de tentativas. Consulte a documentação do PostgreSQL sobre o comportamento de INSERT em caso de conflito e sobre o isolamento de transações.

Nem um conjunto em memória nem uma sequência separada de “verificar e depois inserir” protegem contra a execução simultânea de workers ou reinicializações. Defina o escopo da chave conforme as regras do provedor para identificar eventos. Se um evento supostamente idêntico trouxer dados de identidade ou de payload conflitantes, sinalize a inconsistência em vez de aceitá-lo silenciosamente como duplicata válida.

No exemplo, toda a alteração dos dados de negócio ocorre no mesmo banco de dados. Se o handler real também enviar e-mails, fizer cobranças no cartão ou chamar outro serviço, a transação por si só não tornará esses efeitos externos idempotentes. Antes de ampliar a correção, identifique onde termina a transação e qual mecanismo de entrega ou idempotência o sistema já utiliza.

5. Verifique o comportamento após a alteração

Peça tanto o registro da falha original quanto o resultado após a correção. Use hooks exclusivos para testes em limites de transação identificados e inspecione o estado confirmado a partir de uma conexão separada. O exemplo passa em onze testes locais com PostgreSQL. O arquivo test-evidence.md disponível para download registra esses resultados e as verificações que ainda precisam ser feitas para execução na Nuvem e implantação. Execute a suíte no ambiente publicado e teste uma perda real de conexão durante o commit antes de confiar nesse fluxo de recuperação.

Coordene a concorrência com barreiras ou latches e tempos de espera limitados. Não dependa de pausas fixas nem apenas de duas promises. Libere os workers bloqueados na etapa de limpeza dos testes e use fixtures descartáveis. Um teste de exceção isolado não comprova como o sistema se comporta diante do encerramento abrupto de um processo, da perda de conexão ou da concorrência em produção.

O exemplo executa node main.mjs baseline, node main.mjs regression e node main.mjs no executor de versão fixa. A saída estruturada registra os limites das transações, as contagens de linhas confirmadas, o status e o corpo das respostas e os IDs observados dos processos de backend responsáveis pelos bloqueios.

Ao adaptar o fluxo, use os comandos definidos no seu repositório e informe os resultados reais. Inclua no material de entrega qualquer verificação ignorada ou dependência indisponível e explique como isso afeta a confiança nos resultados.

Revise o material de entrega

Registro compartilhado de evidências

Use o formato de evidências do fluxo de investigação para cada critério de aceitação. Preencha os campos com base na saída observada. O modelo abaixo não representa resultados aprovados. Para um novo teste que ainda não existia na revisão inicial, diferencie “ainda não existia” de uma falha em uma verificação existente.

Criterion / test: [specific behavior and test location]
Environment: [published setup reference; runtime, database and dependency versions]
Before: [revision + test-only diff ID; command; exit code; observed assertion; log path]
After: [final revision or base + diff ID; command; exit code; observed assertion; log path]
Status: [pass / fail / blocked / not run]
Limits / reviewer action: [untested behavior, blocker, or decision required]

Associe as execuções que falharam e as que passaram às revisões efetivamente testadas, incluindo as alterações feitas exclusivamente para testar a revisão original. Inclua os logs, as fixtures de resposta e o diff final no material de entrega. Se a revisão final mudar, atualize as evidências. Verificações não executadas ou bloqueadas não podem contar como aprovadas.

Peça ao Codex que deixe o diff do código e estes arquivos para revisão no repositório:

• incident-investigation.md: linha do tempo, referências às evidências, hipóteses testadas, causa sustentada pelas evidências e incertezas restantes.
• test-evidence.md: commit de referência, saída do teste de regressão que falhou, commit ou diff da correção, verificações específicas que passaram, verificações mais amplas e limitações.
• pr-draft.md: explicação concisa do defeito, da mudança de comportamento, das evidências dos testes e do risco restante.
• deployment-handoff.md: premissas verificadas sobre schema, isolamento e retenção de recibos, nome do responsável pela implantação, verificações prévias, métricas de pedidos duplicados, respostas e erros, além dos critérios abaixo para prosseguir com a implantação ou revertê-la.

Antes de aceitar o patch, verifique se o código original falha no novo teste, se o código corrigido passa e se o diff resolve o defeito demonstrado. No exemplo do webhook, examine o escopo da chave do evento, os limites das transações, a cobertura dos cenários de concorrência e os efeitos fora da transação. Revise separadamente os pedidos duplicados já existentes. Prevenir novas duplicatas não corrige os registros históricos.

Planeje a implantação e a reversão

O patch protege apenas os workers que executam o handler corrigido. Workers antigos ainda podem gravar um pedido antes de reservar o evento pelo recibo. Por isso, uma implantação canário com versões diferentes não comprova que o defeito foi eliminado.

O responsável pela implantação deve escolher entre uma estratégia já testada com versões diferentes e um procedimento operacional existente que pause a ingestão, aguarde os workers antigos concluírem o processamento em andamento, atualize todos os consumidores e retome sem perdas as entregas retidas.

Antes de escolher a segunda opção, confirme como o provedor e a fila lidam com novas tentativas e retenção. Não presuma que seja possível pausar sem perdas.

Antes de retomar as entregas retidas, identifique os pedidos legados já confirmados que não têm recibo correspondente. Pausar os consumidores antigos e aguardar a conclusão do processamento em andamento impede novas gravações pelo código legado, mas não corrige os pedidos existentes. Bloqueie cada chave de evento afetada usando a fila existente ou o procedimento de quarentena. Se os registros legados não permitirem determinar a identidade completa do evento, mantenha pausadas as entregas afetadas ou as entregas do período afetado para revisão pelo responsável, sem declarar a varredura concluída.

Só reconcilie uma chave bloqueada quando a identificação imutável e confiável do provedor, da conta e do evento, as evidências do payload canônico e o registro de negócio confirmado permitirem determinar o que já aconteceu.

Siga o procedimento de reconciliação aprovado para registrar o recibo correspondente sem repetir a operação de negócio. Em seguida, libere a chave.

Mantenha as chaves afetadas em quarentena para revisão pelo responsável se faltarem evidências, houver conflito entre payloads ou existirem vários registros de negócio. Ao reconstruir a impressão digital do evento original, não use o payload de uma nova tentativa como substituto de evidências confiáveis sobre o evento original.

Só autorize a retomada quando cada chave afetada tiver sido reconciliada ou continuar bloqueada em todos os consumidores.

No ambiente de homologação, prepare um pedido legado e uma nova tentativa pendente para ele. Verifique se o bloqueio impede tanto a criação de outro pedido quanto o envio de qualquer resposta de sucesso. Após a reconciliação com evidências confiáveis, a nova tentativa pode receber a resposta prevista para duplicatas, e deve continuar existindo apenas um pedido. Simule também um caso sem solução: ele deve continuar bloqueado, sem que se crie um recibo sem fundamento. Inclua esse critério no material de implantação, junto com as verificações de pausa e conclusão do processamento em andamento, versões dos consumidores, retenção e reversão.

Antes da implantação, verifique se a restrição de unicidade existente está presente e válida, se todos os consumidores aplicam a mesma política para a chave e o payload do recibo, se a limpeza de recibos preserva a proteção contra reenvios durante todo o período previsto e se os efeitos externos continuam fora do escopo do patch.

Na homologação, simule a sequência escolhida e a nova tentativa após a falha de um worker. Registre o período de observação definido pelo responsável e os limites que exigem interromper a implantação para pedidos duplicados, erros de webhook, latência das respostas, espera por bloqueios e acúmulo de tentativas pendentes. Não invente limites de produção.

Reverter para o handler antigo pode voltar a gerar pedidos duplicados. O material de reversão deve indicar a medida de contenção (por exemplo, o procedimento aprovado de pausa e conclusão do processamento em andamento), a revisão segura e o responsável por decidir quando retomar o processamento. Preserve os recibos. Não os exclua para desbloquear novas tentativas. A correção de pedidos duplicados históricos exige revisão separada.

Cabe ao engenheiro decidir sobre a implantação e qualquer medida corretiva em produção. Um teste isolado que passa fornece evidências para revisão, mas não comprova o bom funcionamento em produção. Depois de revisar o rascunho, crie o pull request, siga os processos habituais de CI e revisão e faça a implantação usando os controles estabelecidos pela equipe.

Continue na mesma tarefa

Faça um pedido específico de acompanhamento para esclarecer dúvidas ou melhorar o material de entrega:

Revise o patch considerando dois cenários: duas entregas simultâneas e uma nova tentativa após a falha de um worker. Mostre quais comportamentos os testes comprovam e quais ainda não foram testados. Limite a alteração a este handler e aos respectivos testes de regressão. Atualize o material de entrega com os riscos que ainda existirem.

Se a primeira execução não conseguiu reproduzir o incidente:

Interrompa a implementação. Liste as hipóteses que as evidências descartam e indique qual das hipóteses restantes tem mais respaldo. Para distingui-la das demais, especifique o mínimo de dados adicionais necessários, sem informações sensíveis, ou o menor experimento isolado que permita fazer essa distinção. Mantenha a causa raiz como não confirmada.