code-tour

Überblick über den code-tour skill

Was code-tour erstellt

Der code-tour skill hilft einem AI Agent dabei, CodeTour-.tour-JSON-Dateien für die VS Code CodeTour extension zu erstellen. Eine Tour ist eine geführte Schritt-für-Schritt-Erkundung, die Erklärungen mit echten Dateien und Zeilennummern verknüpft und normalerweise unter .tours/ gespeichert wird. Der Skill ist für die strukturierte Erkundung von Repositories gedacht, nicht für Codeänderungen: Seine zentrale Grenze ist, ausschließlich Tour-Dateien zu erstellen und keinen Source Code zu verändern.

Am besten geeignet für Technical Writing und Onboarding

Setze code-tour für Technical Writing ein, wenn du einen Onboarding-Pfad, einen Contributor Guide, einen Architektur-Walkthrough, eine PR-Review-Tour, einen Security-Review-Pfad, eine Root-Cause-Analysis-Spur oder einen „So funktioniert das“-Walkthrough brauchst. Am stärksten ist der Skill, wenn die Leserschaft klar definiert ist: neue Backend Engineers, Frontend Maintainer, Reviewer, Incident Responder, Staff Engineers oder nicht-technische Stakeholder, die einen kuratierten Weg durch Implementierungsdetails benötigen.

Warum das mehr leistet als ein generischer Prompt

Ein generischer Prompt fasst Dateien möglicherweise nur grob zusammen. Der code-tour skill lenkt den Agenten auf ein nutzbares Ergebnis: erzählerische, auf eine Persona zugeschnittene Schritte mit konkreten Datei- und Zeilenankern. Das ist wichtig, weil eine Tour in VS Code navigierbar sein muss, vorhandene Pfade referenzieren muss und erklären sollte, warum jeder Halt relevant ist, statt nur eine Ordnerzusammenfassung auszugeben. Das nützliche Ergebnis ist nicht „was im Repo liegt“, sondern „wo diese Leserin oder dieser Leser zuerst klicken sollte, was danach kommt und warum“.

Was vor der Installation zu beachten ist

Der Skill hat ein fokussiertes SKILL.md und keine zusätzlichen Scripts, Regeln oder Reference Packs. Dadurch ist code-tour install leichtgewichtig, zugleich hängt die Qualität aber stark vom Repository-Zugriff und von der Genauigkeit des Prompts ab. Am besten funktioniert der Skill, wenn der Agent den File Tree, README.md, Konfigurationsdateien und Source-Einstiegspunkte untersuchen kann. Weniger geeignet ist er, wenn du ausschließlich Fließtext-Dokumentation, Mermaid-Diagramme, Source Edits oder eine Tour für Dateien möchtest, die der Agent nicht lesen kann.

So verwendest du den code-tour skill

code-tour install und Repository-Kontext

Installiere den Skill aus dem Source Repository mit deinem Skills-Tooling, zum Beispiel:

npx skills add alirezarezvani/claude-skills --skill code-tour

Prüfe nach der Installation bei Bedarf den Skill-Pfad: engineering/code-tour/skills/code-tour/SKILL.md. Im Zielprojekt sollte der Agent zuerst das Root-Verzeichnis, README.md, Package- oder Build-Konfiguration sowie die obersten ein bis zwei Ordnerebenen untersuchen, bevor er mit dem Entwurf beginnt. Die Tour sollte als .tour-JSON-Datei unter .tours/ gespeichert werden und mit der VS Code CodeTour extension kompatibel sein.

Welche Eingaben der Skill braucht

Für eine gute code-tour usage solltest du fünf Dinge angeben: Zielgruppe, Ziel, Umfang, gewünschte Tiefe und alle Dateien oder Feature-Namen, die einbezogen werden müssen. Schwache Anfrage: „make a tour of this repo.“ Starke Anfrage: „Create a CodeTour for a new backend engineer explaining the request lifecycle for login, from route registration through validation, service logic, database access, and error handling. Keep it to 8–12 steps and anchor every step to real files and lines.“

Wenn die Tour für Technical Writing gedacht ist, ergänze den Veröffentlichungszweck: Onboarding-Dokumentation, Unterstützung für Release Notes, interner Architekturleitfaden, Review-Hilfe oder Lernartefakt nach einem Incident.

Empfohlener Ablauf für die erste Tour

Beginne mit Discovery, nicht mit dem Schreiben. Bitte den Agenten zuerst, Projektzweck, Sprachen, Frameworks, Einstiegspunkte und wichtige Verzeichnisse zu identifizieren. Wähle danach einen narrativen Pfad: Setup-bis-zum-ersten-Feature, Request-to-Response, UI-Aktion-bis-API, Bug-Symptom-bis-Root-Cause oder PR-Diff-bis-Risiko. Erst danach sollte die .tour-Datei generiert werden. Diese Reihenfolge reduziert kaputte Anker und verhindert eine oberflächliche „Ordner-Tour“, die nur Verzeichnisse nennt, ohne zu vermitteln, wie das System funktioniert.

