diagram

図

ミッション

ToDiagram のカスタムスキーマに準拠し、すばやく視覚的に理解できる、人が読みやすい .todiagram JSON を生成します。

モードルーター

1. schema-build：ユーザーが .todiagram の構造の作成・修正、またはメモから有効なノード／エッジへの変換を求めている場合。
2. system-architecture：ユーザーがプラットフォーム／サービス／コンポーネントのトポロジーを求めている場合。
3. flow-diagram：ユーザーがワークフロー、ユーザージャーニー、ランブック、または意思決定フローを求めている場合。
4. detail-calibration：ユーザーが密度の高い図の簡略化、情報の追加、または分割を求めている場合。

複数のモードにまたがるリクエストの場合は、次の順序で実行します。

1. schema-build
2. system-architecture または flow-diagram
3. detail-calibration
4. 最終スキーマ検証

全般的な出力要件

• 安定性を考慮し、ファイルを優先して出力します。 .todiagram ファイルを作成し、そのパスを返します。
• ユーザーがインライン出力を明示的に求めた場合に限り、インライン JSON を返します。
• 正規の .todiagram キーを使用します：nodes、edges、direction、id、label、from、to、imageUrl、iconUrl、custom_theme、fields。
• ノードの表示データは fields オブジェクト内に格納します。ノードの直接プロパティはスキーマで非推奨です。
• 同じノードで imageUrl と fields を組み合わせてはいけません。imageUrl を指定すると行の描画が置き換わります。
• imageUrl と iconUrl は使用する場合のみ含め、それ以外の場合はキー自体を省略します。
• ノードレベルの nodes は、実際の子ノードを持つコンテナーに限って使用します。
• direction は RIGHT、LEFT、UP、DOWN に限定します（TOP ではなく UP を使用）。
• ID は全体で一意にし、すべてのエッジの端点が既存の ID を参照するようにします。
• アイコンには Iconify の指定形式（logos:*、fa7-solid:*、fa:gear のような短縮形式）を優先します。外部 URL のアイコンは、ユーザーが明示的に求めた場合に限り使用します。
• 正確な Iconify スラッグが不明な場合は、curl -fsSL 'https://api.iconify.design/search?query=<term>&limit=10'（必要に応じて &prefix=logos）で検索し、返された icons 配列からスラッグを選びます。利用可能な場合は ToDiagram MCP のアイコン検索ツールを使用します。
• ノードごとのテーマ設定には custom_theme（NODE、EDGE、TEXT グループ）を適用します。使用できるキーの一覧はスキーマの仕様を参照してください。

ファイル出力ポリシー

• ユーザーが出力先のパス／名前を指定した場合は、そこに書き込みます。
• ユーザーが指定しない場合は、図のトピックまたは対象から短いケバブケースのファイル名を付けます （例：「システムアーキテクチャ」→ system-architecture.todiagram、「ユーザーオンボーディングフロー」→ user-onboarding-flow.todiagram、「AWS インフラストラクチャ」→ aws-infrastructure.todiagram）。 現在の作業ディレクトリに書き込みます。
• 複数の図を出力する場合は、安定した説明的な名前を使用します。 overview.todiagram、domain-<name>.todiagram、flow-<name>.todiagram。
• 書き込み後、次を実行します。 python scripts/validate_todiagram_schema.py <file>.todiagram

基本ワークフロー

1. 対象読者と意思決定の目的を特定します。
2. モードと詳細度（概要、実務向け、詳細分析）を選択します。
3. まずコンテナー階層を作成し、次にリーフノード、最後にエッジを作成します。
4. 簡潔なラベルと、重要度の高いメタデータのみを追加します。
5. references/authoring-checklist.md に照らして検証し、次を実行します。 python scripts/validate_todiagram_schema.py <file>.todiagram
6. 情報が過多な場合は、共有 ID／名前を維持しながら references/split-strategies.md を使って分割します。

モード別手順

1) スキーマの構築

まず references/schema-contract.md を読みます。

ユーザーが別のエンベロープを指定しない限り、次のひな形を使用します。

{
  "direction": "RIGHT",
  "nodes": [],
  "edges": []
}

ルール：

• キーマッピングがデフォルトと異なる場合に限り、configuration を追加します。
• ペイロードのキーを正規のキーに統一します（children → nodes、source／target → from／to）。
• 非推奨のノード直接プロパティは fields オブジェクトに移します。
• ノードに imageUrl と fields の両方がある場合は、どちらか一方を削除します。両者は共存できません。

2) システムアーキテクチャ

以下をお読みください：

• references/grouping-playbook.md
• references/architecture-patterns.md

ルール：

• 階層は2～3レベルを優先してください。
• ほとんどのコンテナーの子要素は3～8個にしてください。
• 特に指定がない限り、リーフ同士のインタラクションを接続してください。
• 概要図のメタデータは最小限にしてください。

3) フロー図

以下をお読みください：

• references/flow-patterns.md
• references/labeling-guide.md

ルール：

• まず正常系を作成し、その後に分岐、失敗、再試行を追加してください。
• 図ごとに主要な流れの方向を1つにしてください。
• エッジラベルは短く（1～3語）、意味が伝わるものにしてください。

4) 詳細度の調整

以下をお読みください：

• references/complexity-budgets.md
• references/split-strategies.md

ルール：

• 生成する前に詳細度の段階を選んでください。
• 上限を超える場合は、ドメイン、ライフサイクル、環境、対象読者ごとに分割してください。
• 図をまたいで、命名と共有 ID を一貫させてください。

インテントの例

• 「ToDiagramで高レベルのSaaSアーキテクチャを作成してください。」→ system-architecture + 概要レベル
• 「この無効なToDiagram JSONを修正してください。」→ schema-build
• 「このインシデント対応手順書を読みやすいフローにしてください。」→ flow-diagram（詳細度が高い場合は detail-calibration も使用）

トラブルシューティング

• ペイロードの形状が無効：まずキーを正規化し、ラッパーをフラット化してください。
• 図が煩雑すぎる：シグナルの弱いメタデータを削除し、目的別のビューに分割してください。
• 図が抽象的すぎる：重要なリーフに、重要なメタデータプロパティを1～2個追加してください。
• 関係が不明瞭：プロトコル、アクション、結果を簡潔に示すエッジラベルを追加してください。
• スキーマ検証の依存関係エラー：jsonschema を次のコマンドでインストールしてください。 python3 -m pip install --user jsonschema

参考資料

• スキーマ仕様：references/schema-contract.md
• 作成チェックリスト：references/authoring-checklist.md
• アーキテクチャパターン：references/architecture-patterns.md
• グルーピング手引き：references/grouping-playbook.md
• フローパターン：references/flow-patterns.md
• ラベル付けガイド：references/labeling-guide.md
• 複雑さの上限：references/complexity-budgets.md
• 分割戦略：references/split-strategies.md

スクリプト

• 正規形式 + スキーマバリデーター： scripts/validate_todiagram_schema.py