# Structure Visualize

> 指定された開発構造（インフラ構成、ER 図、コンポーネント設計、クラス構成、モジュール依存など）を 自己完結 HTML の構成図として docs/structure-diagrams/ に出力する。入力は会話で説明された設計・ 設計ドキュメント・リポジトリ内の実体（IaC / DB スキーマ / ソースコード）のいずれでもよい。 カテゴリ別配色とエリア枠（レイヤー・所属のグルーピング囲み）、ノード詳細パネル・ズーム/パン付き。 git ブランチ差分の可視化は /branch-visualize（本スキルは指定内容のスナップショット構造を描く）。 ユーザーが「構造を可視化して」「構成図にして」「/structure-visualize」と言ったら起動する。

- Skill: `mjcreativelab/structure-visualize` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add mjcreativelab/structure-visualize`
- Raw SKILL.md: https://api.skillmd.com/api/skills/mjcreativelab/structure-visualize/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: mjcreativelab (https://skillmd.com/u/mjcreativelab)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/mjcreativelab/structure-visualize

---


# 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）
- areas ではエリア内のノードが `nodes` の配列順で縦 1 列に積まれる（エリア同士は横並び）。**各 group のノードは流れの順に並べて渡す**
- ノード数 80 超が見込まれる場合はディレクトリ / リソース種別単位に集約し、集約内容を完了報告に明記する（無言の切り詰めをしない）
- `members` は 1 ノード 10 行を目安とし、超過分は「…他 N 件」の行を置く

### 4. HTML 生成

- 出力先 `docs/structure-diagrams/` が無ければ AskUserQuestion で作成可否を確認する（拒否されたら出力先ディレクトリを尋ねる）
- ファイル名: `<図種プレフィックス>-<対象スラグ>-<日付>.html`
  - 図種プレフィックス: `infra` / `er` / `component` / `class` / `module` / `structure`（汎用）
  - 対象スラグ: 対象の短い kebab-case 表現（例: `payment-system`）
  - 日付: `TZ=Asia/Tokyo date +%Y-%m-%d`
- [assets/diagram-template.html](assets/diagram-template.html) を読み、`__TITLE__` と `__GRAPH_JSON__` を置換して生成する（エスケープ規則は html-guide.md 参照。配色・レイアウトはテンプレートが内蔵しており生成側の座標計算は不要）

### 5. 完了報告

- 生成したファイルのパスを表示する
- 図の要点（主要な要素と関係、エリア構成）を 2〜3 文で添える
- 集約・省略した内容があれば明記する
- 生成物のコミットはしない（コミットするかどうかはユーザーの判断に委ねる）

## エラーハンドリング

| ケース | 挙動 |
|---|---|
| 指定パスが存在しない | エラーを表示して終了 |
| 対象が特定できない（引数なし・会話にも設計の言及なし） | AskUserQuestion で対象を確認 |
| `docs/structure-diagrams/` が無い | AskUserQuestion で作成可否を確認（拒否時は出力先を尋ねる） |
| 対象が広大（ノード数 80 超見込み） | 集約して描画し、完了報告に集約内容を明記 |
| git リポジトリでない | エラーにしない（本スキルは git 不要） |

## やらないこと

- 振る舞い・時系列の図（シーケンス図・フローチャート・状態遷移図）— 静的構造のみを描く
- 多段ネストのコンテナ（入れ子枠）— group は 1 階層のみ
- git ブランチ差分の可視化（→ /branch-visualize）
- 指定スコープ外の無差別リポジトリスキャン（広大な対象は集約 + 明記）
- 生成物の自動コミット
- コード内容の外部送信・外部レンダリング API / CDN への依存（自己完結 HTML・オフライン動作）
- mermaid / d2 出力（HTML のみ）