Asigna a Codex un solo incidente de alcance bien definido para que lo investigue en un entorno en la nube preparado de antemano. El objetivo es obtener un resultado que alguien del equipo de ingeniería pueda revisar: una explicación respaldada por la evidencia, una prueba de regresión que falle antes de la corrección, un parche específico y evidencia de las pruebas ejecutadas.

Este flujo funciona bien cuando la situación ya se estabilizó y queda por entender y corregir un defecto de la aplicación. Si la evidencia disponible no permite determinar la causa, un resultado útil es una descripción clara de la investigación y del siguiente paso para el diagnóstico.

Prepara el entorno y el paquete del incidente

1. En la aplicación web o de escritorio, elige Trabajar en > Nube y selecciona un entorno publicado.

2. Para crear uno, selecciona Crear entorno, elige los repositorios de GitHub y pide a Codex que prepare el entorno de ejecución, las dependencias y los servicios de prueba aislados.

3. Revisa el informe de configuración, resuelve los problemas que detectaron las verificaciones y selecciona Publicar antes de iniciar una tarea nueva.

• Sigue la guía vigente de entornos en la nube.
• Guarda las instrucciones del repositorio en AGENTS.md.

Si cambian las dependencias o la configuración de los servicios, edita el entorno reutilizable, pruébalo y selecciona Volver a publicar. Luego valida el entorno actualizado en una tarea nueva.

Al actualizar el repositorio, no se vuelven a ejecutar los comandos de instalación ni de inicio. Las tareas existentes conservan su propio estado.

Configura por separado los destinos de red necesarios y las credenciales de prueba. Permitir un destino no otorga acceso al servicio.

Confirma que la copia de trabajo afectada, las dependencias, las verificaciones y la base de datos de prueba desechable funcionen en la tarea nueva. Registra el commit inicial y los resultados de referencia de las pruebas.

Prepara la investigación inicial de modo que pueda realizarse con el material suministrado. Coloca un paquete sin datos sensibles en el repositorio o pon sus archivos a disposición de la tarea. Alguien del equipo de ingeniería debe armarlo y revisarlo antes de empezar:

No incluyas tokens de acceso, cargas útiles de clientes ni datos personales en el paquete.

La integración con un servicio de monitoreo es opcional. Si usas una, concede acceso de solo lectura al proyecto y al intervalo de tiempo pertinentes. El flujo basado en archivos no requiere esa integración. Las instrucciones del repositorio deben indicar que las credenciales de prueba se mantengan separadas de la configuración de producción.

Ejecuta el prompt inicial

Usa el prompt inicial de esta página y reemplaza sus marcadores de posición por el ID del incidente, el repositorio y la ruta del paquete. El primer resultado debe relacionar la evidencia con el código afectado, explicar qué se puede reproducir e identificar la información que falta.

Pide a Codex que continúe hasta implementar la corrección solo cuando la evidencia indique que hay un defecto en el código. De lo contrario, revisa la investigación y proporciona la información que falta. Una explicación plausible, un cambio reciente en el código o una prueba que pasó en otra versión no bastan para determinar la causa.

Ejemplo: el reintento de un webhook crea un pedido duplicado

Usa el ejemplo ejecutable del incidente para practicar la investigación. Incluye un paquete del incidente ya preparado, un manejador con un defecto reproducible, el manejador corregido y pruebas con PostgreSQL.

El servicio recibe un webhook order.created, guarda un pedido y registra que se procesó el evento. Durante un incidente, un reintento parece crear un segundo pedido. El equipo ya estabilizó el servicio y quiere revisar un parche.

El ejemplo usa JavaScript, el ejecutor de pruebas de Node.js y PostgreSQL. Su fixture desechable incluye una tabla event_receipts con columnas de identidad que no admiten valores nulos y una clave única no diferible sobre (provider, account_id, event_id).

El esquema permite reservar el evento mediante un registro de recepción antes de que exista el pedido. También conserva la huella de la carga útil canónica necesaria para detectar si se reutiliza la misma clave de evento con datos incompatibles.

Si tu aplicación exige una clave foránea del pedido al reservar el evento o carece de la evidencia necesaria para detectar ese conflicto, detente para que se tome por separado una decisión sobre el esquema o el diseño.

