bughunt

Was macht bughunt?

Unit-Tests und die meisten UI-Tests prüfen die Codepfade, die sich ihre Autoren ausgedacht haben, oft über Test-Hooks, die echte Klicks und Tastatureingaben überspringen. Menschen nutzen eine App nicht so. Sie klicken dorthin, wo der Hook nicht hinkommt, drücken nach allem Rückgängig, arbeiten in einem schmalen Fenster, verlieren mitten im Prozess die Netzwerkverbindung und öffnen die seltsame Datei, die ein Kollege geschickt hat. Die meisten Fehler, auf die sie stoßen, waren schon da – und niemand hat hingesehen.

Diese Fertigkeit sieht hin. Sie steuert die echte App mit echten Eingaben, Bereich für Bereich, und zeichnet jeden bestätigten Fehler doppelt auf: als fehlschlagenden Test, der im Repository bleibt, damit der Fehler nicht unbemerkt zurückkehren kann, und als Eintrag in der Fehlerliste des Repositorys, damit jemand ihn behebt. Eine Jagd ändert keinen Produktivcode. Sie findet, beweist und schreibt auf.

Modi

• Jagd (Standard): Wähle einen Bereich aus, jage ihn, zeichne die Ergebnisse auf, aktualisiere die Rotation. Ein Bereich pro Durchlauf stellt sicher, dass eine Jagd tief genug ist, um echte Fehler zu finden.
• Einrichten: Das Repository hat keine Möglichkeit, die App Ende-zu-Ende zu steuern, oder es fehlen die Grenzen in references/boundaries.md. Erstelle die kleinste Walkthrough-Bahn, die eine Funktion auf jeder Oberfläche ausführen kann (references/walkthroughs.md), und jage dann.
• Sweep: Führe jeden vorhandenen Walkthrough aus und berichte, was seit dem letzten Durchlauf neu, geändert oder behoben wurde. Ein Sweep findet Regressionen, keine neuen Fehlerarten; kombiniere ihn mit Jagden.
• Regeln: Füge eine der Regeln aus references/invariants.md zur Bahn hinzu, sodass sie bei jedem Schritt jedes Walkthroughs läuft. Eine einzige Regel (z.B. „Rückgängig stellt den exakten vorherigen Zustand wieder her“) kann dutzende Fehler in Funktionen aufdecken, auf die niemand Skripte schreiben würde.

1. Lerne zuerst die Grundregeln kennen

Lies die Anweisungsdateien des Repositorys (CLAUDE.md, AGENTS.md, CONTRIBUTING, alle Regeln oder Übergabenotizen), die README der App und die vorhandenen End-to-End-Tests. Finde heraus:

• Wie jede Oberfläche der App gestartet wird: Entwicklungsserver, Desktop-Build, mobiler Simulator. Eine Oberfläche ist ein Host (Web, Desktop, Mobil) in einem Look (Hell, Dunkel, Hoher Kontrast) bei einer Größe (Breit, Schmal, Telefon).
• Wo Fehler verfolgt werden (eine Fehlerdatei, eine Aufgabenliste, ein Issue-Tracker) und welches Format die Einträge dort haben. Schreibe in diesem Format.
• Was ein Test niemals berühren darf: echte Konten, echte Benutzerdateien, Produktionsdaten, echte E-Mails, Zahlungen, die Zwischenablage des Benutzers, Drucker und Browser, die installierte Kopie der App. Lese references/boundaries.md und setze jede geltende Grenze um, bevor du etwas steuerst. Dies ist der Teil einer Jagd, der echten Schaden anrichten kann, also kommt er zuerst.
• Ob das Repository etwas anderes verbietet (Pushen, Netzwerkzugriff, kostenpflichtige Dienste, Starten von Agenten). Diese Regeln haben Vorrang vor dieser Fertigkeit.

Frage nur, wenn die Antwort ändert, was du berühren darfst. Ansonsten entscheide und notiere die Annahme im Jagdbericht.

2. Wähle den Bereich aus und liste auf, was er tut

