pma-draw

ReactFlow 図表クリエーター

形状、位置、接続によって意味を表現する .rfd.json ファイルを生成します。ファイルは、カスタムノードタイプの定義済みカタログを備えた ReactFlow ベースのビューアー（pma-viewer）で使用されます。

このエントリーファイルは小さく保ちます。現在の図表に必要な参照のみを読み込みます。

常時適用されるルール

1. まず同型性を重視します：ノードのレイアウトとエッジのトポロジーは、概念の構造を反映する必要があります。すべてのラベルを取り除いてもアイデアが伝わるなら、適切な設計です。
2. 定義済みのノードタイプのみを使用します。すべてのノードの type は references/node-types.md から取得します。ユーザーから依頼があり、ビューアーが対応している場合を除き、新しいタイプを作成しないでください。
3. 定義済みのエッジタイプのみを使用します。すべてのエッジの type は references/edges.md から取得します。適切なプリセットがない場合を除き、プレーンな default は避けてください。
4. 色は references/colors.md から選びます。ノードのスタイルはプリセットで決まります。意味上必要な場合にのみ上書きしてください。
5. グループ化には親子関係を使用し、コンテナーの四角形を描画しないでください。子ノードには parentNode と extent: "parent" を使用し、親ノードには group タイプを使います。
6. すべての関係にエッジが必要です。近接しているだけでは接続を表しません。
7. ローカルでレンダリングしないでください：このスキルが出力するのは .rfd.json のみです。レンダリングとエクスポートは pma-viewer（SPA）で行います。品質は JSON レベルで確保する必要があります。references/validation.md を参照してください。
8. 大きな図表はセクションごとに構築します。編集のたびにノードとエッジを追加し、セクションのプレフィックス（ingest__、process__、deliver__）で ID の名前空間を分け、セクションをまたぐ参照を読みやすくします。

基本的なワークフロー

ステップ 1：詳細度の評価

• シンプル／概念的 — メンタルモデルや哲学には、抽象的なノードタイプ（process、start、end）と汎用エッジを使用します。
• 包括的／技術的 — 実システム、プロトコル、チュートリアルには、意味を持つノードタイプ（backend、database、queue、ai）、実際のコードや JSON を含む evidence ノード、型付きエッジ（stream、callback）を使用します。

技術的な図表では調査が必要です。JSON を作成する前に、実際の仕様、エンドポイント、イベント名、データ形式を調べてください。

ステップ 2：概念からパターンへのマッピング

主要な概念ごとに、その振る舞いを反映する視覚パターン（分岐、合流、ツリー、タイムライン、循環、組立ライン、並列配置、ギャップ、クラウド）を選びます。複数の主要な概念に同じパターンを使わないでください。詳細は references/design.md を参照してください。

ステップ 3：レイアウトの計画

references/layouts.md からレイアウトテンプレート（vertical-flow、horizontal-pipeline、hub-and-spoke、swimlanes、timeline、matrix）を選びます。ノードを出力する前に、position のグリッドを計算します。ReactFlow は絶対ピクセル座標を使います。一貫性は自動レイアウト処理ではなく、共有グリッドによって保たれます。

ステップ 4：ノードタイプとエッジタイプの選択

• 見つかった各コンポーネントに対し、カタログからノードの type を選びます。
• 各関係に対し、その意味（flow、stream、callback、dependency、comparison）に合うエッジの type を選びます。
• 技術的な図表では、実際のコードスニペットやデータペイロードを含む evidence ノードを追加します。

ステップ 5：JSON の出力

ラッパー、nodes[]、edges[]、viewport を記述します。references/templates.md の定義済みテンプレートを出発点として使用します。ID は内容が分かる名前にします（api-server、edge__api-to-db）。

ステップ 6：検証と引き継ぎ

references/validation.md の事前チェックリスト（ID の一意性、既存ノードへのエッジ参照、parentNode 参照の有効性、sourceHandle／targetHandle とノードの契約との一致、位置の衝突がないこと）を実行します。その後、ファイルを pma-viewer で開くようユーザーに伝えます（references/render.md を参照）。エージェントはレンダリング結果を確認できないため、JSON レベルでの厳密な管理が必須です。

大規模な図をセクションごとに作成する

