mermaid-diagram

Mermaid 図の作成

.mmd ファイルを生成します（ドキュメントに埋め込む場合は、.md ファイル内のフェンス付き ```mermaid ブロックを使用します）。

参照ファイル（必要に応じて読み込み）

ファイル	読み込むタイミング
references/types/<type>.md	図の種類を選択した後（ステップ 6）。その種類の完全な構文、例、レイアウトのヒント、改行ルール、注意点を記載しています。
references/syntax-pitfalls.md	レンダリングに失敗したとき、または構文をデバッグする必要があるとき。引用符のルール、<br> の互換性一覧（セクション 9）、予約語、一般的なエラーを扱っています。
references/mermaid-theme.md	唯一のテーマ設定ファイルです。 ダークモード／ライトモードの配色ガイドライン、classDef のセマンティックなスタイルレシピ（トリガー、成功、エラー、AI、判断）、図の種類ごとの対応に関する注記を記載しています。
references/render_mermaid.sh	レンダリングスクリプトです。読み込まず、bash 経由で実行します。詳しくは「レンダリングと検証」を参照してください。
references/examples/	検証済みの .mmd の例（architecture.mmd、sequence-api.mmd）です。参考にするか、既知の正常なパターンと構文を照合するために確認してください。

カスタマイズ

ブランドスタイルをカスタマイズするには、references/mermaid-theme.md を編集します。これはすべてのテーマ設定（セマンティックなノードスタイルとダークモード／ライトモードの配色ガイドライン）の唯一の信頼できる情報源です。

---

基本理念

図は見せるのではなく、論じるものです。

図は、書式を整えたテキストではありません。言葉だけでは表現できない関係性、因果関係、流れを示す、視覚的な論証です。形そのものが意味を表す必要があります。

同型性テスト：すべてのテキストを取り除いても、構造だけで概念が伝わりますか？ そうでなければ、設計し直してください。

教育テスト：この図から具体的なことを学べますか？ それとも、ただボックスにラベルを付けているだけですか？ 良い図は、実際の形式、イベント名、具体例を示して教えるものです。

悪い例（見せる）	良い例（論じる）
同じ大きさのラベル付きボックスが 5 つ	各概念の振る舞いを反映した形
カードのグリッドレイアウト	概念の構造に合った視覚的な構成
テキストを飾るアイコン	意味そのものを表す形
すべてに同じコンテナーを使用	概念ごとに異なる視覚的な語彙

---

設計プロセス

ステップ 0：詳細度と対象読者を判断する

まず、この図に必要な詳細度を判断します。

• シンプル／概念的：抽象的な形、ラベル、関係性を使います。メンタルモデルの説明、対象読者がすでに詳細を把握している場合、または概念自体が抽象的な場合に使用します。
• 包括的／技術的：具体例、コードスニペット、実データを使います。実際のシステムを図示する場合、教育コンテンツを作成する場合、またはテクノロジーの統合方法を示す場合に使用します。

シンプルな図	包括的な図
「入力」→「処理」→「出力」のような一般的なラベル	入力／出力が実際にどのようなものかを示す
「API」「データベース」「クライアント」のような名前付きボックス	名前付きボックスと実際のリクエスト／レスポンス
「イベント」や「メッセージ」というラベル	仕様書にある実際のイベント名／メッセージ名
説明に約 30 秒	2～3 分程度の学習内容
閲覧者が構造を理解する	閲覧者が構造と詳細の両方を理解する

同じシステムを複数の対象読者向けに説明する必要がある場合は、全員に対応しようとする図を 1 つ作るのではなく、対象読者ごとに図を分けてください。

Step 1: 調査（包括的な図の場合のみ）

技術的な図を描く前に、実際の仕様を調査してください。

プロトコル、API、フレームワークを図にする場合：

1. 実際の JSON／データ形式を調べます
2. 実在するイベント名、メソッド名、API エンドポイントを確認します
3. 各要素が実際にどのようにつながっているかを把握します
4. 汎用的なプレースホルダーではなく、実際の用語を使います

悪い例：「Protocol」→「Frontend」 良い例：「AG-UI がイベント（RUN_STARTED、STATE_DELTA、A2UI_UPDATE）をストリーミングする」→「CopilotKit が createA2UIMessageRenderer() を使ってレンダリングする」

Step 2: 深く理解する

内容を読みます。概念ごとに、次の点を考えます。

• この概念は何をするのか？（何であるかではなく）
• 概念どうしにはどのような関係があるか？
• 中核となる変換やフローは何か？
• これを理解するには、何を見ればよいか？（説明を読むだけでなく）

Step 3: 概念をパターンに対応させる

概念ごとに、その振る舞いを表す視覚パターンを選びます。

概念の特徴	使用するパターン
複数の出力を生成する	ファンアウト（1つのノードから複数のエッジが出る）
複数の入力を1つにまとめる	収束（複数のノードが1つのターゲットに集まる）
階層構造／入れ子構造がある	ツリー（マインドマップまたはサブグラフの入れ子）
手順が連続している	タイムライン（タイムライン図またはシーケンス図）
繰り返す、または継続的に改善する	スパイラル／サイクル（状態の自己遷移またはバックエッジ）
入力を出力に変換する	組み立てライン（フローチャートのパイプライン）
2つのものを比較する	並列配置（並行するサブグラフ）
フェーズごとに分かれている	区切り／分割（サブグラフの境界）

Step 4: 多様性を確保する

複数の概念を扱う図では、主要な概念ごとに異なる視覚パターンを使います。均一なカードやグリッドは使いません。

Step 5: フローをスケッチする

構文を書く前に、図を見たときの視線の流れを頭の中でたどります。明確な視覚的ストーリーが必要です。

Step 6: Mermaid 構文を生成する

1. 以下の判断マトリクスを使って図の種類を選び、references/types/<chosen-type>.md を読み込んで構文の詳細を確認します。
2. 構文を書きます。まず %% コメントブロックを記述し、図の種類と各セクションの説明を含めます。
3. 意味のあるノード ID を使います（A、B、C ではなく、authService、dbWrite、userInput を使います）。
4. 意味に応じたスタイル設定（trigger、success、error、ai、decision）に classDef を追加します。references/mermaid-theme.md（Section 2）を参照し、ダークモードとライトモードの両方で適切に表示されるよう、Section 1 の色選択ガイドラインに従います。
5. 出力形式：デフォルトでは .mmd ファイルを作成します。ユーザーが「embed」「add to docs」「in README」と指定した場合、または出力先が .md ファイルの場合は、フェンス付きの ```mermaid ブロックを使います。