Praktisches Prompt-Muster

Nutze einen Prompt wie:

“Use the code-tour skill to create .tours/auth-onboarding.tour. Audience: new full-stack engineer. Goal: understand authentication flow well enough to make a safe change. Scope: login, session creation, middleware, and tests only. Exclude unrelated account settings. Inspect the repo first, then produce a 10-step CodeTour with real file paths and line numbers. Each step should explain what the reader should notice and why it matters.”

Das funktioniert, weil der Agent damit einen Entscheidungsrahmen bekommt, nicht nur ein Thema.

FAQ zum code-tour skill

Wann sollte ich code-tour statt Dokumentation verwenden?

Verwende code-tour, wenn die Navigation durch den Code selbst das Produkt ist. Klassische Dokumentation eignet sich besser für Konzepte, Richtlinien oder API-Referenzen. Eine CodeTour ist besser, wenn Leserinnen und Leser Dateien nacheinander öffnen und Zusammenhänge zwischen Routes, Services, Tests, Configs und Einstiegspunkten verstehen müssen.

Können Einsteiger den code-tour skill verwenden?

Ja, aber Einsteiger sollten die Anfrage eingrenzen. Bitte zuerst um eine kleine Tour: ein Feature, ein Bug-Pfad oder ein Architektur-Ausschnitt. Breite Anfragen wie „explain the entire codebase“ führen oft zu unübersichtlichen Touren, es sei denn, das Repository ist sehr klein. Für sehr kleine Repositories mit weniger als einer Handvoll Source-Dateien reicht meistens eine kurze Tour mit angemessener Tiefe.

Ändert code-tour meinen Anwendungscode?

Nein. Das vorgesehene Ergebnis ist eine .tour-JSON-Datei, normalerweise in .tours/. Die explizite Grenze des Skills ist, keine Source-Code-Änderungen vorzunehmen. Wenn dein Workflow Code Fixes, Tests oder Refactorings braucht, verwende zuerst einen anderen Engineering Skill und nutze anschließend code-tour, um den entstandenen Pfad zu dokumentieren.

Was kann ein gutes code-tour-Ergebnis verhindern?

Die größten Blocker sind fehlender Repository-Zugriff, eine unklare Zielgruppe, fehlende Eingrenzung des Umfangs und ungeprüfte Dateipfade. CodeTour-Schritte hängen von echten Ankern ab. Wenn der Agent die Zieldateien nicht lesen kann oder sich Zeilennummern während aktiver Änderungen stark verschieben, erstelle die Tour erst, nachdem der Code stabil ist, oder bitte zunächst um Anker auf Pfadebene und verfeinere die Zeilennummern später.

So verbesserst du den code-tour skill

code-tour-Prompts auf eine Persona zuschneiden

Der schnellste Weg zu besseren code-tour-Ergebnissen ist, die Leserschaft konkret zu benennen. „New contributor“ erzeugt einen anderen Pfad als „security reviewer“ oder „technical writer preparing onboarding material“. Beschreibe, was die Leserin oder der Leser bereits weiß und was nach der Tour möglich sein muss. Das verändert die Auswahl der Schritte, die Erklärungstiefe und das Vokabular.

Fordere eine Erzählung an, kein Inventar

Eine schwache Tour listet Dateien auf. Eine starke Tour erzählt eine Geschichte: wo die Ausführung beginnt, wie Daten fließen, wo Entscheidungen getroffen werden, wo Risiken liegen und welche Tests das Verhalten absichern. Bitte den Agenten, jeden Halt mit dem vorherigen zu verbinden und pro Schritt einen Satz zu „warum das wichtig ist“ einzubauen. Das ist besonders wertvoll für Technical Writing, weil das Endergebnis dadurch lehrbar wird und nicht nur anklickbar ist.

Nach dem ersten Ergebnis iterieren

Prüfe den ersten .tour-Entwurf auf drei Punkte: kaputte oder ungenaue Dateipfade, zu breite Schritte und fehlende Übergänge. Bitte dann um gezielte Überarbeitungen: „split step 4 into route and service steps,“ „add the test that covers this behavior,“ oder „reduce frontend detail and focus on API error handling.“ Iteration ist in der Regel wirksamer, als in einem Durchlauf eine perfekte Tour durch das gesamte Repo anzufordern.

Anker vor dem Teilen validieren

Bevor du eine CodeTour veröffentlichst, öffne sie in VS Code mit der CodeTour extension und prüfe, ob jeder Pfad und jede Zeile an der erwarteten Stelle landet. Wenn sich das Repository häufig ändert, bevorzuge Tours, die an stabile Architekturdateien, Tests oder Einstiegspunkte gebunden sind, und generiere Zeilennummern nach größeren Refactorings neu. So bleibt der code-tour skill als Onboarding-Asset nützlich, statt zu einer veralteten Karte zu werden.