Code-Tour

Code Tour

Erstelle CodeTour .tour-Dateien für Codebase-Walkthroughs, die direkt zu echten Dateien und Zeilenbereichen öffnen. Touren leben in .tours/ und sind für das CodeTour-Format gedacht, nicht für ad-hoc Markdown-Notizen.

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

• was er sich ansieht
• warum es wichtig ist
• welchen Pfad er als Nächstes verfolgen sollte

Erstelle nur .tour-JSON-Dateien. Ändere im Rahmen dieser Skill keinen Quellcode.

Wann verwenden

Verwende diese Skill, wenn:

• der Benutzer nach einer Code-Tour, Onboarding-Tour, Architektur-Walkthrough oder PR-Tour 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 benötigt
• die Aufgabe besser durch eine geführte Sequenz als durch eine flache Zusammenfassung gelöst wird

Beispiele:

• Einarbeitung eines neuen Maintainers
• Architektur-Tour für einen Dienst oder ein Paket
• PR-Review-Walkthrough, verankert an geänderten Dateien
• RCA-Tour, die den Fehlerpfad zeigt
• Sicherheits-Review-Tour über Vertrauensgrenzen und wichtige Prüfungen

Wann NICHT verwenden

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

Workflow

1. Entdecken

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

Bestimme die Persona und Tiefe aus der Anfrage.

Anfrageform	Persona	Empfohlene Tiefe
„Onboarding“, „neuer Mitarbeiter“	new-joiner	9–13 Schritte
„kurze Tour“, „Vibe-Check“	vibecoder	5–8 Schritte
„Architektur“	architect	14–18 Schritte
„Tour durch diesen PR“	pr-reviewer	7–11 Schritte
„Warum ist das kaputtgegangen“	rca-investigator	7–11 Schritte
„Sicherheits-Review“	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. Lesen und Verweise prüfen

Jeder Dateipfad und Zeilenanker muss echt sein:

• bestätige, dass die Datei existiert
• bestätige, dass die Zeilennummern im gültigen Bereich liegen
• wenn du eine Auswahl verwendest, überprüfe den exakten Block
• wenn die Datei flüchtig ist, bevorzuge einen muster-basierten Anker

Rate niemals Zeilennummern.

4. Die .tour schreiben

Schreibe in:

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

Halte den Pfad deterministisch und lesbar.

5. Validieren

Bevor du abschließt:

• jeder referenzierte Pfad existiert
• jede Zeile oder Auswahl ist gültig
• der erste Schritt ist an einer echten Datei oder einem echten Verzeichnis verankert
• das ref zeigt auf einen Branch oder Commit, der tatsächlich jede von der Tour referenzierte Datei enthält (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 den Dateien auf der Festplatte. Wenn eine Datei in dieser Revision nicht existiert, wird der Schritt nicht geöffnet – der Leser sieht „Der Editor konnte nicht geöffnet werden, weil 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 werden kann.

Wähle ref nach Tour-Typ:

Tour-Typ	Setze ref auf
PR-Tour	den PR-Branch – niemals den Basis-Branch
Onboarding / Architektur	den Branch, auf dem der Leser sein wird (oft main), oder lasse ihn weg
Unsicher	lasse ref weg, damit CodeTour die 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.

Bestätige vor dem Abschluss, dass die Datei jedes Schritts tatsächlich in 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 Anfragepfad Ende-zu-Ende verfolgen." }

Mache den ersten Schritt nicht nur inhaltsbasiert.

Verzeichnis

Verwende, um den Leser zu einem Modul zu führen:

{ "directory": "src/services", "title": "Service-Schicht", "description": "Die Kern-Orchestrierungslogik befindet sich hier." }

Datei + Zeile

Dies ist der Standard-Schritttyp:

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

Auswahl

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

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

Muster

Verwende, wenn genaue Zeilen variieren können:

{ "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: Was der Leser sich ansieht
• Mechanismus: Wie es funktioniert
• Implikation: Warum es für diese Persona wichtig ist
• Gotcha: Was ein kluger Leser übersehen könnte

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

Narrative Struktur

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

1. Orientierung
2. Modulübersicht
3. Kernausführungspfad
4. Randfall oder Gotcha
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-Tour",
  "description": "Walkthrough des Anfragepfads 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 mit den wichtigsten Ankern verfolgen.“
    }
  ]
}

Anti-Patterns

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

Best Practices

• Halte die Schrittanzahl proportional zur Repo-Größe und Persona-Tiefe
• Verwende Verzeichnisschritte zur Orientierung, Dateischritte für Substanz
• Für PR-Touren behandle zuerst geänderte Dateien
• In Monorepos beschränke auf die relevanten Pakete, anstatt alles zu touren
• Schließe mit dem, was der Leser jetzt tun kann, nicht mit einer Zusammenfassung

Verwandte Skills

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