Incluye en la evidencia el entorno de ejecución exacto, las versiones fijadas de las dependencias, la versión de PostgreSQL, el nivel de aislamiento de las transacciones y el esquema de los registros de recepción. El fixture descargable fija las versiones de Node.js en 24.19.0, de PostgreSQL en 17.6 y de pg en 8.23.1.

Para usar la configuración de Compose incluida, prepara un entorno con el daemon de Docker en funcionamiento y comprueba que docker info se ejecute correctamente antes de publicar el entorno. La base de datos solo acepta credenciales públicas de prueba y escucha únicamente en la interfaz de loopback local. Al adaptar la prueba, usa el motor de base de datos de tu aplicación y los ajustes pertinentes.

Este ejemplo presupone que PostgreSQL usa READ COMMITTED, que los ID de evento del proveedor son estables y que los registros de recepción se conservan durante todo el período en que el proveedor puede reintentar o reenviar eventos.

El manejador corregido guarda el registro de recepción y el pedido en una misma transacción de base de datos. El fixture prepara una base de datos desechable y una tabla delivery_holds para simular el procedimiento de cuarentena de una cola existente. La tabla forma parte de la infraestructura de prueba y no se propone como migración de la aplicación.

La corrección de la aplicación no agrega ninguna cola, servicio de base de datos, migración de esquema ni integración de monitoreo. Si no se cumplen esos supuestos, detente y revisa el alcance.

Ejecuta el ejemplo

Extrae el ZIP, abre su directorio y usa Docker con 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

El comando de referencia debe terminar con el código 1: la aserción del reintento encuentra dos pedidos y un registro de recepción en lugar de uno de cada uno. El comando de regresión ejecuta la misma aserción con el manejador corregido y debe terminar con el código 0.

El último comando de prueba cubre toda la matriz de casos, incluidas las conexiones independientes, la contención por bloqueos en la base de datos y la cuarentena de pedidos anteriores sin registro de recepción.

Si tu instalación incluye docker-compose, usa ese comando en lugar de docker compose. Ejecuta los comandos en orden. El conjunto de pruebas solo restablece el esquema marcado para pruebas.

Inspecciona el manejador de transacciones

Este fragmento proviene del archivo main.mjs incluido en la descarga. Después de extraer el ZIP, ejecuta los archivos completos, que incluyen las pruebas y la configuración del 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. Proporciona un paquete compacto

Usa estos archivos como estructura del paquete:

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

En este escenario, release.json identifica la versión de ejemplo con el SHA 4a1c9e7d2b6f8a0c3d5e7f9012a4b6c8d0e2f413 y la fecha y hora de despliegue 2026-09-22T11:58:00Z. El incidente abarca el intervalo 12:03:00Z–12:05:00Z de ese mismo día. El paquete informa de dos pedidos internos asociados a un solo evento del proveedor. Al preparar tu propio paquete, incluye las cifras confirmadas del impacto e identifica las estimaciones.

Los logs sin datos sensibles contienen estas observaciones correlacionadas:

Mantén el mismo ID de evento en todas las entregas y usa ID de solicitud y de traza distintos para cada entrega. Un identificador por solicitud ocultaría la relación entre el reintento y el evento original.

2. Sigue el rastro de la evidencia y pon a prueba la hipótesis

El informe del incidente plantea que una avalancha de reintentos causó el duplicado. Codex debe tratar esa explicación como una hipótesis. Observar dos entregas no demuestra que haya habido una avalancha, y los reintentos son una situación normal que un manejador de webhooks debe tolerar.

Al inspeccionar el código afectado del ejemplo, se observa esta secuencia: se busca un registro de recepción, se confirma la transacción del pedido y luego se escribe el registro de recepción en una transacción aparte. El intervalo entre ambas confirmaciones ofrece una explicación más sólida. Si el proceso falla durante ese intervalo, puede quedar un pedido sin registro de recepción y un reintento puede crear otro pedido. Dos entregas simultáneas también pueden superar la verificación por separado antes de que alguna escriba su registro de recepción.

