figma-generate-diagram

generate-diagram

generate_diagram ツールを呼び出す前に、必ずこのスキルを読み込んでください。 読み込まないと、回避可能なレンダリングエラーが発生し、出力品質が低下します。

generate_diagram は Mermaid.js の構文を受け取り、編集可能な FigJam ダイアグラムを生成します。このスキルでは、種類ごとの適切なガイダンスを案内し、共通の制約を設定します。

ステップ 1：generate_diagram は適切なツールですか？

対応しているダイアグラムの種類

flowchart、sequenceDiagram、stateDiagram ／ stateDiagram-v2、gantt、erDiagram。

非対応 — ツールを呼び出さないでください

ユーザーが次のいずれかを求めている場合は、ツールを呼び出して失敗するのではなく、generate_diagram は対応していないことを直接伝えてください。

• 円グラフ、マインドマップ、ベン図、クラス図、ジャーニー、タイムライン、クアドラント、C4、Git グラフ、要件図

Figma での編集を勧める場合

このツールでは、次の操作はできません。

• 既存のダイアグラムのフォントを変更する
• 個々の図形を移動する
• 生成後にダイアグラムのノードを個別に編集する

既存のダイアグラムに対してこれらの操作をユーザーが求めている場合は、Figma でダイアグラムを開いて編集するよう勧めてください。内容レベルの変更であれば、通常は再生成するほうが迅速です。

ステップ 2：ダイアグラムの種類を選ぶ

簡易的な振り分け — 最初に該当したものを選んでください。

ユーザーの要望…	種類	次のステップ
サービス＋データストア＋キュー＋連携	アーキテクチャフローチャート	references/architecture.md を読む
決定木、プロセスフロー、パイプライン、依存関係グラフ、ユーザージャーニー	フローチャート	references/flowchart.md を読む
時間経過に伴う関係者間のやり取り（API 呼び出し、認証、メッセージング）	シーケンス図	references/sequence.md を読む
データモデル、テーブル、キー、カーディナリティ	ER 図	references/erd.md を読む
名前付きの状態と状態間の遷移	状態図	references/state.md を読む
日付やマイルストーンを含むプロジェクトのスケジュール	ガントチャート	references/gantt.md を読む

フローチャートが求められていて、サービス、データストア、キュー、外部連携などのソフトウェアインフラストラクチャを説明している場合は、flowchart.md ではなく architecture.md に振り分けてください。判断に迷う場合は、ユーザーに確認してください。

ステップ 3：共通の制約（すべての図の種類に適用）

1. Mermaid ソースのどの部分にも絵文字を使わないでください。ツールで拒否されます。
2. ラベルに \n を使わないでください。改行は本当に必要な場合に限り、エスケープシーケンスではなく実際の改行を使ってください。
3. ラベルに HTML タグを使わないでください。
4. 予約語 — end、subgraph、graph をノード ID に使わないでください。
5. ノード ID：キャメルケース（userService）を使い、スペースは入れないでください。アンダースコアを使うと、一部のプロセッサーでエッジのルーティングが壊れることがあります。
6. ラベル内の特殊文字は引用符で囲んでください：A["Process (main)"]、-->|"O(1) lookup"|。
7. シーケンス図 — Mermaid の Note over X ／ Note left of X ／ Note right of X はレンダラーによって気づかれないまま削除されます。ソースには含めないでください。ユーザーがシーケンス図への注釈を求めている場合は、まずベースの図を生成し、ハイブリッドワークフロー（references/workflow.md）を使って付箋やテキストを追加してください。
8. ガントチャート — classDef、class、その他のスタイル指定は前処理で削除されるため、レンダリングされたチャートに色は付きません。ユーザーが色分けしたフェーズ、マイルストーン、タスクを求めている場合は、まずベースのチャートを生成し、ハイブリッドワークフロー（references/workflow.md）で色や注釈を追加してください。または、スタイル指定が不可欠な図の場合は、代わりに use_figma を使ってタイムラインを直接作成してください（references/gantt.md §11 を参照）。
9. use_figma の拡張では FigJam 専用 API を使ってください。generate_diagram の出力先は FigJam ファイル（figma.com/board/...）なので、ハイブリッド拡張では FigJam 対応 API のみを使用する必要があります。figma.createPage() は呼び出さないでください。これは Design 専用（figma.com/design/...）であり、FigJam では TypeError: figma.createPage no such property 'createPage' on the figma global object が発生します。代わりに FigJam セクションでコンテンツを整理してください（figma-use-figjam を参照）。

ステップ 4：ゴミを入れれば、ゴミが出てくる

生成される図の品質は、作成する Mermaid の品質によって決まり、それは利用できるコンテキストによって左右されます。Mermaid を記述する前に、対象を正確に表現できるだけの実際の情報があることを確認し、現在の環境で利用できる手段を使って情報を集めてください。

利用可能なものに応じて、コンテキストの把握に役立つ情報源には次のものがあります。

