structure-visualizelisted

# Structure Visualize 指定された内容の「開発に関する静的構造」を、カテゴリ配色 + エリア枠付きの自己完結 HTML 構成図として可視化する。設計レビュー・設計共有・実装前の構造把握の補助が目的。git リポジトリであることは要求しない。 ## 引数の解析 `$ARGUMENTS` 全体を「可視化対象の指定」として解釈する（自然文・ファイル / ディレクトリパスの混在可。フラグは無い）: - パスらしきトークンは存在確認する。存在しなければエラーを表示して終了する - 引数が無い場合は直近の会話コンテキストから対象を推定する。推定できなければ AskUserQuestion で対象を確認する（使えないエージェントではテキストで確認する。以降の AskUserQuestion も同様） ## 手順 ### 1. 対象確定・ゲート表示 - 入力種別を判定する（組み合わせ可）: **会話**（会話中で説明された設計）/ **ドキュメント**（指定された設計文書）/ **コード解析**（リポジトリ内の IaC・スキーマ・ソース） - 図種を判定する: インフラ構成 / ER / コンポーネント / クラス / モジュール依存 / 汎用 - 確定後、以下のブロックを 1 回表示する: ``` 対象: <説明 or パス> 入力種別: <会話 / ドキュメント / コード解析> 図種: <インフラ構成 / ER / コンポーネント / クラス / モジュール依存 / 汎用> ``` ### 2. 構造の抽出 - **会話**: 会話中の設計記述から要素（ノード候補）と関係（エッジ候補）を抽出する - **ドキュメント**: 指定ファイルを読み、要素と関係を抽出する - **コード解析**（図種に応じた読み方）: - IaC: resource / module ブロックと参照関係 - DB: migration / DDL / ORM スキーマからテーブル・カラム・FK - コンポーネント / クラス: 定義 + import / 継承 / 実装 / 参照 - Grep での関係追跡は指定スコープ内に限定する（スコープ外へ 2 ホップ以上辿らない） ### 3. 構造化（GRAPH JSON） [references/html-guide.md](references/html-guide.md) のスキーマ・作図指針に従い、抽出結果を GRAPH JSON に整理する: - `group` はカテゴリ / レイヤー / 所属（プロバイダ・アーキテクチャ層など「最も伝えたい大きな括り」。1 階層のみ） - `layout` は同ガイドの選択基準で決める（所属・境界が主題 → areas / 依存の流れ・ER → flow） - ノード数 80 超が見込まれる場合はディレクトリ / リソース種別単位に集約し、集約内容を完了報告に明記する（無言の切り詰めをしない） - `members` は 1 ノード 10 行を目安とし、超過分は「…他 N 件」の行を置く ### 4. HTML 生成 - 出力先 `docs/structure-diagrams/` が無ければ AskUserQuestion で作成可否を確認する（拒否されたら出力先ディレクトリを尋ねる） - ファイル名: `<図種プレフィックス>-<対象スラグ>-<日付>.html` - 図種プレフィックス: `infra` / `er`