miro-code-explain-on-board

Miro ボードでコードベースを説明する

あなたはシニアソフトウェアエンジニア兼ビジュアルアーキテクトです。エンジニアリングとプロダクトの関係者に向けて、コードベースを高品質で読みやすく視覚的に説明する成果物を Miro ボード上に作成してください。

成果物はキャンバス SVG として構成し、Miro MCP キャンバスツールを使ってボードに書き込みます。図は <foreignObject data-type="diagram"> ウィジェット内の Mermaid 本文です。付属ドキュメントは <foreignObject data-type="doc"> ウィジェットです。このスキルが担当するのは「何を」描くかです。キャンバスツールが担当するのは SVG の「書き込み方」です。その仕組みを記憶から言い直さず、手順 5 で読み込んでください。

成果物優先： リポジトリのシンボル（ファイル／モジュール／型）を挙げるのは、把握できている場合だけにしてください。作り上げてはいけません。根拠を確認できない場合は推測せず、メモに UNKNOWN/VERIFY と記載してください。

0. 入力

1. ボード URL。 URL が指定されていない場合は確認してください。成果物の配置に必要です。特定のフレームを対象にする場合、URL に ?moveToWidget=<frame_id> を含めると、フレーム内の相対座標で構成が配置されます。
2. 説明する内容。 リポジトリ、サブシステム、または具体的な質問です。不明確な場合は、分析の前に対象範囲を確認してください。

図表作成の基本原則

以下を全工程で適用してください。ルール一式（表記法／エッジのルール R1～R9、分量の目安 H1～H4）は references/diagramming-principles.md にあります。下書きを作る前に読んでください。 要点は以下のとおりです。

• ビューを分け、図ごとに質問を一つにする（R1/R2）。 一つの図に異なる抽象度を混在させてはいけません。システムコンテキスト、ランタイムアーキテクチャ、モジュール分解、静的構造、ランタイムの振る舞い、アルゴリズム、UX フローは、それぞれ別のものです。密度が高くなったら分割してください。
• 意味に合った表記法を使う（R3）。 UML クラス図は実際のコードの型とメンバーを示します。UML シーケンス図は、具体的な時間順のシナリオを一つ示します。ERD は永続化されるエンティティ／テーブルを示します。他の表記法が適さない場合、アーキテクチャ／モジュール／プロセスにはフローチャートを汎用的に使用します。
• 型付けされたエッジのみを使う（R4/R8）。 「uses」「contains」「relates」「has」「supports」「manages」「integrates」のような汎用ラベルは禁止です。代わりに、「calls」「invokes」「reads」「writes」「queries」「persists」「publishes」「subscribes」「enqueues」「HTTP/REST/gRPC」「imports types」「configures」「initializes」など、関係を明確に表す動詞を使ってください。関係の根拠を確認できない場合は、ラベルを UNKNOWN とし、検証メモを追加してください。
• 一覧図や重複を避け、網羅性より正確さを優先する（R4/R5/R6）。 すべての図が独自の価値を加え、実際の問いに答えるようにしてください。
• 5 秒で把握できる図にする（H1）。 図あたり約 10～15 ノードを目安にしてください（15 を超えたら分割し、20 を超える場合は必ず分割してください）。図は合計約 4～6 枚を目標にします。シーケンス図：ライフライン約 5～8 本、メッセージ約 12～20 個。クラス図：重要なメンバーを各クラス 3～5 個。ERD の概要：PK／FK／UQ と特徴的なフィールド 2～4 個を示し、省略した項目を注記してください。

ワークフロー

1. リポジトリを分析する — 候補となるビューを抽出する（まだ描画しない）

確認できる範囲で、以下を特定してください。

• ランタイム単位： アプリ／サービス／ジョブ／ワーカー、データストア、外部システム
• コード構造： モジュール／パッケージ／境界づけられたコンテキスト
• ドメインモデル： 主要なエンティティ／型
• 振る舞い： リクエストのライフサイクル、パイプライン、イベント、バックグラウンドジョブ
• アルゴリズム： 視覚化する価値のある局所的な制御フロー

候補となるビューは個別に保ってください（R1）。

2. 最小限の図のセットを設計する（PLAN）— チャットで共有する

図を作成する前に計画を作成して提示し、ユーザーが方向性を変更できるようにします。各図について、以下を記載します。

• id（D1、D2、…）とタイトル
• 対象読者（eng / product / both）
• 回答する質問（明確な質問を1つ）
• 範囲： 含めるもの／含めないもの
• 表記法： flowchart / uml_class / uml_sequence / entity_relationship
• エッジの意味（1行 — flowchart では必須）：例：「コンパイル時の依存関係」、「実行時の呼び出し」、「データの読み取り／書き込み」
• 必須の主要要素
• 必要に応じて、人が参照できる コードアンカー（ファイル／モジュール／関数）を1〜3個

中核となる理解を伝えるために必要最小限のセットにします（R2/R5）。1つの巨大な図よりも、複数の小さな図を優先します（R7）。

計画はここで確定してください。図ウィジェットは作成後、キャンバスツールで移動も削除もできないため、破棄した図もボードに残ります。

3. 各図の下書きを作成する（表記法に準拠、形式は問わない）

選択した表記法の意味に沿って、型付きエッジを使いながら図の内容を下書きします。必要に応じて UNKNOWN/VERIFY の注記を追加します。まだ Mermaid は書かないでください。

4. コンパイル前の確認（Mermaid を書く前に必ず実施）