Pide a Codex que siga la ejecución del manejador real, identifique los límites de las transacciones y cite las líneas pertinentes. Debe confirmar que la versión indicada en el paquete coincide con el código que se prueba o explicar por qué probar otro commit limita la conclusión.

3. Reproduce el defecto antes de cambiar el manejador

Agrega una prueba de regresión con el webhook de ejemplo y la base de datos PostgreSQL aislada. En el manejador original, coloca un punto de inyección de fallas exclusivo para pruebas justo después de escribir el pedido y antes de escribir el registro de recepción.

Verifica, a partir de los límites reales de la transacción, que en ese punto ya se haya confirmado la escritura del pedido original. Reintenta con el mismo proveedor, cuenta y evento, y usa una aserción que exija exactamente un pedido y un registro de recepción coincidente. La prueba debe fallar con la implementación que contiene el defecto porque hay dos pedidos.

Después de la corrección, activa el punto de inyección correspondiente después de la sentencia que escribe el pedido, pero antes de confirmar la transacción compartida. El intento fallido debe dejar cero pedidos y cero registros de recepción.

Reintenta y verifica mediante una aserción que haya uno de cada uno. Mantén la misma aserción sobre el comportamiento de negocio en ambas revisiones y registra dónde inyectaste la falla en cada una.

Ejecuta primero la prueba nueva con la implementación original. Para el defecto introducido en este ejemplo, la falla esperada es que haya dos pedidos en lugar de uno. Guarda el comando, el commit inicial, el código de salida y el resultado de la aserción. Si no se produce esa falla, investiga la discrepancia antes de editar el manejador.

Inyectar una excepción pone a prueba el comportamiento transaccional de la aplicación. Deja constancia de que la prueba no reproduce todas las fallas posibles del host, la red o la base de datos.

4. Aplica la corrección mínima que respalde la evidencia

Para este defecto específico, reserva el evento insertando su registro de recepción y escribe el pedido en una sola transacción, con una sola conexión a la base de datos. Usa la clave única existente con INSERT ... ON CONFLICT (provider, account_id, event_id) DO NOTHING RETURNING ....

Solo la entrega que inserta el registro de recepción puede escribir el pedido. Responde con éxito solo después de confirmar la transacción. Si la transacción falla, se revierten ambas escrituras. No captures un error de unicidad para luego seguir usando una transacción abortada.

Una entrega concurrente puede tener que esperar a que termine la primera transacción. Si la primera se confirma, el segundo intento de reserva no inserta nada. Ejecuta un nuevo SELECT con READ COMMITTED, comprueba la identidad del evento y la carga útil según la política aplicable y los datos almacenados, y devuelve el acuse de duplicado existente sin escribir un pedido.

Si la primera transacción se revierte, la entrega concurrente puede reservar y procesar el evento. Si falta el registro de recepción después de omitir una inserción, hay un conflicto de identidad o se produce un error transitorio de base de datos, sigue el procedimiento documentado de reintento o de manejo de errores. No devuelvas una respuesta de éxito sin fundamento.

Con un aislamiento más estricto, las fallas de serialización requieren aplicar la política del repositorio que limita los reintentos de la transacción completa. Consulta la documentación de PostgreSQL sobre el comportamiento de INSERT ante conflictos y el aislamiento de transacciones.

Ni un conjunto en memoria ni una verificación separada del tipo “primero verificar y luego insertar” protegen frente a procesos de trabajo concurrentes o reinicios. Define el alcance de la clave según el contrato de identidad de eventos del proveedor. Si un evento supuestamente idéntico contiene datos de identidad o una carga útil incompatibles, haz visible la inconsistencia en vez de tratarlo en silencio como un duplicado válido.

En el ejemplo, toda la operación que modifica los datos de negocio ocurre en la misma base de datos. Si el manejador real también envía correos, realiza cargos a una tarjeta o llama a otro servicio, esta transacción por sí sola no hace que esos efectos externos sean idempotentes. Antes de ampliar la corrección, identifica ese límite y el mecanismo de entrega o idempotencia que ya usa el sistema.

5. Verifica el comportamiento tras el cambio

