Code-Tour

Code Tour

Erstelle CodeTour .tour-Dateien für Codebase-Rundgänge, die direkt zu echten Dateien und Zeilenbereichen führen. Touren leben in .tours/ und sind für das CodeTour-Format gedacht, nicht für Ad-hoc-Notizen in Markdown.

Eine gute Tour ist eine Erzählung für einen bestimmten Leser:

• worauf er schaut
• warum es wichtig ist
• welchem Pfad er als Nächstes folgen soll

Erstelle nur .tour-JSON-Dateien. Ändere keinen Quellcode im Rahmen dieses Skills.

Wann verwenden

Verwende diesen Skill, wenn:

• der Benutzer nach einem Code-Rundgang, Onboarding-Tour, Architektur-Walkthrough oder PR-Rundgang fragt
• der Benutzer sagt „Erkläre, wie X funktioniert“ und ein wiederverwendbares geführtes Artefakt möchte
• der Benutzer einen Einarbeitungspfad für einen neuen Entwickler oder Reviewer wünscht
• die Aufgabe besser durch eine geführte Sequenz als durch eine flache Zusammenfassung gelöst wird

Beispiele:

• Einarbeitung eines neuen Maintainers
• Architektur-Rundgang für einen Dienst oder ein Paket
• PR-Review-Walkthrough mit Ankern in geänderten Dateien
• RCA-Rundgang, der den Fehlerpfad zeigt
• Sicherheitsreview-Rundgang über Vertrauensgrenzen und wichtige Prüfungen

Wann NICHT verwenden

Statt code-tour	Verwende
Eine einmalige Erklärung im Chat reicht aus	direkt antworten
Der Benutzer möchte Prosa-Dokumente, kein .tour-Artefakt	documentation-lookup oder Bearbeitung von Repo-Dokumenten
Die Aufgabe ist Implementierung oder Refactoring	die Implementierungsarbeit erledigen
Die Aufgabe ist ein breites Codebase-Onboarding ohne Tour-Artefakt	codebase-onboarding

Arbeitsablauf

1. Erkunden

Erkunde das Repository, bevor du etwas schreibst:

• README und Paket-/App-Einstiegspunkte
• Ordnerstruktur
• relevante Konfigurationsdateien
• die geänderten Dateien, wenn die Tour PR-fokussiert ist

Beginne nicht damit, Schritte zu schreiben, bevor du die Struktur des Codes verstanden hast.

2. Den Leser ableiten

Entscheide die Persona und Tiefe anhand der Anfrage.

Anfrageform	Persona	Vorgeschlagene Tiefe
„Onboarding“, „Neuzugang“	new-joiner	9-13 Schritte
„kurzer Rundgang“, „Stimmungscheck“	vibecoder	5-8 Schritte
„Architektur“	architect	14-18 Schritte
„Rundgang durch diesen PR“	pr-reviewer	7-11 Schritte
„Warum ist das kaputtgegangen“	rca-investigator	7-11 Schritte
„Sicherheitsreview“	security-reviewer	7-11 Schritte
„Erkläre, wie diese Funktion funktioniert“	feature-explainer	7-11 Schritte
„Debugge diesen Pfad“	bug-fixer	7-11 Schritte

3. Anker lesen und überprüfen

Jeder Dateipfad und Zeilenanker muss echt sein:

• bestätige, dass die Datei existiert
• bestätige, dass die Zeilennummern im Bereich liegen
• wenn eine Auswahl verwendet wird, überprüfe den genauen Block
• wenn die Datei flüchtig ist, bevorzuge einen Muster-basierten Anker

Rate niemals Zeilennummern.

4. Die .tour schreiben

Schreibe nach:

.tours/<persona>-<fokus>.tour

Halte den Pfad deterministisch und lesbar.

5. Validieren

Überprüfe vor dem Abschluss:

• jeder referenzierte Pfad existiert
• jede Zeile oder Auswahl ist gültig
• der erste Schritt ist an eine echte Datei oder ein echtes Verzeichnis angebunden
• das ref zeigt auf einen Branch oder Commit, der tatsächlich jede Datei enthält, auf die die Tour verweist (siehe unten)
• die Tour erzählt eine kohärente Geschichte anstatt Dateien aufzulisten

Das ref-Feld

ref bindet die Tour an einen Git-Branch oder Commit. Es ist wichtiger, als es aussieht: Wenn ref nicht der Branch ist, den der Leser ausgecheckt hat, öffnet CodeTour die Datei jedes Schritts aus dieser Revision in Git, nicht von der Festplatte. Wenn eine Datei in dieser Revision nicht vorhanden ist, wird der Schritt nicht geöffnet – der Leser sieht „Der Editor konnte nicht geöffnet werden, da die Datei nicht gefunden wurde“, obwohl die Datei direkt dort liegt. Die Tour und ihre Kommentare werden trotzdem angezeigt, sodass die eigentliche Ursache leicht übersehen wird.

Wähle ref nach Tour-Typ:

Tour-Typ	Setze ref auf
PR-Rundgang	den PR-Branch – niemals den Basis-Branch
Onboarding / Architektur	den Branch, auf dem der Leser sein wird (oft main), oder lasse ihn weg
Nicht sicher	lasse ref weg, damit CodeTour Dateien direkt von der Festplatte liest

