Communityコーディング&開発github.com

wingbox

大規模リポジトリやモノレポ向けのコードグラフ。grep やファイルを読む前に、変更が何を壊すか(ブラスト半径、影響分析)、誰がファイル・関数・型・パッケージを使っているか、機能がどこに実装されているか、どのファイルを最初に読むべきか、モジュールやパッケージがどのように依存し合っているかを調べるために使用します。リファクタリング、パッケージ間の変更、または重要な編集の前や、不慣れなコードベースを探索する際に役立ちます。アーキテクチャを考慮したコード検索、依存関係グラフ、呼び出しフロー、モジュール境界、アーキテクチャ違反を構築し、Python、TypeScript、TSX、Rust、C#、Java、Go、Ruby、Ruby on Rails、PHP、Laravel、Blade、Livewire、Eloquent、Dart、Flutter をサポートします。

wingbox とは?

Wingbox は、大規模リポジトリやモノレポ向けのコードグラフツールであり、ソースコードを読む前にアーキテクチャを探索・分析することを可能にします。開発者は `/wingbox` コマンド (Codex では `$wingbox`) を使用して、コードベースのモジュール境界、依存関係、呼び出しフロー、ブラスト半径(影響範囲)を素早く把握できます。内部で `.wingbox/index.sexp` という S式ベースのグラフファイルを構築し、`wingbox build .` で最新の状態に保ちます。このスキルは Claude Code、Codex、Cursor などの AI アシスタントと統合可能で、特に `search`、`analyze`、`impact`、`usages` などのコマンドを提供します。`analyze` が主要コマンドであり、モジュールの完全なコンテキスト(境界ファイル、依存関係、逆依存関係、アーキテクチャ層、違反)を返します。ユーザーはまずグラフを検索してモジュールIDを特定し、そのIDで `analyze` を実行し、出力された境界ファイルのみを読み取るというワークフローが推奨されます。Python、TypeScript、Rust、C#、Java、Go、Ruby、PHP、Dart/Flutter など多数の言語をサポートし、Python インデックス作成には外部パーサー依存関係が不要ですが、他の言語では必要に応じて言語固有のパーサーをインストールできます。

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

Installed? Explore more コーディング&開発 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

Wingbox -- コードグラフアーキテクチャ発見ツール

ソースファイルを読む前に、.wingbox/index.sexp をクエリしてモジュール、境界、依存関係を発見します。決して盲目的にコードを読まず、最初にグラフをクエリしてください。

/wingbox

ユーザーが /wingbox (Codex では $wingbox) と入力した場合、他の何よりも先に以下を実行してください:

  • /wingbox (引数なし): グラフ (プロジェクトルートの .wingbox/index.sexp; すべての wingbox コマンドはサブフォルダからもそれを見つけます) を見つけます。グラフがないか古い場合は wingbox build . でビルドします。グラフは、プロジェクトのファイルがグラフファイルより後に変更された場合に古くなります。この確認は以下のコマンドで行います:

    G=.wingbox/index.sexp
    [ ! -f "$G" ] || find . -type f -newer "$G" -not -path './.git/*' \
      -not -path './.wingbox/*' -not -path '*/node_modules/*' -print -quit
    

    リビルドでは、変更されたファイルのみが再解析されます。その後、.wingbox/REPORT.md を読み、ユーザーにその「主要な発見事項」、最も依存されているモジュール、どこから読み始めるべきかを伝え、マップが .wingbox/map.html にあることを伝えます (wingbox open でブラウザに表示されます、オフラインでも可)。

  • /wingbox <ファイル>: wingbox impact <ファイル> 2 を実行し、そのファイルに依存するものと、最初に読むべきファイルを要約します。

  • /wingbox <コマンド> ...: wingbox <コマンド> ... を実行します (例: /wingbox quick "ファイルアップロード", /wingbox analyze src/billing/invoice)。

コマンドの実行

wingbox コマンドがインストールされている場合 (command -v wingbox)、以下のすべてのクエリに対して wingbox <コマンド> ... を実行し、ビルドには wingbox build PATH を使用します。これらはスクリプトと同じ引数を取ります。wingbox install でインストールされたスキルには scripts/ フォルダはなく、常にコマンドを使用します。

