Codespaces – Entdeckung der Glaubenslandkarten-Architektur

Was macht Codespaces – Entdeckung der Glaubenslandkarten-Architektur?

Fragen Sie .belief_map.sexp ab, um Module, Grenzen und Abhängigkeiten zu entdecken, bevor Sie Quelldateien lesen. Lesen Sie niemals blind Code – fragen Sie zuerst den Graphen ab.

Skripte

Dieser Skill bündelt Python-Skripte. Führen Sie sie aus dem Basisverzeichnis des Skills aus:

• scripts/belief_search.py – den Glaubenslandkarten-Graphen abfragen
• scripts/build_belief_map.py – die Glaubenslandkarte aus dem Quellcode generieren
• scripts/build_infra_topology.py – Kustomize-, Helm- und Terraform-Topologiefakten extrahieren
• scripts/git_descendants.py – alle Commits finden, die von HEAD (oder einem angegebenen Referenz) abstammen

Verwenden Sie niemals projektlokale Kopien dieser Skripte – diese könnten veraltet sein und JSON anstelle von S-Expressions ausgeben.

Voraussetzung

Lokalisieren Sie die Glaubenslandkarte. Wenn sie fehlt, erstellen Sie sie:

ls .belief_map.sexp belief_map.sexp 2>/dev/null
# Erstellen: pip3 install tree-sitter tree-sitter-typescript tree-sitter-python
python3 scripts/build_belief_map.py          # inkrementell ~5s
python3 scripts/build_belief_map.py --full   # vollständiger Neubau ~30s

Verbindlicher Workflow: Abfrage vor dem Code

Führen Sie bei nicht-trivialen Code-Arbeiten eine Glaubenslandkarten-Abfrage durch, bevor Sie rg, find, sed, cat, nl verwenden, Verzeichnisse öffnen oder Quelldateien lesen. Der Skill hilft nur, wenn er als erster Schritt zur Eingrenzung verwendet wird, nicht als Bestätigung, nachdem die Quelle bereits inspiziert wurde.

Schneller erster Durchgang, wenn die Aufgabe ein klares Schlüsselwort hat:

python3 scripts/belief_search.py quick "Schlüsselwort"

quick sucht nach dem ersten passenden Modul und führt sofort analyze aus. Verwenden Sie es, um in einem Schritt Grenzdateien, Abhängigkeiten, Rückwärtsabhängigkeiten, Schichten und Verletzungen zu erhalten. Wenn quick das falsche Modul oder keinen Treffer zurückgibt, verwenden Sie den expliziten search -> analyze-Ablauf unten.

Schritt 1 – Die Modul-ID finden:

python3 scripts/belief_search.py search "Schlüsselwort"
python3 scripts/belief_search.py entity Entitätsname

Verwenden Sie search oder entity, um die Modul-ID zu lokalisieren. Modul-IDs sind vollständige relative Pfade wie pki-service/src/modules/ca/ca.service, keine kurzen Codes wie ps34. Die Glaubenslandkarte kann intern kurze Pfadzuordnungs-IDs enthalten, aber diese werden automatisch aufgelöst – übergeben Sie immer lesbare pfadähnliche Zeichenfolgen. Raten oder erfinden Sie KEINE Modul-IDs – bestätigen Sie immer zuerst mit search.

Schritt 2 – Das Modul analysieren (dies SOFORT und nicht optional durchführen):

python3 scripts/belief_search.py analyze <Modul-ID>

analyze ist der PRIMÄRE Befehl. Er gibt den vollständigen Kontext zurück: Grenzdateien, Abhängigkeiten, Rückwärtsabhängigkeiten, Architekturebene und Verletzungen. Führen Sie ihn immer aus, bevor Sie eine Quelle lesen.

Schritt 3 – Nur die in der analyze-Ausgabe aufgeführten Grenzdateien lesen.

Schritt 4 – Lesen Sie NICHT ganze Verzeichnisse. Wenn die Grenze 2-3 relevante Dateien anzeigt, lesen Sie nur diese Dateien. Ignorieren Sie alles andere im Verzeichnis.

Befehlsreferenz

