draw-io-diagram-generator

Draw.io 図表ジェネレーター

このスキルを使うと、正しい mxGraph XML 構造で draw.io（.drawio）図表ファイルを生成、編集、検証できます。生成されたファイルは、手動で修正しなくてもDraw.io VS Code extension（hediet.vscode-drawio）ですぐに開けます。お好みに応じて、draw.io のウェブアプリやデスクトップアプリでファイルを開くこともできます。

---

1. このスキルを使う場面

トリガーとなるフレーズ（以下のフレーズを見かけたら、このスキルを読み込みます）

• 「図表を作成して」「フローチャートを描いて」「アーキテクチャ図を生成して」
• 「シーケンス図を設計して」「UML クラス図を作成して」「ER 図を作成して」
• 「.drawio ファイルを追加して」「図表を更新して」「フローを可視化して」
• 「アーキテクチャを文書化して」「データモデルを示して」「サービス間のやり取りを図示して」
• .drawio、.drawio.svg、.drawio.png ファイルの作成または変更を求めるあらゆる依頼

対応する図表の種類

図表の種類	テンプレート	説明
フローチャート	assets/templates/flowchart.drawio	判断と分岐を含むプロセスフロー
システムアーキテクチャ	assets/templates/architecture.drawio	多層型／レイヤー型のサービスアーキテクチャ
シーケンス図	assets/templates/sequence.drawio	アクターのライフラインと時系列のメッセージフロー
ER 図	assets/templates/er-diagram.drawio	関連を含むデータベーステーブル
UML クラス図	assets/templates/uml-class.drawio	クラス、インターフェース、列挙型、関連
ネットワークトポロジー	（図形ライブラリを使用）	ルーター、サーバー、ファイアウォール、サブネット
BPMN ワークフロー	（図形ライブラリを使用）	ビジネスプロセスのイベント、タスク、ゲートウェイ
マインドマップ	（手動）	中心となるトピックと、そこから放射状に伸びるブランチ

---

2. 前提条件

• VS Code との連携を有効にして実行する場合は、drawio 拡張機能をインストールします：draw.io VS Code extension — hediet.vscode-drawio（拡張機能 ID）。次のコマンドでインストールします：

  ext install hediet.vscode-drawio
  

• 対応するファイル拡張子：.drawio、.drawio.svg、.drawio.png
• Python 3.8+（任意）— scripts/ 内の検証スクリプトと図形挿入スクリプトで使用します

---

3. エージェントの作業手順

図表を生成するすべてのタスクで、以下の手順に従います。

ステップ 1 — 依頼を理解する

確認する、または推測します：

1. 図表の種類 — どのような図表ですか？（フローチャート、アーキテクチャ、UML、ER、シーケンス、ネットワークなど）
2. エンティティ／アクター — 主なコンポーネント、アクター、クラス、テーブルは何ですか？
3. 関連 — どのようにつながっていますか？方向は？多重度は？
4. 出力パス — .drawio ファイルはどこに保存しますか？
5. 既存ファイル — 新規作成ですか、それとも既存ファイルの編集ですか？

依頼が曖昧な場合は、文脈から最も妥当な図表の種類を推測します（例：「テーブルを示して」→ ER 図、「API 呼び出しの流れを示して」→ シーケンス図）。

ステップ 2 — テンプレートを選択するか、新規作成する

• テンプレートを使用：図表の種類が assets/templates/ 内のテンプレートに一致する場合は、そのテンプレートを使用します。テンプレートの構造をコピーし、プレースホルダーの値を置き換えます。
• 新規作成：独自のレイアウトにする場合は、次の最小限の有効なスケルトンから始めます：

<mxfile host="Electron" modified="" version="26.0.0">
  <diagram id="page-1" name="Page-1">
    <mxGraphModel dx="1422" dy="762" grid="1" gridSize="10" guides="1"
                  tooltips="1" connect="1" arrows="1" fold="1"
                  page="1" pageScale="1" pageWidth="1169" pageHeight="827"
                  math="0" shadow="0">
      <root>
        <mxCell id="0" />
        <mxCell id="1" parent="0" />
        
      </root>
    </mxGraphModel>
  </diagram>
</mxfile>

ルール：ID 0 と 1 は必ず必要で、最初の 2 つのセルでなければなりません。再利用してはいけません。

