Draw.io ダイアグラム

概要

ネイティブ draw.io デスクトップアプリ CLI を使用して .drawio XML ファイルを生成し、PNG/SVG/PDF/JPG にローカルでエクスポートします。

サポート形式: PNG、SVG、PDF、JPG — ブラウザ自動化は不要です。

PNG、SVG、PDF エクスポートは --embed-diagram (-e) をサポートしています — エクスポートされたファイルには完全なダイアグラム XML が含まれるため、draw.io で開くと編集可能なダイアグラムを復元できます。埋め込まれた XML を通知するには二重拡張子 (name.drawio.png) を使用します。

バンドルされたリソース

ワークフローが以下のいずれかを参照する場合、必要に応じて読み込みます — 事前にコンテキストに含める必要はありません。

ファイル	読み込むタイミング
references/diagram-types.md	ユーザーが特定のダイアグラムタイプ (ERD、UML クラス、シーケンス、アーキテクチャ、ML/DL、フローチャート) を名前で指定した場合
references/style-presets.md	ユーザーがスタイルプリセットを学習/保存/一覧表示/デフォルト設定/削除するよう要求した場合、または有効なプリセットを解決して適用ルールが必要な場合
references/style-extraction.md	学習フロー内にいて抽出手順が必要な場合 (style-presets.md から呼び出し)
references/troubleshooting.md	エクスポート失敗、ビジョン API による PNG 拒否、レンダリング表示エラーが発生した場合
scripts/repair_png.py	すべての -e PNG エクスポート後 — draw.io の切り詰められた IEND チャンクを修正します (issue #8)
scripts/encode_drawio_url.py	CLI が利用できない場合で、ブラウザフォールバック diagrams.net URL が必要な場合

前提条件

draw.io デスクトップアプリがインストールされ、CLI にアクセスできる必要があります。

# macOS (Homebrew — 推奨)
brew install --cask drawio
draw.io --version

# macOS (PATH に無い場合は完全パス)
/Applications/draw.io.app/Contents/MacOS/draw.io --version

# Windows
"C:\Program Files\draw.io\draw.io.exe" --version

# Linux
draw.io --version

draw.io デスクトップがない場合はインストールします:

• macOS: brew install --cask drawio または https://github.com/jgraph/drawio-desktop/releases からダウンロード
• Windows: https://github.com/jgraph/drawio-desktop/releases からインストーラーをダウンロード
• Linux: https://github.com/jgraph/drawio-desktop/releases から .deb/.rpm をダウンロード — snap を使用しないでください (AppArmor サンドボックスがサーバー上のシークレット/キーリングをブロックし、クラッシュの原因となります)

ワークフロー

ワークフローを開始する前に、ユーザーのリクエストが十分に具体的であるかを評価します。重要な詳細が不足している場合は、1～3 つの焦点を絞った質問をします:

• ダイアグラムタイプ — どのプリセット? (ERD、UML、シーケンス、アーキテクチャ、ML/DL、フローチャート、または汎用)
• 出力形式 — PNG (デフォルト)、SVG、PDF、または JPG?
• 出力場所 — デフォルトはユーザーの作業ディレクトリです。ユーザーが指定した明示的なパス (例: ./artifacts/) を尊重します。ユーザーが言及しなかった場合は尋ねません。
• スコープ/忠実度 — コンポーネント数はいくつ? 特定のテクノロジーやラベルはありますか?

リクエストがすでにこれらの詳細を指定している場合、または明らかに単純な場合 (例: 「X のフローチャートを描く」) は、明確化をスキップします。

ステップ 0 — 有効なプリセットを解決します。 このジェネレーションに適用される (存在する場合) ユーザー定義スタイルプリセットを決定します。

• ユーザーのメッセージをスキャンして、スタイルプリセット名を明確に名前付けるフレーズを探します: 「my <name> style を使用」、「my <name> style で」、「<name> モードで」、「<name> のスタイルで」。単純な with <name> は カウントされません — 「redis を使用してダイアグラムを描く」はコンポーネント名であり、スタイルではありません。明確に一致するものが見つかった場合 → 有効なプリセット = <name>。
• そうでない場合は、~/.drawio-skill/styles/ をチェックして "default": true を持つファイルを探します。見つかった場合 → 有効なプリセット = そのファイル。
• そうでない場合 → プリセットがアクティブではありません。ワークフローの残りの組み込みカラー/シェイプ/エッジ規約にフォールスルーします。

プリセット JSON を ~/.drawio-skill/styles/<name>.json から読み込み、<this-skill-dir>/styles/built-in/<name>.json にフォールバックします。名前付きプリセットが両方の場所に存在しない場合、ユーザーに名前が不明であることを伝え、利用可能なプリセット (ユーザーディレクトリ + 組み込み) をリストしてから停止します — デフォルトへのフォールバックは しません。

プリセットが正常に読み込まれた場合、返信の最初の行に記載します: 「プリセット <name> を使用しています (信頼度: <level>)。」 プリセットがカラー/シェイプ/エッジ/フォント決定をどのように変更するかについては、以下の プリセットの適用 サブセクションを参照してください。

1. 依存関係を確認 — draw.io --version が成功することを確認します。正しい CLI パスのプラットフォームに注意します。
2. 計画 — シェイプ、リレーションシップ、レイアウト (LR または TB)、ティア/レイヤー別のグループを特定します。
3. 生成 — .drawio XML ファイルをディスクに書き込みます。デフォルト出力ディレクトリはユーザーの作業ディレクトリです。ユーザーが出力パスまたはディレクトリ (例: ./artifacts/、docs/images/) を指定した場合、代わりにそれを使用します — ターゲットディレクトリを最初に mkdir -p します。同じディレクトリ選択をステップ 4 および 7 の PNG/SVG/PDF エクスポートに適用します。
4. ドラフト エクスポート — CLI を実行してプレビュー PNG を作成します。このステップで -e を 渡さないでください — 埋め込みされた zTXt mxGraphModel チャンクが原因で、ビジョン API (Claude を含む) はステップ 5 で 400 「Could not process image」エラーを返します。クリーンなプレビューを <name>.png (単一拡張子) として保存します。埋め込みは最終エクスポートのみです (ステップ 7)。
5. 自己確認 — エージェントの組み込みビジョン機能を使用してエクスポートされた PNG を読み込み、明らかな問題をキャッチし、ユーザーに表示する前に自動修正します (Claude Sonnet/Opus などのビジョン対応モデルが必要)。PNG の読み込みが 400 / 「Could not process image」エラーを返す場合、ほぼ間違いなく -e 付きでエクスポートされました — -e なしで再エクスポートして 1 回再試行します。それでも失敗した場合、自己確認をスキップしてステップ 6 に進みます。
6. レビュー ループ — ユーザーに画像を表示し、フィードバックを集め、ターゲット XML 編集を適用し、再エクスポート、承認まで繰り返します。
7. 最終エクスポート — 承認されたバージョンをすべてのリクエストされた形式に再エクスポートします。ここで -e を使用します (PNG/SVG/PDF) ので、納品物は draw.io で編集可能なままです。埋め込まれた XML を通知するために <name>.drawio.png として保存します。PNG に -e を使用する場合、直後に python3 <this-skill-dir>/scripts/repair_png.py <name>.drawio.png を実行します — draw.io CLI は -e PNG 出力で IEND チャンクを切り詰めます (8 バイト不足)。これにより、ビジョン API と厳密な PNG デコーダーが拒否する破損ファイルが生成されます (issue #8)。ファイルパスを報告します。

ステップ 5: 自己確認

ドラフト PNG をエクスポートした後、エージェントのビジョン機能 (例: Claude の画像入力) を使用して画像を読み込み、ユーザーに表示する前に以下の問題をチェックします。エージェントがビジョンをサポートしない場合、自己確認をスキップして PNG を直接表示します。

重要: ここで読み込まれるドラフト PNG は -e なし でエクスポートされている必要があります。Draw.io の -e フラグは IEND チャンク (タイプ + CRC の 8 バイト不足) が切り詰められた PNG を出力し、Anthropic ビジョン API は 400 「Could not process image」で拒否します (issue #8)。プレビュー ステップの最も単純な修正は -e を完全にスキップすることです。ステップ 7 の最終エクスポートは -e を保持し、修復スニペットを実行します。ここで 400 エラーが表示された場合、-e なしで再エクスポートして 1 回再試行します。それでも失敗した場合 (その他の理由)、自己確認をスキップしてステップ 6 に進みます。

チェック	確認内容	自動修正アクション
重なるシェイプ	2 つ以上のシェイプが積み重ねられている	シェイプを ≥200px 離す
クリップされたラベル	テキストがシェイプの境界でカットオフされている	シェイプの幅/高さを増やしてラベルをフィットさせる
接続の欠落	矢印がシェイプに視覚的に接続していない	source/target id が既存のセルと一致することを確認
キャンバス外のシェイプ	負の座標または主要グループから遠い位置にあるシェイプ	正の座標近くのクラスターに移動
エッジとシェイプの重複	エッジ/矢印が無関係なシェイプを視覚的に横切っている	ウェイポイント (<Array as="points">) を追加してシェイプの周りをルーティング、またはシェイプ間の間隔を増やす
積み重ねられたエッジ	複数のエッジが同じパスで互いに重なっている	シェイプの周囲に出入口を分散 (異なる exitX/entryX 値を使用)

• 最大 2 回の自己確認ラウンド — 2 つの修正後に問題が残っている場合、ユーザーに表示します。
• 各修正後に再エクスポートして新しい PNG を再読み込みします。

ステップ 6: レビュー ループ

自己確認後、エクスポートされた画像を表示し、ユーザーにフィードバックを求めます。

ターゲット編集ルール — フィードバックのタイプごとに、最小限の XML 変更を適用します:

ユーザーのリクエスト	XML 編集アクション
X の色を変更	value が X と一致する mxCell を見つけ、style の fillColor/strokeColor を更新
新しいノードを追加	次の利用可能な id を持つ新しい mxCell 頂点を追加し、関連するノード近くに配置
ノードを削除	mxCell 頂点と一致する source/target を持つすべてのエッジを削除
シェイプ X を移動	一致する mxCell の mxGeometry の x/y を更新
シェイプ X をサイズ変更	一致する mxCell の mxGeometry の width/height を更新
A から B への矢印を追加	A と B の id と一致する source/target を持つ新しい mxCell エッジを追加
ラベルテキストを変更	一致する mxCell の value 属性を更新
レイアウト方向を変更	完全な再生成 — 新しい向きで XML を再構築

ルール:

• 単一要素の変更の場合: 既存の XML をインプレースで編集 — 以前のイテレーションのレイアウト調整を保持します。
• レイアウト全体の変更 (例: LR↔TB の交換、「最初からやり直す」): 完全な XML を再生成します。
• 各イテレーション で同じ {name}.png を上書き ( -e なし) — v1、v2、v3 ファイルを作成しません。-e はステップ 7 の最終エクスポート用に予約されています。
• 編集を適用した後、再エクスポートして更新された画像を表示します。
• ループはユーザーが承認/完了/LGTM と言うまで続きます。
• 安全弁: 5 イテレーション ラウンド後、ユーザーに .drawio ファイルを draw.io デスクトップで開いて細かい調整を行うことを提案します。

ステップ 7: 最終エクスポート

ユーザーが承認したら:

• すべてのリクエストされた形式 (PNG、SVG、PDF、JPG) にエクスポート — 指定されていない場合は PNG をデフォルトにします。
• .drawio ソースファイルとエクスポートされた画像の両方のファイルパスを報告します。
• 自動起動: .drawio ファイルを draw.io デスクトップで開いて微調整する機会を提供 — open diagram.drawio (macOS)、xdg-open (Linux)、start (Windows)
• ファイルが保存され、使用可能であることを確認します。

スタイル プリセット

スタイル プリセット は、ユーザーのビジュアル設定 (パレット、シェイプ、フォント、エッジ) をキャプチャした名前付き JSON ファイルです。アクティブな場合、スキル内の組み込みカラー/シェイプ規約を完全に置き換えます。

SKILL.md のステップ 0.5 がプリセット名を解決する場合の参照順:

1. ~/.drawio-skill/styles/<name>.json — ユーザープリセット (git pull で保存)
2. <this-skill-dir>/styles/built-in/<name>.json — 同梱の組み込み (default、corporate、handdrawn)

ファイル操作の前に、ユーザーが提供する名前を常に小文字にします — スキーマが小文字を強制します。

その他すべての場合 — 学習フロー (ファイルからプリセットを抽出)、管理操作 (一覧表示/デフォルト設定/削除/名前変更)、アプリケーション ルール (カラー参照、シェイプ キーワード、エッジ、フォント、その他、ダイアグラムタイプ プリセットとの相互作用)、および検証 — references/style-presets.md を読みます。 これは、ユーザーがこれらのフローを呼び出すか、現在のジェネレーションにアクティブなプリセットを適用する必要がある場合にのみ必要です。

Draw.io XML 構造

ファイル スケルトン

<?xml version="1.0" encoding="UTF-8"?>
<mxfile host="drawio" version="26.0.0">
  <diagram name="Page-1">
    <mxGraphModel>
      <root>
        <mxCell id="0" />
        <mxCell id="1" parent="0" />
        <!-- user shapes start at id="2" -->
      </root>
    </mxGraphModel>
  </diagram>
</mxfile>

ルール:

• id="0" と id="1" は必須のルートセル — 決して省略しません。
• ユーザーのシェイプは id="2" から始まり、順番に増加します。
• すべてのシェイプは parent="1" を持ちます (コンテナ内の場合を除き、コンテナの id を使用)。
• すべてのテキストは適切なレンダリングのため、スタイルで html=1 を使用します。
• XML コメント内で -- を使用しません — XML 仕様では違法であり、解析エラーが発生します。
• 属性値の特殊文字をエスケープ: &、<、>、"
• ラベルの複数行テキスト: value 属性内で改行に 
 を使用 (リテラル \n ではなく)。例: value="Line 1
Line 2"

シェイプ タイプ (頂点)

スタイル キーワード	使用用途
rounded=0	プレーン矩形 (デフォルト)
rounded=1	角が丸い矩形 — サービス、モジュール
ellipse;	円/楕円 — 開始/終了、データベース
rhombus;	ダイアモンド — デシジョン ポイント
shape=mxgraph.aws4.resourceIcon;	AWS アイコン
shape=cylinder3;	シリンダー — データベース
swimlane;	グループ/コンテナ (タイトル バー付き)

必須プロパティ

<!-- 矩形 / 角が丸い四角形 -->
<mxCell id="2" value="Label" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;" vertex="1" parent="1">
  <mxGeometry x="100" y="100" width="160" height="60" as="geometry" />
</mxCell>

<!-- シリンダー (データベース) -->
<mxCell id="3" value="DB" style="shape=cylinder3;whiteSpace=wrap;html=1;fillColor=#f5f5f5;strokeColor=#666666;fontColor=#333333;" vertex="1" parent="1">
  <mxGeometry x="350" y="100" width="120" height="80" as="geometry" />
</mxCell>

<!-- ダイアモンド (デシジョン) -->
<mxCell id="4" value="Check?" style="rhombus;whiteSpace=wrap;html=1;fillColor=#fff2cc;strokeColor=#d6b656;" vertex="1" parent="1">
  <mxGeometry x="100" y="220" width="160" height="80" as="geometry" />
</mxCell>

コンテナとグループ

ネストされた要素を持つアーキテクチャ ダイアグラムの場合、draw.io の親子含有を使用します — より大きなシェイプの上にシェイプを配置するだけではありません。

タイプ	スタイル	使用タイミング
グループ (非表示)	group;pointerEvents=0;	ビジュアル枠線が不要で、コンテナに接続がない
スイムレーン (タイトル付き)	swimlane;startSize=30;	コンテナに表示されるタイトル バーが必要であるか、コンテナ自体に接続がある
カスタム コンテナ	任意のシェイプに container=1;pointerEvents=0; を追加	独自の接続を持たないコンテナとして機能する任意のシェイプ

重要なルール:

• コンテナ スタイルに pointerEvents=0; を追加して、子間の接続をキャプチャしないようにします。
• 子は parent="containerId" を設定し、コンテナを基準とした 座標を使用します。

<!-- スイムレーン コンテナ -->
<mxCell id="svc1" value="User Service" style="swimlane;startSize=30;fillColor=#dae8fc;strokeColor=#6c8ebf;" vertex="1" parent="1">
  <mxGeometry x="100" y="100" width="300" height="200" as="geometry"/>
</mxCell>
<!-- コンテナ内の子 — 親を基準とした座標 -->
<mxCell id="api1" value="REST API" style="rounded=1;whiteSpace=wrap;html=1;" vertex="1" parent="svc1">
  <mxGeometry x="20" y="40" width="120" height="60" as="geometry"/>
</mxCell>
<mxCell id="db1" value="Database" style="shape=cylinder3;whiteSpace=wrap;html=1;" vertex="1" parent="svc1">
  <mxGeometry x="160" y="40" width="120" height="60" as="geometry"/>
</mxCell>

コネクタ (エッジ)

重要: すべてのエッジ mxCell には <mxGeometry relative="1" as="geometry" /> 子要素が含まれている必要があります。自己終了エッジセル (<mxCell ... edge="1" ... />) は 無効 であり、レンダリングされません。常に展開形式を使用します。

<!-- 有向矢印 — 常に rounded、orthogonalLoop、jettySize を含めてクリーンなルーティングを実現 -->
<mxCell id="10" value="" style="edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;html=1;" edge="1" parent="1" source="2" target="3">
  <mxGeometry relative="1" as="geometry" />
</mxCell>

<!-- ラベル付き矢印 + 方向を制御する明示的な出入口ポイント -->
<mxCell id="11" value="HTTP/REST" style="edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0.5;entryY=0;entryDx=0;entryDy=0;" edge="1" parent="1" source="2" target="4">
  <mxGeometry relative="1" as="geometry" />
</mxCell>

<!-- ウェイポイント付き矢印 — エッジが他のシェイプの周りをルーティングする必要がある場合に使用 -->
<mxCell id="12" value="" style="edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;html=1;" edge="1" parent="1" source="3" target="5">
  <mxGeometry relative="1" as="geometry">
    <Array as="points">
      <mxPoint x="500" y="50" />
    </Array>
  </mxGeometry>
</mxCell>

エッジ スタイル ルール:

• アニメーション付きコネクタ: 任意のエッジ スタイルに flowAnimation=1; を追加して、矢印に沿う移動ドット アニメーションを表示します。SVG エクスポートと draw.io デスクトップで機能します — データフロー図とパイプライン ダイアグラムに最適です。例: style="edgeStyle=orthogonalEdgeStyle;flowAnimation=1;rounded=1;..."
• 常に rounded=1;orthogonalLoop=1;jettySize=auto を含める — これらはスマート ルーティングを有効にして重複を回避します。
• ノードに 2 つ以上の接続がある場合、すべてのエッジで exitX/exitY/entryX/entryY をピン留め — シェイプの周囲に線を分散します。
• エッジが中間シェイプの周りを迂回する必要がある場合、<Array as="points"> ウェイポイントを追加します。
• 矢印の先端用の余白を残す: 最後の曲がり角とターゲット シェイプの間の最後の直線セグメントは ≥20px である必要があります。短すぎると、矢印の先端が曲がり角と重なり、壊れているように見えます。ノードの間隔を増やすか、明示的なウェイポイントを追加して修正します。

シェイプに接続を配分

複数のエッジが同じシェイプに接続する場合、別々の出入口ポイントを割り当てて積み重なりを防ぎます:

| 位置 | exitX/entryX | exitY/entry