whyso — Was git blame nicht zeigt

git blame zeigt, wer, wann und was geändert hat. whyso zeigt, warum.

Das Problem

Wenn man verstehen will, warum eine Codezeile so aussieht, wie sie aussieht, bleibt einem git blame und die Commit-Nachrichten. Das ist alles.

$ git blame internal/handler/page.go
a3f1b2c (parkjunwoo 2026-03-08) func CreatePage(c *gin.Context) {

Wer, wann und was geändert hat – das sieht man. Warum geändert wurde – das sieht man nicht.

Man könnte den Grund in die Commit-Nachricht schreiben, klar. Aber die Realität sieht so aus:

fix: update handler
refactor: clean up
wip

Gute Commit-Nachrichten zu schreiben ist eine Frage der Disziplin. Egal wie gut das Team seine Konventionen aufstellt – wer um drei Uhr morgens einen Bug behebt, denkt selten daran, den Kontext und die Begründung der Änderung sorgfältig festzuhalten.

Im Zeitalter des AI-Codings ist das anders. Der Grund für eine Änderung ist bereits dokumentiert.

Die Sitzungsdaten von Claude Code

Claude Code speichert alle Gespräche als JSONL-Dateien unter ~/.claude/projects/. Jeder Eintrag enthält die Nutzernachricht, die AI-Antwort, tool_use-Aufrufe (Write, Edit, Bash) und eine parentUuid-Kette, die alles miteinander verbindet.

Nutzer: "Fang mit der Implementierung des whyso validate-Befehls an"
  → AI: Write internal/crosscheck/crosscheck.go
    → AI: Edit internal/crosscheck/crosscheck.go
      → AI: "Initiales crosscheck-Paket erstellt — SSaC↔OpenAPI operationId-Matching-Validierung"

Warum eine Datei erstellt wurde, warum sie geändert wurde – das alles steckt im Gespräch selbst. Das ist reichhaltiger als Commit-Nachrichten und muss nicht bewusst verfasst werden. Wer das Gespräch geführt hat, hat es automatisch dokumentiert.

whyso parst diese Daten und extrahiert daraus die Änderungshistorie pro Datei.

Das gesamte Leben einer Datei

file: internal/crosscheck/crosscheck.go
created: 2026-03-08T14:23:01Z
history:
  - timestamp: 2026-03-08T14:23:01Z
    session: 09351222-d7be-41fe-994f-87c2d7067e5d
    user_request: "Fang mit der Implementierung des whyso validate-Befehls an"
    answer: "Initiales crosscheck-Paket erstellt — SSaC↔OpenAPI operationId-Matching-Validierung"
    tool: Write

  - timestamp: 2026-03-09T10:15:33Z
    session: 4e9b4e5e-3a50-43f2-be6e-e5db228ecc3b
    user_request: "Validierung hinzufügen, ob x-sort-Spalte im DDL vorhanden ist"
    answer: "x-sort/x-filter-Spalten → DDL-Kreuzvalidierung hinzugefügt"
    tool: Edit

  - timestamp: 2026-03-10T09:41:22Z
    session: b2e43b4f-cb21-4286-975d-1eb9de8a16c0
    user_request: "Auch Func-Spec-Kreuzvalidierung hinzufügen"
    answer: "@call ↔ Func spec Argument-Anzahl/Typ-Kreuzvalidierung hinzugefügt"
    tool: Edit

Warum die Datei entstanden ist, auf welche Anforderung hin sie sich wie weiterentwickelt hat – das gesamte Leben einer Datei wird sichtbar.

Warum das notwendig ist

Die Lücke im Code-Review

Beim Review eines Pull Requests kommt unweigerlich die Frage: „Warum wurde das geändert?" Fehlt die Begründung in der Commit-Nachricht, muss man beim Autor nachfragen. Kann der Autor sich nicht mehr erinnern, muss man den Code erneut lesen und rückschließen.

In einer AI-Coding-Umgebung steckt die Antwort auf diese Frage in den Sitzungsdaten. whyso holt sie heraus.

Onboarding

Der schnellste Weg für ein neues Teammitglied, eine Codebasis zu verstehen, ist zu wissen, „warum der Code so geworden ist". git log ist eine chronologische Auflistung von Änderungen, Dokumentation ist ein Snapshot des aktuellen Zustands. whyso zeigt den Raum dazwischen – die Kette der Absichten.

Persönliche Dokumentation

Selbst beim Solo-Entwickeln kommt der Moment, in dem man sich nicht mehr erinnert, warum man vor drei Monaten eine bestimmte Entscheidung getroffen hat. whyso rekonstruiert das Gespräch zwischen dem früheren Ich und der AI. Der Kontext, der nie in die Commit-Nachricht geflossen ist, steckt dort.

Das Verhältnis zu git blame

whyso ersetzt git blame nicht. Es ergänzt es.

Wenn git blame das commit-basierte „offizielle Protokoll" ist, dann ist whyso das gesprächsbasierte „Arbeitstagbuch". Kontext, der im offiziellen Protokoll keinen Platz fand, ist im Arbeitstagbuch festgehalten.

Eine Struktur, in der AI ihre eigenen Aufzeichnungen liest

Der interessanteste Anwendungsfall von whyso ist, dass nicht ein Mensch, sondern die AI selbst die Aufzeichnungen liest.

Claude Code vergisst nach Ende einer Sitzung alles. Wenn das gleiche Projekt in der nächsten Sitzung geöffnet wird, ist alles weg: warum gestern etwas so gebaut wurde, welche Alternativen erwogen und verworfen wurden, in welchem Kontext der Nutzer die Anforderung gestellt hatte. Der Code wird gelesen und Schlussfolgerungen werden gezogen.

Stell dir vor, man fügt eine Zeile in CLAUDE.md ein:

Vor jeder Dateiänderung `whyso history <file>` ausführen. Falls eine Historie vorhanden ist, diese lesen, bevor geändert wird.

Was diese eine Zeile verändert:

Man weiß, welche Änderungen nicht rückgängig gemacht werden dürfen

Man liest eine Datei vor der Bearbeitung und findet einen Code, der seltsam aussieht. Rein aus dem aktuellen Zustand würde man sagen: „Ist das ein Fehler?" und es korrigieren wollen. Aber wenn die whyso-Historie vermerkt: „Der Nutzer hat diese Struktur ausdrücklich angefordert, aus Gründen der Lesbarkeit, nicht der Performance" – dann lässt man es unangetastet.

Man schlägt verworfene Alternativen nicht erneut vor

In einer früheren Sitzung gab es das Gespräch: „Sollen wir Ansatz A versuchen?" → „Nein, lass uns B nehmen." Die AI der neuen Sitzung weiß das nicht und schlägt A erneut vor. Für den Nutzer ist das frustrierend. Mit whyso weiß man, welche Richtungen bereits geprüft und abgelehnt wurden.

Man knüpft nahtlos an laufende Aufgaben an

„Mach bitte den gestrigen Refactoring-Schritt weiter" – aktuell muss man den Diff lesen und rückschließen. Mit einer whyso-Historie liest man sofort, was der Nutzer in der gestrigen Sitzung angefragt hat und auf welcher Basis die AI ihre Entscheidung getroffen hat. Statt Rückschlüssen gibt es faktenbasierte Fortsetzung.

Aufzeichnungen häufen sich sitzungsübergreifend an

Mit dieser Struktur wächst die whyso-Historie mit jeder Sitzung. Der Grund für eine Änderung in der aktuellen Sitzung wird der AI der nächsten Sitzung übergeben. Das Problem des fehlenden sitzungsübergreifenden Gedächtnisses wird auf Dateiebene gelöst – ohne ein gesondertes Memory-System.

Was whyso festhält, wurde von der AI getan. Aber die AI erinnert sich nicht daran. Die eigene Aufzeichnung, die man selbst am dringendsten benötigt. Das ist der einzigartige Punkt, an dem whyso mit AI-Coding-Tools zusammenwirkt.

Für Menschen ist whyso „ein Tool, das automatisch gute Commit-Nachrichten hinterlässt". Für die AI ist whyso sitzungsübergreifendes Gedächtnis.

Verwendung

Installation

go install github.com/park-jun-woo/whyso/cmd/whyso@latest

Dateihistorie abfragen

# Einzelne Datei
whyso history README.md

# Gesamtes Verzeichnis
whyso history internal/ --all

# Ausgabe mit gespiegelter Dateistruktur
whyso history . --all --output .file-histories/

# JSON-Format
whyso history README.md --format json

Sitzungsliste

whyso sessions

So funktioniert es

Rückverfolgung der parentUuid-Kette

Jeder Eintrag in der JSONL-Datei ist über uuid und parentUuid verbunden. Wenn man von einem tool_use, das eine Datei verändert hat, die parentUuid-Kette zurückverfolgt, gelangt man zur ursprünglichen Nutzeranfrage, die diese Änderung ausgelöst hat.

user message (uuid: A)          ← "Validierung hinzufügen, ob x-sort-Spalte im DDL vorhanden ist"
  → assistant tool_use (parentUuid: A)
    → tool_result (parentUuid: B)
      → assistant Edit (parentUuid: C)  ← Grund dieser Änderung = A

Da zwischendurch Nachrichten vom Typ tool_result auftauchen, extrahiert man nur solche mit type == "user" und textuellen content-Werten, um die echten Nutzeranfragen zu finden.

Design-Entscheidungen

Nur Write/Edit werden verfolgt. Write und Edit tool_use von Claude Code enthalten explizit den Dateipfad und die Änderung. Dateioperationen in Bash-Befehlen (rm, mv, cp) werden heuristisch erkannt, aber Write/Edit sind die primären Verfolgungsziele. Da Claude Code dafür konzipiert ist, Dateien über Write/Edit zu bearbeiten, werden mit diesen beiden Tools nahezu alle Änderungen erfasst.

Sub-Agents werden einbezogen. Wenn Claude Code komplexe Aufgaben bearbeitet, kann es Sub-Agents erstellen. Die Sitzungen dieser Sub-Agents werden unterhalb des übergeordneten Sitzungsverzeichnisses gespeichert. whyso parst auch diese Sub-Agent-Sitzungen und erstellt so eine vollständige Historie.

Inkrementelle Aktualisierung. Beim Ausgeben in ein Verzeichnis mit der --output-Option werden bereits geparste Sitzungen übersprungen. Auch wenn die Sitzungen auf Hunderte anwachsen, wird nicht jedes Mal alles neu geparst.

Zahlen

Ergebnis der Verfolgung der whyso-Eigenentwicklung mit whyso:

Aus 17 Sitzungen wurde die Änderungshistorie von 480 Dateien extrahiert. Für jede Datei ist festgehalten, warum sie erstellt wurde und warum sie sich verändert hat.

Einschränkungen

• Nur für Claude Code. Andere AI-Coding-Tools verwenden andere Sitzungsdatenformate. Aktuell wird nur das JSONL-Format von Claude Code unterstützt.
• Nur Textdateien werden verfolgt. Write/Edit tool_use zielt auf Textdateien ab. Änderungen an Bildern und Binärdateien werden nicht verfolgt.
• Die Sitzungsdaten müssen lokal vorhanden sein. Die Sitzungsdateien müssen unter ~/.claude/projects/ liegen. Wurden sie gelöscht oder auf einem anderen Rechner erstellt, sind diese Aufzeichnungen nicht vorhanden.

Fazit

Im Zeitalter des gemeinsamen Schreibens von Code mit einer AI müssen die Gründe für Änderungen nicht länger allein von Commit-Nachrichten abhängen. Das Gespräch selbst ist die Dokumentation, und aus dieser Dokumentation lässt sich die Änderungshistorie pro Datei automatisch extrahieren.

Wenn git blame zeigt „wer, wann und was geändert hat", zeigt whyso „warum geändert wurde".

Code: github.com/park-jun-woo/whyso