エビデンス資料（包括的な図の場合）

正確性を示し、閲覧者の学習に役立つ具体例を含めます。

• データペイロードやメッセージ形式には、シーケンス図のノートを使います。
• 簡潔なインラインの根拠として、<br> を使った複数行のノードラベルを使います。
• 領域を示すサブグラフタイトルを付けます。
• ノード内のテキストに収まらない大きなペイロードやコードスニペットには、補足の .md ファイルを用意します。

重要な原則：単に名前を示すだけでなく、実際の見た目を示します。

マルチズーム（包括的な図の場合）

次の3つのズームレベルを同時に目指します。

1. 概要フロー — パイプライン全体の簡略図（Input → Processing → Output）
2. セクションの境界 — 関連するコンポーネントを責任、フェーズ、チームなどでまとめる、ラベル付きのサブグラフ
3. セクション内の詳細 — 各セクション内のエビデンス資料や具体例

大きな図の分割

• ノード数が約20個を超える前に、複数の図に分割します。
• 複雑なシステムでは、レイヤーごとに1つの .mmd ファイルを作成します（Context → Container → Component）。
• 密集したサブグラフは別ファイルに分け、本文で相互参照します。

Step 7: レンダリングと検証

レンダリングスクリプトを実行し、出力を検証します。以下のレンダリングと検証セクションを参照してください。

