mermaid-diagrams-expert

Mermaid 図のエキスパート

目的

構造、関係性、順序、アーキテクチャを視覚的に示すことで分かりやすくなる場合に、ソフトウェアドキュメント向けの保守しやすい Mermaid 図を作成します。対象となる図は、フローチャート、シーケンス図、クラス図、ER 図、C4 図、アーキテクチャ図、状態図、Git 図、ガント図、チャート、カンバン図、パケット図、ベン図、特性要因図です。バージョンに依存する構文やベータ構文を使う前に、対象のレンダラーと Mermaid のバージョンを確認してください。選んだ図の種類に必要なリファレンスを読み込んでください。

基本原則

1. 読者が関係性、順序、状態、トポロジー、分岐、依存関係について考える必要がある場合にのみ図を使います。単純な事実は文章のほうが分かりやすく説明できます。
2. Mermaid の構文には移植性がありますが、レンダラーの挙動にはありません。対象のレンダラーを互換性の制約として扱ってください。
3. スタイル設定より先にモデルを作成します。まずノード、エッジ、ラベル、方向、境界を定めてください。
4. バージョンに依存する構文を使う前に、対象のレンダラーとバージョンを確認してください。
5. レンダラーを利用できない場合は、確認済みであるかのように示すのではなく、図が未レンダリングであることを伝えてください。
6. 図は読みやすい大きさに保ちます。フォントを縮小するのではなく、エンティティが10～15個程度になったら分割してください。
7. 独自のアーキテクチャ、認証情報、個人データをオンラインレンダラーに送信してはいけません。
8. 図のラベルや周囲のドキュメントでは、em ダッシュを使用しないでください。

承認モデル

ユーザーの指示	承認される範囲
「これを図にして」	指定された構造を示す Mermaid ブロックを作成する
「README に図を追加して」	図と、ファイルに必要な周囲の説明
「これがレンダリングされるか確認して」	レンダラーがすでに利用可能な場合にレンダリングする
「Mermaid CLI をインストールして確認して」	ツールのインストールを含む、別途の承認
「これをオンラインエディターに入れて」	送信する内容を明示した後に限り、機密情報を含まない場合にのみ実行する

レンダラー、アイコンパック、Docker のインストールは環境を変更するため、それぞれ個別の承認が必要です。図の検証のために、暗黙のうちに環境をセットアップしてはいけません。

ステップ 0：図を使う価値があるか判断する

読者が関係性、順序、状態、トポロジー、分岐、依存関係について考える必要がある場合に図を使います。文章のほうが明確に説明できる単純な事実に、無理に図を使わないでください。

永続的なドキュメントでは、対象のレンダラーを互換性の制約として扱ってください。

ステップ 1：図の種類を選ぶ

references/diagram-type-selection.md を読んでください。モデル化する構造に合った図を選びます。

構造	推奨する種類
プロセスまたは意思決定ツリー	フローチャート
時間経過に伴うインタラクション	シーケンス図
ドメインオブジェクトと関係性	クラス図または ER 図
サービスアーキテクチャ	C4 図またはアーキテクチャ図
クラウドおよびデプロイのトポロジー	アーキテクチャ図
ライフサイクル	状態図
リポジトリの履歴	Git グラフ
依存関係を含むスケジュール	ガント図
単純な比率	円グラフまたは xychart
作業段階と引き継ぎ	カンバン図
ビット範囲ごとのパケットレイアウト	パケット図
集合の重なり	ベン図
原因と結果	特性要因図
階層構造またはブレインストーミング	マインドマップ、ツリーマップ、またはタイムライン

専用の図は、その意味づけが読者の理解に役立つ場合にのみ使ってください。venn、ishikawa、kanban、packet、radar、treemap、mindmap、timeline、journey、sankey を使う場合は、先に references/new-diagrams.md を読んでください。

ステップ 2：互換性を確認する

リポジトリに図を保存する場合は、対象のレンダラーと Mermaid のバージョンを特定してください。レンダラーが不明な場合は、バージョン依存であることが分かっている構文を避け、前提を明記してください。

ベータ構文、新しいディレクティブ、テーマ、アイコンパックを使う前に、references/renderer-adapters.md を読んでください。永続的なドキュメントでベータ版の図の種類を使う場合は、明示的な代替案を用意するか、バージョンを固定する必要があります。

ステップ 3：スタイル設定より先にモデルを作成する

まずノード、エッジ、ラベル、方向、境界を定義してください。ラベルは短く、意味が明確なものにします。サブグラフまたは C4 の境界を使って、所有範囲とシステム境界を明示してください。

