Postmortem Template: Das Format, das ich für jeden Produktionsvorfall verwende (und warum)

Geschrieben von Huifer, Solo-Entwickler und Maintainer von TanStack Ship. Ich habe 2024 angefangen, Postmortems zu schreiben, nachdem ich einen fehlerhaften Abrechnungsflow ausgeliefert hatte, der zwei Enterprise-Kunden etwas gekostet hat. Die unten stehende Vorlage ist die Version, die sich bewährt hat — jeder Vorfall in der TanStack Ship-Infrastruktur wurde seitdem so dokumentiert, einschließlich des D1 Write-Lock-Storms, des Stripe-Webhook-Duplikats und des E-Mail-Queue-Replays.

Verifizierte Quellen: TanStack Ship GitHub-Organisation · TanStack Start Docs Letzte Aktualisierung: 2026-07-21 · Changelog

TL;DR: Ein gutes Incident Postmortem ist ein Dokument mit festgelegter Struktur und sieben Abschnitten: Hintergrund, Vorfall, Untersuchung, Ursache, Lösung, Erkenntnisse und verknüpftes Modul. Die Struktur erzwingt eine schuldfreie Darstellung, macht jeden Vorfall reproduzierbar und verwandelt vor allem jedes Feuer in einen Standard, sodass derselbe Fehler nicht wieder auftreten kann. Wenn Sie Ihr nächstes Postmortem in einer anderen Form schreiben, verschwenden Sie die teuerste Feedback-Schleife in SaaS.

Warum eine festgelegte Struktur besser ist als freie Postmortems

Der erste Produktionsvorfall, den ich jemals in TanStack Ships Abrechnungsmodul ausgeliefert habe, war ein Stripe-Webhook-Race, der 18 Kunden doppelt belastet hat. Ich habe mich hingesetzt, um ein Postmortem zu schreiben, und drei Seiten abschweifender Prosa produziert — halb Entschuldigung, halb Bewusstseinsstrom, halb vages „wir sollten das überwachen". Ich habe es nie wieder gelesen. Dasselbe Race ist im nächsten Quartal zweimal wieder aufgetreten.

Der zweite Vorfall, den ich mit einer festgelegten Sieben-Abschnitte-Vorlage geschrieben habe. Das Team (nur ich, aber die Disziplin skaliert) konnte es sechs Monate später kalt lesen, den Bug anhand der Vorlage reproduzieren und die Guardrail ausliefern, die das Postmortem in einen Standard verwandelt hat. Dieses Format ist der Gegenstand dieses Beitrags.

Freie Postmortems scheitern aus drei strukturellen Gründen:

1. Sie gleiten in Entschuldigungen ab. Ohne einen Abschnitt mit der Bezeichnung „Lösung" ist der Standardmodus des Autors Erklärung und Ausrede. Die Leser gehen mit den Gefühlen des Autors weg, nicht mit der Codeänderung, die das Wiederauftreten verhindert.
2. Sie verbergen die Timeline. Ohne einen Abschnitt mit der Bezeichnung „Vorfall" mit Start-/End-Zeitstempeln kann der Leser nicht erkennen, ob die Reaktion gut oder schlecht war. Fünfminütige Vorfälle sehen in Erzählform genauso aus wie fünfstündige.
3. Sie werden nie zu Produktstandards. Ohne einen expliziten Abschnitt „Verknüpftes Modul" ist das Postmortem ein historisches Dokument. Mit diesem Abschnitt ist es ein Liefer-Artefakt.

Eine festgelegte Struktur ist eine Erzwingungsfunktion. Jeder Abschnitt hat eine Aufgabe. Wenn Sie einen Abschnitt nicht füllen können, verstehen Sie den Vorfall noch nicht. Wenn der Abschnitt kurz ist, war die Arbeit dort dünn. Die Form ist die Wahrheit.

Die sieben Abschnitte im Detail

Im Folgenden ist die Abschnittsreihenfolge, die ich verwende, mit der Begründung und der Frage, die jeder Abschnitt beantwortet.

