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-search | Claude Code の PreToolUse フック。標準入力からフック入力を読み取り、読み取り前にグラフを更新します |
wingbox hook dirty | Claude 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 REPL | repl |
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。エンティティ名は従来の大文字小文字の区別を維持します。