Confiez à Codex l’analyse d’un incident bien délimité dans un environnement cloud préparé à cet effet. L’objectif est de fournir à un ingénieur une explication étayée, un test de régression qui échoue avant la correction, un correctif ciblé et les résultats des tests exécutés pour qu’il puisse les examiner.

Cette démarche convient lorsque la situation est stabilisée et qu’il reste à comprendre et à corriger un défaut de l’application. Si les éléments disponibles ne permettent pas d’établir la cause, un compte rendu clair de l’enquête et la prochaine étape du diagnostic constituent un résultat utile.

Préparez l’environnement et le dossier d’incident

1. Dans l’application web ou l’application de bureau ChatGPT, choisissez Travailler dans > Cloud, puis sélectionnez un environnement publié.

2. Pour en créer un, sélectionnez Créer un environnement, choisissez les dépôts GitHub et demandez à Codex de préparer l’environnement d’exécution, les dépendances et les services de test isolés.

3. Examinez le rapport de configuration, corrigez les problèmes signalés par les vérifications en échec, puis sélectionnez Publier avant de lancer une nouvelle tâche.

• Suivez le guide à jour des environnements cloud.
• Consignez les instructions du dépôt dans AGENTS.md.

Si les dépendances ou la configuration des services changent, modifiez l’environnement réutilisable, testez-le et sélectionnez Republier. Validez ensuite l’environnement mis à jour dans une nouvelle tâche.

L’actualisation du dépôt ne relance pas les commandes d’installation ou de démarrage. Les tâches existantes conservent leur propre état.

Configurez séparément les destinations réseau requises et les identifiants de test. Autoriser une destination ne donne pas accès au service.

Dans la nouvelle tâche, vérifiez que la copie de travail concernée, les dépendances, les vérifications et la base de données de test jetable sont opérationnelles. Consignez le commit de départ et les résultats de référence des tests.

Réunissez tout le nécessaire pour la première phase de l’enquête. Placez dans le dépôt un dossier expurgé des données sensibles ou rendez ses fichiers accessibles à la tâche. Avant de commencer, un ingénieur doit constituer et vérifier ce dossier.

N’incluez dans le dossier aucun jeton d’accès, aucune charge utile provenant d’un client ni aucune donnée personnelle.

L’intégration d’un outil de supervision est facultative. Si vous en utilisez un, accordez un accès en lecture seule limité au projet et à la plage horaire concernés. Le workflow fondé sur les fichiers fonctionne sans cette intégration. Les instructions du dépôt doivent prévoir de séparer les identifiants de test de la configuration de production.

Exécutez le prompt de départ

Utilisez le prompt de départ de cette page et remplacez les paramètres fictifs par l’identifiant de votre incident, votre dépôt et le chemin du dossier. Le premier résultat doit relier les observations au code concerné, expliquer ce qui est reproductible et préciser les informations manquantes.

Demandez à Codex de passer à la correction uniquement si les observations étayent l’existence d’un défaut dans le code. Sinon, examinez le compte rendu et fournissez les éléments manquants. Une explication plausible, une modification récente du code ou un test réussi sur une autre version ne suffisent pas à établir la cause.

Exemple : une nouvelle tentative de livraison d’un webhook crée une commande en double

Entraînez-vous à mener l’enquête avec cet exemple d’incident exécutable. Il comprend un dossier d’incident prêt à l’emploi, un gestionnaire présentant un défaut reproductible, sa version corrigée et des tests PostgreSQL.

Le service reçoit un webhook order.created, écrit une commande et enregistre que l’événement a été traité. Lors d’un incident, une nouvelle tentative de livraison semble créer une deuxième commande. L’équipe a déjà stabilisé le service et souhaite examiner un correctif.

L’exemple utilise JavaScript, l’exécuteur de tests de Node.js et PostgreSQL. Son dispositif de test jetable comporte une table event_receipts dont les colonnes d’identification interdisent les valeurs nulles et dont la contrainte d’unicité sur (provider, account_id, event_id) est non différable.

Le schéma permet de réserver l’événement en insérant un reçu avant que la commande existe. Il conserve l’empreinte canonique de la charge utile nécessaire pour détecter la réutilisation de la même clé d’événement avec des données incompatibles.

Si votre application exige une clé étrangère vers la commande dès la réservation ou ne conserve pas les éléments nécessaires pour détecter ces conflits, arrêtez-vous pour traiter séparément cette question de schéma ou de conception.