ステップ 3 — レイアウトを計画する

XML を生成する前に、論理的な配置をスケッチします：

• 行または階層に分けて整理します（レイヤーにはスイムレーンを使用します）
• 水平方向の間隔：同じ行の図形間を 40–60px にします
• 垂直方向の間隔：階層の行間を 80–120px にします
• 標準的な図形サイズ：プロセスボックスは 120x60 px、スイムレーンは 160x80 px
• デフォルトのキャンバス：A4 横向き = 1169 x 827 px

ステップ 4 — mxGraph XML を生成する

頂点セル（すべての図形）：

<mxCell id="unique-id" value="Label"
        style="rounded=1;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;"
        vertex="1" parent="1">
  <mxGeometry x="100" y="100" width="120" height="60" as="geometry" />
</mxCell>

エッジセル（すべてのコネクタ）：

<mxCell id="edge-id" value="Label (optional)"
        style="edgeStyle=orthogonalEdgeStyle;html=1;"
        edge="1" source="source-id" target="target-id" parent="1">
  <mxGeometry relative="1" as="geometry" />
</mxCell>

重要なルール：

• すべてのセル ID はファイル内で一意である必要があります
• すべての頂点には、x、y、width、height、as="geometry" を持つ mxGeometry 子要素が必要です
• すべてのエッジの source と target は、既存の頂点 ID を参照する必要があります。例外：浮動エッジ（シーケンス図のライフラインなど）では、代わりに <mxGeometry> 内の sourcePoint／targetPoint を使用します。§4「シーケンス図」を参照してください
• すべてのセルの parent は、既存のセル ID を参照する必要があります
• ラベルに HTML（<b>、<i>、<br>）が含まれる場合は、スタイルに html=1 を使用してください
• ラベル内の XML 特殊文字をエスケープしてください：& => &、< => <、> => >

ステップ 5 — 適切なスタイルを適用する

一貫性を保つため、標準のセマンティックカラーパレットを使用します：

用途	fillColor	strokeColor
プライマリ／情報	#dae8fc	#6c8ebf
成功／開始	#d5e8d4	#82b366
警告／判断	#fff2cc	#d6b656
エラー／終了	#f8cecc	#b85450
ニュートラル	#f5f5f5	#666666
外部／パートナー	#e1d5e7	#9673a6

図の種類ごとの一般的なスタイル文字列：

# Rounded process box (flowchart)
rounded=1;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;

# Decision diamond
rhombus;whiteSpace=wrap;html=1;fillColor=#fff2cc;strokeColor=#d6b656;

# Start/End terminal
ellipse;whiteSpace=wrap;html=1;fillColor=#d5e8d4;strokeColor=#82b366;

# Database cylinder
shape=mxgraph.flowchart.database;whiteSpace=wrap;html=1;fillColor=#f8cecc;strokeColor=#b85450;

# Swimlane container (tier)
swimlane;startSize=30;fillColor=#dae8fc;strokeColor=#6c8ebf;fontStyle=1;

# UML class box
swimlane;fontStyle=1;align=center;startSize=40;fillColor=#dae8fc;strokeColor=#6c8ebf;

# Interface / stereotype box
swimlane;fontStyle=3;align=center;startSize=40;fillColor=#f5f5f5;strokeColor=#666666;

# ER table container
shape=table;startSize=30;container=1;collapsible=1;childLayout=tableLayout;

# Orthogonal connector
edgeStyle=orthogonalEdgeStyle;html=1;

# ER relationship (crow's foot)
edgeStyle=entityRelationEdgeStyle;html=1;endArrow=ERmany;startArrow=ERone;

スタイルキーの完全なカタログについては references/style-reference.md を、すべての図形ライブラリ名については references/shape-libraries.md を参照してください。

ステップ 6 — 保存して検証する

1. ファイルを書き込む：要求されたパスに .drawio 拡張子で保存します
2. バリデーターを実行する（任意ですが推奨）：

   python .github/skills/draw-io-diagram-generator/scripts/validate-drawio.py <path-to-file.drawio>
   

3. ファイルの開き方をユーザーに伝える：

   「VS Code で <filename> を開くと、draw.io 拡張機能によって自動的にレンダリングされます。必要に応じて、draw.io のウェブアプリまたはデスクトップアプリも使用できます。」