---

図の種類の選択マトリクス

クイックリファレンス：必要なビジュアルパターンに最適な図の種類を選び、対応するリファレンスファイルを開いてください。

ビジュアルパターン	最適な図の種類	リファレンス
ファンアウト（1 対多）	フローチャート	references/types/flowchart.md
集約（多対 1）	フローチャート	references/types/flowchart.md
ステップ／インタラクションの順序	シーケンス図	references/types/sequence.md
階層／ツリー	マインドマップ	references/types/mindmap.md
状態遷移／ライフサイクル	状態図	references/types/state.md
オブジェクトの構造／関係	クラス図	references/types/class.md
システムアーキテクチャ／コンテキスト	C4 図	references/types/c4.md
タイムライン／順序付きイベント	タイムライン図	references/types/timeline.md
スパイラル／サイクル（ループ）	状態図またはフローチャート	references/types/state.md references/types/flowchart.md
並べて比較	フローチャート（並列サブグラフ）	references/types/flowchart.md
データスキーマ／エンティティ間の関係	ER 図	references/types/er-diagram.md
フロー量／リソースの割り当て	サンキー図	references/types/sankey.md

対象外の図の種類

以下の種類は使用しないでください。構造的な論証を表現する能力がないか、専門性が高すぎます。

種類	対象外の理由
円グラフ	単純な割合の表示に限られ、構造的な論証を表現できない
ガントチャート	概念のマッピングではなく、プロジェクトのスケジュール管理に特化している
Git グラフ	Git ブランチの可視化に限られる
XY チャート	構造図の作成ではなく、定量データのグラフ化を目的としている
ユーザージャーニー	範囲が狭すぎるため、通常はシーケンス図で表す方が適している

レンダリングと検証（必須）

レンダリング方法：

bash .claude/skills/mermaid-diagram-skill/references/render_mermaid.sh <path.mmd> [output.png]

最初の実行では npx 経由で mmdc をダウンロードするため、約 30 秒かかる場合があります。

手順：

1. Mermaid の構文を記述します。
2. レンダリングスクリプトを実行します。 3a. mmdc が構文エラーで失敗した場合：エラーメッセージを読み、構文を修正します。よくある失敗については references/syntax-pitfalls.md を参照してください（通常は、引用符で囲まれていない特殊文字、誤ったキーワード、end の不足です）。 3b. mmdc が成功した場合：PNG を表示し、レイアウトを評価します。
3. レイアウトに問題がある場合：ノード／エッジの宣言順を入れ替えて配置を変更したり、rankDir（TD ↔ LR）を切り替えたり、サブグラフを追加または削除したりして構成を見直します。
4. 再レンダリングして、レイアウトで概念を明確に伝えられるまで繰り返します。

ラベルの引用符ルール：ラベルに括弧、カンマ、@、/、<、>、または : が含まれる場合は、常に [label text] ではなく ["label text"] を使用してください。迷ったら引用符で囲みましょう。["My label"] の方が常に安全です。このルールだけで、レンダリングエラーの約 50％を防げます。詳しくは references/syntax-pitfalls.md を参照してください。

graph ではなく flowchart：常に flowchart TD（新しい構文）を使用し、graph TD（旧式）は使用しないでください。graph はサブグラフの方向指定や、その他の新しい機能に対応していません。

end は予約語です：ラベル全体が end のノードは、ブロックの終了として解析されます。必ず引用符で囲んでください：B["end"]。

要素をピクセル単位で配置することはできません。 レイアウトの改善はすべて、宣言順、rankDir、サブグラフ、非表示の線で行います。座標を調整することはできません。

線の交差を減らす — 自動生成される図の視覚的な品質を左右する主な課題です。