Consignez la version exacte de l’environnement d’exécution, les versions verrouillées des dépendances, la version de PostgreSQL, le niveau d’isolation des transactions et le schéma des reçus. L’exemple téléchargeable fixe les versions de Node.js à 24.19.0, de PostgreSQL à 17.6 et de pg à 8.23.1.

Pour la configuration Compose fournie, préparez un environnement doté d’un démon Docker opérationnel et vérifiez que docker info s’exécute correctement avant de publier l’environnement. La base de données accepte uniquement les identifiants de test publics et n’écoute que sur l’interface de bouclage locale. Lorsque vous adaptez le test, utilisez le moteur de base de données de votre application et ses paramètres pertinents.

Cet exemple suppose que PostgreSQL utilise le niveau d’isolation READ COMMITTED, que le fournisseur attribue des identifiants stables aux événements et que les reçus sont conservés pendant toute la période où le fournisseur peut retenter ou rejouer une livraison.

Le gestionnaire corrigé écrit le reçu et la commande dans une seule transaction. Le dispositif de test crée une base de données jetable et une table delivery_holds qui simule la procédure de mise en quarantaine d’une file d’attente existante. Cette table sert aux tests et ne fait pas partie d’une proposition de migration de l’application.

Le correctif applicatif n’ajoute ni file d’attente, ni service de base de données, ni migration de schéma, ni intégration de supervision. Si ces hypothèses ne se vérifient pas, arrêtez-vous et redéfinissez le périmètre.

Exécutez l’exemple

Décompressez l’archive ZIP, ouvrez le répertoire extrait et utilisez Docker avec 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

La commande de référence doit se terminer avec le code 1 : après la nouvelle tentative, l’assertion relève deux commandes et un reçu alors qu’elle attend une commande et un reçu. La commande de régression vérifie la même assertion sur le gestionnaire corrigé et doit se terminer avec le code 0.

La dernière commande de test couvre l’ensemble des scénarios, notamment les connexions indépendantes, la contention sur les verrous de la base de données et la mise en quarantaine des anciennes commandes sans reçu.

Si votre installation fournit docker-compose, utilisez cette graphie à la place de docker compose. Exécutez ces commandes dans l’ordre, l’une après l’autre. La suite de tests réinitialise uniquement le schéma qu’elle a marqué comme schéma de test.

Examinez le gestionnaire de transaction

Cet extrait provient du fichier main.mjs de l’archive. Une fois l’archive ZIP décompressée, exécutez les fichiers complets. Ils contiennent les tests et la configuration du dispositif de test.

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. Fournissez un dossier succinct

Utilisez ces fichiers comme trame du dossier :

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

Dans ce scénario, release.json indique que la version de l’exemple correspond au SHA 4a1c9e7d2b6f8a0c3d5e7f9012a4b6c8d0e2f413 et a été déployée à 2026-09-22T11:58:00Z. L’incident couvre la plage 12:03:00Z–12:05:00Z le même jour. Le dossier signale deux commandes internes associées à un seul événement du fournisseur. Dans votre propre dossier, chiffrez l’impact confirmé et indiquez quels chiffres sont des estimations.

Les journaux expurgés contiennent les observations corrélées suivantes :

Conservez le même identifiant d’événement d’une livraison à l’autre et attribuez à chaque livraison des identifiants de requête et de trace distincts. Un identifiant propre à la requête masquerait le lien entre la nouvelle tentative et l’événement initial.

2. Remontez des observations au code et testez l’hypothèse

Le rapport d’incident avance qu’un afflux massif de nouvelles tentatives a provoqué le doublon. Codex doit traiter cette explication comme une hypothèse. Observer deux livraisons ne suffit pas à établir un afflux massif. Les nouvelles tentatives font partie du fonctionnement normal qu’un gestionnaire de webhook doit prendre en charge.

Dans la version défectueuse de l’exemple, l’examen du code source révèle que le gestionnaire recherche un reçu, valide la transaction qui écrit la commande, puis écrit le reçu dans une transaction distincte. L’intervalle entre les deux validations fournit une explication mieux étayée. Si le processus s’arrête pendant cet intervalle, la commande peut rester sans reçu et une nouvelle tentative peut en créer une autre. Deux livraisons concurrentes peuvent également franchir chacune la vérification avant que l’une ou l’autre écrive son reçu.

