utility-mermaid-diagrams

Mermaid 図

プロダクト文書向けに、効果的で構文的に有効な Mermaid 図を作成します。

使用する場面

• PRD、仕様書、ロードマップ、ステークホルダー向けプレゼンテーション用の Mermaid 図を作成する
• 15 種類の図から、特定のコミュニケーション上の目的に合うものを選ぶ
• レンダリングされない、または誤ってレンダリングされる Mermaid コードをデバッグする
• 図の明瞭さ、正確さ、アクセシビリティを確認する

使用しない場面

• 図を画像ファイル（PNG/SVG）にエクスポートする場合。これはレンダリングツールの役割です
• Mermaid 以外の作図ツール（Figma、Lucidchart、draw.io）を使用する場合
• 情報を伝える目的のない、純粋に装飾的なビジュアルを作成する場合
• 単独の図ではなく、全体的なカスタマージャーニーの成果物（ステージ、タッチポイント、感情曲線、ペインポイント）を作成する場合。タイムラインまたはフローチャートのセクションでこのスキルを構成要素として使う discover-journey-map を使用してください

最も重要なルール

リストで表現できることを図にしないでください。

図が役立つのは、文章では平坦化されてしまう関係性、分岐、またはフローを明らかにするときです。図を作成する前に、次のことを確認してください。

これは、リストや表では平坦化されてしまう分岐、関係性、またはフローを示していますか？

• はい → 図を作成します
• いいえ → 代わりに番号付きリスト、箇条書き、または表を使用します

直線的な 5 ステップのプロセスはリストです。2 つの判断ポイントと再試行ループがある 5 ステップのプロセスは図です。

図の選択ガイド

示したい内容	使用する図	併せて検討する図
判断または承認プロセス	フローチャート	状態図
複数サービスまたは複数関係者のやり取り	シーケンス図	フローチャート
機能のライフサイクルまたはステータス遷移	状態図	フローチャート
作業ステージまたはパイプラインのステータス	カンバン	状態図
依存関係を含むリリースまたはスプリントのタイムライン	ガント	タイムライン
バージョン履歴または時系列のマイルストーン	タイムライン	ガント
2 次元の優先順位付け（工数／影響度、リスク／価値）	クアドラント	-
割り当ての内訳または構成	円グラフ	ツリーマップ
問題の分解またはブレインストーミング	マインドマップ	-
ドメインモデルまたはデータの関係	ER 図	クラス図
API またはオブジェクトのコントラクト	クラス図	ER 図
システムのトポロジーまたはインフラストラクチャ	アーキテクチャ図	フローチャート
フローの量または予算配分	サンキー図	円グラフ
階層的な比例データ	ツリーマップ	円グラフ
トレンドまたは時系列の指標	XY チャート	-

PM のタスク別にまとめた実例については、references/pm-use-cases.md を参照してください。 種類ごとの完全な構文とオプションについては、references/diagram-catalog.md を参照してください。

構文の有効性に関する原則

レンダリングの失敗のほとんどを防ぐ 6 つのルール：

1. ラベルを引用符で囲む - スペース、丸括弧、角括弧、コロン、カンマ、または予約語を含むラベルは、二重引用符で囲む必要があります
2. 特殊文字をエスケープする - Mermaid または Markdown で特別な意味を持つ文字（>、<、行頭の -、#）は、エスケープするか引用符で囲む必要があります
3. 参照する前に宣言する - エッジで使用する前にノードを定義します。未宣言のノードを参照すると、一部の種類ではエラーが表示されずに失敗します
4. 制限を守る - 各図の種類には、可読性が損なわれる最大ノード数または最大参加者数があります（種類ごとの上限については references/diagram-catalog.md を参照してください）
5. 意図をコメントに残す - %% コメントを使って、明らかでない選択（このレイアウト方向にした理由、このグループ分けにした理由）を記録します
6. 公開前にテストする - Mermaid レンダラー（mermaid.live、VS Code プレビュー、または対象の環境）に貼り付けて、正しくレンダリングされることを確認します

構文の完全なリファレンスについては、references/syntax-guide.md を参照してください。

手順

1. 伝える内容を特定する - どのような関係、流れ、階層、比率を可視化する必要がありますか？対象読者は誰ですか？
2. 基本原則を適用する - 図がリストや表よりも価値を提供することを確認します
3. 図の種類を選択する - 上記の選択ガイドを使うか、タスク別に references/pm-use-cases.md を参照するか、種類別に references/diagram-catalog.md を参照します
4. 図を計画する - references/TEMPLATE.md の計画ワークシートに記入します：目的、対象読者、ノード一覧、種類を選んだ理由
5. mermaid コードを記述する - references/syntax-guide.md のルールに従い、references/diagram-catalog.md の最小構文の例から始めて拡張します
6. 検証する - 以下の品質チェックリストに沿って確認します
7. 埋め込む - 検証済みの mermaid コードブロックをドキュメントに配置します

出力要件

• 計画成果物：記入済みの図の計画ワークシート（references/TEMPLATE.md）
• 最終出力：対象ドキュメントに埋め込まれた、構文的に有効な mermaid コードブロック
• 品質ゲート：品質チェックリストのすべての項目に合格すること

品質チェックリスト

• 対象環境で図がエラーなくレンダリングされる
• 基本原則を満たしている - リストや表では、これほど明確に伝えられない
• 分岐、関係、階層のない直線的なシーケンスがない
• スペースや特殊文字を含むすべてのラベルが適切に引用符で囲まれている
• 必要な箇所で特殊文字がエスケープされている
• ノード／参加者数が種類ごとの上限内である
• 色がアクセシブルである（WCAG AA のコントラスト比は最低 3:1、明るい背景には黒いテキストを使用）
• 色だけで要素を区別していない - 形状やラベルでも区別している
• 図に内容を表すタイトル、または周囲の文脈を示す文章がある
• %% コメントで、明白でないレイアウトやグループ化の選択を説明している

参考資料

ファイル	用途
references/TEMPLATE.md	図の計画ワークシート - mermaid コードを記述する前に記入します
references/EXAMPLE.md	記入例：PM が製品ローンチ用に 4 つの図を作成
references/diagram-catalog.md	15 種類すべての図：構文、PM の例、上限、注意点
references/pm-use-cases.md	PM のタスク → 図の種類の対応付けと、簡単な記入例
references/syntax-guide.md	構文の有効性、エスケープ、スタイル設定、検証チェックリストに関する完全なルール