drawio-generator

Draw.io 図生成ツール

有効な draw.io XML として、プロフェッショナルな図を生成します。すべてのリクエストは、ファイルを書き込む前に、理解、提案、生成、検証の4つのフェーズを経ます。本文はエージェントのコンテキスト予算を守るため、意図的に簡潔にしています。詳細は references/ を参照してください。

diagram-generator スイートの一部です。手描き風／スケッチ風にしたい場合は、代わりに excalidraw-generator を使用してください。diagram-generator の傘下ツールが、両者を使い分けます。

環境の確認

Agent ツールが利用できる場合、大規模な図には Subagent Architecture に従ってサブエージェントを使用してください。新しいコンテキストで検証することで、1回の処理でコンテキストがあふれるのを防げます。利用できない場合（例：Claude.ai）は、すべてのフェーズをインラインで実行し、9つのチェック項目に照らして自己レビューしてください。

編集前のリポジトリ同期（必須）

既存の .drawio ファイルを読み込む前（反復作業）、それ以外の場合はフェーズ4で書き込む前に、1回実行します。同期先は出力ファイルのディレクトリです。

1. repo="$(git -C "<output dir>" rev-parse --show-toplevel)" を実行します。失敗した場合は同期をスキップし、sync: skipped (not a git repo) と記録します。
2. git -C "$repo" remote get-url origin を実行します。失敗した場合はステップ3～6をスキップし、sync: skipped (no origin) と記録します。
3. branch="$(git -C "$repo" rev-parse --abbrev-ref HEAD)" を実行します。出力が HEAD の場合はステップ4～6をスキップし、sync: skipped (detached HEAD) と記録します。
4. git -C "$repo" status --porcelain を実行します。出力が空の場合は、git -C "$repo" fetch origin && git -C "$repo" pull --rebase origin "$branch" を実行します。
5. 出力が空でない場合は、git -C "$repo" stash push -u -m "drawio-generator pre-sync" を実行してから、同じ fetch と pull を実行し、その後 git -C "$repo" stash pop を実行します。
6. rebase で競合が発生した場合は、git -C "$repo" rebase --abort を実行し、ステップ5で stash していた場合は git -C "$repo" stash pop を実行します。stash pop で競合が発生した場合は、stash をそのまま残します。いずれの場合もファイルを書き込まず、続行方法をユーザーに確認してください。回答がない場合、ステータスは BLOCKED です。

このスキルはファイルを1つ書き込みますが、コミットは行いません。

基本ワークフロー

フェーズ1：理解

生成を始める前に、何を描くかを確認します。

• 明確なリクエスト — 内容を簡潔に言い換え、可視化の種類を提案します。

  「レイヤー構成の C4 コンテナ図を作成します。上部に API ゲートウェイ、中段にサービス、下部にデータベースを配置します。よろしいですか？」

• 曖昧な入力 — 主要なエンティティ、関係、フローの方向、複数ページの要否について、的を絞った質問をします。
• コード、スキーマ、設定が提示された場合 — 構造を抽出します。
  • コード → クラス／依存関係／アーキテクチャ
  • SQL／スキーマ → ER 図
  • JSON／YAML 設定 → アーキテクチャ、デプロイ
  • 手順／プロセス → フローチャート、シーケンス図

フェーズ2：提案

以下の番号付きプランを提示します。

• リクエストで図の種類とすべての要素が指定されている場合は、選択したデフォルトを1行で示し、フェーズ3に進みます。
• それ以外の場合は、ユーザーがプランを承認または変更するまで待ちます。ユーザーの回答前に XML を生成してはいけません。

1. 図の種類（複数の種類が適している場合は代替案を提示）
2. 主要な要素 — ノード／図形を列挙
3. レイアウト — 例：(A) 上から下、(B) 左から右、(C) レイヤー構成
4. スタイル — (1) プロフェッショナル、(2) C4 公式、(3) モノクロ
5. 複数ページ？ — C4 の場合は、レベルごとに1ページを提案
6. 複雑さの見積もり — 小規模（10未満）、中規模（10～30）、大規模（30以上）