1. Hintergrund — Was geschah vorher?

Zwei Absätze. Beschreiben Sie das System, das ausgefallen ist, die Last, der es ausgesetzt war, und die für den Kunden sichtbare Oberfläche. Der Leser sollte sich eine Topologie und einen Request-Graph vorstellen können, bevor er liest, was schiefgelaufen ist. Hier benennen Sie die Produkte, Module, Drittanbieter und die Volumenstufe (z. B. „3.200 zahlende Kunden, 200 req/s auf der Billing-Route, D1 SQLite-Backend, Stripe Live-Modus").

2. Vorfall — Was sah der Nutzer?

Bulleted Timeline mit HH:MM:SS-Zeitstempeln. Beginnen Sie mit dem ersten kundenwirksamen Signal (ein 500er-Spike, eine Webhook-Retry-E-Mail, ein Stripe-Support-Ticket). Enden Sie mit dem Moment, als der Rauch sich verzogen hat. Fügen Sie die Anzahl der Kunden impact hinzu — fehlgeschlagene Checkouts, verlorene Guthaben, Anzahl der Rückerstattungen. Keine Prosa hier, nur Zeitstempel und Zahlen.

3. Untersuchung — Was zeigten die Traces?

Dies ist der längste Abschnitt in guten Postmortems. Gehen Sie durch die Kette der Inspections-Befehle, Dashboard-Screenshots (referenziert nach Zeitfenster) und den Moment, in dem die „rauchende Pistole" auftauchte. Zitieren Sie den tatsächlichen Fehler-String. Zeigen Sie die tatsächliche SQL-Abfrage. Das Ziel ist die Reproduktion. Wenn ein Leser die Untersuchung nicht anhand eines frischen Repros nachvollziehen kann, ist dieser Abschnitt zu vage.

4. Ursache — Warum ist das passiert?

Ein Absatz, normalerweise drei bis fünf Sätze. Der Fehler der Alltagssprachlichen Beschreibung (z. B. „der Consumer hielt keine per-batch-Reservation, sodass der Retry eine doppelte Stripe-Anfrage sendete"). Spekulieren Sie hier nicht — geben Sie nur an, was die Traces und die Code-Review bewiesen haben. Wenn Sie es noch nicht wissen, lassen Sie diesen Abschnitt als „Untersuchung läuft" und liefern Sie einen Follow-up nach.

5. Lösung — Was hat sich in Code und Config geändert?

Ein Code-Diff, eine Config-Änderung oder beides. Zeigen Sie die tatsächlichen Zeilen, die sich geändert haben, mit dem Dateipfad und dem Commit-Hash. Wenn die Lösung eine Queue ist, zeigen Sie die Queue-Definition. Wenn die Lösung eine Guard ist, zeigen Sie die Guard. Der Leser muss in der Lage sein, Ihre Lösung auf ein ähnliches System anzuwenden.

6. Erkenntnisse — Was hat die Organisation gelernt?

Hier verdient das Postmortem seinen Mehrwert. Zwei bis vier Bulletpoints. Jede Erkenntnis sollte eine Regel sein, die das Team vor dem nächsten Vorfall anwenden kann, keine Plattitüde. „Alle Stripe-Webhooks müssen auf event.id idempotent sein" ist eine Erkenntnis. „Wir sollten vorsichtiger mit Webhooks sein" ist es nicht.

7. Verknüpftes Modul — Wo taucht das noch auf?

TanStack Ship-spezifisch. Jedes Postmortem beantwortet: Welches Modul kodiert jetzt die Erkenntnis? Das D1-Postmortem verlinkt auf den Queue-basierten Billing-Write-Path des Billing-Moduls. Das Stripe-Postmortem verlinkt auf das Webhook-Ledger. Der Abschnitt „Verknüpftes Modul" ist die Brücke vom Vorfall zum Produktstandard — der Teil, der ein Postmortem in ein Liefer-Artefakt verwandelt.

Die Vorlage in der Praxis

Im Folgenden finden Sie das Markdown-Skelett, das ich für jedes Postmortem in der TanStack Ship-Infrastruktur erstelle. Es wird im Repository unter /docs/postmortems/<date>-<slug>.md abgelegt und wird Teil der durchsuchbaren Historie.

# <Vorfalltitel>

**Datum:** JJJJ-MM-TT
**Schweregrad:** SEV-1 / SEV-2 / SEV-3
**Autor:** Huifer
**Status:** Behoben / Abgemildert / Läuft

## Hintergrund
<2 Absätze System- + Lastkontext>

## Vorfall
- HH:MM:SS — <erstes Signal>
- HH:MM:SS — <Pager / Kundenticket / Dashboard-Alarm>
- HH:MM:SS — <Abhilfe ausgeliefert>
- HH:MM:SS — <vollständig behoben>

Kundenauswirkung: <Metrik + Einheit>

## Untersuchung
<geordnete Traces, Queries, Dashboard-Referenzen>

## Ursache
<3–5 Sätze zur Ursache in Alltagssprache + Beweis>

## Lösung
- <Commit-Hash> — <Einzeilige Zusammenfassung>
- <Config-Änderung> — <Einzeilige Zusammenfassung>

## Erkenntnisse
- <Regel 1>
- <Regel 2>
- <Regel 3>

## Verknüpftes Modul
<Pfad in TanStack Ship, das jetzt die Lösung kodiert>

Das Skelett ist absichtlich minimal. Jeder Abschnitt ist ein Platzhalter. Wenn Sie sich dabei erwischen, mehr als eine Seite in einem Abschnitt zu schreiben, ist dieser Abschnitt entweder der richtige Ort, um die Lösung auszuliefern (kehren Sie nach dem Commit dorthin zurück), oder Sie schreiben einen Essay statt eines Artefakts — lagern Sie den Essay aus.

Wann man das Postmortem schreibt

Schreiben Sie innerhalb von 72 Stunden nach der Behebung. Das ist nicht willkürlich — es ist das Fenster, in dem Traces noch verfügbar und der Untersuchungskontext frisch sind. Nach 72 Stunden haben Log-Retention-Richtlinien möglicherweise die relevanten Daten bereits rotiert. Nach einer Woche verblasst der Kontext „warum ich zuerst auf dieses Dashboard geschaut habe".

Der Auslöser ist die Behebung, nicht die Entdeckung. Sie schreiben das Postmortem, nachdem der Vorfall behoben wurde, nicht während er noch aktiv ist. Während des Vorfalls geht Ihre Energie in die Abhilfe. Das Postmortem ist für die Zukunft — nachdem das Feuer gelöscht ist.

Schreiben Sie es auch für kleine Vorfälle. Die Gewohnheit, Postmortems für 30-minütige Vorfälle zu schreiben, baut die Fähigkeit für 30-stündige Vorfälle auf. Die Vorlage funktioniert in jeder Größenordnung.

Die eine Ausnahme: wenn Sie die Grundursache noch nicht verstehen, veröffentlichen Sie ein unvollständiges Postmortem mit „Grundursache TBD", anstatt auf perfektes Verständnis zu warten. Teilweise Informationen summieren sich; Stille tut es nicht.

Schuldfreie Darstellung in der Praxis

„Schuldfrei" wird in der Postmortem-Kultur viel herumgeworfen. Meistens bedeutet es „keine Namen im Dokument". Das ist der Boden, nicht die Decke. Eine schuldfreie Darstellung in der Praxis hat drei konkrete Schritte:

1. Ersetzen Sie menschliche Namen durch Systemrollen. „Alices Migrationsskript ist kaputtgegangen" wird zu „das Schema-Migration, eingeführt um 14:02, hat den Index gelöscht." Der Leser weiß jetzt von der Migration, nicht vom Menschen. Das ist eine kleine Änderung mit überproportionalen Darstellungseffekten.
2. Ersetzen Sie Absicht durch Mechanismus. „Wir haben vergessen, Idempotenz hinzuzufügen" wird zu „der Consumer hat die Event-ID vor dem Retry nicht reserviert." Fehler werden zu fehlenden Mechanismen — behebbar, wiederholbar, verteidigbar.
3. Ersetzen Sie Schuldzuweisung durch Timing. „Der On-Call war eingeschlafen" wird zu „der Page wurde für 11 Minuten an ein Handy im Flugmodus weitergeleitet." Jetzt ist die Frage, wie das On-Call-Routing konfiguriert ist, nicht ob eine Person schuld ist.

Der Test: Lesen Sie das Postmortem laut vor, ersetzen Sie den Teamnamen durch „Acme Engineering", und prüfen Sie, ob das Dokument noch sinnvoll ist. Wenn die Kultur Ihres Teams davon abhängt, wessen Name im Dokument erscheint, braucht die Struktur mehr Arbeit.

Wie Postmortems zu TanStack Ship-Standards werden

Der Grund, warum ich diese Vorlage weiterhin schreibe, ist, dass sie sich amortisiert hat. Jedes Postmortem seit 2024 hat eine Codeänderung produziert, die als Standard ausgeliefert wird. Das Muster ist mechanisch:

• Der Abschnitt „Lösung" produziert einen Commit.
• Der Abschnitt „Verknüpftes Modul" benennt, wo die Lösung lebt.
• Das nächste Release von TanStack Ship liefert die Lösung als Standard für neue Projekte.
• Neue Projekte erhalten die Erkenntnis, ohne je das Postmortem gelesen zu haben.

Das ist dieselbe Schleife wie die Open-Source-Sicherheitshaltung: Vorfälle bezahlen die Codebasis. Jeder Produktionsfehler finanziert einen Standard, der das nächste Auftreten verhindert, in jedem Projekt, das das Boilerplate übernimmt. Für einen Solo-Dev, der 12+ Produktions-Apps auf TanStack Ship-Infrastruktur wartet, ist diese Schleife der einzige Weg, wie Postmortems erschwinglich bleiben.

Konkrete Beispiele aus der TanStack Ship-Postmortem-Serie:

• Das D1 Write-Lock-Postmortem (/blog/postmortem-d1-write-lock) hat einen Queue-basierten Billing-Write-Path ausgeliefert, der jetzt der Standard im Billing-Modul ist.
• Das Stripe-Webhook-Duplikat-Postmortem (/blog/postmortem-stripe-webhook-duplicate) hat ein Event-ID-Ledger ausgeliefert, das jetzt für jede Stripe-Integration im Boilerplate erforderlich ist.
• Das Postmortem zu gestapelten Rabatten (/blog/postmortem-stacked-discounts-checkout-failures) hat eine Precedence- und Floor-Prüfung ausgeliefert, die jetzt der einzige Pfad ist, den das Pricing-Modul akzeptiert.

Jeder dieser Standard-Fixes ist ein Postmortem, das zu einem Liefer-Artefakt geworden ist. Die Vorlage ist der Trichter, der diese Schleife ermöglicht.

Wofür die Vorlage nicht gedacht ist

Einige Dinge, die diese Vorlage bewusst nicht leistet:

• Sie ist kein Status-Update. Status-Updates gehören in den Chat oder eine Statusseite, nicht in ein Postmortem. Status-Updates betreffen die Gegenwart; Postmortems betreffen die Vergangenheit.
• Sie ist keine öffentliche PR-Erklärung. Wenn Vorfälle öffentlich Kunden betreffen, ist die öffentliche Version normalerweise ein viel kürzeres, blanderes Dokument. Das interne Postmortem sollte die technische Wahrheit bewahren; die externe Erklärung kann eine bereinigte Zusammenfassung sein.
• Sie ist keine Kundenentschuldigung. Der Abschnitt „Lösung" ist die Entschuldigung. Die richtige Entschuldigung ist der Commit-Hash, der verhindert, dass derselbe Kunde auf denselben Bug stößt.
• Sie ist keine Retrospektive. Retrospektiven fragen „Was sollten wir als Team anders machen?" Postmortems fragen „Was sollte das System ablehnen." Retrospektiven verändern Kultur; Postmortems verändern Code.

Warum ich den „Erkennung"-Abschnitt weggelassen habe, den die meisten Vorlagen hinzufügen

Postmortem-Vorlagen aus SRE-Büchern fügen oft einen „Erkennung"-Abschnitt zwischen Hintergrund und Vorfall hinzu: „Wie haben wir es herausgefunden?" Ich habe ihn aus dieser Vorlage entfernt — die Frage wird bereits im Abschnitt „Vorfall" beantwortet, wenn Sie die Timeline gut schreiben.

Wenn die Timeline sagt „14:02 — PagerDuty wurde wegen SLO-Burn-Alarm auf der Billing-Route ausgelöst", ist das Erkennung. Wenn die Timeline sagt „14:42 — Stripe hat einen Fall eröffnet, weil 18 Kunden doppelte Belastungsreklamationen eingereicht haben", ist das auch Erkennung. Erkennung als separaten Abschnitt zu schreiben verdoppelt die Arbeit und produziert ein Dokument, das sich wiederholt.

Die Ausnahme: wenn die Erkennung fehlgeschlagen ist und der Kunde den Bug zuerst gefunden hat. Fügen Sie eine einzelne Zeile unter Untersuchung hinzu: „Erkennungslücke — erstes Signal kam von einem Kundenbericht um HH:MM:SS, kein interner Alarm wurde ausgelöst." Dann machen Sie weiter. Die Erkenntnis gehört in den Abschnitt „Erkenntnisse", nicht in einen strukturellen Slot.

Wie Sie den Rest der Serie lesen

Wenn Sie TanStack Ship evaluieren und wissen möchten, ob die Standards des Boilerplates aus echten Vorfall-Daten stammen, ist die Postmortem-Serie der Prüfpfad. Jeder Beitrag folgt dieser Vorlage, benennt die Produktionsbedingungen, enthält die tatsächlichen Zahlen und verlinkt auf das Modul, das jetzt die Lösung kodiert. Wenn Sie die Module in TanStack Ship mit den Modulen in einem Konkurrenz-Boilerplate vergleichen, fragen Sie sich, ob der Konkurrent Ihnen den vorfallgetriebenen Standard für jedes Feature zeigen kann. Die meisten können es nicht.

Für Solo-Devs, die Produktions-SaaS betreiben, empfehle ich die folgende minimale Kadenz:

• Schreiben Sie nach jedem Produktionsvorfall ein Postmortem in dieser Vorlage innerhalb von 48 Stunden, während die Traces noch warm sind.
• Überprüfen Sie jeden Monat die Abschnitte „Verknüpftes Modul" der letzten 90 Tage — diese Liste ist Ihre echte Produkt-Roadmap.
• Wenn Sie eine neue Abhängigkeit aufnehmen, fragen Sie sich, ob die Abhängigkeit einen aktuellen Vorfall verhindert hätte. Wenn die Antwort nein ist, verdient die Abhängigkeit ihren Platz nicht.

Die Disziplin ist klein. Der kumulative Effekt auf ein Ein-Mann-Engineering-Team ist erheblich.

Lesen Sie den ersten Vorfallbericht: /blog/postmortem-d1-write-lock — ein D1 Write-Lock-Storm bei 200 req/s und der Queue-basierte Fix, der zum Billing-Modul-Standard wurde. Oder durchsuchen Sie das vollständige Vorfall-Postmortem-Archiv und die Feature-Modulliste, um zu sehen, welche Standards von welchen Vorfällen stammen.

Wenn Sie die Sieben-Abschnitte-Vorlage als einzelne Datei möchten, die Sie direkt in Ihr eigenes Repo übernehmen können, liefert das Boilerplate sie unter /docs/postmortems/TEMPLATE.md im TanStack Ship Repo. Und wenn Sie Boilerplates anhand der Stärke ihrer Standards vergleichen, führen die Vergleiche vs-shipfast und vs-makerkit durch, wie sich die vorfallgetriebenen Module gegen die Alternativen behaupten.