構造が正しくなるまでは、スタイル設定を最小限に抑えてください。関係性がそのままの状態で明確に読み取れるようになってから、色やレイアウトを加えてください。

ステップ 4：検証

必要に応じて、references/validation-and-rendering.md、references/security.md、および図の種類に関するリファレンスを読みます。次の点を確認してください。

• 対象のレンダラーで構文を解析できる
• ラベルが明確で、必要に応じて引用符で囲まれている
• 方向とエッジの意味が正しい
• ID が安定しており、一意である
• 特殊文字が安全に引用されている
• 長期にわたって使用するドキュメントでは、ベータ構文にフォールバックまたはバージョンの固定がある
• 図が想定サイズで読みやすい
• シークレット、認証情報、個人データが埋め込まれていない

レンダラーを利用できる場合は、レンダリングテストを行います。利用できない場合は、静的な構文チェックを実施し、レンダリングしていないことを明記します。

ステップ 5：提出先に合わせて仕上げる

チャットでは、Mermaid ブロックと、役立つ場合は短い解説を提示します。README／Wiki／PR のコンテンツでは、フェンス付きブロックと必要な周辺の説明をそのまま維持します。

エラーへの対処

図がレンダリングされない、または対象が受け付けない場合：

1. 意図した見た目を説明するのではなく、実際のパーサーまたはレンダラーのエラーを報告する
2. 関連するリファレンスで図の種類を示すキーワードを確認する。タイプミスは明確なエラーになるため、別の形式に置き換わることはない
3. 設定名とテーマオプション名を確認する。認識されないオプションは通常、無視されるため、意図したスタイルが適用されていなくても図がレンダリングされたように見えることがある
4. テキストを縮小するのではなく、図を分割して簡潔にする
5. 対象のレンダラーが必要な機能に対応していない場合は、その旨を伝え、広くサポートされている構文を提案する
6. リントしただけの図を、レンダリングしたと主張しない

エラーなしで終了し、出力ファイルが作成されていれば、構文は解析されています。それ以外の場合は、図を完成品として提示する前に修正してください。

避けるべきパターン

• どのプラットフォームでも Mermaid のサポートが同じだと決めつける。
• レンダラーやバージョンの対応状況を確認せずに、新しい構文やベータ構文を使う。
• フォールバックやバージョンの固定なしに、長期にわたって使用するドキュメントでベータ版の図を使う。
• すべての段落を図にする。
• ノードに文章を詰め込みすぎる。
• 例にシークレット、認証情報、実在する個人データを含める。
• リントしただけの図を、レンダリングしたと主張する。
• キーワード、設定キー、バージョンの対応状況を記憶だけで創作する。
• ドキュメントで全角ダッシュを使う。

同梱のリファレンス

references/diagram-type-selection.md、選択した図の種類に関するリファレンス、および要求された構文に必要な高度な機能のリファレンスを読み込んでください。

• references/diagram-type-selection.md：モデル化する対象に基づいて、適切な図の種類を選ぶためのガイド。
• references/flowcharts.md：フローチャートの構文、構造、および一般的なパターン。
• references/sequence-diagrams.md：シーケンス図の構文、アクター／参加者のパターン、および一般的な慣用表現。
• references/class-diagrams.md：クラス図の構文、関係、および一般的なパターン。
• references/erd-diagrams.md：ER 図の構文、カーディナリティ、および一般的なパターン。
• references/c4-diagrams.md：C4 モデルの構文、コンテキスト／コンテナー／コンポーネントの境界、および一般的なパターン。
• references/architecture-diagrams.md：アーキテクチャ図の構文、クラウド／デプロイのトポロジー、および一般的なパターン。
• references/misc-diagrams.md：状態図、Git グラフ、ガントチャート、円グラフ／棒グラフ。
• references/new-diagrams.md：カンバン、パケット、ベン図、石川図、レーダーチャート、ツリーマップ、マインドマップ、タイムライン、ジャーニー、サンキーダイアグラムなどの特殊な図の種類と、必要な最小バージョンおよびベータ版のルール。
• references/security.md：シークレット、個人データ、インジェクションのリスク、安全な検証の境界。
• references/advanced-features.md：新しい構文、ディレクティブ、テーマ、バージョン依存の機能。
• references/renderer-adapters.md：対象のレンダラーおよびバージョンとの互換性チェック。
• references/validation-and-rendering.md：図の提出前の検証方法、よくある落とし穴、エクスポートの選択肢、エクスポートせずに図をレンダリングできる場所。
• references/proactive-trigger.md：依頼されていなくても図を作成すべき場合と、作成を控えるべき場合。
• references/verification-and-failure.md：検証および失敗時の対応に関する共通原則。