フェーズ 3：生成

draw.io の XML をメモリ上で生成します。ファイルの書き込みはフェーズ 4 で行います。

出力パス：ユーザーが指定したパスを使用します。指定がない場合は、現在の作業ディレクトリに、説明的なケバブケース名で .drawio で終わるファイルを使用します（auth-flow.drawio）。そのファイルが存在し、ユーザーが更新を依頼していない場合は、上書きする前にユーザーに確認してください。更新する場合は、Iteration に従ってください。

図形／エッジ／コンテナーの構文、サイズ設定ルール、複数ページの構造、ファイル名については、references/xml-authoring.md を読んでください。XML スキーマ全体とカラーパレットについては、references/drawio-format.md を読んでください。

すべての図形に適用する重要なルール：

• 必ずスタイル文字列に html=1;whiteSpace=wrap; を含めてください
• 説明的なケバブケースの ID を使用してください（node-api-gateway）
• ラベルに収まるサイズの <mxGeometry x y width height as="geometry"/> を指定してください
• エッジには source、target、および <mxGeometry relative="1" as="geometry"/> が必要です

フェーズ 4：検証

ファイルを書き込む前に、9 項目すべてのチェックを実行してください。チェック項目と修正方法の全一覧は、references/validation-checks.md を参照してください。

1. 9 項目のチェックを実行します。すべて合格したら、Repo Sync を実行してファイルを書き込み、ステータス COMPLETE の Final Report を提示します。
2. チェックに失敗した場合は修正し、9 項目すべてを再実行します。チェック 1 または 8 の失敗は、パッチではなくフェーズ 3 での再生成が必要です。修正サイクルは 3 回で終了します。
3. チェック 1～5 は合格しているものの、3 回目の修正サイクル後もチェック 6～9 のいずれかに失敗する場合は、Repo Sync を実行してファイルを書き込み、失敗したチェック番号を記載した PARTIAL を報告します。
4. 3 回目の修正サイクル後もチェック 1～5 に失敗している場合は、ファイルを書き込まず、失敗したチェックを記載して BLOCKED を報告します。

9 項目のチェック：（1）XML 構造とシステムセル、（2）図形の必須属性、（3）ページごとの ID の一意性、（4）エッジのバインド、（5）エッジのジオメトリ、（6）10px を超える重なりがないこと、（7）コンテナー階層、（8）意味上の完全性、（9）テキストの可読性と図形への適合。

---

期待される出力

有効な .drawio ファイルをディスクに書き込んだ後、Final Report を提示します（生の XML）。最小限の完全なファイルは、references/xml-authoring.md → Minimal complete file にあります。

最終レポート

停止する場合も含め、すべての実行の最後に、この簡潔なテキストブロックを出力してください。ユーザーの回答を待つフェーズ 1～2 の質問では、実行は終了しません。ユーザーが回答しないまま実行を終了した場合は、BLOCKED を報告してください。ステータスは COMPLETE（ファイルが書き込まれ、9 項目すべて合格）、PARTIAL（ファイルが書き込まれ、チェック 6～9 のいずれかが不合格）、または BLOCKED（ファイル未書き込み）です。記入ルール、PARTIAL と BLOCKED の例、および読者チェックについては、references/final-report.md を参照してください。例：

Result: COMPLETE. Wrote flow.drawio (1 page, 2 shapes, 1 edge, 0 containers).
Evidence: /abs/path/flow.drawio. Validation 9/9 checks passed (inline, 1 cycle). sync: skipped (not a git repo)
Uncertainty: Rendering in draw.io untested. Assumed top-to-bottom flow; the request gave no direction.
Decision: No approval needed.

受け入れ基準

すべての実行について、以下を確認してください。