• 宣言順が重要です：レイアウトエンジンは、ソースの順序に基づいてランクを割り当てます。ノードは読み進める順序（上から下、または左から右）で宣言してください。先に宣言したノードほど、上または左に配置されます。
• 逆方向のエッジを最小限にします：先に宣言したノードへ「逆方向」に流れるエッジは、すべて交差を引き起こします。循環がある場合は、ステート図を使うか、逆方向のエッジをサブグラフに分離してください。
• 関連するノードをソース内でまとめます：同じ論理グループのノードは、コード内でも隣接させてください。宣言が散らばると、配置も散らばり、交差が発生します。
• レイアウトのヒントとしてサブグラフを使います：関連するノードを subgraph で囲むと配置が制約され、全体的な交差を防げます。各サブグラフには独自の direction（例：direction LR）を指定でき、密集の問題を解消できます。
• 分岐の数を減らします：5 本以上の出力エッジがある単一ノードは、スパイダーウェブ状のレイアウトを作り出します。ディスパッチャー／グループノードを挿入して分岐を整理してください。
• 向きを切り替えます：交差が解消されない場合は、直交する rankDir（TD ↔ LR）を試してください。これだけで、交差の大半を解消できることがよくあります。
• 非表示の線：見えないエッジでノードの配置を制約すると効果があるか検討してください。

終了の目安：構文が有効で、レイアウトが概念を伝えており、線の交差が最小限で、ラベルが重なっておらず、図を自然な順序で見られる状態です。

---

品質チェックリスト

コンセプトと深さ（技術図の場合は最初に確認）：

1. 調査済み：実際の仕様、形式、イベント名を調べましたか？
2. 根拠となる成果物：メモ、複数行のノードラベル、大きなペイロード用の関連 .md ファイルはありますか？
3. 複数のズームレベル：概要フロー＋セクションのサブグラフ＋詳細ラベルがありますか？
4. 抽象的な表現より具体的な表現：実際の API 名やイベント名を使い、汎用的な「処理」などを避けていますか？
5. 教育的価値：この図から学べることがありますか？

図の設計： 6. 同型性のテスト：視覚的な構造は、概念の動作を反映していますか？ 7. 主張：テキストだけでは伝えられないことを図で示していますか？ 8. 多様性：主要な概念ごとに、異なる視覚パターンやノード形状を使っていますか？ 9. 図の種類を意図的に選んでいますか（決定マトリックスにある概念のパターンに合っていますか）？ 10. ノード ID は読みやすく、1 文字だけのものではありませんか？

Mermaid 固有： 11. 意味に応じたスタイル（トリガー、成功、エラー、AI、判断）に classDef を使っていますか？ 12. すべての classDef で fill、stroke、color を設定していますか？（color は必ず設定してください。ダークモード／ライトモードのガイドラインについては references/mermaid-theme.md のセクション 1 を参照してください） 13. 出力形式は正しいですか（.mmd とフェンス付きブロックのどちらですか）？ 14. 除外された図の種類を使っていませんか？（除外対象：円グラフ、ガントチャート、Git グラフ、XY チャート、ユーザージャーニー。上記の決定マトリックスを参照） 15. ノード／エッジの宣言順は読み進める方向に沿っていますか（線の交差を最小限にしていますか）？ 16. ディスパッチャーで分割せずに、5 本以上のエッジを持つノードはありませんか？ 17. 逆方向のエッジは分離されていますか（サイクルを状態図で扱うか、サブグラフ内に収めていますか）？

レンダリングの検証（必須）： 18. 構文を検証済みですか：mmdc はエラーなしで実行されますか？ 19. PNG を確認し、レイアウトを目視で検査しましたか？ 20. ラベルの重なりや、テキストを横切る線はありませんか？ 21. 図を自然な流れで目で追えますか？ 22. 線の交差を最小限にしましたか（必要に応じて並べ替えや rankDir の変更を試しましたか）？

クリーンアップ ユーザーが出力に満足したら、PNG や MMD ファイルなどの一時的な出力を削除してください。