Solicita tanto el resultado fallido original como el resultado posterior a la corrección. Usa puntos de inyección exclusivos para pruebas en límites de transacción identificados e inspecciona el estado confirmado desde otra conexión. El ejemplo pasa once pruebas locales con PostgreSQL. El archivo test-evidence.md de la descarga documenta esos resultados y las verificaciones pendientes para la ejecución en la nube y el despliegue. Ejecuta el conjunto de pruebas en tu entorno publicado y prueba una pérdida real de conexión durante la confirmación antes de confiar en ese mecanismo de recuperación.

Coordina la concurrencia con barreras o mecanismos de sincronización tipo latch y tiempos de espera limitados. Evita las pausas de duración fija o el simple uso de dos promesas. Libera los procesos bloqueados durante la limpieza de la prueba y usa fixtures desechables. Una prueba con una excepción no demuestra por sí sola cómo se comporta el sistema ante la terminación abrupta de un proceso, una falla de transporte o la concurrencia en producción.

El ejemplo usa node main.mjs baseline, node main.mjs regression y node main.mjs dentro del entorno de ejecución con versiones fijas. La salida estructurada registra los límites de las transacciones, la cantidad de filas confirmadas, el código de estado y el cuerpo del acuse, y los ID observados de los procesos de la base de datos que causaron bloqueos.

Al adaptar el flujo, usa los comandos que realmente define tu repositorio e informa de sus resultados reales. Incluye en la entrega cualquier verificación omitida o dependencia no disponible e indica cómo afecta la confianza en los resultados.

Revisa la entrega

Registro compartido de evidencia

Usa el formato de evidencia del flujo de incidentes para cada criterio de aceptación. Complétalo con los resultados observados. Los campos siguientes son una plantilla y no indican que las pruebas hayan pasado. Si una prueba nueva no existía en la versión de referencia, distingue entre “aún no existía” y una verificación existente que falló.

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]

Vincula las ejecuciones fallidas y exitosas con los estados exactos que se probaron, incluidos los cambios exclusivos de prueba aplicados a la revisión original. Incluye en la entrega los logs, los fixtures de respuesta y el diff final. Si cambia la revisión final, actualiza la evidencia. Las verificaciones bloqueadas o no ejecutadas no pueden contar como exitosas.

Pide a Codex que deje el diff del código y estos archivos para revisión en el repositorio:

• incident-investigation.md: cronología, referencias a la evidencia, hipótesis evaluadas, causa respaldada por la evidencia e incertidumbres pendientes.
• test-evidence.md: commit de referencia, salida de la prueba de regresión fallida, commit o diff de la corrección, verificaciones específicas que pasaron, verificaciones generales y limitaciones.
• pr-draft.md: explicación concisa del defecto, del cambio de comportamiento, de la evidencia de las pruebas y del riesgo restante.
• deployment-handoff.md: supuestos verificados sobre el esquema, el aislamiento y la retención de los registros de recepción, nombre de la persona responsable del despliegue, verificaciones previas al despliegue, métricas de pedidos duplicados, acuses y errores, y las condiciones para continuar o revertir el despliegue que se indican a continuación.

Antes de aceptar el parche, verifica que el código original falle en la prueba nueva, que el código corregido la pase y que el diff resuelva el defecto demostrado. En el ejemplo del webhook, revisa el alcance de la clave de evento, los límites de las transacciones, la cobertura de concurrencia y los posibles efectos fuera de la transacción. Revisa por separado los pedidos duplicados existentes. Evitar nuevos duplicados no corrige los registros históricos.

Planifica el despliegue y la reversión

El parche solo protege a los procesos de trabajo que ejecutan el manejador corregido. Los procesos antiguos aún pueden escribir un pedido antes de reservar el evento mediante un registro de recepción. Por eso, un despliegue canario con versiones distintas no demuestra que se haya eliminado el defecto.

La persona responsable del despliegue debe elegir entre una estrategia probada de coexistencia de versiones y un procedimiento operativo existente que pause la recepción de eventos, permita que los procesos antiguos terminen el trabajo en curso, actualice todos los consumidores y reanude las entregas retenidas sin pérdidas.

Antes de elegir la segunda opción, confirma cómo gestionan los reintentos y la retención tanto el proveedor como la cola. No des por hecho que se puede pausar sin perder entregas.