Verwende den Bereich, den die Person genannt hat. Ansonsten lies bughunt/areas.md (erzeuge es beim ersten Durchlauf aus templates/areas.md) und wähle in dieser Reihenfolge: einen Bereich, der noch nie gejagt wurde, dann einen, der seit seiner letzten Jagd geändert wurde (git log auf seinen Pfaden), dann den ältesten. Ein Bereich ist eine Menge von Funktionen, die eine Person gemeinsam nutzt: der Dokumenteneditor, der Dateibrowser, Anmeldung und Konten, Einstellungen, Teilen, Zahlungen.

Liste die Funktionen des Bereichs aus dem Repository auf: einer Funktionsregistrierung, den Menüs und der Befehlsliste, Routen, den Hilfeseiten, den Einstiegspunkten des Codes. Jede Funktion erhält mindestens einen Durchlauf auf jeder Oberfläche.

3. Jagen

Führe für jede Funktion zuerst das aus, was eine Person damit tut, von Anfang bis Ende, mit realistischen synthetischen Dateien. Arbeite dann die references/checklist.md durch. Sie ist eine Liste von Aktionen feindseliger Benutzer, die Apps immer wieder zum Scheitern bringen: Rückgängig nach jedem Schritt, nur Tastatur, schmales Fenster, Dark Mode, mittendrin offline, die größte und die kaputteste Datei, ein Roundtrip durch ein anderes Format, dasselbe in zwei Tabs, ein absichtlicher Fehler.

Steuere die App mit echten Eingabeereignissen (Klicks, Tastendrücke, Ziehen, Tippen) in menschlichem Tempo. Ein Skript handelt schneller als ein Mensch, also gib einem Klick eine kurze Pause vor der nächsten Aktion und lasse eine halbe Sekunde zwischen zwei Änderungen, die du getrennt rückgängig machen erwartest. Sonst dokumentierst du Timing-Artefakte als Fehler.

Beobachte jeden Schritt auf:

• das falsche Ergebnis oder ein richtiges Ergebnis, das nicht bestehen bleibt (verschwunden nach Neuladen, Speichern, Rückgängig oder Tab-Wechsel)
• verlorene Arbeit: Änderungen, Einstellungen, Auswahl, Scrollposition
• Rückgängig, das zu viel, zu wenig oder nichts rückgängig macht
• einen Befehl, der nichts tut, nur von einem seiner Einstiegspunkte funktioniert oder nicht deaktiviert ist, wenn er nicht ausgeführt werden kann
• rohen Fehlertext: Stacktraces, Fehlercodes, interne Pfade
• Konsolenfehler, Abstürze, leere Fenster, Hänger
• Text, der zu blass, beschnitten, überlappend oder mitten im Wort gebrochen ist (die Screenshot-Prüfungen in references/invariants.md fangen das meiste davon automatisch)
• denselben Schritt, der sich auf einer anderen Oberfläche anders verhält

Notiere jeden Kandidaten, wenn du ihn siehst, mit der Oberfläche, dem Schritt und deiner Erwartung. Fahre dann fort; bestätige am Ende der Funktion.

4. Bestätige, bevor du dokumentierst

Eine Jagd ist nur so gut wie ihre Ergebnisse wahr sind. Für jeden Kandidaten:

1. Reproduziere ihn zweimal aus einem sauberen Zustand in menschlichem Tempo, manuell oder mit einem minimalen Skript. Wenn er sich nicht reproduzieren lässt, verwirf ihn oder dokumentiere ihn als „Unbestätigt:“ mit deiner Beobachtung und dem Ort.
2. Schließe den Test als Ursache aus. Timing (siehe oben), ein Selektor, der das falsche Element traf, die eigenen Stubs des Tests, ein Fenster, das nicht fokussiert war, der Mauszeiger, der auf etwas mit Hover-Zustand ruhte. Ein Ergebnis, das mit der Mausposition kommt und geht, ist real, benötigt aber eine feste Zeigerposition in seinem Test.
3. Finde die Ursache, wenn es günstig ist. Lies den Code an der wahrscheinlichen Stelle und nenne die Datei und Funktion. Verbringe nicht viel Zeit damit; der Beheber wird es tun.
4. Überprüfe den Tracker. Wenn ein Eintrag es bereits abdeckt, füge die neue Oberfläche oder das Detail zu diesem Eintrag hinzu, anstatt einen neuen zu erstellen.
5. Gruppiere nach Ursache. Mehrere Symptome teilen sich oft eine Ursache (eine fehlende Tastenkombination kann Rückgängig in fünf Editoren auf einem Host brechen). Sage dies, damit die Behebung einmal erfolgt.

