Skill: codebase-orient
Zweck
Orientieren Sie Claude über den aktuellen Stand dieses Repos, bevor nicht-triviale Arbeiten durchgeführt werden. Es erstellt oder gleicht ein festes, mit Herkunftsnachweisen versehenes Paket aus vier Artefakten in docs/ai/ ab. Quellcode und Projektkonfiguration bleiben maßgeblich.
Wann diese Skill verwendet werden sollte
Verwenden Sie diese Skill, wenn
- Sie ein neues oder unbekanntes Repo betreten
- Sie eine neue Sitzung nach einer längeren Abwesenheit vom Repo beginnen
- Vor umfangreichen oder dateiübergreifenden Implementierungsarbeiten
- Vor Refactorings, Bereinigungen, Architekturplanung oder Agenten-Übergabe
- Nach strukturellen Änderungen: Routen, Schema, Authentifizierung, Deployment, Konfiguration oder Admin-Oberflächen
- Wenn
docs/ai/fehlt, veraltet, unvollständig oder intern inkonsistent ist - Wenn die Repo-Struktur, Änderungsoberflächen, Deploy-Ziele, Auth-Verhalten, Admin-Routen, Befehle oder die Teststruktur unklar sind
- Wenn der Agent ansonsten signifikanten Kontext damit verschwenden würde, das, was bereits in
docs/ai/oder in dessen Nähe ist, neu zu entdecken - Jedes Mal, wenn der Benutzer „scannen“, „orientieren“, „verstehen“, „kartieren“, „überprüfen“, „auditieren“, „untersuchen“, „vertraut machen“ oder „bevor ich beginne“ sagt
Überspringen Sie diese Skill, wenn
- Sie eine winzige, lokale, bekannte Änderung an einer einzelnen Datei vornehmen
- Sie einen Fehler in einer einzelnen Datei beheben, bei dem die betreffende Datei und die Änderung bereits klar sind
- Sie reine Kopier- oder Textänderungen vornehmen
- Die Aufgabe eng auf Dateien beschränkt ist, die bereits im aktuellen Kontext überprüft wurden
docs/ai/gerade erst aktualisiert wurde und die Aufgabe eng genug ist, um keinen vollständigen Orientierungsdurchlauf zu benötigen
Token-bewusste Nutzungshinweise
docs/ai/ ist ein Orientierungs-Cache. Ein frischer Cache reduziert die wiederholten Token-Kosten für die Repo-Erkennung über Sitzungen und Agenten-Übergaben hinweg.
- Wenn
docs/ai/frisch und vollständig ist: Lesen Sie es als Kontext und fahren Sie fort. Überspringen Sie die erneute Ausführung der Orientierung. - Wenn
docs/ai/möglicherweise veraltet oder nicht vorhanden ist: Führen Sie die Skill aus, um den Cache zu aktualisieren. Die anfänglichen Token-Kosten amortisieren sich über die bevorstehende Arbeit. - Wenn die Aufgabe winzig ist und die Zieldatei bereits bekannt ist: Überspringen Sie die Orientierung. Verwenden Sie stattdessen gezielte Lesevorgänge.
- Wenn der Agent viele Token damit verbringen würde, das, was
docs/ai/bereits erfasst, neu zu entdecken: Aktualisieren Sie den Cache.
Sparen Sie keine Token, indem Sie die Orientierung überspringen und dann über die Struktur raten. Wenn eine breite Repo-Erkennung ansonsten wiederholt oder teuer wäre, aktualisieren Sie stattdessen den Cache.
Harte Regeln während der Orientierung
- Ändern Sie keinen Anwendungs- oder Quellcode.
- Führen Sie kein Refactoring durch.
- Führen Sie keine Commits durch.
- Überprüfen Sie Behauptungen gegen den Quellcode, bevor Sie sie niederschreiben.
- Kennzeichnen Sie jede sinnvolle Behauptung mit einem Vertrauenslabel.
Normalmodus vs. Trockenlaufmodus
Normalmodus (Standard – verwenden, wenn der Benutzer nichts anderes angibt):
- Lösen Sie kleine aufgabenrelevante Unklarheiten automatisch durch Lesen von Quelldateien
- Erstellen Sie bei der ersten Verwendung in einem sauberen Repository ein vollständiges Paket
- Verwenden Sie ein exakt aktuelles, sauberes Paket wieder, ohne es neu zu schreiben
- Behandeln Sie eine unspezifische Aufforderung zum Aktualisieren oder Abgleichen als vollständigen Abgleich
- Berichten Sie am Ende, was sich geändert hat
Trockenlauf-/Nur-Bericht-Modus (verwenden, wenn der Benutzer „trockenlauf“, „nur Bericht“, „nicht schreiben“, „zuerst Änderungen vorschlagen“, „nur auditieren“, „keine Schreibvorgänge“ oder ähnliches sagt):
- Untersuchen und sammeln Sie vorgeschlagene Änderungen
- Melden Sie vorgeschlagene Bearbeitungen an
docs/ai/, ohne sie zu schreiben - Warten Sie auf explizite Genehmigung, bevor Sie schreiben
Wenn kein Modus angegeben ist, standardmäßig den Normalmodus verwenden.
Lebenszyklus und Schreibsicherheit
- Explizite Aktualisierung: Aktualisieren oder gleichen Sie nur ab, wenn der Benutzer dies explizit verlangt, nachdem ein exakt aktuelles Paket gefunden wurde.
- Bereichsbezogene Aktualisierung: Folgen Sie einem expliziten Benutzerbereich und seinen direkten Abhängigkeiten. Zeichnen Sie die abgedeckte Fläche auf, ohne einen paketweiten vollständigen Snapshot zu erstellen oder zu beanspruchen. Erstellen Sie kein teilweise unterstütztes Paket, bevor ein vollständiges Paket existiert.
- Legacy-Übernahme: Markdown-Artefakte ohne
ORIENTATION_STATE.jsonsind Legacy-Material. Untersuchen Sie sie, holen Sie jedoch eine explizite Genehmigung ein, bevor Sie ein Manifest schreiben oder sie ändern. Gleichen Sie nach der Genehmigung aus der Quelle ab. - Unsauberer Baum: Bevor Sie einen Zustand schreiben, der nicht-commitierte Arbeit darstellt, fragen Sie, ob ein unsauberer Snapshot geschrieben oder nur berichtet werden soll. Zeichnen Sie den Baumzustand auf; halten Sie ihn als unsauber markiert, bis eine saubere Aktualisierung ihn ersetzt.
- Keine nutzbare Git-Historie: Führen Sie eine vollständige Abstimmung durch und zeichnen Sie auf, dass ein Revisionsvergleich nicht verfügbar ist.
- Manuelle Bearbeitungen: Die Orientierung besitzt das Paket. Versprechen Sie kein Merge- oder Erhaltungsverhalten für manuell bearbeitete Orientierungszustände.
Vertrauenslabels
- Fakt: direkt im Code oder in den Dokumenten überprüft
- Starke Ableitung: durch mehrere Dateien gestützt
- Schwache Ableitung: plausibel, aber nicht bestätigt
- Unbekannt: benötigt weitere Untersuchung vor der Bearbeitung
Unterscheiden Sie, wie eine Behauptung aufgestellt wurde:
- unabhängig aus Quelle/Konfiguration überprüft: Behauptung gegen die tatsächliche Quelle oder Konfigurationsdatei geprüft, nicht aus Dokumenten übernommen
- aus vorhandenen Dokumenten übernommen: Behauptung aus CLAUDE.md, README oder anderen Dokumentationen ohne unabhängige Überprüfung übernommen
- übernommen und dann überprüft: Behauptung stammte aus Dokumenten und wurde anschließend gegen die Quelle bestätigt
- Pfadexistenz bestätigt: Datei gefunden, aber nicht gelesen
- Teilweises Lesen: Teil der Datei eingesehen; möglicherweise nicht der gesamte Kontext erfasst
- Vollständiges Quell-Lesen: Vollständiger Dateiinhalt eingesehen
- Aus Implementierung abgeleitet: Aus dem Code-Verhalten abgeleitet, nicht explizit angegeben
- Aus Kommentaren/Tests/Fixtures abgeleitet: Aus nicht-autoritativem Kontext stammend; bestenfalls als Starke Ableitung behandeln
- Verhalten durch Test überprüft: Durch erfolgreiche Testausführung bestätigt
- Unbekannt: Grundlage nicht ermittelt; nicht als Fakt präsentieren
Kennzeichnen Sie in Abschlussberichten und Orientierungsdokumenten jede nicht-triviale Behauptung mit einem der obigen Ursprünge, damit die Leser beurteilen können, welche Behauptungen vor dem Handeln erneut überprüft werden müssen.
Erkennungsreihenfolge
Anpassungshinweis: Die nachstehende Erkennungsreihenfolge ist bewusst breit gehalten und funktioniert ohne Bearbeitung für die meisten Projektformen. Sie können die Dateipfade und die Reihenfolge für ein bestimmtes Projekt anpassen, aber dies ist optional – nicht erforderlich vor der ersten Verwendung.
Führen Sie in dieser Reihenfolge aus:
- Projektanweisungsdateien wie
CLAUDE.md,AGENTS.mdundREADME.md, falls vorhanden – Produktzweck, Agentenregeln, Projektkonventionen. Dokumente-als-Hypothesen-Regel- Behandeln Sie diese Dokumente als hilfreiche Hypothesen, nicht als autoritative Wahrheit.
- Extrahieren Sie hochwirksame Sachbehauptungen über Architektur, Routen, Deployment, Tests und Quellen-der-Wahrheit-Dateien.
- Überprüfen Sie diese Behauptungen gegen den Quellcode, bevor Sie sich darauf verlassen. Konzentrieren Sie sich auf Behauptungen, die zukünftige Bearbeitungen beeinflussen würden; prüfen Sie nicht jeden Satz.
- Kopieren Sie Behauptungen aus diesen Dokumenten nicht in
CODEBASE_MAP.md, ohne zu kennzeichnen, ob sie unabhängig aus Quelle/Konfiguration überprüft oder aus vorhandenen Dokumenten übernommen wurden. - Wenn ein Anweisungsdokument im Vergleich zu dem, was die Quelle zeigt, veraltet oder irreführend ist, dokumentieren Sie die Abweichung in
OPEN_QUESTIONS.mdgemäß der Melde-Regel für versteckte Risiken und kennzeichnen Sie es als Dokumentationsabweichung. - Kartieren Sie die Anweisungsebenen-Topologie: notieren Sie, welche Anweisungsdateien vorhanden sind (z. B.
CLAUDE.md,AGENTS.md,.claude/settings.json) und in welchem Umfang (projektlokal vs. benutzerweit). Dokumentieren Sie dies inCODEBASE_MAP.md; es hilft zukünftigen Agenten zu wissen, welche Regeln gelten.
- Projektmanifest (z. B.
package.json,pyproject.toml,Cargo.toml) – Abhängigkeiten, Skripte, Build/Test-Befehle - Build- und Konfigurationsdateien (z. B. Framework-Konfiguration, Bundler-Konfiguration) – Adapter, Build-Konfiguration
scripts/-Verzeichnis, falls vorhanden – kann manuell ausgeführte Tools enthalten, die nicht in den Paketskripten oder CI dargestellt sind- Einstiegspunkte und Routing-Ebene – alle Seiten, Controller oder API-Routen
- Kern-Geschäftslogik – Domänentypen, Modelle, Bewertung, Berichtslogik
- Serverseitige Dienste – Auth, DB/Schema, E-Mail, externe Integrationen
- UI/Präsentationsebene – Komponenten, Ansichten, Templates
- Internationalisierungs- oder Kopierdateien – Sprachdateien
- Request-Lifecycle / Middleware – Hooks, Interceptors, Middleware
- Datenbankebene – Migrationen, Schema-Snapshots
- Tests – Teststruktur und Abdeckungsform
- Dokumentation – vorhandene Dokumente, Überprüfungsmatrizen. Wenn ein Release-Plan, ein Meilenstein-Tracking-Dokument oder ein Versions-Changelog gefunden wird, fügen Sie einen Abschnitt
## Release-StatuszuCODEBASE_MAP.mdhinzu, der die aktuelle Version, den aktiven Meilenstein und das, was das nächste Release blockiert, zusammenfasst. Lassen Sie diesen Abschnitt weg, wenn kein Release-Lebenszyklus-Artefakt vorhanden ist. - Bekannte Unsicherheit
Framework-spezifische Sonden
Wenden Sie diese Sonden zusätzlich zur generischen Erkennungsreihenfolge an, wenn das entsprechende Framework erkannt wird.
Die wiederverwendbare Skill enthält derzeit einen explizit abgestimmten Sondensatz für SvelteKit. Andere Frameworks verwenden derzeit die generische Erkennungsreihenfolge, es sei denn, spätere Live-Fire- oder Auswertungsnachweise rechtfertigen einen dedizierten abgestimmten Sondenabschnitt.
SvelteKit
Durchsuchen Sie die folgenden Dateimuster, wenn ein SvelteKit-Projekt erkannt wird:
src/routes/**/+page.svelte: UI-Routenseiten; jede Datei ist ein Routenkandidat; überprüfen Sie Unterverzeichnisse, nicht nur die oberste Ebenesrc/routes/+page.sveltesrc/routes/**/+page.server.ts: serverseitiges Datenladen, Formularaktionen und routenbezogene Zugriffskontrollesrc/routes/**/+layout.svelte: gemeinsame Layout-Schalensrc/routes/**/+layout.server.ts: serverseitige Ladefunktionen für Auth, Sitzung oder Daten auf Layout-Ebenesrc/routes/**/+server.ts: API-Endpunkte und server-only Request-Handler
Serverseitige Routendateien (+page.server.ts, +layout.server.ts, +server.ts) sind entscheidend für das Verständnis von Auth, Datenladen, Formularaktionen, API-Endpunkten und routenbezogener Zugriffskontrolle. Überspringen Sie sie nicht beim Kartieren von Routen oder Änderungsoberflächen.
- Die Standard-App-Shell-Vorlage ist
src/app.html. - Die Adapterwahl in
svelte.config.jsbestimmt das Deploy-Ziel – bestätigen Sie dies, bevor Sie deploy-bezogene Behauptungen aufstellen.
CI-/Deployment-Präzisionsregel
Beim Lesen von CI- oder Deployment-Workflow-Dateien bewahren Sie operativ relevante Details. Fassen Sie Spezifika nicht zu vagen Zusammenfassungen zusammen.
Erfassen und berichten Sie:
- Name der Nebenläufigkeitsgruppe (welche Läufe konkurrieren miteinander)
cancel-in-progress-Verhalten – wenntrue, sagen Sie „neuere Läufe brechen laufende Läufe derselben Gruppe ab“, nicht nur „verhindert parallele Deployments“fail-fast-Verhalten- Deploy-Artefaktpfade
- Release-Benennungsformat einschließlich etwaiger Zeitstempel- oder Hash-Komponenten
- Aufbewahrungs- und Bereinigungsrichtlinie für alte Releases oder Artefakte
- Manuelle vs. automatische Auslösebedingungen
- Erforderliche Geheimnisse und Umgebungsvariablen
- Ob das Deployment an Ort und Stelle überschreibt, zu einem temporären Pfad wechselt, Symlinks verwendet oder versionierte Release-Verzeichnisse verwendet
Kennzeichnen Sie CI-/Deployment-Behauptungen mit unabhängig aus Quelle/Konfiguration überprüft, wenn sie direkt aus der Workflow-Datei gelesen werden. Fassen Sie diese Details nicht auf eine Weise zusammen, die die Präzision verliert, die ein Betreiber während eines Vorfalls benötigen würde.
Lese-Tiefen-Heuristik
Lesen Sie nicht standardmäßig jede große CSS-, Konfigurations- oder generierte Datei.
- Vollständig lesen: Dateien, die die angeforderte Aufgabe direkt betreffen (Einstiegspunkte, Routing, Auth, Schema, Build-Konfiguration, die zu bearbeitende Datei).
- Teilweises Lesen oder nur Pfadbestätigung: sekundäre Oberflächen wie große Stylesheets, eingekaufte Bibliotheken, generierte Ausgabe oder Konfigurationsdateien, die für die Aufgabe nicht relevant sind. Wenn Sie nur den Pfad einer Datei bestätigen oder einen Teil lesen, geben Sie dies im Bericht explizit an, indem Sie die unter Vertrauenslabels definierten Bezeichnungen Pfadexistenz bestätigt oder teilweises Lesen verwenden.
- Überspringen: Dateien, die eindeutig außerhalb des Aufgabenbereichs liegen (z. B. Binär-Assets, Sperrdateien, Test-Snapshots), es sei denn, eine spezifische Frage macht sie relevant.
Im Zweifelsfall bevorzugen Sie es, zuerst die Existenz zu bestätigen und nur dann vollständig zu lesen, wenn eine Behauptung dies erfordert.
Pfadexistenz vs. Inhaltslesen
Die Pfadexistenz allein ist für risikoarme Bestandsbehauptungen ausreichend – Bestätigen einer Verzeichnisstruktur, Auflisten der Dateianzahl oder Feststellen, dass eine Konfigurationsdatei vorhanden ist.
Lesen Sie den tatsächlichen Dateiinhalt, wenn die Behauptung Verhalten, Architektur, Risiko, Befehle, Deployment, Auth, Routing oder Änderungsoberflächen betrifft. Kennzeichnen Sie eine Behauptung nicht als unabhängig aus Quelle/Konfiguration überprüft, die nur auf der Pfadexistenz basiert, wenn die Datei billig zu überprüfen ist und ihr Inhalt die Karte wesentlich beeinflussen würde.
Regel zum Lesen kleiner Quellen-der-Wahrheit-Dateien
Wenn eine kleine Datei das Vokabular oder die Quellen-der-Wahrheit-Token zu definieren scheint, die im gesamten Projekt verwendet werden, lesen Sie genug davon, um das Vokabular zu überprüfen, anstatt das Vokabular aus Dokumenten zu übernehmen.
Beispiele, bei denen dies zutrifft:
- CSS-Custom-Property-Token-Dateien
- Routen- oder Menükonfigurationsdateien
- Kleine Schema- oder Konstantendateien
- Befehls- oder Plugin-Registrierungen
Verwenden Sie ein teilweises Lesen, wenn dies ausreichend ist. Kennzeichnen Sie die resultierenden Behauptungen mit dem entsprechenden Behauptungsursprung (teilweises Lesen, vollständiges Quell-Lesen). Kennzeichnen Sie sie nicht als unabhängig aus Quelle/Konfiguration überprüft, wenn Sie die Datei nicht tatsächlich gelesen haben.
Regel für billige Artefakt-Globs
Bevor Sie eine offene Frage zur Existenz oder zum Umfang von statischen Assets, Skripten, generierten Ausgaben, Dokumentation, Tests, Migrationen oder Konfigurationsdateien hinterlassen, klären Sie sie mit einem billigen Pfad-Glob.
Häufige Glob-Muster zum Ausprobieren:
static/**/*public/**/*scripts/**/*tests/**/*odertest/**/*oderspec/**/*.github/workflows/*docs/**/*migrations/**/*dist/**/*oderbuild/**/*
Lesen Sie nicht standardmäßig alle übereinstimmenden Dateien tiefgehend. Verwenden Sie das Glob, um Existenz- und Umfangsfragen billig zu klären. Führen Sie gezielte Lesevorgänge nur dann durch, wenn der Inhalt einer bestimmten Datei benötigt wird.