• ステータスが BLOCKED でない限り、.drawio ファイルがディスクに書き込まれ、その XML が解析できること。
• references/validation-checks.md のチェック 1～7 と 9 がすべてのページで合格すること。または、失敗したチェックが Final Report にすべて記載されていること。
• ユーザーの依頼に含まれるすべてのエンティティと関係性が出力に反映されていること（チェック 8）。
• Final Report が Result: とステータスで始まり、Evidence:、Uncertainty:、Decision: の各行を含むこと。Evidence: には実行したチェックのみを記載し、すべて合格した場合に限り 9/9 を記載すること。
• Final Report が references/final-report.md の 4 つの読者チェック（結果の見つけやすさ、事実と前提の分離、主張の追跡可能性、次の判断の明確さ）に合格すること。人間のレビュアーから回答がない場合、人間の理解は未確認です。

エッジケース

• 入力が空、または曖昧な場合（「図を作って」など）：生成する前に、的を絞った確認質問をします。プレースホルダーを生成してはいけません。
• 図が非常に大きい場合（要素が50個超）：1ページでは混み合うことを警告し、複数ページまたは階層型 C4 を提案します。
• 未対応の図の種類（例：実際の日付軸の目盛りがあるガントチャート）：制限を説明し、最も近い対応可能な代替案（例：スイムレーンタイムライン）を提案します。
• ユーザーが既存の .drawio ファイルを提供した場合：まず読み込み、既存のセル ID を保持して新しい要素を追加します。最初から再生成してはいけません。
• レイアウト制約が競合する場合：競合点を提示し、どちらを優先するか確認します。
• ページ間で ID が衝突する場合：各 <diagram> は独自の ID 名前空間を持ちます。システムセル id="0" と id="1" は、各ページにそれぞれ存在する必要があります。
• テキストが図形に収まらない場合：テキストをはみ出したままにせず、行が増えるごとに図形の高さを約20pxずつ自動的に拡張します。

---

ステップ完了レポート

各フェーズの後に、そのフェーズのチェック項目を含む短いステータスレポートを出力します。テンプレートとフェーズごとのチェック項目は references/step-reports.md にあります。Validate レポートは Final Report より前に出力します。Validate レポートは Final Report の代わりにはなりません。

スタイルと図の種類

デフォルトのスタイルは Professional です。C4 のリクエストには公式 C4 パレットを使用します。色のルールと対応する図の種類については、references/xml-authoring.md → スタイルガイドライン と 対応する図の種類 を参照してください。

反復

既存の図を反復して編集する場合は、ファイルを読み込み、XML をメモリ上で変更します。変更されていない要素 ID は保持します。ファイルを書き換える前に、結果に対してフェーズ4を実行します。BLOCKED の結果になった場合は、元のファイルを変更しません。

---

サブエージェントのアーキテクチャ

フェーズ2の複雑さの推定を使用します。大規模（要素が30個以上）の場合はこのサブエージェントループを実行し、小規模および中規模の場合はインラインで処理します。

フェーズ3 — agents/xml-generator.md

• 入力：図の種類、要素、エッジ、スタイル、複雑さ
• 出力：必要な属性をすべて含む完全な draw.io XML
• 制約：図形はテキストラベルに収まるサイズにします

フェーズ4 — レビューループ（最大3サイクル）

1. 検証 — agents/xml-validator.md を起動します。9項目すべてのチェックについて PASS／FAIL を出力します。
2. 修正 — NEEDS_FIX の場合は、レポートとともに agents/xml-fixer.md を起動します。XML にパッチを適用します。再生成してはいけません。意味または構造上の問題はスキップします（それらにはジェネレーターの修正が必要です）。
3. 再検証 — PASS になるか、サイクル数が3になるまで、サイクル数を1増やして繰り返します。フィクサーが ready_for_validation: false（チェック1または8）を返した場合は、バリデーターのレポートとともに agents/xml-generator.md を再度起動します。これは1サイクルとして数えます。
4. XML と最新のバリデーターのレポートをメインエージェントに返し、メインエージェントがフェーズ4のステップ1～4（書き込み、PARTIAL、または BLOCKED）を適用します。