Befehl	Zweck	Beispiel
search "<Muster>"	Regex-Suche im Graphen (Modul-IDs finden)	search "operative.*service"
analyze <ID>	Vollständige Modulanalyse (PRIMÄRER Befehl)	analyze drive/modules/drive/drive_schema
quick <Schlüsselwort>	Suche + Analyse des ersten Treffers (Abkürzung)	quick operatives
boundary <ID>	Zu lesende Dateien für eine Änderung	boundary operatives.service
boundary <ID> --files-only	Nur Dateipfade (kompakt)	boundary operatives.service --files-only
entity <Name>	Definitionen + Referenzen finden	entity DrivePath
deps <ID> [Tiefe]	Abgehende Abhängigkeitsbaum	deps operatives.service 3
rdeps <ID> [Tiefe]	Auswirkungsbereich (wer hängt von diesem ab)	rdeps drive_schema 2
flow <ID> <Fn>	Aufruf-/Datenfluss verfolgen	flow drive_api fetchFiles
module <ID>	Einzelnes Modul mit Kanten	module operatives.controller
boundaries [ID|all]	Architekturverletzungen prüfen	boundaries all
invariants [ID|all]	Verstöße gegen Namenskonventionen prüfen	invariants all
layers	Alle Module nach Schicht anzeigen	layers
find_function <Name>	Funktions-/Methodendefinitionen finden	find_function createOrder
find_type <Name>	Typ-/Klassen-/Schnittstellen-/Enumdefinitionen finden	find_type DriveDbCommitResponse
find_callchain <Src> <Tgt> [Tiefe]	Aufrufpfad zwischen Funktionen verfolgen	find_callchain createOrder processPayment
find_callers <Fn> [Tiefe]	Wer ruft diese Funktion auf	find_callers handleRequest 3
find_calls <Fn> [Tiefe]	Was ruft diese Funktion auf	find_calls createOrder 2
grep_functions <Muster>	Funktionskörper im Quellcode durchsuchen	grep_functions "validate.*input"
diff_functions [Ref]	Geänderte Funktionen im Git-Diff	diff_functions HEAD~3
query '<Sexp>'	Zusammensetzbare Scheme-Abfrage	query '(count (boundary "X"))'
repl	Interaktive Scheme-REPL	repl

Kurzreferenz: rg-Abfragen

Wenn Sie schnelle, gezielte Nachschlageanfragen benötigen, ohne das Python-Skript aufzurufen, fragen Sie die Glaubenslandkarte direkt mit rg ab. Der gebündelte Builder schreibt .belief_map.sexp; wenn ein Repository noch die alte belief_map.sexp verwendet, ersetzen Sie diesen Dateinamen in den folgenden Befehlen:

# Alle Fakten zu einem Modul
rg 'drive/modules/drive_db/api ' .belief_map.sexp

# Wer importiert ein Modul
rg 'imports .* drive/modules/commons/result' .belief_map.sexp

# Was importiert ein Modul
rg 'imports drive/modules/drive_db/api' .belief_map.sexp

# Alle Referenzen auf eine Entität
rg 'DriveDbCommitResponse' .belief_map.sexp

# Alle Klassen in einem Repository
rg '^\(cls drive/' .belief_map.sexp

# Datenflusskanten
rg 'data-flow' .belief_map.sexp

Diese Einzeiler sind nützlich für schnelle Überprüfungen. Für strukturierte Ausgaben und vollständige Analysen verwenden Sie die Python-Skriptbefehle.

Ausgabenotation

Die gesamte Ausgabe besteht aus S-Expression-Fakten, eine pro Zeile. Siehe references/sexp-notation.md für das vollständige Format.

Wichtige Muster:

(boundary <mod> :lang py :file <pfad> :purpose "<beschreibung>")
(boundary-dep <mod> <dep> :lang ts :file <pfad> :relation imports)
(boundary-rdep <mod> <rdep> :lang tsx :file <pfad> :relation imports)
(boundary-summary <mod> :total 10 :deps 7 :rdeps 2)
(entity-def cls <mod> <Name> <zeile> :lang py :file <pfad>)
(violation <src> <tgt> :src-layer domain :tgt-layer api :via imports :lang ts "<grund>")
(result <modul-oder-pfad>)
(result-count 42)

:lang-Werte: py = Python (snake_case), ts = TypeScript (camelCase), tsx = TSX (PascalCase).

Scheme-Abfragesprache

Stellen Sie Abfragen für komplexe Analysen zusammen. Siehe references/scheme-queries.md für die vollständige Referenz.

Grundlagen:

(boundary "id")                ; Ziel + Abhängigkeiten + Rückwärtsabhängigkeiten (Änderungsgrenze)
(entity "Name")                ; Module, die die Entität definieren
(deps "id" tiefe)              ; Abgehende Abhängigkeiten
(rdeps "id" tiefe)             ; Rückwärtsabhängigkeiten
(find-function "name")         ; Module mit passenden Funktionsdefinitionen
(find-type "name")             ; Module mit passenden Typdefinitionen
(find-callers "fn" tiefe)      ; Module, die eine Funktion aufrufen
(find-calls "fn" tiefe)        ; Module, die eine Funktion aufruft
(intersect A B)                ; Schnittmenge
(filter SET "muster")          ; Regex-Filter
(files SET)                    ; In Dateipfade auflösen
(count SET)                    ; Mitglieder zählen
(violations)                   ; Module mit Grenzverletzungen
(layer "id")                   ; Architekturebene eines Moduls

Analyseplanmuster

Erstellen Sie vor dem Ändern von Code einen Plan aus Abfragen:

; 1. Eingrenzung
(boundary "operatives.service")
(count (boundary "operatives.service"))

; 2. Architekturbeschränkungen
(violations "operatives.service")
(layer "operatives.service")

; 3. Sprachübergreifende Grenzen
(filter (refs-to "DrivePath") "app-service")

; 4. Auf umsetzbare Dateien eingrenzen
(filter (boundary "operatives.service") "dto")
(intersect (deps "controller" 2) (deps "service" 2))

