Wingbox -- Code Graph Architektur-Entdeckung
Durchsuche .wingbox/index.sexp, um Module, Grenzen und Abhängigkeiten zu entdecken, bevor du Quelldateien liest. Lies niemals Code blind -- frage zuerst den Graphen ab.
/wingbox
Wenn der Benutzer /wingbox eingibt (in Codex $wingbox), tue dies vor allem anderen:
-
/wingboxohne Argument: Finde den Graphen (.wingbox/index.sexpim Projektstammverzeichnis; jederwingbox-Befehl findet ihn auch aus einem Unterordner). Erstelle ihn mitwingbox build ., wenn er fehlt oder veraltet ist. Der Graph ist veraltet, wenn eine Datei des Projekts nach der Graph-Datei geändert wurde; dieser Check findet eine solche:G=.wingbox/index.sexp [ ! -f "$G" ] || find . -type f -newer "$G" -not -path './.git/*' \ -not -path './.wingbox/*' -not -path '*/node_modules/*' -print -quitEin Neubau parst nur die Dateien neu, deren Inhalt sich geändert hat. Lies dann
.wingbox/REPORT.mdund gib dem Benutzer dessen "Schlüsselerkenntnisse", die am meisten abhängigen Module und wo er mit dem Lesen beginnen soll, und sage, dass die Karte.wingbox/map.htmlist (wingbox openzeigt sie im Browser an, offline). -
/wingbox <datei>: Führewingbox impact <datei> 2aus und fasse zusammen, was von der Datei abhängt und welche Dateien zuerst gelesen werden sollten. -
/wingbox <befehl> ...: Führewingbox <befehl> ...aus (zum Beispiel/wingbox quick "Datei-Upload",/wingbox analyze src/billing/invoice).
Ausführen der Befehle
Wenn der wingbox-Befehl installiert ist (command -v wingbox), führe wingbox <befehl> ... für jede folgende Abfrage aus und wingbox build PFAD zum Erstellen; sie akzeptieren die gleichen Argumente wie die Skripte. Ein durch wingbox install installierter Skill hat keinen scripts/-Ordner und verwendet immer den Befehl.
| Befehl | Zweck |
|---|---|
| `wingbox install [--global | --project] [--assistant NAME ...] [--dry-run]` |
| `wingbox uninstall [--global | --project] [--assistant NAME ...]` |
wingbox open [PFAD] | Öffne .wingbox/map.html des Projekts im Browser (gibt den Pfad aus, wenn kein Browser vorhanden ist) |
wingbox update [--check] [--dry-run] | Aktualisiere mit pipx, uv oder pip, aktualisiere dann die installierten Skills, Blöcke und Hooks; warnt vor Dateien, die eine frühere Version hinterlassen hat (.code_graph*, wingbox-out/) |
wingbox hook pre-search | Der PreToolUse-Hook von Claude Code; liest die Hook-Eingabe von stdin; aktualisiert den Graphen, bevor er ihn liest |
wingbox hook dirty | Der PostToolUse-Hook von Claude Code bei Edit und Write: markiert die geänderte Datei, sodass der Graph vor der nächsten Verwendung aktualisiert wird |
Jeder dieser Befehle gibt Fakten als Text aus; füge --sexp für S-Ausdrücke hinzu.
Skripte
Dieser Skill bündelt Python-Skripte. Löse die Skill- und Ziel-Stammverzeichnisse auf, bevor du sie ausführst, sodass das gescannte Projekt immer explizit ist:
scripts/code_graph_search.py-- durchsuche den Code-Graphenscripts/build_code_graph.py-- generiere den Code-Graphen aus dem Quellcodescripts/build_infra_topology.py-- extrahiere Kustomize-, Helm- und Terraform-Topologiefaktenscripts/git_descendants.py-- finde alle Commits, die von HEAD (oder einem gegebenen Ref) abstammen
Verwende niemals projektspezifische Kopien dieser Skripte -- sie könnten veraltet sein und JSON statt sexp ausgeben.
Voraussetzung
Lokalisiere den Code-Graphen. Wenn er fehlt, erstelle ihn:
ls .wingbox/index.sexp 2>/dev/null
SKILL_ROOT="$(pwd -P)"
TARGET_ROOT="$(cd /absoluter/pfad/zum/projekt && pwd -P)"
python3 "$SKILL_ROOT/scripts/build_code_graph.py" --root "$TARGET_ROOT"
python3 "$SKILL_ROOT/scripts/build_code_graph.py" --root "$TARGET_ROOT" --full
Python-Indizierung hat keine externen Parser-Abhängigkeiten. Für andere erkannte Sprachen schlägt der erste Build vor der Veröffentlichung fehl, wenn ein Parser fehlt oder die falsche Version hat, und gibt den genauen sprachspezifischen Befehl aus, der ausgeführt werden muss, z.B.:
python3 -m pip install -r "$SKILL_ROOT/requirements/typescript.txt"
python3 -m pip install -r "$SKILL_ROOT/requirements/csharp.txt"
python3 -m pip install -r "$SKILL_ROOT/requirements/ruby.txt"
python3 -m pip install -r "$SKILL_ROOT/requirements/php.txt"
python3 -m pip install -r "$SKILL_ROOT/requirements/dart.txt"
Installiere nur die vom Builder genannten Anforderungsdateien und führe ihn dann erneut aus. requirements.txt ist für die Infrastruktur-Topologie-Abhängigkeit reserviert.
Obligatorischer Workflow: Abfrage vor Code
Führe für nicht-triviale Code-Arbeiten eine Code-Graph-Abfrage vor rg, find, sed, cat, nl, dem Öffnen von Verzeichnissen oder dem Lesen von Quelldateien durch. Der Skill hilft nur, wenn er als erster Schritt der Eingrenzung verwendet wird, nicht als Bestätigung, nachdem der Quellcode bereits untersucht wurde.
Schneller erster Durchlauf, wenn die Aufgabe ein klares Schlüsselwort hat:
python3 scripts/code_graph_search.py quick "Schlüsselwort"
quick sucht nach dem ersten passenden Modul und führt sofort analyze aus. Verwende es, um Grenzdateien, Abhängigkeiten, reverse Abhängigkeiten, Schichten und Verletzungen in einem Schritt zu erhalten. Wenn quick das falsche Modul oder keine Übereinstimmung zurückgibt, verwende den expliziten search -> analyze-Fluss unten.
Schritt 1 -- Finde die Modul-ID:
python3 scripts/code_graph_search.py search "Schlüsselwort"
python3 scripts/code_graph_search.py entity EntityName
Verwende search oder entity, um die Modul-ID zu lokalisieren. Modul-IDs sind vollständige relative Pfade wie billing-service/src/modules/invoice/invoice.service, keine kurzen Codes wie bs34. Der Code-Graph kann intern kurze Pfadzuordnungs-IDs enthalten, aber sie werden automatisch aufgelöst -- übergib immer menschenlesbare pfadartige Zeichenfolgen. RATE oder ERFINDE keine Modul-IDs -- bestätige sie immer zuerst mit search.
Schritt 2 -- Analysiere das Modul (führe dies SOFORT aus, nicht optional):
python3 scripts/code_graph_search.py analyze <modul-id>
analyze ist der PRIMÄRE Befehl. Er gibt den vollständigen Kontext zurück: Grenzdateien, Abhängigkeiten, reverse Abhängigkeiten, Architekturschicht und Verletzungen. Führe ihn immer aus, bevor du Quellcode liest.
Schritt 3 -- Lies nur die Grenzdateien, die in der analyze-Ausgabe aufgelistet sind.
Schritt 4 -- Lies NICHT ganze Verzeichnisse. Wenn die Grenze 2-3 relevante Dateien anzeigt, lies nur diese Dateien. Ignoriere alles andere im Verzeichnis.
Befehlsreferenz
| Befehl | Zweck | Beispiel |
|---|---|---|
search "<muster>" | Sichere wörtliche/.*-Suche im Graphen | search "operative.*service" |
analyze <id> [--all] | Vollständige Modulanalyse (PRIMÄRER Befehl); nennt höchstens 200 Abhängige, es sei denn --all; endet mit dem (advice ...), das das Modul betrifft | analyze drive/modules/drive/drive_schema |
quick <schlüsselwort> | Suche + analysiere erste Übereinstimmung (Abkürzung) | quick operatives |
boundary <id> | Dateien, die für eine Änderung gelesen werden müssen | boundary operatives.service |
boundary <id> --files-only | Nur Dateipfade (kompakt) | boundary operatives.service --files-only |
entity <Name> [--positions] | Finde Definitionen + die Module, die sie verwenden; --positions: jede Verwendung mit Zeile und Spalte | entity DrivePath --positions |
usages <symbol> [--sexp] [--all] | Jede Verwendung eines Symbols (Name, <datei>::Name, <datei>::Klasse.methode) durch Re-Exports und Aliase, nach Datei, zeile:spalte und Art (import, re-export, call, type, extends, reference; unresolved-call für einen Methodenaufruf, dessen Empfängertyp nicht sichtbar ist); höchstens 200, es sei denn --all; ein in mehreren Dateien definierter Name listet die Kandidaten auf | usages src/billing/invoice.ts::Invoice |
deps <id> [tiefe] | Ausgehender Abhängigkeitsbaum | deps operatives.service 3 |
rdeps <id> [tiefe] | Betroffenheitsradius (wer hängt von diesem ab) | rdeps drive_schema 2 |
| `impact <datei | id> [tiefe] --sexp [--all]` | Betroffenheitsradius einer Datei: Abhängige nach kürzester Tiefe + zuerst zu lesende Dateien; listet höchstens 200, es sei denn --all, Zählungen sind immer vollständig; endet mit dem Ratschlag, der die Datei betrifft |
flow <id> <fn> | Verfolge Aufruf-/Datenfluss | flow drive_api fetchFiles |
module <id> | Einzelnes Modul mit Kanten | module operatives.controller |
wingbox init [PFAD] [--force] [--sexp] [--synonyms] | Teile das Repository in Teile auf, bewerte den Architekturstil jedes Teils (mit Punktzahl, Belegen und Quellen) und schreibe .wingbox/config.yaml (behalten, es sei denn --force); --synonyms bildet auch Ordnernamen durch die eingebauten Wortvektoren ab; in einem leeren Ordner --language L --style S --yes [--scaffold] startet ein neues Projekt (ohne diese gibt es die Auswahlmöglichkeiten aus und beendet sich mit 2) | wingbox init --sexp |
wingbox advice [--sexp] [--learned] / `wingbox advice accept | reject [--reason TEXT]` | Öffne Empfehlungen des letzten Builds (verschieben, verletzung-beheben, fehlender-ordner) ohne die abgelehnten oder lange ignorierten; zeichne eine Entscheidung in .wingbox/decisions.sexp auf |
wingbox align [TEIL] [--to STIL] [--learn] [--sexp] | Lücken jedes Teils gegenüber seinem Stil (platzierte Dateien, befolgte Regeln, nicht platzierte Ordner, gebrochene Regeln); --to gegenüber einem anderen Stil; --learn schreibt gelernte Ordner und eine Basislinie, sodass nur neue Verletzungen gemeldet werden | wingbox align --sexp |
wingbox place "<was>" [--part TEIL] [--sexp] | Schicht und Ordner für neuen Code durch die Platzierungsregeln des Stils des Teils (:new, wenn der Ordner noch nicht existiert) und was er importieren darf | wingbox place "repository für rechnungen" --sexp |
wingbox compare [--sexp] | Teile eines Monorepos nach Sprache: Stil, Schichten, Unterschiede (fehlende Schichten, ein Ordnername, der eine andere Schicht bedeutet, ein vom Rest abweichender Stil) und Ratschlag für das abweichende Teil | wingbox compare --sexp |
wingbox learn --agent [TEIL] [--sexp] / wingbox learn --apply [DATEI] | /wingbox learn: führe wingbox learn --agent aus, lies die Dateien, die es nennt, antworte nur in seinem Format ((layer <teil> <ordner> <schicht> :because "..."), (unknown ...), höchstens ein (style ...)), leite die Antwort an wingbox learn --apply weiter, zeige das Ergebnis; bei Fehlern korrigiere die genannten Zeilen und sende die gesamte Antwort erneut. Wenn der Code sich nicht für einen Ordner entscheidet, frage den Benutzer im Chat und antworte mit :because "operator: <seine worte>"; rate niemals. Um .wingbox/config.yaml zu ändern, befolge die Anweisungen am Anfang | wingbox learn --agent |
| `boundaries [id | all]` | Überprüfe die Grenzregeln des Stils jedes Teils (oder der Regeln, die das Teil deklariert); jede Zeile nennt :part, :style und :rule; Typ-Importe und geschätzte Schichten werden separat gemeldet; dann, welche Dateien das tun, was ihre Schicht nicht darf (capability-violation: SQL außerhalb der Repositories, ausgehendes HTTP außerhalb der Infrastruktur, das Framework in der Domäne, mit :line und :evidence) und die Musterprüfungen des Stils (pattern-violation). boundaries-ok nur, wenn jedes Teil geprüft wurde; ein Teil, dessen deklarierte Regeln nicht gelesen wurden oder ohne bestimmten Stil, ist boundaries-not-checked mit boundaries-partial anstelle von ok. Exit-Status: 2 nicht geprüft (deklarierte Regeln nicht gelesen), 1 Verletzungen, 0 sonst - melde niemals einen Bestehen bei Exit 2 |
| `invariants [id | all]` | Überprüfe Verstöße gegen Namenskonventionen |
layers | Zeige alle Module nach Schicht, mit dem Teil, Stil und der Regel, die jede Schicht festgelegt hat | layers |
find_function <name> | Finde Funktions-/Methodendefinitionen | find_function createOrder |
find_type <name> | Finde Typ-/Klassen-/Modul-/Interface-/Enum-Definitionen | find_type DriveDbCommitResponse |
find_callchain <src> <tgt> [tiefe] | Verfolge Aufrufpfad zwischen Funktionen | 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> | Durchsuche Funktionskörper im Quellcode | 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 |
wingbox mcp [--root VERZ] | Führe diese Befehle als Werkzeuge eines MCP-Servers auf stdio aus (build, impact, usages, analyze, quick, boundary, deps, ...) für MCP-Clients | claude mcp add wingbox -- wingbox mcp |
impact akzeptiert einen gewöhnlichen Dateipfad. Ohne --sexp gibt es lesbaren Text für Menschen aus; Agenten übergeben --sexp, um dieselben Fakten in der kompakten S-Ausdrucksform zu erhalten, dem Format, das jeder andere Befehl verwendet.
Kurzreferenz: rg-Abfragen
Wenn du schnelle, zielgerichtete Nachschlagewerke benötigst, ohne das Python-Skript aufzurufen, frage den Code-Graphen direkt mit rg ab. Der Builder schreibt den Graphen nach .wingbox/index.sexp:
# Alle Fakten über ein Modul
rg 'drive/modules/drive_db/api ' .wingbox/index.sexp
# Wer ein Modul importiert
rg 'imports .* drive/modules/commons/result' .wingbox/index.sexp
# Was ein Modul importiert
rg 'imports drive/modules/drive_db/api' .wingbox/index.sexp
# Alle Referenzen auf eine Entität
rg 'DriveDbCommitResponse' .wingbox/index.sexp
# Alle Klassen in einem Repo
rg '^\(cls drive/' .wingbox/index.sexp
# Datenflusskanten
rg 'data-flow' .wingbox/index.sexp
# Python-Module, die über einen aus einer Konfigurationsdatei gelesenen Namen geladen werden
rg 'registry-wires' .wingbox/index.sexp
Diese Einzeiler sind nützlich für schnelle Überprüfungen. Für strukturierte Ausgaben und vollständige Analysen verwende die Python-Skript-Befehle.
Ausgabenotation
Die gesamte Ausgabe besteht aus S-Ausdrucks-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), cs = C#, java = Java, go = Go, rb = Ruby, php = PHP, dart = Dart, rs = Rust.
Edge-Fälle und häufige Fehler
Der Graph fehlt oder ist leer
Wenn .wingbox/index.sexp nicht existiert oder null Fakten enthält:
- Stelle sicher, dass das Projekt nicht leer ist.
- Führe
wingbox build .im Projektstammverzeichnis aus. - Wenn der Build fehlschlägt, folge den Anweisungen zur Installation von Parser-Abhängigkeiten.
- Lese nach dem Build
.wingbox/REPORT.mdfür eine Zusammenfassung.
Die Suche findet nichts
- Verwende
entitymit verschiedenen Schreibweisen. - Verwende
grep_functionsundgrep_types - Stelle die Groß-/Kleinschreibung um (TypeScript verwendet
camelCase, Pythonsnake_case) - Zeige alle Module:
layers
Der Befehl gibt "module not found" zurück
Rate oder erfinde keine Modul-ID. Verwende immer search oder entity, um die genaue Modul-ID zu finden. Modul-IDs sind Pfade wie src/billing/invoice, nicht kurze Namen.
Der Graph ist veraltet
# Erkenne veralteten Graphen
test .wingbox/index.sexp -nt $(find . -type f -not -path './.git/*' -not -path './node_modules/*' | head -1) && echo "Der Graph ist aktuell" || echo "Der Graph ist veraltet"
# Aktualisiere den Graphen
wingbox build .
MCP-Server startet nicht
# Debugging
WINGBOX_DEBUG=1 claude mcp add wingbox -- wingbox mcp --root /absoluter/pfad/zum/projekt
# Stelle sicher, dass der wingbox-Befehl installiert ist
command -v wingbox || pipx install wingbox
Rebuild nach großen Änderungen
Nach einem Merge oder Rebase führe erneut wingbox build . aus. Der Builder parst nur Dateien neu, die sich geändert haben.
Monorepo-Init schlägt fehl
Wenn wingbox init fehlschlägt:
- Stelle sicher, dass das Projekt nicht leer ist.
- Verwende
wingbox init --force, um die Konfiguration zu überschreiben. - Lese
.wingbox/config.yamlund passe Teile und Stile nach Bedarf manuell an. - Führe
wingbox initmit--synonymserneut aus, um automatische Ordnerzuordnung zu erhalten.