drawio-skill

Draw.io アーキテクチャスタジオ

平坦化された画像ではなく、編集可能な .drawio 成果物を作成します。推奨のエントリーポイントは scripts/diagramctl.py です。共有の Diagram IR を基盤として、生成、差分同期、マルチビュー投影、セマンティッククエリ／テスト／レビュー、障害分析、アクセシブルな公開を一元化します。

ワークフローを選択する

リクエスト	手順
正確なスタイルを指定した自然言語の図	references/diagram-types.md を読み、続けて references/xml-authoring.md を読んで XML を作成します
特別なスタイル指定のない標準的なフローチャート／マインドマップ／ガントチャート／タイムラインなど	draw.io 30 以降の場合は、references/mermaid-authoring.md を読んで Mermaid をネイティブの .drawio に変換します
自動レイアウトが必要な大規模なグラフ（ノード約 15 個以上）	autolayout.py を使用します。--layout の値を渡す前に references/autolayout.md を読んでください
コード、Terraform、K8s、compose、SQL、OpenAPI、AsyncAPI、または CI のソース	diagramctl.py build を使用します。references/diagram-ir.md を読んでください
Protocol Buffers スキーマ（.proto）	protoimports.py または diagramctl.py build を使用します。references/toolbox.md を読んでください
GraphQL SDL スキーマ（.graphql/.gql）またはイントロスペクション JSON	graphqlerd.py または diagramctl.py build を使用します。references/toolbox.md を読んでください
稼働中のクラスター／スタック／クラウド（宣言された設定ではなく実際の状態）	references/live-infra.md を読み、続けて tfstate.py、dockerimports.py、または k8simports.py - を使用します
手動のレイアウトを失わずに生成済みの図を更新	diagramctl.py sync を使用します。references/diagram-ir.md を読んでください
エグゼクティブ／システム／デプロイメント／データフロー／セキュリティのビュー	diagramctl.py views を使用します。references/diagram-ir.md を読んでください
クエリ、アーキテクチャポリシー、レビュー、what-if、またはガイド付きウォークスルー	references/semantic-workflows.md を読んでください
MCP ホスト（Claude Desktop、Cursor、VS Code、Codex）からこれらのワークフローを呼び出す場合	scripts/diagramctl_mcp.py を登録します。references/mcp.md を読んでください
図の種類やセマンティックワークフロー向けのプロンプトの表現	references/cookbook.md を読んでください
GitHub Actions CI でアーキテクチャルールやビジュアル差分を適用	references/ci-gate.md を読んでください
PR レビューコメントとして表示前後の画像や差分画像を掲載	prdiff.py を使用します。references/pr-bot.md を読んでください
既存の .drawio を HTML／PPTX／Mermaid／Markdown／アニメーション／ランブックに変換	references/toolbox.md を読んでください。diagramctl.py transform から既存のツールを利用できます
地下鉄路線図として描くパイプライン、ジャーニー、またはサブシステムのマップ	tubemap.py を使用します。references/tubemap.md を読んでください
図形、クラウド／ベンダー、AI、または Databricks のアイコン	references/shapes.md または references/databricks.md を読んでください。図形名を推測しないでください
ビジュアルスタイルの学習／適用／管理	references/style-presets.md を読んでください
既存の図やテーマから再利用可能なスタイルを抽出	references/style-extraction.md を読んでください
既存の画像を編集可能な図に変換（スクリーンショット、ホワイトボードの写真、旧式の PNG）	references/derasterize.md を読んでください
エクスポート／プラットフォームの問題	references/troubleshooting.md を読んでください。アクセス／ネットワークに関する質問は references/security.md を読んでください

統合 CLI

このスキルのディレクトリから実行するか、scripts/ をこのスキルの scripts ディレクトリの絶対パスに置き換えてください。

python3 scripts/diagramctl.py doctor
python3 scripts/diagramctl.py build model.json --from ir -o architecture.drawio
python3 scripts/diagramctl.py build ./infra --from terraform --group \
  --ir-output architecture.ir.json -o architecture.drawio
python3 scripts/diagramctl.py sync architecture.drawio ./infra --from terraform \
  -o architecture.next.drawio
python3 scripts/diagramctl.py views architecture.ir.json \
  --views executive,system,deployment,dataflow,security -o views.drawio
python3 scripts/diagramctl.py test architecture.drawio --rules policy.yml
python3 scripts/diagramctl.py review architecture.drawio -o review.md
python3 scripts/diagramctl.py query architecture.drawio --from internet --to orders-db
python3 scripts/diagramctl.py whatif architecture.ir.json --fail kafka \
  --drawio kafka-failure.drawio -o impact.json
python3 scripts/diagramctl.py story architecture.ir.json -o walkthrough.html

