creating-mermaid-diagrams

Mermaid ダイアグラム

.mmd テキストファイルを生成し、mmdc（ローカル）または Kroki API（インストール不要）を使って PNG／SVG／PDF にエクスポートします。

主な利点： テキストベースの構文で、レイアウトが完全に自動化されます。x／y 座標を指定する必要はありません。

使用する場合／使用しない場合

このスキルを使用する場合： 自動レイアウトを使ったコードとしてのダイアグラム（フローチャート、シーケンス、クラス、状態、ER、ガント、マインドマップ）。Git に保存され、Markdown に埋め込めるテキストソースです。

次の場合は使用せず、別のツールを選んでください：

• ピクセル単位の厳密な配置、カスタムレイアウト、ブランドアイコン、または高度なスタイリング → drawio。
• 手描き風のラフな見た目 → excalidraw または tldraw。
• 自由形式のホワイトボードやフリーハンドの線 → tldraw。
• 厳密で標準的な UML 表記 → plantuml。

前提条件

オプション A：ローカル（mmdc） — ヘッドレス Chrome も必要です（mmdc は Puppeteer 経由でレンダリングします）

npm install -g @mermaid-js/mermaid-cli
npx puppeteer browsers install chrome-headless-shell   # required — mmdc has no bundled browser
mmdc --version

Chrome がインストールされていなくても mmdc --version は成功しますが、その場合はエクスポートのたびに Could not find Chrome で失敗します。上記のブラウザーをインストールするか、PUPPETEER_EXECUTABLE_PATH にシステムの Chrome を設定してください。インストールできない場合は、ブラウザーが不要な Kroki（オプション B）を使用してください。

オプション B：Kroki API（インストール不要）

curl --version  # Just need curl

ワークフロー

1. 依存関係を確認 — mmdc --version を実行し、ヘッドレス Chrome がインストールされていることも確認します（--version が通るだけではエクスポート可能とは限りません）。いずれかが不足している場合は Kroki に切り替えます
2. ダイアグラムの種類を選択 — 下の表から選びます
3. 生成 — .mmd ファイルをディスクに書き込みます
4. 検証 — 検証を実行します（エクスポート前に必須）
5. エクスポート — mmdc または Kroki API を使って PNG／SVG／PDF を生成します
6. セルフチェック（視覚） — エクスポートした PNG を読み取り、自動レイアウトでは防げない可読性やレイアウトの問題（ラベルの切れ、詰め込みすぎ、向きの誤り）を修正してから、再検証して再エクスポートします。最大 2 回まで行います。視覚機能がない場合は省略します。下の セルフチェック（視覚） を参照してください。
7. レビューループ — 画像をユーザーに見せ、リクエストに応じて最小限の .mmd 編集を行い、承認されるまで再エクスポートします（安全弁として最大 5 ラウンド）。下の レビューループ を参照してください。
8. 報告 — 出力ファイルのパスをユーザーに伝えます

検証（必須）

検証せずにダイアグラムをエクスポートしてはいけません。

# Validate with mmdc (local)
mmdc -i diagram.mmd -o /tmp/test.png 2>&1

# Validate with Kroki (if mmdc unavailable)
curl -s -X POST -H "Content-Type: text/plain" --data-binary @diagram.mmd https://kroki.io/mermaid/svg -o /tmp/test.svg && echo "Valid" || echo "Invalid"

# If error, fix the .mmd file and validate again
# Only proceed to export after validation passes

よくある検証エラー：

• 特殊文字を含むラベルに引用符がない
• 矢印の構文が誤っている（シーケンスには ->>、フローチャートには --> を使用します）
• シーケンス図で参加者が宣言されていない

mmdc で発生する Could not find Chrome（または puppeteer）エラーは、ダイアグラムのエラーではなく、セットアップの問題です。.mmd は完全に正しい可能性があります。ブラウザーをインストールする（「前提条件」を参照）か、正しい構文を「修正」するのではなく、Kroki で検証してください。

セルフチェック（ビジョン）

