CommunitySchreiben & Editierengithub.com

Shaelz/codebase-orient-skill

Eine wiederverwendbare Skill für die Codebase-Orientierung für Claude Code und Codex.

Was ist codebase-orient-skill?

Diese Skill ermöglicht es einem KI-Agenten, sich schnell und zuverlässig in einer neuen, veränderten oder unbekannten Codebase zu orientieren. Sie erstellt ein konsistentes Set von vier Artefakten im `docs/ai/`-Verzeichnis, die als kompakter Orientierungs-Cache dienen. So müssen Agenten nicht bei jeder Sitzung oder jedem Handover die Codebase von Grund auf neu erkunden, was Token-kostspielig und zeitaufwendig wäre. Die Skill gibt klare Regeln vor, wann sie verwendet werden sollte (z. B. vor Refactorings, nach strukturellen Änderungen, bei Agenten-Übergaben) und wann sie übersprungen werden kann (z. B. bei kleinen, lokalen Änderungen). Sie unterstützt sowohl einen normalen Modus, in dem die Artefakte automatisch aktualisiert werden, als auch einen Dry-Run-Modus, der nur Änderungen vorschlägt. Die Skill enthält umfangreiche Anleitungen zur Token-bewussten Nutzung, definiert Vertrauensstufen für Behauptungen (von 'Fact' bis 'Unknown') und gibt eine detaillierte Erkennungsreihenfolge vor, um die Codebase effizient zu analysieren. Plattform-spezifische Sonden, wie für SvelteKit, helfen dabei, relevante Dateimuster zielgerichtet zu scannen. Nach der Orientierung liegt ein aktuelles, referenzierbares Verständnis der Architektur, des Deployments und der Änderungsoberflächen vor, das direkten Einfluss auf zukünftige Bearbeitungen hat.

Funktioniert mit✓Claude Code✓Codex CLI~Cursor
npx skills add Shaelz/codebase-orient-skill

Installed? Explore more Schreiben & Editieren skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

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.json sind 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:

  1. Projektanweisungsdateien wie CLAUDE.md, AGENTS.md und README.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.md gemäß 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 in CODEBASE_MAP.md; es hilft zukünftigen Agenten zu wissen, welche Regeln gelten.
  2. Projektmanifest (z. B. package.json, pyproject.toml, Cargo.toml) – Abhängigkeiten, Skripte, Build/Test-Befehle
  3. Build- und Konfigurationsdateien (z. B. Framework-Konfiguration, Bundler-Konfiguration) – Adapter, Build-Konfiguration
  4. scripts/-Verzeichnis, falls vorhanden – kann manuell ausgeführte Tools enthalten, die nicht in den Paketskripten oder CI dargestellt sind
  5. Einstiegspunkte und Routing-Ebene – alle Seiten, Controller oder API-Routen
  6. Kern-Geschäftslogik – Domänentypen, Modelle, Bewertung, Berichtslogik
  7. Serverseitige Dienste – Auth, DB/Schema, E-Mail, externe Integrationen
  8. UI/Präsentationsebene – Komponenten, Ansichten, Templates
  9. Internationalisierungs- oder Kopierdateien – Sprachdateien
  10. Request-Lifecycle / Middleware – Hooks, Interceptors, Middleware
  11. Datenbankebene – Migrationen, Schema-Snapshots
  12. Tests – Teststruktur und Abdeckungsform
  13. 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-Status zu CODEBASE_MAP.md hinzu, 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.
  14. 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 Ebene src/routes/+page.svelte
  • src/routes/**/+page.server.ts: serverseitiges Datenladen, Formularaktionen und routenbezogene Zugriffskontrolle
  • src/routes/**/+layout.svelte: gemeinsame Layout-Schalen
  • src/routes/**/+layout.server.ts: serverseitige Ladefunktionen für Auth, Sitzung oder Daten auf Layout-Ebene
  • src/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.js bestimmt 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 – wenn true, 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/**/* oder test/**/* oder spec/**/*
  • .github/workflows/*
  • docs/**/*
  • migrations/**/*
  • dist/**/* oder build/**/*

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.

Verwandte Skills