コマンド目的
wingbox install [--global|--project] [--assistant NAME ...] [--dry-run]このスキルを各アシスタントにコピーし、always-on ブロックを CLAUDE.md / AGENTS.md に追加し、Claude Code の検索・編集フックを追加します
wingbox uninstall [--global|--project] [--assistant NAME ...]install が追加したものを正確に削除します
wingbox open [PATH]プロジェクトの .wingbox/map.html をブラウザで開きます (ブラウザがない場合はパスを表示します)
wingbox update [--check] [--dry-run]pipx、uv、または pip でアップグレードし、インストールされたスキル、ブロック、フックを更新します。以前のバージョンが残したファイル (.code_graph*、wingbox-out/) について警告します
wingbox hook pre-searchClaude Code の PreToolUse フック。標準入力からフック入力を読み取り、読み取り前にグラフを更新します
wingbox hook dirtyClaude Code の PostToolUse フック (編集・書き込み時)。変更されたファイルをマークし、次回使用前にグラフが更新されるようにします

これらの各コマンドはテキストとして情報を出力します。--sexp を付けると S式で出力します。

スクリプト

このスキルには Python スクリプトがバンドルされています。スキルルートとターゲットルートを解決してから実行し、スキャン対象のプロジェクトが常に明示的になるようにしてください:

  • scripts/code_graph_search.py -- コードグラフをクエリ
  • scripts/build_code_graph.py -- ソースからコードグラフを生成
  • scripts/build_infra_topology.py -- Kustomize、Helm、Terraform のトポロジー情報を抽出
  • scripts/git_descendants.py -- HEAD (または指定された ref) から派生するすべてのコミットを見つける

プロジェクトローカルなコピーは決して使用しないでください。それらは古く、JSON を出力する可能性があります。

前提条件

コードグラフを見つけます。存在しない場合はビルドします:

ls .wingbox/index.sexp 2>/dev/null
SKILL_ROOT="$(pwd -P)"
TARGET_ROOT="$(cd /absolute/path/to/project && 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 のインデックス作成には外部パーサーの依存関係は必要ありません。他の検出された言語については、初回ビルドはパーサーがないかバージョンが間違っている場合に公開前に失敗し、以下のような言語ごとの正確なコマンドを表示します:

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"

ビルダーが指定した要件ファイルのみをインストールし、再実行します。requirements.txt はインフラトポロジーの依存関係のために予約されています。

必須ワークフロー: コードの前にクエリ

重要なコード作業の場合は、rg、find、sed、cat、nl、ディレクトリを開く、またはソースファイルを読む前に、コードグラフクエリを実行してください。このスキルは、最初のスコープ設定のステップとして使用された場合にのみ役立ち、ソースがすでに検査された後の確認として使用された場合には役立ちません。

タスクに明確なキーワードがある場合の高速な最初のパス:

python3 scripts/code_graph_search.py quick "キーワード"

quick は最初に一致したモジュールを検索し、すぐに analyze を実行します。これにより、境界ファイル、依存関係、逆依存関係、レイヤー、違反を一度に取得できます。quick が間違ったモジュールを返したり、一致しない場合は、以下の明示的な search -> analyze フローを使用してください。

ステップ 1 -- モジュール ID を見つける:

python3 scripts/code_graph_search.py search "キーワード"
python3 scripts/code_graph_search.py entity EntityName

search または entity を使用してモジュール ID を見つけます。モジュール ID は billing-service/src/modules/invoice/invoice.service のような完全な相対パスであり、bs34 のような短いコードではありません。コードグラフは内部的に短いパスマップ ID を含む場合がありますが、自動的に解決されます。常に人間が読めるパス風の文字列を渡してください。モジュール ID を推測したり発明したりせず、必ず最初に search で確認してください。

ステップ 2 -- モジュールを分析する (すぐに実行してください。任意ではありません):

python3 scripts/code_graph_search.py analyze <モジュールID>

analyze は主要なコマンドです。完全なコンテキスト (境界ファイル、依存関係、逆依存関係、アーキテクチャ層、違反) を返します。ソースを読む前に必ず実行してください。

ステップ 3 -- analyze の出力にリストされた境界ファイルのみを読んでください。

ステップ 4 -- ディレクトリ全体を読まないでください。 境界に 2~3 の関連ファイルしか表示されていない場合は、それらのファイルのみを読んでください。ディレクトリ内の他のすべては無視します。

コマンドリファレンス

