Eine unbekannte Codebasis an einem Tag kennenlernen: ein Erkundungsprotokoll mit schriftlicher Karte

Ziel

Innerhalb eines Arbeitstages den Punkt erreichen, an dem eine kleine Änderung sicher gemacht werden kann: Der Code baut, die Tests laufen, der Hauptpfad ist verstanden, und alles Gelernte ist für die nächste lesende Person (oder die nächste Sitzung eines Agenten) aufgeschrieben.

Voraussetzungen

Ein Checkout, das README und der Beitragsleitfaden, eine funktionierende Toolchain sowie eine zu Beginn angelegte Kartendatei (MAP.md oder eine Notiz) mit den unten verwendeten Überschriften.

Schritte

1. Erste Stunde: die Testsuite exakt so bauen und ausführen, wie es die Dokumentation vorgibt. Jede Abweichung festhalten, die nötig war, damit es funktioniert; das sind die ersten Einträge unter „offene Fragen“.
2. Die Geschichte vor dem Code lesen. git shortlog -sn (die Dokumentation beschreibt shortlog als Zusammenfassung der Ausgabe von git log) zeigt, wer am meisten geschrieben hat; git log --stat -20 zeigt, welche Dateien gemeinsam geändert werden; git log --follow -- <path> auf eine verdächtige Datei zeigt ihre Geschichte über Umbenennungen hinweg. Die drei am häufigsten geänderten Verzeichnisse notieren.
3. Die Verzeichnisstruktur bis zur zweiten Ebene zeichnen und pro Verzeichnis eine Zeile schreiben, was es vermutlich enthält. Vermutungen mit „?“ kennzeichnen.
4. Die Einstiegspunkte finden: main, HTTP-Routen, CLI-Unterbefehle, geplante Jobs. Mit Datei und Zeile auflisten.
5. Eine repräsentative Anfrage oder einen Befehl auswählen und von Anfang bis Ende verfolgen, dabei jeden Zwischenschritt (Funktion, Datei, Zeile) in die Karte eintragen. Aufhören, sobald die Daten den Speicher erreichen oder den Prozess verlassen.
6. Das Datenmodell identifizieren: das Schema, die zentralen Typen und welche Invarianten der Code prüft (Unique Constraints, Validierung, Assertions). Die Invarianten in Worten festhalten.
7. Die Tests für den verfolgten Pfad lesen; sie beschreiben das erwartete Verhalten klarer als der Code.
8. Eine triviale Änderung vornehmen (eine Log-Zeile, ein Test, der etwas bereits Wahres behauptet), die Tests laufen lassen, dann rückgängig machen. Das beweist, dass der Kreislauf funktioniert.
9. Letzte Stunde: die Karte für eine lesende Person umschreiben, die den Code nicht gesehen hat, dabei die „?“-Markierungen und die Liste der offenen Fragen behalten. Den Commit-Hash festhalten, den die Karte beschreibt.

Erwartetes Ergebnis

Eine einseitige Karte mit Einstiegspunkten, einem nachverfolgten Pfad, dem Datenmodell und den Invarianten, den Eigenheiten des Build-Vorgangs und einer Liste offener Fragen, datiert und an einen Commit gebunden.

Grenzen und Prüfbasis

Dies ist ein vorgeschlagenes Protokoll; es wird weder eine Zeitangabe noch eine Erfolgsquote behauptet. Grosse Monorepos brauchen vor Schritt 3 eine Entscheidung über den Umfang. Generierter Code, eingebundene Abhängigkeiten (vendored dependencies) und dynamischer Dispatch machen den verfolgten Pfad unvollständig; die Karte sollte festhalten, wo die Spur verloren ging.