1. ラッパー（schema、type、viewport、metadata）と、セクション 1 の nodes ＋ edges を記述します。
2. 編集のたびにセクションを 1 つずつ追加します。後続セクション間のエッジを読みやすくするため、ID にセクション名を接頭辞として付けます（ingest__source、ingest__queue など）。
3. 新しいセクションのエッジが前のセクションのノードを参照する場合は、既存のノード ID を正確に指定します。
4. セクションごとに位置の名前空間を分けます。後から追加する編集が既存のセクションと重ならないよう、列（x）または行（y）をセクションごとに確保します。
5. すべてのセクションを作成したら、ファイル全体を一度読み直し、エッジ参照と位置の重複を確認してから引き渡します。

包括的な図全体を 1 回の応答で生成したり、ジェネレータースクリプトを手書きしたり、JSON の生成をコーディングサブエージェントに委任したりしないでください。 いずれの方法も、セクションごとに編集する場合より品質が低くなります。

出力

• ファイル：デフォルトでは docs/architecture/<name>.rfd.json、またはユーザーが指定したパスを使用します。拡張子 .rfd.json は ReactFlow Diagram スキーマを示し、プレーンな JSON ツールとの互換性を維持します。
• 表示：pma-viewer（ReactFlow ベースの SPA）で開きます。PNG / SVG のエクスポートと編集はそこで行います。引き渡しについては references/render.md を参照してください。
• 埋め込み：references/integration.md に 4 つの方法があります。
  • React / MDX サイト → <PmaViewer src="..." /> コンポーネント
  • プレーンな HTML → pma-viewer UMD <script> ＋ PmaViewer.mount(...)
  • インタラクティブリンク → ?src=<url> クエリパラメーターを指定したホスト済みビューアー
  • 静止画像（GitHub README、メール、PDF）→ サーバー側で SVG をレンダリングする GET /render.svg?src=<url> エンドポイント

リファレンスパック

• references/design.md ビジュアルパターンライブラリ、エビデンス成果物、マルチズームアーキテクチャ、概念とパターンの対応付け。
• references/json-schema.md ファイルラッパー、nodes / edges / viewport の構造、parentNode のグループ化ルール、ハンドル。
• references/node-types.md データスキーマがタイプごとに定義されたカスタムノードのプリセットカタログ。セマンティック、構造、ユーティリティのカテゴリがあります。
• references/edges.md エッジのプリセットカタログ：フロー、ストリーム、コールバック、依存関係、比較、注釈付き。ハンドルの位置、アニメーション、ラベル。
• references/colors.md セマンティックカラーのパレット（デフォルト / AWS / Azure / GCP / K8s）とテキスト階層。ノードタイプのリファレンスにあるスタイル付きプリセットからこのファイルを参照します。
• references/layouts.md レイアウトテンプレート（垂直フロー、水平パイプライン、ハブ＆スポーク、スイムレーン、タイムライン、マトリクス）とグリッド計算。
• references/templates.md コピー＆ペーストできるノード / エッジの JSON と、完全なスターター図（3 層構成、マイクロサービス、イベント駆動型、データパイプライン、CI/CD）。
• references/validation.md 事前チェックのアルゴリズム、チェックリスト、よくあるバグの修正手順。
• references/render.md pma-viewer SPA の仕様、引き渡し形式、ビューアー内でのエクスポート、トラブルシューティング。
• references/integration.md 下流の利用者が図を埋め込む方法：MDX / React コンポーネント、ブラウザーの <script> SDK、ホスト済みビューアーで URL から読み込む JSON、サーバー側で SVG をレンダリングするエンドポイント（GitHub の README、メール、PDF 向け）。

クイックルーティング

• ゼロから設計する場合：references/design.md を読み込み、次に references/layouts.md を読み込みます。
• ノード / エッジのタイプを選ぶ場合：references/node-types.md ＋ references/edges.md を読み込みます。
• JSON を記述する場合：references/json-schema.md ＋ references/templates.md を読み込みます。
• コードベースからアーキテクチャを抽出する場合：references/node-types.md ＋ references/layouts.md を読み込みます。
• 提供前に検証する場合：references/validation.md を読み込みます。
• pma-viewer での開き方やエクスポート方法をユーザーに案内する場合：references/render.md を読み込みます。
• ドキュメント（MDX / HTML / README / SVG）に図を埋め込む場合：references/integration.md を読み込みます。

ワークフロー制御にも /pma を使用するプロジェクトの場合は、最初に /pma を読み込み、図が必要な場合にのみ /pma-draw を読み込みます。