コマンド目的例
search "<パターン>"グラフに対する安全なリテラル/.* 検索search "operative.*service"
analyze <id> [--all]完全なモジュール分析 (主要なコマンド); --all がない限り最大200の依存元を表示; 最後にモジュールに関する (advice ...) を表示analyze drive/modules/drive/drive_schema
quick <キーワード>最初の一致を検索 + 分析 (ショートカット)quick operatives
boundary <id>変更のために読むべきファイルboundary operatives.service
boundary <id> --files-onlyファイルパスのみ (コンパクト)boundary operatives.service --files-only
entity <名前> [--positions]定義 + それらを使用するモジュールを見つける; --positions: すべての使用箇所を行・列付きで表示entity DrivePath --positions
usages <シンボル> [--sexp] [--all]1つのシンボル (Name、<ファイル>::Name、<ファイル>::Class.method) のすべての使用箇所を、再エクスポートやエイリアスを含めて、ファイル・行:列・種類 (import、re-export、call、type、extends、reference; レシーバー型が見えないメソッド呼び出しは unresolved-call) ごとに表示; --all がない限り最大200; 複数のファイルで定義された名前は候補をリストusages src/billing/invoice.ts::Invoice
deps <id> [深さ]外部への依存関係ツリーdeps operatives.service 3
rdeps <id> [深さ]ブラスト半径 (これに依存するもの)rdeps drive_schema 2
impact <ファイル|id> [深さ] --sexp [--all]1つのファイルのブラスト半径: 最短深さごとの依存元 + 最初に読むべきファイル; --all がない限り最大200をリスト、カウントは常に完全; ファイルに関するアドバイスで終了impact src/billing/invoice.service.ts --sexp
flow <id> <関数>呼び出し/データフローをトレースflow drive_api fetchFiles
module <id>エッジ付きの単一モジュールmodule operatives.controller
wingbox init [PATH] [--force] [--sexp] [--synonyms]リポジトリをパートに分割し、それぞれのアーキテクチャスタイルを評価 (スコア、根拠、ソース付き) し、.wingbox/config.yaml を書き込み (--force がない限り保持); --synonyms は組み込みの単語ベクトルを使用してフォルダ名もマッピング; 空のフォルダでは --language L --style S --yes [--scaffold] で新しいプロジェクトを開始 (これらがない場合は選択肢を表示して終了コード2で終了)wingbox init --sexp
wingbox advice [--sexp] [--learned] / wingbox advice accept|reject <id> [--reason TEXT]最後のビルドの推奨事項 (move、fix-violation、missing-folder) を、却下されたものや長期間無視されたものを除いて表示; .wingbox/decisions.sexp に決定を記録wingbox advice --sexp
wingbox align [PART] [--to STYLE] [--learn] [--sexp]各パートのスタイルに対するギャップ (配置されたファイル、従われたルール、配置されていないフォルダ、破られたルール); --to で別のスタイルと比較; --learn は学習したフォルダとベースラインを書き込み、新しい違反のみが報告されるようにするwingbox align --sexp
wingbox place "<何を>" [--part PART] [--sexp]パートのスタイルの配置ルール (フォルダがまだ存在しない場合は :new) とインポート可能なものに基づく、新しいコードのレイヤーとフォルダwingbox place "repository for invoices" --sexp
wingbox compare [--sexp]モノレポのパートを言語ごとに: スタイル、レイヤー、差異 (欠落しているレイヤー、別のレイヤーを意味するフォルダ名、大多数と異なるスタイル) と、逸脱しているパートへのアドバイスwingbox compare --sexp
wingbox learn --agent [PART] [--sexp] / wingbox learn --apply [FILE]/wingbox learn: wingbox learn --agent を実行し、それが指定したファイルを読み、そのフォーマットのみで回答 ((layer <part> <folder> <layer> :because "...")、(unknown ...)、最大1つの (style ...))、その回答を wingbox learn --apply にパイプし、結果を表示; エラー時は指定された行を修正し、回答全体を再送信。コードがフォルダを決定しない場合は、チャットでユーザーに尋ね、:because "operator: <ユーザーの言葉>" で回答; 決して推測しない。.wingbox/config.yaml を変更するには、ファイル先頭の指示に従うwingbox learn --agent
boundaries [id|all]各パートのスタイルの境界ルール (またはパートが宣言するルール) をチェック; 各行は :part、:style、:rule を命名; 型のみのインポートと推測されたレイヤーは別途報告; 次に、ファイルがそのレイヤーでしてはいけないこと (capability-violation: リポジトリ外のSQL、インフラ外のアウトバウンドHTTP、ドメイン内のフレームワーク) を :line と :evidence 付きで、およびスタイルのパターンチェック (pattern-violation) を報告。すべてのパートがチェックされた場合のみ boundaries-ok; 宣言されたルールが読み取られなかったパート、またはスタイルが決定されていないパートは boundaries-not-checked となり、ok の代わりに boundaries-partial が表示。終了ステータス: 2 (宣言されたルールが読み取られずチェックされなかった場合)、1 (違反あり)、0 (それ以外) - 終了コード2で合格を報告しないboundaries all
invariants [id|all]命名規則違反をチェックinvariants all
layersレイヤーごとにすべてのモジュールを、各レイヤーを設定したパート、スタイル、ルールとともに表示layers
find_function <名前>関数/メソッド定義を見つけるfind_function createOrder
find_type <名前>型/クラス/モジュール/インターフェース/列挙型定義を見つけるfind_type DriveDbCommitResponse
find_callchain <src> <tgt> [深さ]関数間の呼び出しパスをトレースfind_callchain createOrder processPayment
find_callers <関数> [深さ]この関数を呼び出すものfind_callers handleRequest 3
find_calls <関数> [深さ]この関数は何を呼び出すかfind_calls createOrder 2
grep_functions <パターン>ソース内の関数本体を検索grep_functions "validate.*input"
diff_functions [ref]git diff で変更された関数diff_functions HEAD~3
query '<sexp>'合成可能な Scheme クエリquery '(count (boundary "X"))'
repl対話型 Scheme REPLrepl
wingbox mcp [--root DIR]これらのコマンドを MCP サーバーのツールとして stdio 上で実行 (build、impact、usages、analyze、quick、boundary、deps、...) MCP クライアント向けclaude mcp add wingbox -- wingbox mcp