• ソースコード — 関連ファイルを grep／読み込み、実際のサービス名、エッジラベル、データストア、エントリーポイントを図に反映してください。記憶を頼りに再現するよりも、実際のルート、ハンドラー、コンシューマーをたどるほうが確実です。
• ユーザーから提供されたドキュメント — PRD、仕様書、会議メモ、文字起こし、調査の統合資料、オンボーディング文書、プロセスの説明などです。対象がコードではない場合は、ユーザーに貼り付けるか添付するよう依頼してください。
• 既存の Figma または FigJam ファイル — 新しい図をユーザーがすでに持っている図に合わせる場合は、get_figjam または get_design_context で内容を確認してください（figma-use および figma-use-figjam スキルを参照）。
• 利用可能なその他の MCP サーバーやツール — 課題管理ツール、ドキュメントサイト、CRM、分析ツール、社内 Wiki、デザインシステム、データベーススキーマなどです。図にする内容の正確な情報が接続済みのツールにある場合は、推測せずにその情報を取得してください。
• ユーザー本人 — 説明が不足している、または曖昧な場合（フローの方向、範囲、重要なエンティティが不明確な場合）は、生成する前に焦点を絞った質問を 1 つか 2 つしてください。例：「主なステップは 3〜5 個ありますか？」「各ステップの担当者は誰ですか？」「次のステップを開始するきっかけは何ですか？」良い質問を 1 つするほうが、役に立たない図を 1 つ作るより効果的です。

図を「完成」させるために、エッジ、ラベル、エンティティを作り出さないでください。情報が欠けている場合は、幻覚による情報で補うよりも、空白を残してユーザーに伝えるほうが適切です。

ステップ 5：図に Mermaid では表現できない要素が必要ですか？

Mermaid ですべてを表現できるわけではありません。特定のノードに結び付いた付箋の注釈、ERD のノードごとのドメイン色分け、データを添付したコールアウトなどには、generate_diagram と use_figma の組み合わせが必要です（figma-use-figjam スキルを使用）。これがハイブリッドワークフローです。

これはデフォルトではなく、状況に応じて判断します。ユーザーの要望に明らかに役立つ場合に実行し、基本的な図で十分だと明らかな場合は省略します。実行すべきサイン：ユーザーが注釈、色、コールアウト、または「各ノードに X を付ける」ことを明示的に求めている、特定のノードに対応付けられるデータを共有している、図が思考を整理するためのスケッチではなく共有可能な成果物である。実行しないサイン：短く、説明不要な依頼、小規模な図、ユーザーが試行またはテストをしている。

ハイブリッドが適切な場合は、generate_diagram を呼び出す前に references/workflow.md を読んでください。パターン、2 つの基本レシピ（注釈＋色分け）、コミュニケーションのスタイル、失敗時の対応について説明しています。適切でない場合は、ステップ 6 に進んでください。

ステップ 6：ツールの呼び出し

必須：

• name：説明的なタイトル（ユーザーに表示されます）
• mermaidSyntax：Mermaid のソース

任意：

• userIntent：ユーザーが何をしようとしているかを説明する短い文。テレメトリーや後続の調整に役立ちます
• useArchitectureLayoutCode：アーキテクチャ図の場合のみ。値は references/architecture.md で指定されています
• fileKey：新規ファイルではなく、既存の FigJam ファイルに図を追加したい場合に指定します

generate_diagram の前に create_new_file を呼び出さないでください。ツールが独自のファイルを作成します。

ステップ 7：生成後

• ツールは、ユーザーがクリックして FigJam で図を開けるリンク（またはウィジェット）を返します。クライアントがインラインウィジェットを表示しない場合は、Markdown リンクとして提示してください。
• 追加が適切な場合（ステップ 5 を参照）は、ここで use_figma と組み合わせます。パターンとレシピは references/workflow.md にあります。
• 同じ図を 2 回試してもユーザーが満足しない場合は、再生成を止めてください。具体的に何が問題なのか尋ねるか、ツールの呼び出しを重ねる代わりに、Figma で開いて手動で編集することを提案してください。

反復や関連図の追加では同じファイルを再利用する

fileKey を指定せずに generate_diagram を呼び出すたびに、ユーザーの下書きに新しい FigJam ファイルが作成されます。4 回再生成すると、整理が必要な下書きファイルが 4 つできます。次の場合は既存のファイルを再利用してください。

• ユーザーが同じ図を反復して調整している場合（「もう一度…」「ラベルを変更して…」）。
• 最初の図と並べて配置する追加の図をユーザーが求めている場合（例：同じシステムのフローチャートの横に配置するシーケンス図）。

再利用方法：

1. 以降の generate_diagram 呼び出しで fileKey を指定します。figma.com/board/{fileKey}/... URL から抽出してください。新しいファイルを作るのではなく、既存のファイルに図が追加されます。
2. 前の図の横に追加するのではなく置き換えたい場合は、まず use_figma ツール（figma-use-figjam スキルを参照）を使って古い図のノードを削除し、その後、同じ fileKey を指定して generate_diagram を呼び出します。または、古い図を残して新しい図を横に配置してもかまいません。試行の履歴が見えることで、閲覧者に役立つこともよくあります。

初めて反復するときは、どちらがよいかユーザーに尋ねてください。「前の図を置き換えますか、それとも両方を並べて残しますか？」と確認し、セッション中はその回答を覚えておいてください。