Demandez à Codex de suivre le chemin réellement emprunté dans le gestionnaire, de repérer les limites des transactions et de citer les lignes pertinentes. Codex doit confirmer que la version indiquée dans le dossier correspond au code testé ou expliquer en quoi un test sur un autre commit limite les conclusions.

3. Reproduisez le défaut avant de modifier le gestionnaire

Ajoutez un test de régression qui utilise le webhook de l’exemple et la base PostgreSQL isolée. Dans le gestionnaire d’origine, prévoyez un point d’injection de panne réservé aux tests immédiatement après l’écriture de la commande et avant celle du reçu.

Vérifiez, d’après les limites réelles des transactions, que la transaction de la commande initiale a bien été validée à ce stade. Retentez la livraison avec les mêmes fournisseur, compte et événement. Vérifiez par une assertion qu’il existe exactement une commande et un reçu correspondant. Avec le défaut introduit dans l’exemple, le test doit échouer en comptant deux commandes.

Après la correction, déclenchez la panne au point correspondant, après l’instruction qui écrit la commande mais avant la validation de la transaction commune. La tentative en échec doit laisser la base sans commande ni reçu.

Retentez la livraison et vérifiez qu’il existe une commande et un reçu. Conservez la même assertion métier d’une révision à l’autre et consignez l’emplacement du point d’injection dans chacune.

Exécutez d’abord le nouveau test sur la version d’origine. Pour le défaut introduit dans cet exemple, l’échec attendu est la présence de deux commandes au lieu d’une. Conservez la commande de test, le commit de départ, le code de sortie et le résultat de l’assertion. Si vous n’observez pas cet échec, cherchez la raison de l’écart avant de modifier le gestionnaire.

L’injection d’une exception permet de tester le comportement transactionnel de l’application. Précisez qu’elle ne reproduit pas toutes les pannes possibles de l’hôte, du réseau ou de la base de données.

4. Apportez la correction minimale justifiée par les observations

Pour ce défaut précis, réservez l’événement en insérant son reçu et écrivez la commande dans une même transaction sur une seule connexion à la base de données. Utilisez la clé unique existante avec INSERT ... ON CONFLICT (provider, account_id, event_id) DO NOTHING RETURNING ....

Seule la livraison qui insère le reçu peut écrire la commande. Ne renvoyez un accusé de réception positif qu’après la validation de la transaction. En cas d’échec, la transaction annule les deux écritures. Si vous interceptez une erreur d’unicité, ne continuez pas à utiliser la transaction interrompue.

Une livraison concurrente peut devoir attendre la fin de la première transaction. Si celle-ci est validée, la deuxième tentative de réservation n’insère rien. Exécutez un nouveau SELECT au niveau READ COMMITTED, vérifiez l’identité enregistrée de l’événement et le respect de la règle applicable à sa charge utile, puis renvoyez l’accusé de réception prévu pour les doublons sans écrire de commande.

Si la première transaction est annulée, la livraison concurrente peut réserver et traiter l’événement. Si le reçu est absent après une insertion ignorée, si les identités sont incompatibles ou si une erreur transitoire de base de données survient, suivez la procédure documentée de nouvelle tentative ou de traitement des erreurs. Ne signalez pas un succès fictif.

Avec un niveau d’isolation plus strict, les échecs de sérialisation nécessitent de relancer la transaction entière, dans les limites prévues par le dépôt. Consultez la documentation PostgreSQL sur le comportement d’INSERT en cas de conflit et l’isolation des transactions.

Ni un ensemble conservé en mémoire ni une séquence « vérifier puis insérer » en deux opérations distinctes ne protègent contre les traitements concurrents ou les redémarrages. Définissez la portée de la clé selon les règles d’identification des événements du fournisseur. Si un événement supposé identique contient une identité ou une charge utile incompatible, signalez l’incohérence au lieu de le traiter silencieusement comme un doublon valide.

Dans la démonstration, la modification des données métier se fait intégralement dans la même base de données. Si le gestionnaire réel envoie aussi un e-mail, débite une carte ou appelle un autre service, la transaction seule ne rend pas ces effets externes idempotents. Avant d’élargir le correctif, repérez cette limite et identifiez le mécanisme de livraison ou d’idempotence déjà en place dans le système.

5. Vérifiez le comportement après correction