5. Zeichne jeden bestätigten Fehler auf

• Zuerst ein fehlschlagender Test. Füge einen Schritt zum Walkthrough der Funktion (oder einem neuen Walkthrough) hinzu, dessen Erwartung den Soll-Zustand beschreibt. Führe ihn aus und überprüfe, dass er fehlschlägt, und zwar aus dem Grund des Fehlers, nicht aus einem anderen. Er besteht, sobald der Fehler behoben ist. Schwäche niemals eine bestehende Erwartung oder Screenshot-Prüfung, damit ein Durchlauf bestanden wird. Wenn eine Prüfung falsch ist, erkläre den Grund im Bericht und lasse sie für eine Person stehen.
• Dann der Fehlereintrag am Ende der Fehlerliste des Repositorys in seinem Format unter Verwendung von templates/bug-entry.md: das Symptom in den Worten eines Benutzers, was passiert gegenüber dem, was passieren sollte, die gemessenen Zahlen, wo im Code, welcher Test ihn schützt und auf welchen Oberflächen er auftritt.
• Keine Produktivcode-Änderungen während einer Jagd, es sei denn, die Person hat Korrekturen erbeten. Das Reparieren während der Jagd verbirgt das Ergebnis und vermischt zwei Arten von Überprüfungen.
• Übermittle die neuen Tests und die Fehlereinträge, wenn die Regeln des Repositorys es erlauben, und stage die Dateien nach Namen. Pushe nicht, es sei denn, die Person hat es gesagt.

6. Berichten und rotieren

Schreibe den Jagdbericht aus templates/hunt-report.md: der Bereich, die Oberflächen, jedes Ergebnis mit seinem Test und Eintrag, die Kandidaten, die du verworfen hast und warum, was du nicht testen konntest, und vorgeschlagene Korrekturgruppen nach Ursache. Aktualisiere die Zeile des Bereichs in bughunt/areas.md (Datum, Commit, Ergebnisse).

Beende den Bericht, indem du der Person in einfacher Sprache sagst: wie viele Fehler bestätigt wurden, die schlimmsten drei, die Korrekturgruppen und den nächsten Bereich, den die Rotation auswählen würde.

Finde sie weiterhin

Eine abgeschlossene Jagd hinterlässt Tests, die dieselben Fehler abfangen, wenn sie zurückkommen. Neue Fehler erfordern neues Hinsehen:

• Jage erneut in Rotation. Jage einen Bereich nach großen Änderungen erneut.
• Mache einen Fehler, der immer wieder an neuen Stellen auftaucht, zu einer Regel (references/invariants.md), sodass jeder Schritt ihn prüft.
• Jeder Fehler, den eine Person meldet, wird vor seiner Behebung zu einem Walkthrough-Schritt.
• Führe die gesamte Bahn vor jeder Veröffentlichung und, wenn das Repository einen Planer erlaubt, jede Nacht aus. Berichte nur über neue und geänderte Fehlschläge, damit ein bekannter Fehler keinen neuen begräbt.

Wenn die Arbeit umfangreich ist

Wenn du die Arbeit auf mehrere Modelle oder Sitzungen aufteilen kannst, jage mit deinem stärksten Modell und bestätige mit einem anderen in einer neuen Sitzung. Der zweite Durchlauf führt jeden fehlschlagenden Test aus einem sauberen Zustand erneut aus und liest jeden Eintrag kalt. Das fängt die übermütigen falsch-positiven Ergebnisse, die ein einzelner Durchlauf tendenziell behält.