Draw.io ダイアグラムエンジニアは何をしますか？

決定論的な中間表現（IR）を通じて図を作成します。IR を信頼できる唯一の情報源とし、.drawio をコンパイル成果物として扱います。

ワークフロー

初回使用時または環境障害後は doctor を実行してください。機能の状態、スターターの選択、バンドル内容、および安全な上書き動作については user-workflows.md を参照してください。一般的でないコマンドの構成や終了コードの解釈には cli.md を参照してください。レガシーまたはバージョン管理された Diagram IR については、compatibility.md を読み、編集前に migrate --check を実行してください。
リクエストと関連するソースマテリアルを検査します。ユーザーが指定しない場合、適切な図の種類、スコープ、方向、テーマを推論します。連携したアーキテクチャ図パックの場合は blueprint.md を読み、blueprint.schema.json に従ってモデルを作成し、blueprint を使用します。 ERD の場合は erd.md を読み、erd.schema.json に従ってモデルを作成し、erd を使用します。SQL DDL が信頼できる情報源である場合は、直接受け入れます。高可用性の場合は ha.md を読み、ha.schema.json に従ってモデルを作成し、ha を使用します。
最小限の構造化ソースを作成または適用します。ソースが存在しない場合は init architecture、init blueprint、init erd、または init ha を使用します。Diagram IR については ir-format.md を、図固有の選択肢については authoring.md を参照してください。 Python/TypeScript のツリー、OpenAPI、SQL、Compose、Terraform、Kubernetes、GitHub Actions、または GitLab CI から開始する場合は、importers.md を読み、import を使用して IR を生成します。自動コネクタが視覚的に曖昧なままである場合、または固定インターフェースが重要な場合は、明示的なポートを割り当てる前に routing.md を参照してください。組織のスタイル設定やより詳細なビジュアル QA が必要な場合は、style-system.md を読み、検証済みのテーマパックを使用します。信頼できないコンテンツをインポートする場合、またはリリースバンドルを準備する場合は、security.md を参照してください。ラベル、説明、リンク、メタデータ、またはエンティティのデフォルトに認証情報を決して配置しないでください。
1 コマンドのバンドルワークフローを推奨します：
```
python3 <skill-dir>/scripts/drawio_tool.py build source.json \
  -o build/diagram --name diagram --strict
```
これにより、正規化された IR、編集可能な .drawio、すべての SVG プレビュー、audit.json、security.json、および bundle.json が作成されます。低レベルの compile、validate、preview、security、および audit コマンドは、ユーザーが個別のアーティファクトや段階的なワークフローを必要とする場合にのみ使用してください。
draw.io Desktop が利用可能で、Desktop エクスポートが要求された場合は、desktop-export.md を読み、バンドルの .drawio からレンダリングし、その検証レポートを保持します：
```
python3 <skill-dir>/scripts/drawio_tool.py render build/diagram/diagram.drawio \
  -o diagram.png --report diagram.export.json
```
バンドルされたすべてのプレビューを視覚的に検査します。階層、テキストのクリッピング、衝突、不明瞭なエッジ、弱いコントラスト、過剰な詳細を修正します。最良の結果を提示する前に、最大 2 回リビルドします。
バンドルの編集可能な .drawio、IR ソース、監査レポート、プレビュー、および要求されたエクスポートを提供します。Desktop エクスポートがスキップされた場合、その旨を明確に記載します。

承認されたアーキテクチャと新しく生成されたモデルを比較する場合は、drift.md を読み、diff を実行し、機械可読なレポートと編集可能なドリフトビューの両方を提供します。

既存図の編集

ユーザーのアーティファクトを保持します。まず検査と検証から開始します：

python3 <skill-dir>/scripts/drawio_tool.py inspect existing.drawio
python3 <skill-dir>/scripts/drawio_tool.py validate existing.drawio

意味編集の前に、レビュー可能な Diagram IR を復元します：

python3 <skill-dir>/scripts/drawio_tool.py extract existing.drawio \
  -o existing.diagram.json --report existing.extraction.json --strict

復元されたモデルに依存する前に round-trip.md を参照してください。lossless: true は、すべての意味セルがサポートされているコンパイラメタデータを使用したことを意味します。--strict がコード 3 で終了した場合でも、有効なベストエフォートモデルが書き込まれる可能性があります。元のモデルを置き換える前に、推定されたすべてのセルをレビューしてください。

IR ベースの図の場合は、意味操作を作成し、アトミックに適用します：

python3 <skill-dir>/scripts/drawio_tool.py patch diagram.json changes.json -o diagram.updated.json

破壊的編集や複数ページ編集の前に patching.md を参照してください。抽出でサポートされていない XML のみのコンテンツが報告された場合は、該当する mxCell の値、スタイル、またはジオメトリのみを変更し、元の状態を保持して視覚的レビューが合格するまで待ちます。見た目を整えるためだけに安定した ID を決して振り直さないでください。

品質契約