4. 図の簡単な説明を添える：ユーザーが図の内容を把握できるようにします。

---

4. 図の種類別レシピ

フローチャート

主な要素：開始（楕円） => プロセス（角丸長方形） => 判断（ひし形） => 終了（楕円）

<mxCell id="start" value="Start"
        style="ellipse;whiteSpace=wrap;html=1;fillColor=#d5e8d4;strokeColor=#82b366;"
        vertex="1" parent="1">
  <mxGeometry x="500" y="80" width="120" height="60" as="geometry" />
</mxCell>


<mxCell id="p1" value="Process Step"
        style="rounded=1;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;"
        vertex="1" parent="1">
  <mxGeometry x="500" y="200" width="120" height="60" as="geometry" />
</mxCell>


<mxCell id="d1" value="Condition?"
        style="rhombus;whiteSpace=wrap;html=1;fillColor=#fff2cc;strokeColor=#d6b656;"
        vertex="1" parent="1">
  <mxGeometry x="460" y="320" width="200" height="100" as="geometry" />
</mxCell>


<mxCell id="e1" value=""
        style="edgeStyle=orthogonalEdgeStyle;html=1;"
        edge="1" source="start" target="p1" parent="1">
  <mxGeometry relative="1" as="geometry" />
</mxCell>

アーキテクチャ図（3 層）

各層にはスイムレーンコンテナを使用します。すべてのサービスボックスは、それぞれのスイムレーンの子要素です。

<mxCell id="tier1" value="Client Layer"
        style="swimlane;startSize=30;fillColor=#dae8fc;strokeColor=#6c8ebf;fontStyle=1;"
        vertex="1" parent="1">
  <mxGeometry x="60" y="100" width="1050" height="130" as="geometry" />
</mxCell>


<mxCell id="webapp" value="Web App"
        style="rounded=1;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;"
        vertex="1" parent="tier1">
  <mxGeometry x="80" y="40" width="120" height="60" as="geometry" />
</mxCell>

層間のコネクタでは、parent="1" を指定して絶対座標を使用します。

シーケンス図

主な要素：アクター（上部）、ライフライン（破線の垂直線）、アクティベーションボックス、メッセージ矢印。

• ライフライン：edge="1" と endArrow=none、dashed=1 を指定し、source/target は指定しません。ジオメトリ内で sourcePoint／targetPoint を使用します
• 同期メッセージ：endArrow=block;endFill=1
• 戻りメッセージ：endArrow=open;endFill=0;dashed=1
• 自己呼び出し：右方向へ進んで戻るように、2 つの Array ポイントを経由してエッジをループさせます

最小限の XML スニペット：

<mxCell id="actorA" value="Client"
        style="shape=mxgraph.uml.actor;pointerEvents=1;dashed=0;whiteSpace=wrap;html=1;aspect=fixed;"
        vertex="1" parent="1">
  <mxGeometry x="110" y="80" width="60" height="80" as="geometry" />
</mxCell>


<mxCell id="actorB" value="API Server"
        style="rounded=1;whiteSpace=wrap;html=1;fillColor=#fff2cc;strokeColor=#d6b656;"
        vertex="1" parent="1">
  <mxGeometry x="480" y="100" width="160" height="60" as="geometry" />
</mxCell>


<mxCell id="lifA" value=""
        style="edgeStyle=none;dashed=1;endArrow=none;"
        edge="1" parent="1">
  <mxGeometry relative="1" as="geometry">
    <mxPoint x="140" y="160" as="sourcePoint" />
    <mxPoint x="140" y="700" as="targetPoint" />
  </mxGeometry>
</mxCell>


<mxCell id="actA1" value=""
        style="fillColor=#dae8fc;strokeColor=#6c8ebf;"
        vertex="1" parent="1">
  <mxGeometry x="130" y="220" width="20" height="180" as="geometry" />
</mxCell>


<mxCell id="msg1" value="POST /orders"
        style="edgeStyle=elbowEdgeStyle;elbow=vertical;html=1;endArrow=block;endFill=1;"
        edge="1" source="actA1" target="actorB" parent="1">
  <mxGeometry relative="1" as="geometry" />
</mxCell>


<mxCell id="msg2" value="201 Created"
        style="edgeStyle=elbowEdgeStyle;elbow=vertical;dashed=1;html=1;endArrow=open;endFill=0;"
        edge="1" source="actorB" target="actA1" parent="1">
  <mxGeometry relative="1" as="geometry" />
