Story Walkthrough

Was macht Story Walkthrough?

Der Nutzer möchte ein Problem verstehen, das er nicht selbst erlebt hat. Er kennt weder die Komponenten, die Fachbegriffe noch die Reihenfolge der Ereignisse. Eine Liste von Erkenntnissen oder eine Diff-Zusammenfassung hilft ihm nicht weiter. Eine Geschichte hingegen schon: Sie führt jeden Akteur einmal ein, zeigt dann, was jeder tut, und zwar in der Reihenfolge, in der es geschieht, bis der Fehler ganz natürlich eintritt.

Recherchiere zuerst. Die Geschichte ist nur so gut wie die Fakten, auf denen sie basiert. Lies also den Code, Logs, Tickets, Dokumente und den Verlauf, bevor du schreibst. Wenn die Untersuchung bereits früher im Gespräch stattgefunden hat, nutze sie erneut, anstatt sie zu wiederholen.

Form der Antwort

Beginne mit einem Satz, der den Rahmen setzt, z.B. "Hier ist die ganze Geschichte von Anfang an, ohne dass ich voraussetze, dass du den Code kennst." Verwende dann diese Abschnitte. Überspringe einen Abschnitt, der nichts Relevantes zu sagen hat, anstatt ihn aufzublähen.

Die Charaktere

Stelle jeden Akteur vor, den die Geschichte braucht, und sonst nichts: Komponenten, Klassen, Nachrichten, Timer, Daten und bei einem Prozess auch die beteiligten Personen, Teams, Formulare und Einstellungen. Gib jedem einen fettgedruckten Namen und ein oder zwei einfache Sätze darüber, was es ist und was es in dieser Geschichte tut.

• Benenne jeden Charakter präzise und verlinke ihn mit dem Code. Schreibe price_cache_key() mit einem file:line-Link, nicht "der Schlüssel-Bauer". Eine ungenaue Bezeichnung führt dazu, dass der Leser innehalten und nachfragen muss, was gemeint ist. Wenn ein Charakter sich über mehrere Code-Stücke erstreckt (eine Methode plus die Framework-Hooks darum herum), sage das hier. Bei einem Problem außerhalb des Codes verlinke stattdessen die Quelle: das Dokument und den Schritt, das Formularfeld oder den Einstellungspfad.
• Wähle eine einzige physikalische Metapher für den abstrakten Mechanismus und behalte sie für die ganze Geschichte bei. Zum Beispiel werden Nachrichten-Header zu "am Umschlag angeheftete Notizen", ein Cache wird zur "Tafel", ein Schloss wird zum "Schlüssel". Führe die Metapher neben dem richtigen Namen ein ("der Preis-Cache, eine Tafel neben jedem Webserver"), damit der Leser sie wieder dem Code zuordnen kann. Wechsle die Metapher nicht mitten in der Geschichte und staple nicht zwei Metaphern übereinander.
• Gib die Regel an, der jeder Charakter folgt, formuliert als den eigenen Gedanken des Charakters in kursiver Schrift: "Heute ist das Datum, das meine Uhr anzeigt." Fehler und Prozessunterbrechungen entstehen meist aus dem Aufeinandertreffen zweier vernünftiger Regeln, und dies macht den Zusammenprall später sichtbar.

Kapitel

Erzähle, was in zeitlicher Reihenfolge passiert, ein Kapitel pro Schritt: ## Kapitel 1: Ein Käufer betrachtet Preise kurz vor Mitternacht, ## Kapitel 2: Die neuen Preise treffen ein und so weiter. Kurze Titel, die sagen, was passiert.

• Halte jedes Kapitel kurz: ein paar Sätze oder ein paar Aufzählungspunkte.
• Fette das Schlüsseldetail des Kapitels – die eine Tatsache, die der Leser nicht übersehen darf ("Der Import löscht die falsche Ecke der Tafel").
• Wenn zwei Dinge gleichzeitig passieren, gib ihnen ein eigenes Kapitel und zeige beide Seiten nacheinander.
• Das Fehlerkapitel zitiert die genaue Fehlermeldung als Blockzitat und sagt, welcher Code sie abfängt und was er loggt.

Warum das Symptom so aussieht, wie es aussieht

Erkläre nach dem Fehler das beobachtete Muster: warum nur in den ersten paar Stunden, warum nur auf manchen Servern, warum nur nach einem Neustart. Verknüpfe es mit dem, was das Ticket oder die Logs tatsächlich gezeigt haben. Dies ist der Test, ob die Geschichte stimmt, also behalte ihn.

Wenn das Problem ein Risiko ist, kein Fehler

Manchmal geht es in der Geschichte um etwas, das schiefgehen könnte: ein Review-Kommentar, ein latenter Fehler, ein "Was wäre, wenn". Es ist nichts fehlgeschlagen, also gibt es keine Log-Zeile oder ein Ticket-Symptom, an dem die Geschichte verankert werden kann. Erzähle es anders, denn ein Leser, der ein zitiertes Error sieht, wird annehmen, dass es passiert ist.

