Ramp

Was macht Ramp?

Verwandle ein Thema in einem unbekannten Repo in eine interaktive Karte: gruppierte Knoten, beschriftete Kanten, ein anklickbares Detailpanel und eine nummerierte Walkthrough, die den tatsächlichen Laufzeitablauf nachzeichnet.

Die Pipeline ist bewusst aufgeteilt. Ein statischer Durchlauf findet welche Code relevant ist, du entscheidest was er bedeutet, und ein Renderer zeichnet ihn. Den statischen Durchlauf zu überspringen und das Repository frei zu lesen ist langsamer und übersieht Dateien; deinen Durchlauf zu überspringen erzeugt einen Call-Graphen, aus dem niemand etwas lernt.

Workflow

1. Scannen

node ~/.claude/skills/ramp/scripts/scan.js <repo> --topic "<topic>" --max 30 --out /tmp/scan.json

Pfade sind absolut, weil du vom Ziel-Repo aus ausführst, nicht von hier.

Führe es zuerst ohne --topic aus, wenn du die Form des Repos noch nicht kennst – das gibt eine Übersicht mit Sprachmischung, größten Verzeichnissen und den am häufigsten importierten Dateien (Hubs), was normalerweise ausreicht, um ein gutes Thema auszuwählen.

Der Thementest gibt eine Rangliste der nodes zurück (Dateien, mit score, gefundenen Begriffen und extrahierten defs) plus edges zwischen ihnen. seed: true markiert eine direkte Übereinstimmung mit dem Thema; der Rest kam durch Graphenerweiterung hinzu und sind die Aufrufer und Aufgerufenen, die das Bild vervollständigen.

Wenn nichts zurückkommt, erscheinen die Themenbegriffe nicht im Code. Versuche die Vokabeln, die die Codebasis verwendet, anstatt die Vokabeln, die der Benutzer verwendet hat.

2. Lesen

Lies die Seed-Dateien und jeden erweiterten Knoten mit einem aussagekräftigen Namen. Lies sie gründlich – der gesamte Wert der Karte liegt in der Erklärung, und du kannst kein nützliches detail aus einer Dateiliste schreiben.

Suche beim Lesen gezielt nach:

• dem Einstiegspunkt – wo beginnt dieser Ablauf zur Laufzeit?
• dem Nicht-Offensichtlichen – der Guard, der einen Bug verhindert, das Config-Flag, das die eigentliche Arbeit macht, das, was einen Neuling überraschen würde
• der tatsächlichen Reihenfolge – was ruft was auf, in welcher Reihenfolge, zur Laufzeit

3. Modellieren

Schreibe ein Modell-JSON (Schema unten). Dies ist der Teil, der Urteilsvermögen erfordert.

4. Rendern

node ~/.claude/skills/ramp/scripts/render.js /tmp/model.json -o /tmp/<repo>-<topic>.html

Es validiert streng und weigert sich, ein defektes Modell zu rendern – unbekannte Knoten-IDs in Kanten, doppelte IDs, nicht referenzierte Walkthrough-Referenzen. Warnungen zu unerklärten oder verwaisten Knoten solltest du besser beheben als ignorieren.

5. Veröffentlichen

Veröffentliche die gerenderte Datei mit dem Artifact-Tool und gib dem Benutzer den Link. Lade nicht zuerst artifact-design – die Vorlage ist bereits entworfen; veröffentliche sie so, wie sie ist.

Modell-Schema

{
  "title": "Sign-in-Flow",
  "repo": "my-app",
  "summary": "Ein oder zwei Sätze: die Form der Sache und die einzelne nützlichste Tatsache darüber.",
  "groups": [{ "id": "boot", "label": "App-Start", "hint": "optionaler Tooltip" }],
  "nodes": [{
    "id": "provider",
    "label": "AuthProvider",
    "group": "provider",
    "role": "Besitzt Sitzungszustand",
    "detail": "Der Absatz, den ein Neuling wirklich braucht.",
    "files": ["src/context/AuthContext.jsx:12"],
    "symbols": ["AuthProvider", "signInWithGoogle"]
  }],
  "edges": [{ "from": "provider", "to": "supabase", "label": "getSession, OAuth" }],
  "walkthrough": [{ "node": "provider", "text": "Was in diesem Schritt passiert." }]
}

groups sind Spalten, von links nach rechts, in Abhängigkeitsreihenfolge – Einstiegspunkte links, Grundelemente rechts. Kanten werden vom Importeur zum Importierten gezeichnet, sodass ein Modell, dessen Gruppen dieser Reihenfolge folgen, sich sauber anordnet. Bis zu sechs Gruppen erhalten unterschiedliche Farben.

walkthrough ist optional, aber es ist die Funktion, die lehrt. Ordne sie nach Laufzeitreihenfolge, nicht nach Dateistruktur. Ein Knoten kann mehr als einmal vorkommen – Abläufe kehren zurück, und das zu zeigen ist der Punkt.

Was eine gute Karte von einer nutzlosen unterscheidet

Knoten sind Konzepte, nicht Dateien. Zwei Dateien, die eine Idee sind (AuthContext.jsx + AuthContextValue.js), können ein Knoten sein; eine Datei, die zwei nicht zusammenhängende Verantwortlichkeiten hat, kann zwei sein. Trage trotzdem jede echte Datei in files ein.

6–14 Knoten. Eine Karte mit 40 Knoten ist der Wirrwarr, den der Benutzer bereits angestarrt hat. Reduziere auf das, was den Ablauf trägt – die score-Reihenfolge des Scans sagt dir, was behalten werden soll. Sag in der summary, was du weggelassen hast.

role ist eine Aufgabe, keine Wiederholung. „Besitzt Sitzungszustand" – nicht „Auth-Provider-Komponente".

detail verdient den Klick. Gib das, was nicht offensichtlich aus dem Namen hervorgeht: warum es so aufgeteilt ist, das Flag, das zählt, den Fehler, den es verhindert, die Annahme, die es trifft. Wenn ein detail nur das Label umschreibt, lösche den Knoten oder finde heraus, was es wirklich tut.

Beschrifte jede Kante mit der tatsächlichen Beziehung – „sperrt auf Benutzer", „getSession, OAuth" – nicht „verwendet" oder „importiert".

Zitiere Zeilen. path/to/file.ts:42 in files zeigt dem Leser die genaue Stelle.

Sag, was tragend ist und was nicht. Ein Neuling muss vor allem wissen, welche Teile er ignorieren kann.

Hinweise

• Der Scan ist Node ohne Abhängigkeiten und benötigt keine Installation. Er respektiert .gitignore, wenn das Ziel ein Git-Repository ist.
• Swift und Java/C# im selben Paket haben keine Importe auf Dateiebene; für diese leitet der Scan Kanten stattdessen aus eindeutigen Typreferenzen ab. Behandle diese Kanten als starke Hinweise, nicht als Gewissheiten.
• Die Importauflösung basiert auf regulären Ausdrücken, nicht auf einem Typprüfer. Sie löst relative Pfade, Bundler-Aliase (@/) und Paket-Stil-Bezeichner durch Pfadsuffixe auf. Dynamische und generierte Importe werden übersehen – wenn eine Datei, die du erwartest, fehlt, füge sie selbst zum Modell hinzu.