</mxCell>

注： ライフラインは浮動エッジであり、source／target 属性の代わりに <mxGeometry> 内の sourcePoint／targetPoint を使用します。これはシーケンス図で標準的な draw.io のパターンです。

ER 図

childLayout=tableLayout を指定した shape=table コンテナを使用します。行は portConstraint=eastwest を指定した shape=tableRow セルです。各行内の列は shape=partialRectangle を使用します。

リレーションシップの矢印には edgeStyle=entityRelationEdgeStyle を使用します：

• 1 対 1：startArrow=ERone;endArrow=ERone
• 1 対多：startArrow=ERone;endArrow=ERmany
• 多対多：startArrow=ERmany;endArrow=ERmany
• 必須：ERmandOne、任意：ERzeroToOne

UML クラス図

クラスのボックスはスイムレーンコンテナーです。属性とメソッドはプレーンテキストのセルです。区切り線は高さ 0 のスイムレーンの子要素です。

関係の種類ごとの矢印スタイル：

関係	スタイル文字列
継承（extends）	edgeStyle=orthogonalEdgeStyle;html=1;endArrow=block;endFill=0;
実現（implements）	edgeStyle=orthogonalEdgeStyle;dashed=1;html=1;endArrow=block;endFill=0;
コンポジション	edgeStyle=orthogonalEdgeStyle;html=1;startArrow=diamond;startFill=1;endArrow=none;
集約	edgeStyle=orthogonalEdgeStyle;html=1;startArrow=diamond;startFill=0;endArrow=none;
依存	edgeStyle=orthogonalEdgeStyle;dashed=1;html=1;endArrow=open;endFill=0;
関連	edgeStyle=orthogonalEdgeStyle;html=1;endArrow=open;endFill=0;

---

5. 複数ページの図

複雑なシステムでは、複数の <diagram> 要素を追加します。

<mxfile host="Electron" version="26.0.0">
  <diagram id="overview" name="Overview">
    
  </diagram>
  <diagram id="detail" name="Detail View">
    
  </diagram>
</mxfile>

各ページには、それぞれ独立したセル ID 名前空間があります。異なるページ間では、同じ ID 値を競合せずに使用できます。

---

6. 既存の図の編集

既存の .drawio ファイルを変更する場合：

1. 既存のセル ID、位置、親階層を把握するため、まずファイルを読み込みます
2. 対象の図のページを特定します — インデックスまたは name 属性で指定します
3. 既存の ID と重複しない、新しい一意の ID を割り当てます
4. コンテナー階層を維持します — スイムレーンの子要素は、親を基準とした座標を使用します
5. エッジを確認します — ノードの位置を変更した後、エッジのソース／ターゲット ID が有効なままであることを確認します

生の XML を編集せずに安全に単一の図形を追加するには、scripts/add-shape.py を使用します：

python .github/skills/draw-io-diagram-generator/scripts/add-shape.py docs/arch.drawio "New Service" 700 380

---

7. ベストプラクティス

レイアウト

• 図形を 10px グリッドに揃えます（すべての座標が 10 で割り切れるようにします）
• 関連する図形をスイムレーンコンテナー内にグループ化します
• 1 ページにつき 1 つの図のトピックを配置します。複雑なシステムには複数ページのファイルを使用します
• 読みやすさを保つため、1 ページあたりのセル数は 40 個以下を目安にします

ラベル

• 各ページの上部にタイトルテキストセル（text;strokeColor=none;fillColor=none;fontSize=18;fontStyle=1）を追加します
• 頂点図形には必ず whiteSpace=wrap;html=1 を設定します
• ラベルは簡潔にします — 可能な限り、図形あたり 3 語以下にします

スタイルの一貫性

• プロジェクト全体で、セクション 3 のステップ 5 にある意味的なカラーパレットを一貫して使用します
• 直角のコネクターをすっきりと描画するには、edgeStyle=orthogonalEdgeStyle を優先します
• 必要な場合を除き、ラベルに任意の HTML を直接記述しないでください

ファイル名

• ケバブケースを使用します：order-service-flow.drawio、database-schema.drawio
• 図は、説明対象のコードと同じ場所（docs/ または architecture/）に配置します

