CommunityCodierung & Entwicklunggithub.com

wingbox

Code-Graph für große Repositories und Monorepos. Nutze ihn vor grep oder dem Lesen von Dateien, wenn es darum geht, was eine Änderung kaputt macht (Blast Radius, Auswirkungsanalyse), wer eine Datei, Funktion, Type oder ein Paket verwendet, wo eine Funktion implementiert ist, welche Dateien zuerst gelesen werden sollten oder wie Module und Pakete voneinander abhängen; vor einem Refactoring, einer paketübergreifenden Änderung oder einer nicht-trivialen Bearbeitung; und beim Erkunden einer unbekannten Codebasis.

Was ist wingbox?

Wingbox ist ein AI-Agenten-Skill für Code-Graph-basierte Architektur-Entdeckung, der speziell für große Repositories und Monorepos entwickelt wurde. Er unterstützt die Sprachen Python, TypeScript, TSX, Rust, C#, Java, Go, Ruby, Ruby on Rails, PHP, Laravel, Blade, Livewire, Eloquent, Dart und Flutter. Der Skill wird von Claude Code, Codex und anderen KI-Assistenten genutzt, indem er den Befehl `/wingbox` (bzw. `$wingbox` in Codex) bereitstellt. Er erstellt und durchsucht einen Code-Graphen (`wingbox build .`), um Abhängigkeitsgraphen, Aufrufflüsse, Modulgrenzen und Architekturverletzungen zu analysieren. Seine primären Anwendungsfälle sind die Blast-Radius-Analyse, die Dateisuche in großen Codebasen, die Impact-Analyse vor Änderungen und die Erkundung unbekannter Projekte. Der Skill arbeitet mit S-Ausdrücken und bietet mehr als 20 Befehle wie `analyze`, `quick`, `impact`, `boundary`, `search`, `deps`, `rdeps`, `flow` und `entity`. Er installiert sich selbst über `wingbox install` und kann als MCP-Server (`wingbox mcp`) ausgeführt werden, um eine strukturierte, Graph-gesteuerte Code-Navigation vor dem Lesen von Quelldateien zu ermöglichen.

Funktioniert mit✓Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/aileron-tech/wingbox/tree/HEAD

Installed? Explore more Codierung & Entwicklung skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

In Ihrer bevorzugten KI fragen

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

Dokumentation

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:

  • /wingbox ohne Argument: Finde den Graphen (.wingbox/index.sexp im Projektstammverzeichnis; jeder wingbox-Befehl findet ihn auch aus einem Unterordner). Erstelle ihn mit wingbox 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 -quit
    

    Ein Neubau parst nur die Dateien neu, deren Inhalt sich geändert hat. Lies dann .wingbox/REPORT.md und 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.html ist (wingbox open zeigt sie im Browser an, offline).

  • /wingbox <datei>: Führe wingbox impact <datei> 2 aus und fasse zusammen, was von der Datei abhängt und welche Dateien zuerst gelesen werden sollten.

  • /wingbox <befehl> ...: Führe wingbox <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.

BefehlZweck
`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-searchDer PreToolUse-Hook von Claude Code; liest die Hook-Eingabe von stdin; aktualisiert den Graphen, bevor er ihn liest
wingbox hook dirtyDer 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-Graphen
  • scripts/build_code_graph.py -- generiere den Code-Graphen aus dem Quellcode
  • scripts/build_infra_topology.py -- extrahiere Kustomize-, Helm- und Terraform-Topologiefakten
  • scripts/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

BefehlZweckBeispiel
search "<muster>"Sichere wörtliche/.*-Suche im Graphensearch "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 betrifftanalyze 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üssenboundary operatives.service
boundary <id> --files-onlyNur Dateipfade (kompakt)boundary operatives.service --files-only
entity <Name> [--positions]Finde Definitionen + die Module, die sie verwenden; --positions: jede Verwendung mit Zeile und Spalteentity 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 aufusages src/billing/invoice.ts::Invoice
deps <id> [tiefe]Ausgehender Abhängigkeitsbaumdeps operatives.service 3
rdeps <id> [tiefe]Betroffenheitsradius (wer hängt von diesem ab)rdeps drive_schema 2
`impact <dateiid> [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-/Datenflussflow drive_api fetchFiles
module <id>Einzelnes Modul mit Kantenmodule 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 acceptreject [--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 werdenwingbox 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 darfwingbox 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 Teilwingbox 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 Anfangwingbox learn --agent
`boundaries [idall]`Ü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 [idall]`Überprüfe Verstöße gegen Namenskonventionen
layersZeige alle Module nach Schicht, mit dem Teil, Stil und der Regel, die jede Schicht festgelegt hatlayers
find_function <name>Finde Funktions-/Methodendefinitionenfind_function createOrder
find_type <name>Finde Typ-/Klassen-/Modul-/Interface-/Enum-Definitionenfind_type DriveDbCommitResponse
find_callchain <src> <tgt> [tiefe]Verfolge Aufrufpfad zwischen Funktionenfind_callchain createOrder processPayment
find_callers <fn> [tiefe]Wer ruft diese Funktion auffind_callers handleRequest 3
find_calls <fn> [tiefe]Was ruft diese Funktion auffind_calls createOrder 2
grep_functions <muster>Durchsuche Funktionskörper im Quellcodegrep_functions "validate.*input"
diff_functions [ref]Geänderte Funktionen im git-Diffdiff_functions HEAD~3
query '<sexp>'Zusammensetzbare Scheme-Abfragequery '(count (boundary "X"))'
replInteraktive Scheme-REPLrepl
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-Clientsclaude 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:

  1. Stelle sicher, dass das Projekt nicht leer ist.
  2. Führe wingbox build . im Projektstammverzeichnis aus.
  3. Wenn der Build fehlschlägt, folge den Anweisungen zur Installation von Parser-Abhängigkeiten.
  4. Lese nach dem Build .wingbox/REPORT.md für eine Zusammenfassung.

Die Suche findet nichts

  1. Verwende entity mit verschiedenen Schreibweisen.
  2. Verwende grep_functions und grep_types
  3. Stelle die Groß-/Kleinschreibung um (TypeScript verwendet camelCase, Python snake_case)
  4. 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:

  1. Stelle sicher, dass das Projekt nicht leer ist.
  2. Verwende wingbox init --force, um die Konfiguration zu überschreiben.
  3. Lese .wingbox/config.yaml und passe Teile und Stile nach Bedarf manuell an.
  4. Führe wingbox init mit --synonyms erneut aus, um automatische Ordnerzuordnung zu erhalten.

Verwandte Skills