上記の検証で確認できるのは構文が正しいことだけです。レンダリングされた図が読みやすいかどうかは分かりません。エクスポート後、エージェントのビジョン機能を使って PNG を読み取り、自動レイアウトでは防げない問題がないか確認します。Mermaid はすべての要素の配置を自動で決めるため、ここで確認する問題は重なりではなく、内容と読みやすさに関するものです。

確認項目	確認する内容	修正方法
ラベルの切れ	ノード／エッジのテキストが欠けたり、途中で切れたりしていないか	ラベルを短くするか、<br/> で改行します
窮屈で読みにくい密度	ノードが多すぎて詰め込まれていたり、線が絡み合ったりしていないか	方向（TD↔LR）を切り替えるか、subgraph に分割するか、ノードを減らします
向き／縦横比の誤り	図が横または縦に長すぎて読みにくくなっていないか	flowchart TD↔LR を切り替えるか、クラス図／ステート図で direction を設定します
エッジの複雑な絡み	多くのエッジが交差し、追いにくくなっていないか	接続されたノードが隣り合うようにノード宣言の順序を変えるか、subgraph でグループ化します
図の種類の誤り	内容に合わない種類の図になっていないか（例：タイムラインをフローチャートで表現）	種類を切り替えます（gantt、sequenceDiagram、stateDiagram-v2 など）
コントラスト不足	テキストがノードの塗りつぶし色に溶け込んでいないか	テキストと塗りつぶし色のコントラストが高くなるよう、classDef／テーマを調整します

• セルフチェックは最大 2 回までです。2 回修正しても問題が残る場合は、そのままユーザーに提示します。
• 修正のたびに構文を再検証し、再エクスポートします。
• ビジョン機能を利用できない場合は、セルフチェックを省略して PNG をそのまま提示します。

レビューループ

セルフチェック後、エクスポートした画像を提示してフィードバックを集めます。各リクエストに対して 最小限の .mmd 編集を行い、その後、再検証して再エクスポートします。

ユーザーのリクエスト	編集方法
ラベルを変更する	.mmd 内のノード／エッジのテキストを編集します
ノードまたはエッジを追加／削除する	該当する行を追加または削除します
色を変更する	classDef と class <node> <className> を追加／調整します
レイアウトの方向を変更する	TD↔LR（フローチャート）を切り替えるか、direction（クラス図／ステート図）を設定します
構成を変更／グループ化する	関連するノードを subgraph で囲むか、再生成します

• 各ラウンドで同じ diagram.mmd／diagram.png を上書きします。v1、v2 などのファイルは作成しないでください。
• 安全策： 5 ラウンド後は、ユーザーに mermaid.live での微調整を提案します。

図の種類

種類	キーワード	用途
フローチャート	flowchart TD/LR	プロセス、パイプライン、判断
シーケンス図	sequenceDiagram	API 呼び出し、メッセージの受け渡し
クラス図	classDiagram	OOP モデル、データ構造
ER 図	erDiagram	データベーススキーマ
ステート図	stateDiagram-v2	ステートマシン、ライフサイクル
ガントチャート	gantt	プロジェクトのタイムライン
円グラフ	pie	比率
Git グラフ	gitGraph	ブランチ戦略
C4 コンテキスト図	C4Context	高レベルのアーキテクチャ
マインドマップ	mindmap	トピックの分類
ユーザージャーニー	journey	ユーザーエクスペリエンスの流れ

構文リファレンス

フローチャート： reference/FLOWCHART.md を参照してください シーケンス図： reference/SEQUENCE.md を参照してください クラス図と ER 図： reference/CLASS-ER.md を参照してください その他の種類： reference/OTHER-TYPES.md を参照してください

例

例 1：API 認証フロー

ユーザーのプロンプト：

JWT 認証のシーケンス図を作成してください

生成された .mmd：

sequenceDiagram
  participant C as Client
  participant G as API Gateway
  participant A as Auth Service
  participant D as Database

  C->>G: POST /login {email, password}
  G->>A: validate(credentials)
  A->>D: SELECT user WHERE email=?
  D-->>A: user record
  A-->>A: verify password hash
  A-->>G: 200 OK + JWT token
  G-->>C: {token: "eyJhbG..."}

出力ファイル： auth-flow.mmd + auth-flow.png

---

例 2：マイクロサービスアーキテクチャ