• Sage früh, dass es nicht passiert ist. Stelle in der Einleitungszeile oder im ersten Kapitel klar, dass dies ein möglicher Fehler ist, der durch das Lesen des Codes gefunden wurde, nicht einer, der in Logs oder Tests gesehen wurde.
• Nenne die Bedingungen explizit. Das Fehlerkapitel listet genau auf, was wahr sein muss, damit der Fehler auftritt, als nummerierte Bedingungen ("1. Die Operation ruft einen anderen Dienst auf, nachdem der Gültigkeitsbereich geschlossen wurde, und 2. es ist kein neuer Gültigkeitsbereich um diesen Aufruf herum geöffnet"). Benenne dann, was schiefgehen würde: den Assert, den Ausnahmetyp, die Zeile. Zitiere keine Fehlermeldung, die niemand gesehen hat. Wenn du eine Ausnahme nennst, sage, dass sie aus dem Lesen des Codes stammt.
• Ersetze "Warum das Symptom so aussieht" durch "Warum es heute niemanden trifft". Gehe jeden tatsächlichen Aufrufer oder Ablauf durch und zeige, welche Bedingung er nicht erfüllt, mit Links. Dieser Abschnitt trägt das Gewicht der Geschichte, denn der Leser muss entscheiden, ob das Risiko akut ist.
• Suche nach den Aufrufern, die du nicht überprüft hast. Das Erstellen der "Wie schlimm ist es"-Liste für ein Risiko ist der Punkt, an dem ungeprüfte Pfade auftauchen: ein Aufruf außerhalb der üblichen Stelle, ein anderer Transport, eine Hintergrundaufgabe. Liste jeden als nicht überprüft auf, anstatt ihn wegzulassen, und sage, welche Beweise es gibt (z.B. ein sauberer Testlauf, der ihn ausgeführt hat, ohne ihn zu verfolgen).
• Vergleiche die Kosten im Abschnitt zur Behebung. Eine Behebung für ein Risiko kann einen echten Fehler zurückbringen. Wenn das der Fall ist, sage das deutlich: Die Behebung tauscht ein Risiko, das niemanden trifft, gegen einen Fehler ein, der auftritt.

Warum es jetzt passiert

Wenn das Verhalten eine Regression ist, sage, was sich geändert hat, wann und warum diese Änderung für sich genommen sinnvoll war. Nenne den PR oder Commit zuerst in Worten, mit der ID in Klammern. Der Leser muss wissen, dass die frühere Änderung nicht unvorsichtig war, sondern nur unvollständig.

Wie schlimm es ist

Liste die tatsächlichen Auswirkungen auf: Daten, Zahlen, Alarme, Log-Rauschen. Trenne Bestätigtes von Vermutetem, denn der Leser wird diese Behauptungen gegenüber anderen wiederholen.

• Markiere jede Behauptung als überprüft (und wie: ein Test, eine Log-Abfrage, ein Code-Pfad von Anfang bis Ende gelesen) oder als nicht überprüft.
• Schreibe nicht "die Daten sind in Ordnung", es sei denn, etwas hat es verifiziert. Eine plausible Behauptung, die sich als falsch herausstellt, kostet mehr Vertrauen als ein ehrliches "noch nicht überprüft".

Wie man es behebt

Gib die Optionen von der kleinsten bis zur größten (z.B. eine schnelle Behebung und eine richtige Behebung), was jede in der Geschichte ändert ("beide Charaktere denselben Kalender geben"), und ihre Grenzen. Schließe mit einer kurzen Empfehlung.

Stil

• Einfache Worte. Definiere jeden Begriff beim ersten Auftreten oder lass ihn weg.
• Behalte Code-Identifikatoren in Backticks neben der Metapher, damit die Geschichte nachvollziehbar zum Code bleibt.
• Bevorzuge kurze Absätze und Aufzählungspunkte gegenüber langen Textblöcken.
• Befolge die Schreibstilregeln des Nutzers aus seiner CLAUDE.md oder AGENTS.md.

Nach der Geschichte

Erwarte Folgefragen zu einem Charakter ("Also ist X der Handler?"). Beantworte sie, indem du den Charakter an den genauen Code bindest: Liste auf, was in welcher Reihenfolge läuft, mit file:line-Links, und sage, welcher Teil das tut, was wichtig ist. Wenn die Frage zeigt, dass die ursprüngliche Geschichte etwas ungenau benannt hat, korrigiere die Benennung in deiner Antwort, anstatt sie zu verteidigen.

Beispiel

references/example-stale-prices.md enthält eine vollständige Geschichte in diesem Stil für einen Stal-Cache-Fehler, plus Anmerkungen dazu, was falsch lief. Lese sie, bevor du deine erste Geschichte in einer Sitzung schreibst, um Länge und Ton zu kalibrieren.