Demandez à voir l’échec initial et le résultat après correction. Utilisez des points d’injection réservés aux tests à des étapes précisément identifiées de la transaction et examinez l’état validé depuis une connexion distincte. L’exemple réussit onze tests PostgreSQL en local. Le fichier test-evidence.md de l’archive consigne leurs résultats et les vérifications qui restent à effectuer pour l’exécution dans le Cloud et le déploiement. Exécutez la suite dans votre environnement publié et testez une perte réelle de connexion pendant la validation avant de vous fier à ce mécanisme de reprise.

Coordonnez les traitements concurrents au moyen de barrières ou de mécanismes de synchronisation à déclenchement et fixez des délais d’attente maximaux. De simples temporisations ou une paire de promesses ne suffisent pas. Libérez les processus bloqués lors du nettoyage en fin de test et utilisez des dispositifs de test jetables. Un test par injection d’exception ne suffit pas à établir le comportement en cas d’arrêt brutal d’un processus, de perte de connexion ou de traitements concurrents en production.

L’exemple exécute node main.mjs baseline, node main.mjs regression et node main.mjs dans un environnement d’exécution dont les versions sont fixées. Sa sortie structurée consigne les limites des transactions, le nombre de lignes validées, le statut et le corps des accusés de réception ainsi que les identifiants des processus PostgreSQL observés qui bloquent les autres.

Lorsque vous adaptez le workflow, utilisez les commandes effectivement définies dans votre dépôt et rapportez leurs résultats réels. Dans le dossier de transmission, signalez toute vérification omise ou dépendance indisponible et précisez en quoi cela limite la confiance dans les résultats.

Examinez le dossier de transmission

Relevé commun des résultats

Pour chaque critère d’acceptation, utilisez le format de relevé prévu par le workflow d’incident. Remplissez-le à partir des sorties observées. Les champs ci-dessous constituent un modèle et ne préjugent pas de la réussite des tests. Si un nouveau test n’existait pas dans la version de référence, distinguez « test encore absent » de l’échec d’une vérification existante.

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]

Associez chaque exécution en échec ou réussie à l’état exact du code testé, y compris les modifications limitées aux tests appliquées à la révision d’origine. Joignez les journaux, les données de réponse utilisées pour les tests et le diff final au dossier de transmission. Si la révision finale change, actualisez les résultats. Une vérification bloquée ou non exécutée ne peut pas compter comme réussie.

Demandez à Codex de laisser le diff du code et les documents suivants dans le dépôt pour la revue :

• incident-investigation.md : chronologie, références aux éléments observés, hypothèses testées, cause étayée et incertitudes restantes.
• test-evidence.md : commit de référence, sortie du test de régression en échec, commit ou diff du correctif, vérifications ciblées réussies, vérifications plus larges et limites.
• pr-draft.md : explication concise du défaut, du changement de comportement, des résultats des tests et du risque résiduel.
• deployment-handoff.md : hypothèses vérifiées sur le schéma, l’isolation et la conservation des reçus, nom du responsable du déploiement, vérifications préalables, métriques sur les commandes en double, les accusés de réception et les erreurs, ainsi que les conditions de déploiement et de retour arrière décrites ci-dessous.

Avant d’accepter le correctif, vérifiez que le nouveau test échoue sur le code d’origine, qu’il réussit après correction et que le diff traite le défaut démontré. Dans l’exemple du webhook, examinez la portée de la clé d’événement, les limites des transactions, la couverture des scénarios de concurrence et les éventuels effets hors transaction. Examinez séparément les commandes déjà en double. Empêcher de nouveaux doublons ne corrige pas les données historiques.

Planifiez le déploiement et le retour arrière

Le correctif ne protège que les processus qui exécutent le gestionnaire corrigé. Les anciens processus peuvent encore écrire une commande avant de réserver l’événement par insertion du reçu. Un déploiement canari où coexistent plusieurs versions ne prouve donc pas que le défaut est éliminé.

Le responsable du déploiement doit choisir entre une stratégie testée de coexistence des versions et une procédure existante qui suspend l’ingestion, laisse les anciens processus terminer les traitements en cours, met à jour tous les consommateurs, puis reprend sans perte le traitement des livraisons conservées.

Avant de choisir cette dernière option, vérifiez comment le fournisseur et la file d’attente gèrent les nouvelles tentatives et la conservation des livraisons. Ne présumez pas qu’une suspension est sans perte.