Der PR-Fall ist die häufige Falle: Ein PR fügt normalerweise neue Dateien hinzu, und neue Dateien existieren noch nicht auf dem Basis-Branch. Zeige ref auf den Basis-Branch (z. B. develop), und jeder Schritt zu einer neuen Datei schlägt fehl.

Überprüfe vor dem Abschluss, ob die Datei jedes Schritts tatsächlich auf dem von dir gewählten ref existiert.

Schritt-Typen

Inhalt

Verwende sparsam, normalerweise nur für einen abschließenden Schritt:

{ "title": "Nächste Schritte", "description": "Du kannst nun den Anforderungspfad Ende-zu-Ende nachverfolgen." }

Mache den ersten Schritt nicht rein inhaltlich.

Verzeichnis

Verwende, um den Leser in ein Modul zu führen:

{ "directory": "src/services", "title": "Service-Ebene", "description": "Die Kernorchestrierungslogik befindet sich hier." }

Datei + Zeile

Dies ist der Standard-Schritt-Typ:

{ "file": "src/auth/middleware.ts", "line": 42, "title": "Auth-Gate", "description": "Jede geschützte Anfrage passiert zuerst diese Stelle." }

Auswahl

Verwende, wenn ein einzelner Codeblock wichtiger ist als die gesamte Datei:

{
  "file": "src/core/pipeline.ts",
  "selection": {
    "start": { "line": 15, "character": 0 },
    "end": { "line": 34, "character": 0 }
  },
  "title": "Anforderungspipeline",
  "description": "Dieser Block verbindet Validierung, Authentifizierung und nachgelagerte Ausführung."
}

Muster

Verwende, wenn genaue Zeilen sich verschieben könnten:

{ "file": "src/app.ts", "pattern": "export default class App", "title": "Anwendungseinstieg" }

URI

Verwende für PRs, Issues oder Dokumentation, wenn hilfreich:

{ "uri": "https://github.com/org/repo/pull/456", "title": "Der PR" }

Schreibregel: SMIG

Jede Beschreibung sollte beantworten:

• Situation: worauf der Leser schaut
• Mechanismus: wie es funktioniert
• Implikation: warum es für diese Persona wichtig ist
• Gotcha: was ein kluger Leser übersehen könnte

Halte Beschreibungen kompakt, spezifisch und im tatsächlichen Code verankert.

Erzählstruktur

Verwende diesen Bogen, es sei denn, die Aufgabe erfordert eindeutig etwas anderes:

1. Orientierung
2. Modulübersicht
3. Kernausführungspfad
4. Randfall oder Fallstrick
5. Abschluss / nächster Schritt

Die Tour sollte sich wie ein Pfad anfühlen, nicht wie ein Inventar.

Beispiel

{
  "$schema": "https://aka.ms/codetour-schema",
  "title": "API-Service-Rundgang",
  "description": "Walkthrough des Anforderungspfads für den Zahlungsdienst.",
  "ref": "main",
  "steps": [
    {
      "directory": "src",
      "title": "Quellwurzel",
      "description": "Der gesamte Laufzeitcode des Dienstes beginnt hier."
    },
    {
      "file": "src/server.ts",
      "line": 12,
      "title": "Einstiegspunkt",
      "description": "Der Server startet hier und verbindet Middleware, bevor eine Route erreicht wird."
    },
    {
      "file": "src/routes/payments.ts",
      "line": 8,
      "title": "Zahlungsrouten",
      "description": „Jede Zahlungsanfrage tritt über diesen Router ein, bevor sie die Servicelogik erreicht.“
    },
    {
      "title": "Nächste Schritte",
      "description": "Du kannst nun jede Zahlungsanfrage Ende-zu-Ende verfolgen, während die Hauptanker gesetzt sind."
    }
  ]
}

Anti-Patterns

Anti-Pattern	Lösung
Flache Dateiauflistung	Erzähle eine Geschichte mit Abhängigkeiten zwischen den Schritten
Allgemeine Beschreibungen	Benenne den konkreten Codepfad oder das Muster
Geratene Anker	Überprüfe zuerst jede Datei und Zeile
Zu viele Schritte für einen kurzen Rundgang	Schneide aggressiv
Erster Schritt ist nur Inhalt	Verankere den ersten Schritt an einer echten Datei oder einem echten Verzeichnis
Persona-Fehlpassung	Schreibe für den tatsächlichen Leser, nicht für einen generischen Entwickler

Best Practices

• Halte die Schrittanzahl proportional zur Repository-Größe und Persona-Tiefe
• Verwende Verzeichnisschritte zur Orientierung, Dateischritte für Substanz
• Decke bei PR-Rundgängen zuerst die geänderten Dateien ab
• Bei Monorepos beschränke dich auf die relevanten Pakete, anstatt alles zu bereisen
• Schließe mit dem ab, was der Leser jetzt tun kann, nicht mit einer Zusammenfassung

Verwandte Skills

• codebase-onboarding
• coding-standards
• council
• Offizielles Upstream-Format: microsoft/codetour