Anwendungsfall für Codex
Einen Vorfall untersuchen und die Fehlerbehebung testen
Reproduziere den Fehler anhand der Unterlagen zum Vorfall, erstelle einen gezielten Patch und dokumentiere die Ergebnisse so, dass dein Team sie prüfen kann.
Stelle Codex Cloud bereinigte Unterlagen zum Vorfall und eine funktionsfähige Testumgebung bereit. Prüfe die Belege. Wenn sie auf einen Codefehler hindeuten, reproduziere ihn. Übergib einen gezielten Patch mit den Ergebnissen des Regressionstests und einer Anleitung für Deployment und Rollback.
Besonders geeignet für
- Kleine Entwicklungsteams, die einen Vorfall untersuchen, nachdem sich die Lage stabilisiert hat.
- Anwendungsfehler, für die bereinigte Belege und sichere Eingabedaten zur Reproduktion vorliegen.
- Teams, die eine gezielte Fehlerbehebung in einer funktionsfähigen, isolierten Testumgebung prüfen.
Inhalt
Einen Vorfall untersuchen und die Fehlerbehebung testen
Reproduziere den Fehler anhand der Unterlagen zum Vorfall, erstelle einen gezielten Patch und dokumentiere die Ergebnisse so, dass dein Team sie prüfen kann.
Stelle Codex Cloud bereinigte Unterlagen zum Vorfall und eine funktionsfähige Testumgebung bereit. Prüfe die Belege. Wenn sie auf einen Codefehler hindeuten, reproduziere ihn. Übergib einen gezielten Patch mit den Ergebnissen des Regressionstests und einer Anleitung für Deployment und Rollback.
Stelle Codex Cloud bereinigte Unterlagen zum Vorfall und eine funktionsfähige Testumgebung bereit. Prüfe die Belege. Wenn sie auf einen Codefehler hindeuten, reproduziere ihn. Übergib einen gezielten Patch mit den Ergebnissen des Regressionstests und einer Anleitung für Deployment und Rollback.
Weiterführende Links
Besonders geeignet für
- Kleine Entwicklungsteams, die einen Vorfall untersuchen, nachdem sich die Lage stabilisiert hat.
- Anwendungsfehler, für die bereinigte Belege und sichere Eingabedaten zur Reproduktion vorliegen.
- Teams, die eine gezielte Fehlerbehebung in einer funktionsfähigen, isolierten Testumgebung prüfen.
Prompt für den Einstieg
Lass Codex einen klar abgegrenzten Vorfall in einer vorbereiteten Cloud-Umgebung untersuchen. Das Engineering-Team soll das Ergebnis prüfen können. Dazu gehören eine durch Befunde gestützte Erklärung, ein Regressionstest, der vor der Korrektur fehlschlägt, ein gezielter Patch und die Ergebnisse der tatsächlich ausgeführten Tests.
Dieses Vorgehen eignet sich, wenn der Betrieb bereits stabilisiert ist und du noch einen Anwendungsfehler verstehen und beheben musst. Lässt sich die Ursache anhand der verfügbaren Befunde nicht feststellen, sind auch eine nachvollziehbare Beschreibung der Untersuchung und der nächste Diagnoseschritt ein brauchbares Ergebnis.
Umgebung und Unterlagen zum Vorfall vorbereiten
-
Wähle in der Web- oder Desktop-App Arbeiten in > Cloud und dann eine veröffentlichte Umgebung.
-
Um eine Umgebung zu erstellen, wähle Umgebung erstellen, wähle die GitHub-Repositorys aus und bitte Codex, die Laufzeitumgebung, die Abhängigkeiten und die isolierten Testdienste vorzubereiten.
-
Prüfe den Setup-Bericht, behebe die Ursachen fehlgeschlagener Prüfungen und wähle Veröffentlichen, bevor du eine neue Aufgabe startest.
- Folge der aktuellen Anleitung für Cloud-Umgebungen.
- Halte die Anweisungen für das Repository in AGENTS.md fest.
Wenn sich Abhängigkeiten oder die Konfiguration der Dienste ändern, bearbeite und teste die wiederverwendbare Umgebung. Wähle Erneut veröffentlichen und prüfe die aktualisierte Umgebung anschließend in einer neuen Aufgabe.
Beim Aktualisieren des Repositorys werden die Installations- und Startbefehle nicht erneut ausgeführt. Bestehende Aufgaben behalten ihren jeweiligen Zustand.
Konfiguriere die erforderlichen Netzwerkziele und Testzugangsdaten separat. Die Freigabe eines Netzwerkziels gewährt noch keinen Zugriff auf den Dienst.
Vergewissere dich in der neuen Aufgabe, dass der betroffene Checkout, die Abhängigkeiten, die Prüfungen und die temporäre Testdatenbank funktionieren. Dokumentiere den Ausgangs-Commit und die Testergebnisse vor der Änderung.
Stelle alle Unterlagen für die erste Untersuchung zusammen. Lege das bereinigte Paket im Repository ab oder stelle seine Dateien der Aufgabe zur Verfügung. Vor dem Start sollte jemand aus dem Engineering-Team das Paket zusammenstellen und prüfen.
| Unterlage | Inhalt |
|---|---|
| Zusammenfassung des Vorfalls | Vorfalls-ID, Zeitfenster in UTC, erwartetes und beobachtetes Verhalten, bekannte Auswirkungen und aktueller Status. Unterscheide bestätigte Zahlen von Schätzungen. |
| Angaben zum Release | Commit-SHA der bereitgestellten Version, Zeitpunkt der Bereitstellung, relevante Konfigurationswerte ohne Geheimnisse und, sofern bekannt, das letzte fehlerfreie Release. |
| Zusammengehörige Befunde | Log- und Trace-Auszüge mit Zeitstempeln, Ereignis-IDs, Anfrage-IDs, Trace-IDs und Dateiverweisen. Achte beim Bereinigen darauf, dass die Kennungen konsistent bleiben. |
| Sichere Reproduktion | Anfrageinhalte für Tests, relevante Test-Fixtures und Anweisungen, um den verdächtigen Codepfad ohne Aufrufe an produktive Dienste auszuführen. |
| Hinweise zum Repository | Relevante Pfade, Datenbanksystem, Testbefehle, zulässige Änderungen und die Person aus dem Engineering-Team, die das Ergebnis prüft. |
Das Paket darf keine Zugriffstoken, Nutzdaten aus Kundenanfragen oder personenbezogenen Daten enthalten.
Eine Monitoring-Integration ist optional. Wenn du eine verwendest, erteile ihr eine Berechtigung ohne Schreibzugriff und beschränke sie auf das relevante Projekt und Zeitfenster. Für den dateibasierten Ablauf brauchst du die Integration nicht. Die Anweisungen im Repository sollten vorgeben, dass Testzugangsdaten getrennt von der Produktivkonfiguration bleiben.
Start-Prompt ausführen
Verwende den Start-Prompt auf dieser Seite und ersetze die Platzhalter durch deine Vorfalls-ID, dein Repository und den Pfad zum Paket. Das erste Ergebnis sollte die Befunde mit dem betroffenen Code in Verbindung bringen, erklären, was sich reproduzieren lässt, und fehlende Informationen benennen.
Bitte Codex erst dann, die Korrektur umzusetzen, wenn die Befunde auf einen Codefehler schließen lassen. Prüfe andernfalls die Untersuchung und stelle die fehlenden Informationen bereit. Eine plausible Erklärung, eine kürzliche Codeänderung oder ein erfolgreicher Test mit einem anderen Release reichen nicht aus, um die Ursache festzustellen.
Beispiel: Ein erneut zugestellter Webhook erzeugt eine doppelte Bestellung
Übe die Untersuchung mit dem ausführbaren Vorfallsbeispiel. Es enthält vorbereitete Unterlagen zum Vorfall, einen Handler mit einem reproduzierbaren Fehler, den korrigierten Handler und PostgreSQL-Tests.
Der Dienst empfängt einen order.created-Webhook, speichert eine Bestellung und vermerkt, dass das Ereignis verarbeitet wurde. Während eines Vorfalls scheint eine erneute Zustellung eine zweite Bestellung anzulegen. Das Team hat den Dienst bereits stabilisiert und möchte einen Patch prüfen.
Das Beispiel verwendet TypeScript, den Testrunner von Node.js und PostgreSQL. Die temporäre Test-Fixture enthält eine Tabelle namens event_receipts. Ihre Identitätsspalten lassen keine NULL-Werte zu. Für (provider, account_id, event_id) gilt eine nicht aufschiebbare Eindeutigkeitsbedingung.
Das Schema erlaubt es, ein Ereignis durch einen Empfangseintrag zu reservieren, bevor die Bestellung existiert. Es speichert den Fingerabdruck der kanonischen Nutzdaten, damit sich Widersprüche erkennen lassen, wenn derselbe Ereignisschlüssel erneut verwendet wird.
Falls deine Anwendung schon bei der Reservierung einen Fremdschlüssel für die Bestellung benötigt oder die nötigen Daten zur Konflikterkennung fehlen, halte hier an. Kläre zunächst separat, wie Schema und Anwendung damit umgehen sollen.
Dokumentiere die genaue Laufzeitversion, die festgeschriebenen Abhängigkeiten, die PostgreSQL-Version, die Isolationsstufe der Transaktionen und das Schema der Empfangseinträge. Die herunterladbare Fixture verwendet die festgelegten Versionen Node.js 24.19.0, PostgreSQL 17.6 und pg 8.23.1.
Bereite für das mitgelieferte Compose-Setup eine Umgebung mit einem funktionierenden Docker-Daemon vor und prüfe sie vor der Veröffentlichung mit docker info. Die Datenbank akzeptiert ausschließlich öffentliche Testzugangsdaten und ist an die lokale Loopback-Schnittstelle gebunden. Wenn du den Test anpasst, verwende das Datenbanksystem und die relevanten Einstellungen deiner Anwendung.
Das Beispiel setzt PostgreSQL mit READ COMMITTED und stabile Ereignis-IDs des Anbieters voraus. Die Empfangseinträge müssen mindestens so lange erhalten bleiben, wie der Anbieter Ereignisse erneut zustellen oder wiedergeben kann.
Der korrigierte Handler schreibt den Empfangseintrag und die Bestellung in derselben Datenbanktransaktion. Die Fixture stellt eine temporäre Datenbank und die Tabelle delivery_holds bereit, um das Quarantäneverfahren einer vorhandenen Warteschlange nachzubilden. Die Tabelle gehört zur Testinfrastruktur. Sie ist kein Migrationsvorschlag für die Anwendung.
Die Korrektur führt weder eine Warteschlange noch einen Datenbankdienst, eine Schemamigration oder eine Monitoring-Integration ein. Treffen die genannten Annahmen nicht zu, halte an und grenze die Aufgabe neu ab.
Beispiel ausführen
Entpacke die ZIP-Datei, wechsle in das entpackte Verzeichnis und führe die Befehle mit Docker und Compose aus.
docker compose -p codex-incident-rehearsal up -d --wait postgres
docker compose -p codex-incident-rehearsal run --rm runner node --experimental-strip-types main.ts baseline
docker compose -p codex-incident-rehearsal run --rm runner node --experimental-strip-types main.ts regression
docker compose -p codex-incident-rehearsal run --rm runner
docker compose -p codex-incident-rehearsal down --volumes
Der Baseline-Befehl muss mit Exitcode 1 enden. Bei der erneuten Zustellung findet der Test zwei Bestellungen und einen Empfangseintrag, obwohl er jeweils genau einen Datensatz erwartet. Der Regressionstest prüft dieselbe Bedingung mit dem korrigierten Handler und muss mit Exitcode 0 enden.
Der letzte Testbefehl prüft alle Fälle, darunter unabhängige Verbindungen, konkurrierende Zugriffe auf Datenbanksperren und die Quarantäne für Altbestellungen ohne Empfangseintrag.
Falls deine Installation docker-compose bereitstellt, verwende diese Schreibweise anstelle von docker compose. Führe die Befehle nacheinander aus. Die Testsuite setzt nur ihr entsprechend gekennzeichnetes Testschema zurück.
Transaktionslogik im Handler prüfen
Dieser Ausschnitt stammt aus der Datei main.ts im Download. Entpacke die ZIP-Datei und führe die vollständigen Dateien aus. Sie enthalten auch die Tests und das Setup für die Fixture.
Ereignis reservieren und Bestellung in derselben Transaktion speichern
import type { Client } from "pg";
type IncidentEvent = {
provider: string;
accountId: string;
eventId: string;
payload: { type: string; orderId: string; amountCents: number };
};
async function fixed(
client: Client,
input: IncidentEvent,
hook = async (_boundary: string) => {}
) {
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. Ein kompaktes Paket zusammenstellen
Orientiere dich beim Zusammenstellen an diesen Dateien.
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
In diesem Szenario nennt release.json die SHA des Beispiel-Releases 4a1c9e7d2b6f8a0c3d5e7f9012a4b6c8d0e2f413 und den Bereitstellungszeitpunkt 2026-09-22T11:58:00Z. Der Vorfall liegt im Zeitfenster 12:03:00Z–12:05:00Z desselben Tages. Laut den Unterlagen gehören zwei interne Bestellungen zu einem einzigen Ereignis des Anbieters. Gib in deinem eigenen Paket bestätigte Zahlen zu den Auswirkungen an und kennzeichne Schätzungen.
In den bereinigten Logs lassen sich folgende Beobachtungen einander zuordnen.
| Uhrzeit (UTC) | Zuordnung | Beobachtung |
|---|---|---|
| 12:03:04.110 | Ereignis evt_demo_042, Konto acct_demo_01, Anfrage req_demo_a, Trace trace_demo_a |
Die erste Zustellung erreicht den Webhook-Handler. |
| 12:03:04.145 | Dasselbe Ereignis, erster Trace | Die Transaktion für die Bestellung ord_demo_101 wird per Commit abgeschlossen. |
| 12:03:04.150 | Derselbe Worker | Der Worker beendet sich, bevor ein erfolgreicher Schreibvorgang für den Empfangseintrag oder eine Antwort protokolliert wird. Der Auszug allein belegt nicht, dass der Empfangseintrag fehlt. |
| 12:03:14.203 | Derselbe Anbieter, dasselbe Konto und Ereignis, Anfrage req_demo_b, Trace trace_demo_b |
Die erneute Zustellung erreicht den Handler. Er protokolliert, dass er keinen passenden Empfangseintrag gefunden hat. |
| 12:03:14.241 | Dasselbe Ereignis, zweiter Trace | Die Transaktion für die Bestellung ord_demo_102 wird per Commit abgeschlossen und ein Empfangseintrag wird gespeichert. |
Behalte über alle Zustellungen hinweg dieselbe Ereignis-ID bei und verwende für jede Zustellung eigene Anfrage- und Trace-IDs. Eine Kennung, die nur für eine Anfrage gilt, würde den Zusammenhang zwischen der erneuten Zustellung und dem ursprünglichen Ereignis verdecken.
2. Befunde nachvollziehen und die Hypothese prüfen
Der Vorfallsbericht vermutet, dass eine Flut von Wiederholungsversuchen die doppelte Bestellung verursacht hat. Codex sollte das als Hypothese behandeln. Zwei beobachtete Zustellungen belegen keine solche Häufung. Erneute Zustellungen sind ein Normalfall, mit dem ein Webhook-Handler umgehen muss.
Der betroffene Beispielcode zeigt, dass der Handler zunächst nach einem Empfangseintrag sucht, dann die Transaktion für die Bestellung mit einem Commit abschließt und erst anschließend den Empfangseintrag in einer separaten Transaktion schreibt. Das Zeitfenster zwischen den beiden Commits erklärt das Duplikat besser. Fällt der Worker in diesem Zeitfenster aus, kann eine Bestellung ohne Empfangseintrag zurückbleiben. Eine erneute Zustellung kann dann eine weitere Bestellung erzeugen. Bei zwei gleichzeitigen Zustellungen können außerdem beide die separate Prüfung passieren, bevor eine von ihnen ihren Empfangseintrag schreibt.
Lass Codex den tatsächlichen Ablauf im Handler und die Transaktionsgrenzen nachvollziehen und die relevanten Codezeilen angeben. Codex sollte bestätigen, dass der getestete Code dem Release aus den Unterlagen entspricht, oder erklären, wie ein Test mit einem anderen Commit die Aussagekraft einschränkt.
3. Fehler reproduzieren, bevor du den Handler änderst
Ergänze einen Regressionstest mit dem Beispiel-Webhook und der isolierten PostgreSQL-Datenbank. Füge im ursprünglichen Handler direkt nach dem Schreiben der Bestellung und vor dem Schreiben des Empfangseintrags einen Hook ein, der ausschließlich im Test einen Fehler auslöst.
Prüfe anhand der tatsächlichen Transaktionsgrenzen, dass die ursprüngliche Bestellung zu diesem Zeitpunkt bereits per Commit gespeichert ist. Stelle dasselbe Ereignis für denselben Anbieter und dasselbe Konto erneut zu. Prüfe, dass genau eine Bestellung und ein passender Empfangseintrag vorliegen. Bei der mitgelieferten fehlerhaften Implementierung sollte der Test zwei Bestellungen finden und fehlschlagen.
Löse nach der Korrektur den entsprechenden Hook nach der Datenbankanweisung für die Bestellung, aber vor dem Commit der gemeinsamen Transaktion aus. Nach dem fehlgeschlagenen Versuch dürfen weder Bestellungen noch Empfangseinträge vorhanden sein.
Wiederhole die Zustellung und prüfe, dass es jeweils genau einen Datensatz gibt. Prüfe in beiden Revisionen dieselbe fachliche Bedingung und dokumentiere für jede Revision die Position des Hooks.
Führe den neuen Test zuerst mit der ursprünglichen Implementierung aus. Beim absichtlich eingebauten Fehler in diesem Beispiel muss der Test fehlschlagen, weil er zwei Bestellungen statt einer findet. Halte Befehl, Ausgangs-Commit, Exitcode und Ausgabe der fehlgeschlagenen Prüfung fest. Tritt der erwartete Fehler nicht auf, untersuche die Abweichung, bevor du den Handler änderst.
Eine gezielt ausgelöste Exception prüft das Transaktionsverhalten der Anwendung. Dokumentiere, dass sie nicht jeden möglichen Ausfall des Hosts, des Netzwerks oder der Datenbank nachbildet.
4. Den nachgewiesenen Fehler mit einer möglichst kleinen Änderung beheben
Reserviere für diesen konkreten Fehler das Ereignis über seinen Empfangseintrag und schreibe die Bestellung in derselben Transaktion über dieselbe Datenbankverbindung. Nutze den vorhandenen eindeutigen Schlüssel mit INSERT ... ON CONFLICT (provider, account_id, event_id) DO NOTHING RETURNING ....
Nur die Zustellung, die den Empfangseintrag einfügt, darf die Bestellung schreiben. Bestätige den Erfolg erst nach dem Commit. Schlägt die Transaktion fehl, werden beide Schreibvorgänge zurückgerollt. Fange eine Verletzung der Eindeutigkeitsbedingung nicht ab, um anschließend mit der bereits abgebrochenen Transaktion weiterzuarbeiten.
Eine konkurrierende Zustellung muss möglicherweise auf die erste Transaktion warten. Wird die erste Transaktion per Commit abgeschlossen, fügt der zweite Reservierungsversuch nichts ein. Führe unter READ COMMITTED eine neue SELECT-Abfrage aus und prüfe die gespeicherten Daten anhand der Regeln für Ereignisidentität und Nutzdaten. Gib die vorgesehene Bestätigung für Duplikate zurück, ohne eine Bestellung zu schreiben.
Wird die erste Transaktion zurückgerollt, kann die konkurrierende Zustellung das Ereignis reservieren und verarbeiten. Fehlt nach einem übersprungenen Einfügevorgang der Empfangseintrag, widersprechen sich die Identitätsdaten oder tritt ein vorübergehender Datenbankfehler auf, folge dem dokumentierten Ablauf für Wiederholungen oder Fehler. Gib keine unbegründete Erfolgsbestätigung zurück.
Bei strengerer Isolation musst du im Fall eines Serialisierungsfehlers die gesamte Transaktion wiederholen. Halte dich dabei an die im Repository festgelegte Höchstzahl von Versuchen. Siehe die PostgreSQL-Dokumentation zum Verhalten von INSERT bei Konflikten und zur Transaktionsisolation.
Weder eine Menge im Arbeitsspeicher noch eine separate Prüfung vor dem Einfügen schützt vor Duplikaten bei parallelen Workern oder Neustarts. Lege den Geltungsbereich des Schlüssels danach fest, wie der Anbieter Ereignisse eindeutig identifiziert. Enthält ein vermeintlich identisches Ereignis widersprüchliche Identitäts- oder Nutzdaten, melde den Widerspruch, statt das Ereignis stillschweigend als gültiges Duplikat zu behandeln.
Im Beispiel findet die gesamte fachliche Datenänderung in derselben Datenbank statt. Wenn der tatsächliche Handler auch E-Mails verschickt, eine Karte belastet oder einen anderen Dienst aufruft, macht die Transaktion allein diese externen Vorgänge nicht idempotent. Kläre, wo diese Grenze verläuft und welchen Mechanismus das System bereits für Zustellung oder Idempotenz nutzt, bevor du den Umfang der Korrektur erweiterst.
5. Das geänderte Verhalten überprüfen
Lass dir sowohl den ursprünglichen Fehler als auch das Ergebnis nach der Korrektur zeigen. Verwende reine Test-Hooks an ausdrücklich benannten Transaktionsgrenzen und prüfe über eine separate Verbindung, welche Daten per Commit gespeichert wurden. Das Beispiel besteht elf lokale PostgreSQL-Tests. Die Datei test-evidence.md im Download dokumentiert ihre Ergebnisse und die Prüfungen, die für die Ausführung in der Cloud und die Bereitstellung noch ausstehen. Führe die Testsuite in deiner veröffentlichten Umgebung aus und teste einen tatsächlichen Verbindungsabbruch während des Commits, bevor du dich auf die Wiederherstellung in diesem Fall verlässt.
| Prüfung oder Fehlerzeitpunkt | Erforderliches Verhalten |
|---|---|
| Erste Zustellung und Duplikat nach dem Commit | Die erste Zustellung erzeugt eine Bestellung und einen Empfangseintrag. Bei erneuter Zustellung desselben Ereignisses gibt der Handler die vereinbarte Bestätigung zurück. Die Anzahl der Datensätze bleibt gleich. Dokumentiere den genauen Status und Antwortinhalt. |
| Vor der Reservierung des Ereignisses | Bei einem Fehler entsteht keiner der beiden Datensätze und der Handler bestätigt keinen Erfolg. Eine erneute Zustellung erzeugt jeweils einen Datensatz. |
| Nach der Reservierung, vor dem Schreiben der Bestellung | Bei einem Fehler wird der Empfangseintrag zurückgerollt. Es gibt keine Bestellung. Eine erneute Zustellung kann das Ereignis wie vorgesehen reservieren und verarbeiten. |
| Nach dem Schreiben der Bestellung, vor dem Commit | Bei einem Fehler werden beide Datensätze zurückgerollt. Damit prüfst du im korrigierten Code die Stelle, an der ursprünglich eine bereits gespeicherte Bestellung ohne Empfangseintrag zurückblieb. Nach einer erneuten Zustellung gibt es jeweils einen Datensatz. |
| Nach dem Commit, vor der Bestätigung | Simuliere den Verlust der Antwort. Beide Datensätze bleiben gespeichert. Bei erneuter Zustellung gibt der Handler die Bestätigung für Duplikate zurück, ohne eine weitere Bestellung anzulegen. |
| Ausgang des Commits unbekannt | Simuliere einen Verbindungsabbruch zum Zeitpunkt des Commits getrennt von einer gewöhnlichen Exception. Bestätige keinen unbelegten Erfolg. Eine erneute Zustellung mit demselben stabilen Ereignisschlüssel muss sicher sein, unabhängig davon, ob die erste Transaktion per Commit abgeschlossen oder zurückgerollt wurde. Kennzeichne den Test als nicht ausgeführt, falls du diesen Verbindungsfehler nicht geprüft hast. |
| Gleichzeitiges Duplikat bei erfolgreichem Commit der ersten Transaktion | Zwei unabhängige Verbindungen oder Worker konkurrieren um denselben Ereignisschlüssel. Halte den ersten Worker nach erfolgreicher Reservierung an und starte den zweiten, bevor du den ersten freigibst. Prüfe, dass der zweite tatsächlich auf die Sperre wartet, und gib dann den ersten frei. Beide müssen die jeweils erwartete Bestätigung liefern. Es gibt genau eine Bestellung und einen Empfangseintrag. |
| Gleichzeitiges Duplikat bei Rollback der ersten Transaktion | Wiederhole die kontrollierte Überschneidung. Löse diesmal vor dem Commit einen Fehler bei dem Worker aus, der das Ereignis reserviert hat. Nach dem Rollback reserviert der zweite Worker das Ereignis und erzeugt eine Bestellung und einen Empfangseintrag. Prüfe beide Antworten und den Endzustand. |
| Ereignisidentität und widersprüchliche Nutzdaten | Unterschiedliche Ereignisse bleiben voneinander unabhängig. Das gilt auch für dieselbe Ereignis-ID bei unterschiedlichen Konten oder Anbietern. Hat ein Ereignis im selben Geltungsbereich dieselbe ID, aber abweichende kanonische Nutzdaten, folge dem vereinbarten Verfahren für Konflikte. Erzeuge keine zweite Bestellung und bestätige keinen abweichenden Vorgang stillschweigend. |
| Altbestellung ohne Empfangseintrag und ausstehende erneute Zustellung | Lege eine per Commit gespeicherte Altbestellung ohne Empfangseintrag an. Ermittle und sperre ihren Ereignisschlüssel, bevor erneute Zustellungen wieder anlaufen. Solange die Sperre besteht, erhält eine erneute Zustellung keine Erfolgsbestätigung und erzeugt keinen Datensatz. Nach einem Abgleich anhand vertrauenswürdiger Daten ist die Bestätigung für Duplikate zulässig. Es gibt dann eine bereits vorhandene Bestellung und einen Empfangseintrag. Bei fehlenden oder widersprüchlichen Belegen bleibt der Schlüssel gesperrt. |
| Weiterführende Prüfungen des Dienstes | Führe die relevanten Integrationstests, das Linting und die Typprüfung aus. Unterscheide neue Fehler, bereits bestehende Fehler und Prüfungen, die sich nicht ausführen ließen. |
Steuere die parallelen Abläufe mit Barrieren oder Latches und begrenzten Wartezeiten. Bloße Wartepausen oder zwei parallel gestartete Promises reichen dafür nicht aus. Gib blockierte Worker beim Aufräumen nach dem Test frei und nutze temporäre Fixtures. Ein Test mit einer Exception allein belegt nicht, wie sich das System bei einem abrupten Prozessabbruch, einem Verbindungsverlust oder konkurrierenden Zugriffen im Produktivbetrieb verhält.
Das Beispiel führt node --experimental-strip-types main.ts baseline, node --experimental-strip-types main.ts regression und node --experimental-strip-types main.ts im Testrunner mit festgelegter Version aus. Die strukturierte Ausgabe erfasst Transaktionsgrenzen, die Anzahl der per Commit gespeicherten Zeilen, Status und Inhalt der Bestätigungen sowie die beobachteten IDs der blockierenden Datenbankprozesse.
Wenn du den Ablauf anpasst, verwende die tatsächlich in deinem Repository definierten Befehle und dokumentiere ihre Ergebnisse. Halte übersprungene Prüfungen und nicht verfügbare Abhängigkeiten in der Übergabe fest. Erkläre, wie sie die Aussagekraft der Ergebnisse einschränken.
Übergabe prüfen
Gemeinsames Prüfprotokoll
Dokumentiere jedes Abnahmekriterium im Nachweisformat für die Vorfallsuntersuchung. Trage die tatsächlich beobachtete Ausgabe ein. Die folgenden Felder sind eine Vorlage und belegen noch keine bestandene Prüfung. Wenn ein neuer Test in der Ausgangsversion noch fehlt, unterscheide „noch nicht vorhanden“ von einer bereits vorhandenen, fehlgeschlagenen Prüfung.
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]
Ordne fehlgeschlagene und erfolgreiche Testläufe dem tatsächlich getesteten Stand zu. Berücksichtige dabei auch reine Teständerungen an der ursprünglichen Revision. Lege der Übergabe die Logs, die Antwort-Fixtures und den endgültigen Diff bei. Ändert sich die endgültige Revision, brauchst du aktualisierte Nachweise. Nicht ausgeführte oder blockierte Prüfungen zählen nicht als bestanden.
Bitte Codex, den Code-Diff und die folgenden Unterlagen zur Prüfung im Repository abzulegen.
incident-investigation.md: zeitlicher Ablauf, Verweise auf Belege, geprüfte Hypothesen, durch Befunde gestützte Ursache und verbleibende Unsicherheiten.test-evidence.md: Ausgangs-Commit, Ausgabe des fehlgeschlagenen Regressionstests, Commit oder Diff der Korrektur, bestandene gezielte Prüfungen, weiterführende Prüfungen und Einschränkungen.pr-draft.md: kurze Erläuterung des Fehlers, des geänderten Verhaltens, der Testergebnisse und des verbleibenden Risikos.deployment-handoff.md: überprüfte Annahmen zu Schema, Isolation und Aufbewahrung der Empfangseinträge, Name der für den Rollout verantwortlichen Person, Prüfungen vor der Bereitstellung, Metriken zu doppelten Bestellungen, Bestätigungen und Fehlern sowie die unten beschriebenen Freigabekriterien für Rollout und Rollback.
Bevor du den Patch akzeptierst, vergewissere dich, dass der ursprüngliche Code den neuen Test nicht besteht, der korrigierte Code ihn besteht und der Diff den nachgewiesenen Fehler behebt. Prüfe im Webhook-Beispiel den Geltungsbereich des Ereignisschlüssels, die Transaktionsgrenzen, die Testabdeckung für parallele Zustellungen und mögliche Auswirkungen außerhalb der Transaktion. Prüfe bereits vorhandene doppelte Bestellungen separat. Das Verhindern neuer Duplikate korrigiert keine historischen Datensätze.
Bereitstellung und Rollback planen
Der Patch schützt nur Worker, die den korrigierten Handler ausführen. Alte Worker können weiterhin eine Bestellung schreiben, bevor sie das Ereignis reservieren. Ein Canary-Rollout mit gemischten Versionen belegt deshalb nicht, dass der Fehler behoben ist.
Wer die Bereitstellung verantwortet, muss sich für eine getestete Strategie mit gemischten Versionen oder für ein vorhandenes Betriebshandbuch entscheiden. Bei der zweiten Variante pausiert das Team die Annahme neuer Ereignisse, lässt alte Worker ihre laufenden Vorgänge abschließen, aktualisiert sämtliche Consumer und nimmt die Verarbeitung zurückgehaltener Zustellungen ohne Verlust wieder auf.
Prüfe vor der Entscheidung für die zweite Variante, wie Anbieter und Warteschlange erneute Zustellungen und die Aufbewahrung handhaben. Setze nicht voraus, dass eine Pause ohne Verluste möglich ist.
Ermittle vor der Wiederaufnahme alle per Commit gespeicherten Altbestellungen, für die ein passender Empfangseintrag fehlt. Wenn du die Verarbeitung pausierst und alte Consumer ihre laufenden Vorgänge abschließen lässt, verhinderst du weitere Schreibvorgänge durch die alte Version. Die vorhandenen Bestellungen werden dadurch nicht korrigiert. Sperre jeden betroffenen Ereignisschlüssel über die vorhandene Warteschlange oder das bestehende Quarantäneverfahren. Lässt sich die Ereignisidentität aus den Altdaten nicht vollständig ermitteln, halte die betroffenen Zustellungen oder die Zustellungen aus dem betroffenen Zeitfenster zur Prüfung durch die verantwortliche Person zurück. Erkläre die Suche in diesem Fall nicht für abgeschlossen.
Gleiche einen gesperrten Schlüssel nur ab, wenn vertrauenswürdige, unveränderliche Identitätsdaten zu Anbieter, Konto und Ereignis zusammen mit Belegen zu den kanonischen Nutzdaten und dem per Commit gespeicherten fachlichen Datensatz eindeutig zeigen, was bereits geschehen ist.
Erfasse nach dem genehmigten Abgleichverfahren den passenden Empfangseintrag, ohne die fachliche Datenänderung zu wiederholen. Hebe danach die Sperre für diesen Schlüssel auf.
Fehlen Belege, widersprechen sich die Nutzdaten oder liegen mehrere fachliche Datensätze vor, belasse die betroffenen Schlüssel zur Prüfung durch die verantwortliche Person in Quarantäne. Um den Fingerabdruck des ursprünglichen Ereignisses zu rekonstruieren, brauchst du vertrauenswürdige Belege für dieses Ereignis. Die Nutzdaten einer erneuten Zustellung können sie nicht ersetzen.
Die Verarbeitung darf erst wieder anlaufen, wenn jeder betroffene Schlüssel abgeglichen ist oder seine Sperre bei allen Consumern weiterhin greift.
Bereite in der Staging-Umgebung eine Altbestellung mit einer ausstehenden erneuten Zustellung vor. Prüfe, dass die Sperre eine weitere Bestellung und jede Erfolgsbestätigung verhindert. Nach einem Abgleich anhand vertrauenswürdiger Daten darf die erneute Zustellung die Bestätigung für Duplikate erhalten. Es muss bei der einen vorhandenen Bestellung bleiben. Spiele auch einen ungeklärten Fall durch. Der Schlüssel muss gesperrt bleiben, ohne dass ein unbelegter Empfangseintrag angelegt wird. Halte dieses Freigabekriterium in der Übergabe für die Bereitstellung fest, zusammen mit den Prüfungen zum Pausieren und Abschließen laufender Vorgänge, zu den Consumer-Versionen, zur Aufbewahrung und zum Rollback.
Vergewissere dich vor dem Rollout, dass die Eindeutigkeitsbedingung vorhanden und gültig ist und dass alle Consumer dieselben Regeln für Empfangsschlüssel und Nutzdaten anwenden. Prüfe außerdem, dass das Löschen alter Empfangseinträge keine erneute Verarbeitung innerhalb des Wiederholungszeitfensters ermöglicht und dass externe Vorgänge vom Patch unberührt bleiben.
Erprobe in der Staging-Umgebung den gewählten Ablauf und die erneute Zustellung nach einem Worker-Ausfall. Dokumentiere das von der verantwortlichen Person festgelegte Beobachtungszeitfenster und die Abbruchschwellen für doppelte Bestellungen, Webhook-Fehler, Latenz der Bestätigungen, Wartezeiten auf Sperren und den Rückstau erneuter Zustellungen. Erfinde keine Schwellenwerte für den Produktivbetrieb.
Beim Wechsel zurück zum alten Handler können erneut doppelte Bestellungen entstehen. Die Rollback-Unterlagen müssen die Maßnahme zur Eindämmung benennen (etwa das genehmigte Verfahren zum Pausieren und Abschließen laufender Vorgänge), die sichere Revision und die Person, die über die Wiederaufnahme der Verarbeitung entscheidet. Bewahre Empfangseinträge auf. Lösche sie nicht, um erneute Zustellungen zu ermöglichen. Für historische Duplikate ist eine separat geprüfte Korrektur erforderlich.
Die zuständige Person aus dem Engineering-Team entscheidet über die Bereitstellung und verantwortet alle Korrekturen im Produktivbetrieb. Ein bestandener isolierter Test liefert einen Beleg für die Prüfung. Er weist nicht nach, dass der Produktivbetrieb fehlerfrei läuft. Erstelle den Pull Request, durchlaufe euren üblichen CI- und Review-Prozess und stelle die Änderung nach Prüfung des Entwurfs gemäß den etablierten Verfahren deines Teams bereit.
In derselben Aufgabe weiterarbeiten
Nutze einen gezielten Folge-Prompt, um offene Fragen zu klären oder die Übergabe zu verbessern.
Prüfe den Patch für zwei Fälle: zwei gleichzeitige Zustellungen und eine erneute Zustellung nach einem Worker-Ausfall. Zeige, welches Verhalten die Tests belegen und welches noch ungeprüft ist. Beschränke die Änderung auf diesen Handler und seine Regressionstests. Halte alle verbleibenden Risiken in den Übergabeunterlagen fest.
Falls sich der Vorfall beim ersten Durchlauf nicht reproduzieren ließ, verwende diesen Prompt.
Stoppe die Implementierung. Liste die Hypothesen auf, die sich anhand der Befunde ausschließen lassen. Benenne die am besten begründete verbleibende Hypothese. Gib an, welche zusätzlichen bereinigten Daten oder welcher isolierte Versuch ausreichen würden, um diese Hypothese von den übrigen zu unterscheiden. Beschränke dich dabei auf das Nötigste. Kennzeichne die Ursache weiterhin als unbestätigt. Verwandte Anwendungsfälle
Ein Validierungsmodul migrieren
Gib Codex einen klar abgegrenzten Migrationsauftrag, Test-Fixtures für die...
Browserspiele entwickeln
Beschreibe deine Spielidee kurz. Codex kann daraus einen konkreten Plan entwickeln und ihn...
Code migrieren
Ordne mit Codex die Bestandteile eines Altsystems dem neuen Stack zu