creating-mermaid-diagrams

Mermaid 図

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

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

前提条件

オプション A：ローカル（mmdc）

npm install -g @mermaid-js/mermaid-cli
mmdc --version

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

curl --version  # Just need curl

ワークフロー

0. 更新確認（通知のみ、プルしない） — 会話ごとに初回使用時に行います。<this-skill-dir>/.last_update を使って24時間に1回に制限します。ユーザーの明示的な同意なく、スキルディレクトリを変更してはいけません。

   • .last_update が存在し、作成から24時間未満の場合は、この手順を完全にスキップします。

   • それ以外の場合は、上流から最新のタグを取得します：

     git -C <this-skill-dir> ls-remote --tags origin 'v*' 2>/dev/null \
       | awk '{print $2}' | sed 's|refs/tags/||' | sort -V | tail -1
     

   • 上流のタグと、このスキルのフロントマターにある metadata.version を比較します。上流のタグが（semver で）より新しい場合は、ユーザーに1行で伝えて、次のように尋ねます：

     「このスキルの新しいバージョンが利用できます：vX.Y.Z → vA.B.C。git pull しますか？」

     ユーザーが了承した場合は、git -C <this-skill-dir> pull --ff-only を実行します。どちらの場合も .last_update を更新し、24時間は確認が繰り返されないようにします。

   • 上流が同じバージョンか古い場合は、.last_update を通知せずに更新して続行します。

   • 失敗した場合（オフライン、Git チェックアウトではない場合 — たとえば ClawHub からインストールされたコピー、読み取り専用パス、権限がない場合など）は、エラーを通知せずに処理を続行し、ユーザーのタスクに取り組みます。失敗について触れてはいけません。

1. 依存関係の確認 — mmdc --version を試し、利用できない場合は Kroki に切り替えます

2. 図の種類を選択 — 下の表から選びます

3. 生成 — .mmd ファイルをディスクに書き込みます

4. 検証 — 検証を実行します（エクスポート前に必須）

5. エクスポート — mmdc または Kroki API を使って PNG／SVG／PDF を生成します

6. 報告 — 出力ファイルのパスをユーザーに伝えます

検証（必須）

検証せずに図をエクスポートしてはいけません。

# 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

よくある検証エラー：

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

図の種類

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

構文リファレンス

フローチャート：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 (default | dark | neutral | forest | base)
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 via Kroki
curl -X POST -H "Content-Type: text/plain" --data-binary @diagram.mmd https://kroki.io/mermaid/pdf -o diagram.pdf

Kroki の利点：

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

Kroki の使用場面：

• mmdc のインストールに失敗した場合
• すぐに単発の図を作成する場合
• Node.js を使わない CI/CD パイプライン

よくある間違い

間違い	修正方法
mmdc が見つからない	npm install -g @mermaid-js/mermaid-cli
シーケンス図の矢印が間違っている	リクエストには ->>、レスポンスには -->> を使用します
ラベルに特殊文字が含まれている	引用符で囲みます：A["Label: value"]
出力が空、または小さい	-w 2048 フラグを追加します
参加者の順序が間違っている	先頭で participant を明示的に宣言します
サブグラフ名に空白が含まれている	引用符で囲みます：subgraph "My Layer"