ユーザーのプロンプト：

E コマースのマイクロサービスアーキテクチャを描いてください

生成された .mmd：

flowchart TD
  subgraph Clients
    M[Mobile App]
    W[Web App]
  end

  GW[API Gateway]

  subgraph Services
    US[User Service]
    OS[Order Service]
    PS[Product Service]
    PAY[Payment Service]
  end

  subgraph Data
    UDB[(User DB)]
    ODB[(Order DB)]
    PDB[(Product DB)]
    REDIS[(Redis Cache)]
  end

  M & W --> GW
  GW --> US & OS & PS & PAY
  US --> UDB
  OS --> ODB
  PS --> PDB
  PAY --> REDIS

出力ファイル： ecommerce-arch.mmd + ecommerce-arch.png

---

例 3：注文のステートマシン

ユーザーのプロンプト：

注文のライフサイクルの状態を示してください

生成された .mmd：

stateDiagram-v2
  [*] --> Pending : order created
  Pending --> Confirmed : payment success
  Pending --> Cancelled : timeout/cancel
  Confirmed --> Shipped : dispatched
  Shipped --> Delivered : received
  Delivered --> [*]
  Cancelled --> [*]

出力ファイル： order-states.mmd + order-states.png

エクスポートコマンド

オプション 1：ローカルエクスポート（mmdc）

ローカルに mmdc がインストールされている必要があります。オフラインでの使用に最適です。

# PNG (recommended: 2048px wide, white background)
mmdc -i diagram.mmd -o diagram.png -w 2048 --backgroundColor white

# PNG with theme — valid -t values: default | dark | neutral | forest
# (`base` is NOT a valid -t value; it only works inside a %%{init: {'theme':'base'}}%% directive)
mmdc -i diagram.mmd -o diagram.png -w 2048 --backgroundColor white --theme neutral

# SVG
mmdc -i diagram.mmd -o diagram.svg

# PDF
mmdc -i diagram.mmd -o diagram.pdf

オプション 2：Kroki API（インストール不要）

mmdc が利用できない場合は、Kroki を使用します。ローカル依存関係は不要です。

# SVG via Kroki
curl -X POST -H "Content-Type: text/plain" --data-binary @diagram.mmd https://kroki.io/mermaid/svg -o diagram.svg

# PNG via Kroki
curl -X POST -H "Content-Type: text/plain" --data-binary @diagram.mmd https://kroki.io/mermaid/png -o diagram.png

# PDF is NOT supported by Kroki for Mermaid — POSTing to /mermaid/pdf returns
# HTTP 400 ("Unsupported output format: pdf for mermaid. Must be one of png or svg").
# For PDF, use the local mmdc path instead:  mmdc -i diagram.mmd -o diagram.pdf

Kroki のメリット：

• ローカルへのインストールが不要です
• curl を利用できる任意のシステムで動作します
• 20 種類以上の図に対応しています（PlantUML、GraphViz、D2 など）

Kroki の使用場面：

• mmdc のインストールに失敗した場合
• 一度限りの図を手早く作成する場合
• Node.js を使わない CI/CD パイプライン

よくある間違い

間違い	修正方法
mmdc が見つからない	npm install -g @mermaid-js/mermaid-cli
mmdc で Could not find Chrome エラーが発生する	ヘッドレスブラウザーをインストールします：npx puppeteer browsers install chrome-headless-shell（または Kroki を使用します）
Kroki で PDF の生成が HTTP 400 エラーになる	Kroki は Mermaid の場合、PNG/SVG のみ対応しています。PDF にはローカルの mmdc を使用します
有効な図が mmdc に「無効」と報告される	このエラーは構文エラーではなく、Chrome/puppeteer のセットアップ失敗です。正しい .mmd を書き換えず、ブラウザーを修正するか Kroki で検証してください
シーケンス図の矢印が間違っている	リクエストには ->>、レスポンスには -->> を使用します
ラベル内の特殊文字	引用符で囲みます：A["Label: value"]
出力が空または小さい	-w 2048 フラグを追加します
参加者の順序が間違っている	先頭で participant を明示的に宣言します
サブグラフ名にスペースが含まれている	引用符で囲みます：subgraph "My Layer"