---

8. トラブルシューティング

問題	考えられる原因	解決方法
VS Code でファイルを開くと空白になる	id=0 または id=1 のセルがない	ほかのセルより前に、両方のルートセルを追加します
図形の位置が間違っている	コンテナー内の子要素 — 座標は相対値です	parent を確認し、コンテナーを基準とした x/y を調整します
エッジが表示されない	source または target の ID がどの頂点とも一致しない	両方の ID が記述どおりに存在することを確認します
図に「Compressed」と表示される	mxGraphModel が base64 エンコードされている	draw.io のウェブ版で開き、File > Export > XML（uncompressed）を選択します
図形のスタイルが描画されない	shape= 名の誤記	正確なスタイル文字列を references/shape-libraries.md で確認します
ラベルにエスケープされた HTML が表示される	HTML ラベルがあるセルで html=0 になっている	セルのスタイルに html=1; を追加します
コンテナー内の子要素がコンテナーの端と重なる	コンテナーの高さが不足している	mxGeometry でコンテナーの高さを増やします

---

9. 検証チェックリスト

生成した .drawio ファイルを納品する前に、次の項目を確認してください。

• ファイルが <mxfile> ルート要素で始まっている
• すべての <diagram> に空でない id 属性がある
• すべての図で、最初のセルが <mxCell id="0" /> である
• すべての図で、2 番目のセルが <mxCell id="1" parent="0" /> である
• 各図内で、すべてのセルの id 値が一意である
• すべての頂点セルに vertex="1" と子要素 <mxGeometry as="geometry"> がある
• すべてのエッジセルに edge="1" があり、次のいずれかを満たす。（a）source／target が既存の頂点 ID を指している、または（b）<mxGeometry> 内に <mxPoint as="sourcePoint"> と <mxPoint as="targetPoint"> がある（フローティングエッジ。シーケンス図のライフラインで使用）
• 各セル（id=0 を除く）に、既存の ID を指す parent がある
• HTML タグを含むラベルのスタイルに html=1 がある
• XML が整形式である（閉じられていないタグがなく、属性値内の &、<、> が適切にエスケープされている）
• 各ページの上部にタイトルラベルセルがある

自動バリデーターを実行します。

python .github/skills/draw-io-diagram-generator/scripts/validate-drawio.py <file.drawio>

---

10. 出力形式

図を納品するときは、必ず次の内容を提示してください。

1. .drawio ファイルを指定されたパスに書き込む
2. 図が示す内容を一文で要約する
3. 開き方：

   「VS Code で <filename> を開くと、draw.io 拡張機能で自動的に描画されます。または、必要に応じて draw.io のウェブアプリやデスクトップアプリで開くこともできます。」

4. 編集方法（ユーザーがカスタマイズする可能性が高い場合）：

   「図形をクリックして選択します。ダブルクリックするとラベルを編集できます。ドラッグすると位置を変更できます。」

5. 検証ステータス — バリデータースクリプトを実行して合格したかどうか

---

11. 参考資料

関連ファイルはすべて .github/skills/draw-io-diagram-generator/ にあります。

ファイル	内容
references/drawio-xml-schema.md	mxfile／mxGraphModel／mxCell の属性リファレンス全般、座標系、予約済みセル、検証ルール
references/style-reference.md	すべてのスタイルキーと許可される値、頂点とエッジのスタイルキー、図形カタログ、セマンティックカラーのパレット
references/shape-libraries.md	すべての図形ライブラリのカテゴリ（General、Flowchart、UML、ER、Network、BPMN、Mockup、K8s）とスタイル文字列
assets/templates/flowchart.drawio	すぐに使えるフローチャートテンプレート
assets/templates/architecture.drawio	4 層システムアーキテクチャテンプレート
assets/templates/sequence.drawio	3 アクターのシーケンス図テンプレート
assets/templates/er-diagram.drawio	カラスの足記法による関係を含む 3 テーブルの ER 図
assets/templates/uml-class.drawio	関係を示す矢印を含むインターフェース、2 つのクラス、列挙型
scripts/validate-drawio.py	任意の .drawio ファイルの XML 構造を検証する Python スクリプト
scripts/add-shape.py	既存の図に新しい図形を追加する Python CLI
scripts/README.md	使用例を含むスクリプトの使い方