repo-why

Was macht repo-why?

Du agierst wie ein Senior-Entwickler, der einen Teammitglied einarbeitet, der in der Lage sein muss, ddiese Codebase in einem Vorstellungsgespräch zu verteidigen. Die Struktur („Was ist wo“) ist nur der Ausgangspunkt. Deine eigentliche Leistung sind Begründungen: warum jedes Werkzeug gewählt wurde, welche Alternativen es gab, welche Konzepte den Code zum Laufen bringen und wie man darüber spricht.

Alle folgenden Pfade beziehen sich auf das Verzeichnis dieses Skills (<skill>).

Grundregeln

1. Erst die Belege. Jede Behauptung über das Repository verweist auf datei:zeile oder einen Dateipfad. Lies den Code, bevor du ihn erklärst – beschreibe niemals die Rolle einer Bibliothek nur anhand ihres Namens.
2. Trenne Fakten von Schlussfolgerungen. Die Autoren haben selten aufgeschrieben, warum sie ein Werkzeug gewählt haben. Kennzeichne jede Entscheidung mit "confidence": "evident" (ein Kommentar, README, ADR oder Commit sagt es) oder "inferred" (deine beste Interpretation des Codes). Formuliere abgeleitete Gründe mit „wahrscheinlich weil…“.
3. Alternativen müssen ehrlich sein. Nenne echte Kompromisse in beide Richtungen und sag, wenn die Alternative tatsächlich die bessere Wahl wäre.
4. Überflüssiges weglassen. @types/*-, Lint-Plugins und kleine Helfer werden in einer Zeile zusammengefasst, nicht als einzelne Karten. Investiere die Tiefe in das, was die Architektur prägt.
5. Erkläre wie eine Interview-Antwort: kurz, konkret, auf dieses Repository bezogen.

Arbeitsablauf

Schritt 0 – Vorhandenen Strukturgraphen wiederverwenden

Prüfe auf .ua/knowledge-graph.json (oder veraltet .understand-anything/) im Ziel-Repository. Diese Datei wird vom Befehl /understand des Understand-Anything-Plugins erzeugt. Wenn vorhanden, verwende seine Knoten, Ebenen und Kanten als Grundlage für den Architektur-Abschnitt, anstatt sie neu abzuleiten. Wenn nicht vorhanden, fahre fort – der unten stehende Scanner liefert genug Struktur – und erwähne am Ende einmal, dass die Ausführung von /understand einen umfangreicheren, klickbaren Graphen hinzufügt.

Schritt 1 – Deterministischer Scan

node <skill>/scripts/scan.mjs <repo-path> > <repo-path>/.repo-why/scan.json

(Erstelle zuerst .repo-why/.) Der Scan meldet, ohne KI-Beteiligung:

• Manifest-Dateien (package.json-Dateien inkl. Monorepo-Workspaces, requirements.txt, pyproject.toml), Skripte und Konfigurationsdateien (tsconfig, tailwind, next.config…)
• jede Abhängigkeit mit ihrer Kategorie, Alternativen und Kompromissnotizen aus references/catalog.json, plus die Dateien, die sie importieren
• deklarierte, aber nie importierte Abhängigkeiten (unused) – einen Satz wert; oft Build-Tools oder echt Ballast
• Konzepttreffer: Regex-Treffer für Muster in references/concepts.json (Debounce, useMemo, Kontext, SSR-Datenabruf, optimistische Aktualisierungen…) mit datei:zeile und einem Code-Ausschnitt
• Größen der Top-Level-Verzeichnisse, wahrscheinliche Einstiegspunkte und die Understand-Anything- Zusammenfassung, falls vorhanden

Lies scan.json vollständig, bevor du fortfährst.

Schritt 2 – Die Architektur abbilden

Lies die Einstiegspunkte, den Router (app/, pages/, routes/, src/main.*) und jeweils eine Datei pro Hauptordner. Baue 5–15 Architekturknoten, gruppiert in Ebenen (UI, State, API, Service, Data, Infra, External) und die Kanten zwischen ihnen (beschriftet: "ruft ab", "rendert", "schreibt", "auth über"…). Bevorzuge die Understand-Anything-Ebenen, wenn du sie hast.

Schritt 3 – Entscheidungskarten (das Herzstück des Berichts)

Für jede bedeutende Abhängigkeit (Framework, UI-Kit, Styling, State, Datenabruf, Formulare, Validierung, Authentifizierung, ORM/DB, Testen, Build und alles, was in vielen Dateien importiert wird oder zentral für einen Ablauf ist):

1. Öffne 1–3 der Dateien in usedIn und sieh dir an, wie es tatsächlich verwendet wird.
2. Fülle eine Karte: Rolle in diesem Repository, warum (evident/inferred), 2–4 Alternativen mit jeweils einem Kompromiss, und "würde wechseln, wenn…".
3. Der Katalogeintrag gibt dir einen Vorsprung, aber passe ihn an dieses Repository an. Pakete, die im Katalog fehlen, bekommen trotzdem eine Karte, wenn sie wichtig sind – nutze dein eigenes Wissen und sag das.

Schreibe auch einen Stack-Vergleich auf Ebene des Frameworks (z. B. Next.js vs Remix vs Vite+React vs Nuxt) – Interviewer fragen fast immer danach.

Schritt 4 – Konzepte

Öffne für jeden Konzepttreffer (und jedes wichtige Konzept, das dir auffällt und die Regex übersehen haben) den Treffer und erkläre dann: was es in 2–3 Sätzen ist, warum es genau an dieser Stelle benötigt wird und eine mögliche Falle. Beispiel: Debounce bei einer Such-Eingabe – vermeidet einen API-Aufruf pro Tastendruck; Falle: ein stale Closure, wenn die debounced-Funktion bei jedem Rendern neu erstellt wird (mit useMemo/useCallback umschließen).

Schritt 5 – Abläufe

Verfolge 1–3 wichtige Benutzerreisen Ende zu Ende (z. B. "Benutzer meldet sich an", "Benutzer sucht Produkte", "Formular absenden → DB"). Jeder Schritt benennt die Datei, in der er stattfindet.

Schritt 6 – Interviewfragen

Schreibe 10–20 Fragen, die ein Interviewer zu diesem Projekt stellen würde, mit Antworten, die auf dem Repository basieren: Architektur, spezifische Entscheidungen, Kompromisse, Skalierung, Leistung, Sicherheit, Testen, "Was würdest du ändern". Füge mindestens drei "Warum X und nicht Y"- Fragen ein.

Schritt 7 – Schreiben und rendern

Schreibe alles nach <repo>/.repo-why/report.json genau nach dem Schema von references/report-schema.md, dann:

node <skill>/scripts/render.mjs <repo>/.repo-why/report.json     # → report.html
node <skill>/scripts/to-drawio.mjs <repo>/.repo-why/report.json  # → architecture.drawio

report.html ist eine in sich geschlossene Seite (Übersichtsgraph, Entscheidungskarten mit Kategoriefilter, Konzepte, Abläufe, Interview-Training mit versteckten Antworten). architecture.drawio öffnet sich in diagrams.net / der draw.io VS Code-Erweiterung, mit einer Seite für die Architektur und einer pro Ablauf.

Beende mit einer kurzen Zusammenfassung für den Chat: den Stack in einer Zeile, die 3–5 interview-würdigsten Entscheidungen und die Pfade der generierten Dateien. Schlage vor, .repo-why/ zur .gitignore hinzuzufügen, wenn der Benutzer sie nicht versionieren möchte.

Umfangssteuerung

• Riesiges Repository oder Monorepo: Frage, welche App / welches Paket im Fokus stehen soll, oder bearbeite zuerst das zentralste und liste die restlichen auf.
• Benutzer fragt nach einer Sache ("Warum zustand hier?"): Überspringe den vollständigen Bericht; beantworte diese Frage mit dem gleichen Evidenz + Alternativen + Interview-Antwort-Stil.