提供前に以下のすべてを満たす必要があります：

ぶら下がったエッジエンドポイント、重複 ID、無効な親参照、またはノードの重なりがないこと。
ラベルがノードに収まり、通常のズームで判読可能であること。
方向とグループ化が意図した階層を伝えていること。
エッジラベルは実装の詳細ではなく、関係性を説明していること。
色は一貫した意味を持ち、唯一の区別要因にならないこと。
装飾的な詳細が主要な読み取り経路を圧迫しないこと。

リリースゲートとして --strict を使用します。チェックが失敗した場合、または図の手動視覚レビューが必要な場合は quality-gates.md を参照してください。

作成ルール

api-gateway のような安定した意味的な ID を使用し、node-7 のような序数 ID は使用しないでください。
ラベルは短く保ちます。長いコンテキストは description に記載してください。
階層、信頼ゾーン、境界付けられたコンテキスト、または所有権には明示的な group 値を使用してください。
リクエスト/データパイプラインには左から右、プロセスや階層には上から下を推奨します。
1 つの図につき 1 つの主要なアイデアを維持します。大きなシステムは、すべてを縮小するのではなく、複数のページまたはレベルに分割してください。
position はユーザーが意図的な配置を必要とする場合にのみ使用し、それ以外はコンパイラにノードを決定論的にレイアウトさせてください。
ベンダー固有の draw.io ステンシル名を推測しないでください。検証済みの図形マッピングが存在するまで、ニュートラルな意味的な種類を使用してください。

ツールの動作

scripts/drawio_tool.py は、JSON 入力には標準ライブラリのみを使用します。YAML 入力は PyYAML がインストールされている場合にサポートされます。提供される機能：

doctor：コアファイルと Python/XML サポートを検証し、オプションの YAML および Desktop 機能を報告します。
init：architecture、Blueprint、ERD、HA、routing、infrastructure、または CI の安全なスターターをコピーします。
build：モデルまたはソースを自動検出し、完全な監査付き drawio-diagram-bundle/v1 を作成します。
migrate：レガシー/バージョンなしの Diagram IR を決定論的にアップグレードし、機械可読な変更レポートを出力します。
compile：IR を検証し、決定論的なレイアウトを計算し、非圧縮の編集可能な draw.io XML を出力します。
extract：圧縮または非圧縮の draw.io から Diagram IR を復元し、コンパイラバックアップされたセマンティクスを保持し、推定されたすべてのレガシーセルを報告します。
blueprint：1 つのアーキテクチャモデルを、コンテキスト、論理、データ、デプロイメント、セキュリティ、および決定のページに投影します。
erd：エンティティ、フィールド、キー、タイプ、およびカーディナリティを検証し、モデルまたは SQL DDL から編集可能な Crow's Foot ERD を生成します。
ha：障害ドメイン、レプリカ、レプリケーション、ヘルスチェック、およびフェイルオーバーを検証し、トポロジとフェイルオーバーページを生成します。
import：Python/TypeScript モジュールツリー、OpenAPI、SQL DDL、Docker Compose、Terraform、Kubernetes、GitHub Actions、または GitLab CI を Diagram IR に変換します。
diff：Diagram IR を意味的に比較し、構造化されたドリフトレポートを出力し、オプションで色と形状でコード化された編集可能なドリフトビューを生成します。
patch：ノード、エッジ、グループ、位置、および図の変更をアトミックに適用します。
preview：draw.io Desktop なしでレビュー可能な SVG を作成します。
audit：構造化ソースと生成されたジオメトリを検査し、修復提案とプレビューパスとともに結果をグループ化します。
security：モデル、.drawio、または完全なバンドルを、認証情報、安全でないリンク、禁止された XML 構造、および decompression リスクについてスキャンします。
validate：IR または .drawio をリントし、0～100 の品質スコアを出力し、--strict では失敗します。
inspect：ページ、ノード、エッジ、グループ、およびキャンバス境界を要約します。
render：macOS、Windows、Linux 全体で draw.io Desktop CLI を検出し、DRAWIO_DESKTOP_BINARY または --binary を優先し、PNG、SVG、PDF、または JPG をエクスポートします。
verify-export：Desktop を起動せずに、ネイティブエクスポートの形式シグネチャ、構造終端記号、寸法、および安全な SVG コンテンツを検証します。

初回使用前に、python3 -c "import xml.etree.ElementTree" を確認してください。macOS Homebrew Python で pyexpat/libexpat のシンボルエラーが発生した場合は、/usr/bin/python3 を使用するか、その Python インストールを修復してください。ABI 障害を図の入力に帰属させないでください。

コンパクトな出発点として、example.architecture.json、example.blueprint.json、example.erd.json、example.ha.json、example.routing.json、example.terraform.tf、または example.kubernetes.json を固定テンプレートとしてではなく使用してください。再利用可能なカスタムテーマの例として corporate.json を適用します。

Draw.io ダイアグラムエンジニア