doctor は --probe を渡さない限り GUI ツールを起動しません。コアのセマンティックコマンドはオフラインで動作し、標準ライブラリのみを使用します。

作成ワークフロー

1. 依頼から図の種類、対象者、範囲、出力形式、保存場所を推測します。選択肢が不明で、結果に大きく影響する場合にのみ確認します。特に指定がなければ、作業ディレクトリに PNG と .drawio を出力します。

2. 上の表から作成方法を選びます。データに基づく図では、Diagram IR を優先し、出典情報を保持します。大規模なグラフにはインポーターまたは autolayout.py を使用し、15 個程度を超えるノードを手動で配置しないでください。

3. 明示的に指定されたスタイルプリセット、またはユーザーのデフォルトプリセットを references/style-presets.md の説明に従って適用します。構造図の規約とビジュアルプリセットは組み合わせて使うものであり、互いに置き換えるものではありません。

4. .drawio を生成し、構造を検証します。

   python3 scripts/validate.py diagram.drawio --score
   

   セマンティックメタデータまたはアーキテクチャポリシーが対象となる場合は、diagramctl.py test も実行します。推測したセマンティックな所見を、実行時に確認された事実として提示しないでください。

5. 埋め込み XML を含めずに PNG のドラフトをエクスポートし、目視で確認します。明らかな重なり、クリッピング、未接続のエッジ、ノードを通るエッジのルーティング、エッジの重なり、読みにくいラベルを修正します。自動による視覚的修正は 2 回までにしてください。drawio バイナリが利用できない場合、または目視確認で判断できない場合は、代わりにレンダラーの DOM を確認します（ビューアーの URL に対する --dump-dom。references/troubleshooting.md を参照）。各エッジの <path> セグメントとラベルのアンカー座標を直接確認してください。視覚情報だけでは、ジオメトリの不具合を見落とす一方で、新たな不具合を幻覚することもあります。

6. ドラフトを提示し、対象を絞った編集を行います。局所的な変更では既存のジオメトリを保持します。ソースに基づく変更には sync を使い、レビュー可能な出力を作成します。削除が依頼された場合に限り --prune を使用します。

7. 承認後、依頼された最終形式を作成し、編集可能なソースとエクスポート先の両方のパスを報告します。

エクスポート時の不変条件

利用可能なバイナリ（drawio、draw.io、macOS アプリのパス、または Windows 実行ファイル）を一度解決し、その実行では同じバイナリを使用します。

# Draft for visual inspection: never use -e here
drawio -x -f png --width 2000 -o diagram.png diagram.drawio

# Final editable PNG
drawio -x -f png -e -s 2 -o diagram.drawio.png diagram.drawio
python3 scripts/repair_png.py diagram.drawio.png

# Final editable SVG/PDF
drawio -x -f svg -e --embed-svg-images -o diagram.svg diagram.drawio
drawio -x -f pdf -e -o diagram.pdf diagram.drawio

--width と -s を併用しないでください。埋め込み PNG のエクスポートには repair_png.py が必要です。視覚確認に使うドラフト PNG では -e を使用しないでください。Linux のヘッドレス環境では、Electron のフラグを即興で指定せず、references/troubleshooting.md に従ってください。macOS のサンドボックスで CLI がクラッシュした場合は、許可された昇格実行を一度試し、その後は encode_drawio_url.py を使うか、XML を提供してください。繰り返し起動しないでください。

編集と識別情報

• 安定したセマンティック ID を使用し、予約済みの ID 0 または 1 は再利用しないでください。
• すべてのエッジに <mxGeometry relative="1" as="geometry"/> が必要です。
• 局所編集では該当するセルのみを変更します。全体の向きを変える場合は、ページを再生成または再レイアウトします。
• ユーザーから別途指示がない限り、出典情報、data-model-id、セマンティックプロパティ、手動設定したジオメトリ、手動設定したスタイルを保持します。
• 調整時には、削除された要素をデフォルトでレビュー可能な薄い表示の要素として残します。
• 境界でエッジが重なっている場合は edgeports.py を実行します。それでもエッジが無関係な図形を横切る場合は、ウェイポイントを追加します。ノード位置を維持する CLI 専用のエッジ再ルーターはありません。

品質と信頼性

魅力的な図であっても、誤っていることがあります。ソースに裏付けられた関係を優先し、必要に応じて出典を示し、正確な抽出と AI による推論を区別し、アーキテクチャレビューの所見は確認を促すものとして表現してください。Story HTML は自己完結型で、キーボードで操作でき、テキストによる代替情報を含める必要があります。出力に埋め込まれるため、ノードのプロパティや出典情報に秘密情報を含めないでください。

対象を絞ったスクリプトと構成パターンについては references/toolbox.md を読み、現在の依頼に必要なタスク固有のリファレンスのみを読み込んでください。