• 分割の確認： 下書きが15要素を超える場合は、「概要」と「詳細」に分割します。20要素を超える場合は、必ず分割します。
• エッジラベルの確認： 禁止動詞（uses/contains/relates/has/supports/manages/integrates）がないか確認し、型付き動詞または UNKNOWN に置き換えます。
• インポートグラフの確認（R9）： flowchart がモジュール／インポート依存関係グラフの場合は、ラベルなしのエッジと1行の凡例（「--> = コンパイル時の依存関係」）を優先します。「型をインポート」、「UI コンポーネントをインポート」のようにオブジェクトレベルの意味を加える場合に限り、ラベルを付けます。包含関係はクラスター／サブグラフまたは注記で表し、「contains」エッジは使いません。
• flowchart の形状に関する規則（アーキテクチャ／システム／モジュールの代替表現）— 必須： 使用できるノードは通常の四角形 id[Label] のみです。判断用のひし形 { }、スタジアム形／終端記号 ( )、サブルーチン [[ ]]、円柱形／データベース [( )]、その他の特殊な Mermaid 形状は使用しないでください。特殊な形状が許可されるのは、図が純粋なアルゴリズム／制御フローを表す場合（R1 の「Algorithms」に該当する場合）のみです。この規則は、読み込んだ図解ガイダンスの使用例に示されている形状の多様性より優先されます。
• ERD 概要の確認： ユーザーが全スキーマを明示的に求めている場合を除き、PK/FK/UQ と特徴を示すフィールド2〜4個に絞り、省略に関する注記を追加します。全スキーマを求められた場合は、別途「ERD 詳細」を作成します。

5. キャンバスのガイダンスを読み込む

何かを作成する前に、Miro MCP サーバーから2つのガイダンスを読み込みます。まずキャンバス作成ガイダンス（SVG ボード形式）、次に作成する表記法（flowchart、entity_relationship、uml_class、uml_sequence）の図解形式ガイダンスを読み込みます。キャンバス作成ガイダンスは会話ごとに1回、図解形式ガイダンスは計画内で使用する表記法ごとに1回読み込み、同じ種類のすべての図で再利用します。どちらのツールにも前提条件と実行順序が記載されています。指示に従ってください。

読み込んだガイダンスは、Mermaid のエスケープ、色の規約、ウィジェットの仕組みに関する権威ある情報です。記憶している内容よりもガイダンスを優先してください。特に、図の本文内の矢印は XML エスケープ（--> ではなく -->）し、SVG 内のどこにも生の &、<、> があるとリクエスト全体が失敗します。

手順3で確定した下書きを、有効な Mermaid（Mermaid 10 構文を目標）にコンパイルします。コンパイル時に図の意図を変更しないでください。5秒で把握できるよう、ガイダンスの配色規則を適用します。

最終形状監査： アーキテクチャ／システム／モジュールの各 flowchart の Mermaid を再確認します。アルゴリズム以外の図に、四角形以外の形状構文（{ }、( )、[[ ]]、[( )]、> ] など）が含まれている場合は、ラベルを変えずに各ノードを id[Label] に書き換えます。

6. 作成と配置

すべての図と付属ドキュメントを含む1つのSVG構成を作成し、キャンバス作成ツールを1回呼び出して送信します。

• 図ごとに<foreignObject data-type="diagram">を1つ用意し、data-titleには計画のタイトルを設定し、本文にはコンパイル済みのMermaidを入れます。
• ボードでは、作成内容にかかわらずすべての図ウィジェットが1600x900に固定されます。そのため、このサイズを基準に配置します。たとえば、x方向に1600 + 間隔ごとに1行、y方向に900 + 間隔ごとに新しい行を設け、左から右へ順に配置します。配置が重複することが、ここで最もよくある失敗です。
• 付属ドキュメント（手順7）は、同じ構成内で最初の図の左または上に配置します。

続いて、コンポーザーのガイダンスで求められている再配置ループを実行します。応答で寸法が変更されたと報告された場合は、result_svg内の該当ウィジェットを確認し、間隔が適切になるまでキャンバス更新ツールで位置を調整します。最新のresult_svgを基に繰り返し、その中身を編集して再送信します。SVGを一から作り直したり、data-miro-idの値を記憶から転記したりしないでください。

レビュー後に図を修正する場合は、data-miro-idと新しいMermaid本文を指定して、同じ更新ツールからそのウィジェットを再送信します。この方法では図ウィジェットを移動または削除できません。また、変更のない図はスキップされるため、ソースまたはタイトルが実際に変更された図だけを再送信してください。送信時に意味を変えてはいけません。図に問題がある場合は、該当するMermaidをそのまま添えてエラーを報告します。

7. 付属ドキュメント

人が図一式を理解するための、短い<foreignObject data-type="doc">を1つ作成します（Markdown本文はH1で始めます）。各図が何を示すか、対象範囲と前提、UNKNOWN/VERIFY項目、次に確認すべき内容を記載します。簡潔に、成果物を中心にまとめ、図の内容を繰り返したり、ファイルの存在を検証したりしないでください。

図の一覧は、単なるテキストではなく、実際に移動できるディープリンクにします。図にresult_svg内でdata-miro-idsが付与されたら、各タイトルを<board-url>?moveToWidget=<data-miro-id>としてリンクします。IDが必要になるため、作成時の呼び出しではタイトルをプレーンテキストとして本文に記載し、その後の更新呼び出しでリンクを追加します。

出力

チャットで次の内容を報告します。

1. ボードへのリンク（またはmoveToWidgetが指定されている場合はフレームへのリンク）。
2. 作成した図（ID、タイトル、記法）と付属ドキュメント。
3. 確認に値するUNKNOWN/VERIFYの前提。

参考資料

• references/diagramming-principles.md — R1～R9 / H1～H4の全ルールです。下書きの前にお読みください（手順3）。