; 5. Nach Änderungen: überprüfen
(violations "operatives.service")

Auslösebeispiele

Verwenden Sie diesen Skill, bevor Sie Quellen lesen für:

• Ursachenanalysen, die Dienste, APIs, Jobs, Ereignisse, UI-Abläufe oder fehlerhaftes Verhalten erwähnen.
• Dienstübergreifende oder modulübergreifende Fragen, einschließlich „wie ruft X Y auf?“ und „wo wird dies gespeichert?“
• Redmine-Klärungen, wenn die Antwort vom Codeverhalten abhängt.
• Architekturüberprüfungen, Auswirkungsanalysen, Änderungen öffentlicher Verträge oder Überprüfungen des Auswirkungsbereichs.
• Überprüfungen von nicht-trivialen bereitgestellten Änderungen, wenn die Abhängigkeitsrichtung oder die Modulzugehörigkeit wichtig ist.

Erzwingen Sie dies nicht für reine Commit-Aufgaben, Git-Protokollzusammenfassungen, manuelle Demo-/Serverläufe, reine Browsertests oder Sitzungsprotokollanalysen.

Fehlerbehebung

Wenn ein Befehl (error no-match ...) zurückgibt:

1. Wiederholen Sie NICHT mit derselben ID oder raten Sie eine andere ID
2. Führen Sie search mit einem breiteren Schlüsselwort aus, um die korrekte Modul-ID zu finden
3. Verwenden Sie das :suggestions-Feld, falls vorhanden – es listet ähnliche Modul-IDs auf

# Falsch: IDs raten
python3 scripts/belief_search.py analyze ps34        # schlägt fehl: ps34 ist eine kurze Pfadzuordnungs-ID
python3 scripts/belief_search.py analyze ca.service  # schlägt fehl: unvollständiger Pfad

# Richtig: zuerst suchen, dann den vollständigen Pfad aus den Ergebnissen verwenden
python3 scripts/belief_search.py search "ca.*service"
# Ausgabe zeigt: pki-service/src/modules/ca/ca.service
python3 scripts/belief_search.py analyze pki-service/src/modules/ca/ca.service

Anti-Patterns

• Modul-IDs erraten. Modul-IDs sind vollständige relative Pfade (z.B. pki-service/src/modules/ca/ca.service). Kurze Codes wie ps34 sind interne Pfadzuordnungs-IDs und dürfen nicht direkt verwendet werden. Führen Sie immer zuerst search aus.
• Erstellen, aber nie abfragen. Das Erstellen der Glaubenslandkarte und dann nie search, analyze oder boundary auszuführen, bringt keinen Mehrwert.
• Abfragen nach dem Lesen von Quellen. Das erste Lesen des Quellcodes sollte aus den boundary-file-Zeilen in der analyze-Ausgabe stammen.
• Lesen von .belief_map.sexp als gesamte Datei. Verwenden Sie search, analyze oder rg, um spezifische Fakten abzufragen.
• Auslassen der Glaubenslandkarte für modulübergreifende Aufgaben. Fragen Sie immer den Graphen ab, um Grenzen zu verstehen, bevor Sie Quelldateien lesen.
• Lesen aller Dateien in einem Verzeichnis. Wenn die Grenze 2-3 Dateien anzeigt, lesen Sie nur diese.
• Verwenden von projektlokalen Skripten. Verwenden Sie immer die gebündelten Skripte dieses Skills. Projektkopien geben möglicherweise JSON anstelle von S-Expressions aus.

Neuerstellen des Graphen

python3 scripts/build_belief_map.py          # inkrementell (~5s)
python3 scripts/build_belief_map.py --full   # vollständiger Neubau (~30s)
python3 scripts/build_belief_map.py ./drive  # einzelnes Unter-Repository
python3 scripts/build_belief_map.py --lsp    # mit LSP-Aufrufhierarchie (~1-5min)

Nach strukturellen Änderungen neu erstellen (Dateien hinzufügen/entfernen, Importe ändern, Klassen hinzufügen).

Infrastruktur-Topologie

Extrahieren Sie die Diensttopologie aus Kustomize-, Helm- und Terraform-Dateien. Dieses Skript erfordert PyYAML (pip3 install pyyaml).

python3 scripts/build_infra_topology.py                    # automatische Erkennung aller IaC
python3 scripts/build_infra_topology.py --kustomize .      # nur kustomize
python3 scripts/build_infra_topology.py --helm ./charts    # nur Helm-Charts
python3 scripts/build_infra_topology.py --terraform ./infra # nur Terraform
python3 scripts/build_infra_topology.py --append .belief_map.sexp  # in den Graphen einfügen

Gibt infra-node, k8s-depends, k8s-service, helm-depends, tf-depends und infra-maps-Kanten aus. Abfragen mit:

rg 'infra-node' .belief_map.sexp                  # alle Dienste
rg 'k8s-depends' .belief_map.sexp                 # Dienstabhängigkeiten
rg 'infra-node.*:component database' .belief_map.sexp  # alle Datenbanken
rg 'infra-maps.*app-service' .belief_map.sexp     # Infrastruktur -> Quellcodezuordnung