Avant de reprendre le traitement des livraisons conservées, repérez les anciennes commandes validées sans reçu correspondant. Suspendre les anciens consommateurs et les laisser terminer leurs traitements empêche de nouvelles écritures par l’ancienne version, mais ne corrige pas les commandes existantes. Bloquez chaque clé d’événement concernée à l’aide de la file d’attente ou de la procédure de quarantaine existante. Si les données historiques ne permettent pas d’établir l’identité complète d’un événement, maintenez la suspension des livraisons concernées ou de celles de la plage horaire touchée pour que le responsable les examine. Ne déclarez pas l’analyse terminée.

Ne procédez au rapprochement d’une clé bloquée que si des identifiants fiables et immuables du fournisseur, du compte et de l’événement, des éléments attestant la charge utile canonique et l’enregistrement métier validé permettent d’établir ce qui a déjà été effectué.

Suivez la procédure de rapprochement approuvée pour enregistrer le reçu correspondant sans répéter l’opération métier, puis débloquez la clé.

Maintenez les clés concernées en quarantaine pour examen par le responsable si des éléments manquent, si les charges utiles sont incompatibles ou si plusieurs enregistrements métier existent. Pour reconstituer l’empreinte de l’événement initial, la charge utile d’une nouvelle tentative ne peut pas remplacer des données fiables sur cet événement.

La reprise n’est autorisée que si chaque clé concernée a fait l’objet d’un rapprochement ou reste effectivement bloquée pour tous les consommateurs.

En préproduction, insérez une ancienne commande et préparez une nouvelle tentative de livraison en attente. Vérifiez que le blocage empêche à la fois la création d’une autre commande et l’envoi d’un accusé de réception positif. Après rapprochement à partir de données fiables, la nouvelle tentative peut recevoir l’accusé de réception prévu pour les doublons et le nombre de commandes doit rester égal à un. Testez également un cas non résolu : il doit rester bloqué sans qu’un reçu soit créé de toutes pièces. Consignez cette condition de reprise dans le dossier de déploiement avec les vérifications portant sur la suspension et la fin des traitements en cours, la version des consommateurs, la conservation des livraisons et le retour arrière.

Avant le déploiement, vérifiez que la contrainte d’unicité existante est présente et valide, que tous les consommateurs appliquent les mêmes règles à la clé du reçu et à la charge utile, que la purge des reçus ne permet pas de traiter à nouveau un événement encore susceptible d’être rejoué et que les effets externes restent hors du périmètre du correctif.

En préproduction, répétez la séquence retenue et testez une nouvelle tentative après la panne d’un processus. Consignez la période d’observation retenue par le responsable et les seuils d’arrêt applicables aux commandes en double, aux erreurs de webhook, au délai d’accusé de réception, aux attentes de verrou et au nombre de nouvelles tentatives en attente. N’inventez pas de seuils pour la production.

Revenir à l’ancien gestionnaire peut réintroduire des commandes en double. Les consignes de retour arrière doivent préciser la mesure de confinement, par exemple la procédure approuvée de suspension et de fin des traitements en cours, la révision sûre et le nom du responsable qui décide de la reprise. Conservez les reçus. Ne les supprimez pas pour débloquer les nouvelles tentatives. La correction des commandes historiques en double doit faire l’objet d’une revue distincte.

La décision de déploiement et toute intervention corrective en production relèvent de l’ingénieur. Un test isolé réussi fournit un élément pour la revue, mais ne prouve pas le bon fonctionnement de la production. Après avoir examiné le brouillon, créez la pull request, suivez votre processus habituel d’intégration continue et de revue de code, puis déployez en appliquant les contrôles établis par votre équipe.

Poursuivez dans la même tâche

Utilisez un prompt de suivi ciblé pour lever une incertitude ou compléter le dossier de transmission :

Examinez le correctif dans deux situations : deux livraisons concurrentes et une nouvelle tentative après la panne d’un processus de traitement. Indiquez quels comportements les tests établissent et lesquels restent à tester. Limitez les modifications à ce gestionnaire et à ses tests de régression. Consignez tout risque résiduel dans le dossier de transmission.

Si la première exécution n’a pas permis de reproduire l’incident :

Arrêtez la mise en œuvre du correctif. Énumérez les hypothèses que les observations permettent d’écarter. Indiquez l’hypothèse restante la mieux étayée et précisez le minimum de données supplémentaires expurgées ou l’expérience isolée la plus simple qui permettrait de la distinguer des autres. Laissez la cause première non confirmée.