impact は通常のファイルパスを受け入れます。--sexp なしでは人間が読めるテキストを出力します。エージェントは --sexp を渡して、他のすべてのコマンドが使用するコンパクトな S式形式で同じ情報を取得します。

クイックリファレンス: rg クエリ

Python スクリプトを呼び出さずに高速で的を絞った検索が必要な場合は、rg でコードグラフを直接クエリします。ビルダーはグラフを .wingbox/index.sexp に書き込みます:

# モジュールに関するすべての情報
rg 'drive/modules/drive_db/api ' .wingbox/index.sexp

# モジュールをインポートしているもの
rg 'imports .* drive/modules/commons/result' .wingbox/index.sexp

# モジュールがインポートしているもの
rg 'imports drive/modules/drive_db/api' .wingbox/index.sexp

# エンティティへのすべての参照
rg 'DriveDbCommitResponse' .wingbox/index.sexp

# リポジトリ内のすべてのクラス
rg '^\(cls drive/' .wingbox/index.sexp

# データフローエッジ
rg 'data-flow' .wingbox/index.sexp

# 設定ファイルから読み取られた名前でロードされた Python モジュール
rg 'registry-wires' .wingbox/index.sexp

これらのワンライナーはクイックチェックに便利です。構造化された出力と完全な分析には、Python スクリプトコマンドを使用してください。

出力表記

すべての出力は S式の情報で、1行に1つです。完全なフォーマットについては references/sexp-notation.md を参照してください。

主要なパターン:

(boundary <モジュール> :lang py :file <パス> :purpose "<説明>")
(boundary-dep <モジュール> <依存先> :lang ts :file <パス> :relation imports)
(boundary-rdep <モジュール> <依存元> :lang tsx :file <パス> :relation imports)
(boundary-summary <モジュール> :total 10 :deps 7 :rdeps 2)
(entity-def cls <モジュール> <名前> <行> :lang py :file <パス>)
(violation <src> <tgt> :src-layer domain :tgt-layer api :via imports :lang ts "<理由>")
(result <モジュールまたはパス>)
(result-count 42)

:lang の値: py = Python (スネークケース)、ts = TypeScript (キャメルケース)、tsx = TSX (パスカルケース)、rs = Rust、cs = C#、java = Java、go = Go、rb = Ruby、php = PHP、dart = Dart。エンティティ名は従来の大文字小文字の区別を維持します。

関連スキル