Antes de reanudar las entregas retenidas, identifica los pedidos anteriores confirmados que no tengan un registro de recepción coincidente. Pausar los consumidores antiguos y dejar que terminen el trabajo en curso evita nuevas escrituras de la versión anterior, pero no corrige los pedidos existentes. Bloquea todas las claves de evento afectadas mediante la cola existente o el procedimiento de cuarentena. Si los registros anteriores no permiten establecer la identidad completa de un evento, mantén en pausa las entregas afectadas o las del intervalo afectado para que las revise la persona responsable, en vez de dar por terminada la inspección.

Concilia una clave bloqueada solo cuando la identidad inmutable y confiable del proveedor, la cuenta y el evento, junto con la evidencia de la carga útil canónica y el registro de negocio confirmado, permitan establecer qué ocurrió.

Sigue el procedimiento de conciliación aprobado para guardar el registro de recepción coincidente sin repetir la operación que modifica los datos de negocio. Luego desbloquea esa clave.

Si falta evidencia, las cargas útiles son incompatibles o existen varios registros de negocio, mantén las claves afectadas en cuarentena para que las revise la persona responsable. Al reconstruir la huella del evento original, la carga útil de un reintento no puede sustituir la evidencia confiable de ese evento.

Solo se cumple la condición para reanudar el procesamiento cuando cada clave afectada se haya conciliado o siga bloqueada en todos los consumidores.

Prepara un pedido de la versión anterior y su reintento pendiente en el entorno de preproducción. Verifica que el bloqueo impida crear otro pedido y devolver un acuse de éxito. Tras una conciliación con evidencia confiable, el reintento puede recibir el acuse de duplicado mientras la cantidad de pedidos existentes se mantiene en uno. Ensaya también un caso sin resolver: debe seguir bloqueado sin que se invente un registro de recepción. Incluye esta condición en la entrega para el despliegue, junto con las verificaciones de pausa y finalización del trabajo en curso, versiones de los consumidores, retención y reversión.

Antes del despliegue, verifica que la restricción de unicidad existente esté presente y sea válida, que todos los consumidores apliquen la misma política para la clave y la carga útil del registro de recepción, que la limpieza de esos registros no vuelva a permitir el procesamiento de eventos reenviados y que los efectos externos sigan fuera del alcance del parche.

En preproducción, ensaya la secuencia elegida y el reintento tras la falla de un proceso de trabajo. Registra el período de observación y los umbrales que defina la persona responsable para detener el despliegue según los pedidos duplicados, los errores del webhook, la latencia de los acuses, las esperas por bloqueos y los reintentos acumulados. No inventes umbrales de producción.

Volver al manejador anterior puede hacer que se vuelvan a crear pedidos duplicados. La documentación de reversión debe especificar la medida de contención (por ejemplo, el procedimiento aprobado de pausa y finalización del trabajo en curso), la revisión segura y quién decide cuándo se puede reanudar el procesamiento. Conserva los registros de recepción. No los elimines para desbloquear los reintentos. La corrección de los pedidos duplicados históricos requiere una revisión por separado.

La persona responsable de ingeniería decide si se despliega el cambio y se encarga de cualquier corrección en producción. Una prueba aislada exitosa aporta evidencia para la revisión, pero no demuestra que el servicio funcione correctamente en producción. Crea el pull request, sigue tu proceso habitual de CI y revisión y, después de revisar el borrador, despliega el cambio mediante los controles establecidos por tu equipo.

Continúa en la misma tarea

Usa un prompt de seguimiento específico para resolver dudas o mejorar la entrega:

Revisa cómo se comporta el parche ante dos entregas concurrentes y ante un reintento después de que falle un proceso de trabajo. Muestra qué comportamientos demuestran las pruebas y cuáles quedan por probar. Limita el cambio a este manejador y a sus pruebas de regresión. Actualiza la documentación de la entrega con los riesgos pendientes.

Si no se pudo reproducir el incidente en la primera ejecución:

Detén la implementación. Enumera las hipótesis que la evidencia permite descartar e identifica la hipótesis restante con mayor respaldo. Indica qué dato adicional sin información sensible o qué experimento aislado bastaría, como mínimo, para distinguir esa hipótesis de las demás. Deja la causa raíz sin confirmar.