mermaid-gen

mermaid-gen

目的

mermaid-gen スキルは、構文解析エラーによるレンダリング失敗を招く一般的な問題を避けながら、構文的に正しい Mermaid 図を作成するための専門的なガイダンスを AI アシスタントに提供します。このスキルでは、図の構文の正確さとベストプラクティスに重点を置いています。

主なメリット：

• エラーの防止：入れ子になった引用符、特殊文字の問題、構文の誤りを回避します
• 構文の習得：フローチャート、シーケンス図、状態機械などに適したパターンを適用します
• 品質保証：実証済みのテンプレートを使用し、レンダリング前に図を検証します
• トラブルシューティング：構文解析エラーを体系的に診断し、修正します
• ベストプラクティス：標準化された命名、スタイル設定、構造の規則に従います

このスキルを使用するタイミング

次の場合に mermaid-gen を使用してください：

• Mermaid の新しい図（フローチャート、シーケンス図、状態機械など）を作成するとき
• 既存の図の構文解析エラーやレンダリングの問題を修正するとき
• 文章による説明を Mermaid の構文に変換するとき
• ドキュメントにコミットする前に図の構文を検証するとき
• 「Expecting X, got Y」という構文解析エラーをデバッグするとき
• 他の形式の図を Mermaid に移行するとき
• ノードの命名、スタイル設定、サブグラフに関するベストプラクティスのガイダンスが必要なとき

次の場合は mermaid-gen を使用しないでください：

• シンプルな表やテキスト形式のリストを作成するとき（Markdown の表を使用してください）
• 図ファイルの管理や SVG の生成が必要なとき（代わりに charts-flow スキルを使用してください）
• データ可視化のグラフ（棒、円、折れ線）を作成するとき（グラフ作成ライブラリを使用してください）
• ガントチャートや Git グラフが必要なとき（主な対象範囲外です）
• 図がすでに問題なく動作しているとき（変更は不要です）

charts-flow スキルとの関係：

• charts-flow：図ファイルを管理し、SVG を生成して、ドキュメントに埋め込みます
• mermaid-gen：ファイル作成前に図の構文が正しいことを確認します
• 併用する場合：charts-flow スキルは図の生成に mermaid-gen を呼び出します

スキルへの入力

必須入力

入力	説明	例
図の種類	Mermaid 図の種類	flowchart、sequence、state、class
図の目的	図が表すもの	「エージェント間の通信フロー」、「状態機械の遷移」
内容の説明	主な要素と関係	「3 つのエージェント、1 つのデータベース、リクエスト／レスポンスのフロー」

任意の入力

入力	説明	既定値
既存のコード	現在の Mermaid コード（修正する場合）	なし（新規作成）
エラーメッセージ	レンダラーからの構文解析エラー	なし
スタイルの希望	配色、レイアウトの方向	プロジェクトの既定値
命名規則	ノード ID の形式	camelCase

スキルのワークフロー

Mermaid 図を作成または修正するには、次の 5 ステップの手順に従ってください。

ステップ 1：要件を把握する

• 図の種類（フローチャート、シーケンス図、状態図、クラス図など）を特定します
• 表現する必要のあるすべてのノード／エンティティを列挙します
• 関係と接続を特定します
• フローの方向（TD、LR など）を決定します
• グループ化が必要かどうか（サブグラフ）を確認します

ステップ 2：ノード構造を計画する

• 意味のあるノード ID を作成します（camelCase、スペースなし）
• 表示ラベルは簡潔でありながら説明的なものにします
• 判断ポイント（ひし形）を特定します
• データベース／ストレージのノード（円柱形）を計画します
• 特殊な形状が必要なノードを決定します

ステップ 3：構文規則を適用する（重要）

• すべてのノードラベルから入れ子になった引用符を削除します
• <br/> を含む複数行のラベルは二重引用符で囲みます
• エッジラベルはシンプルに保ち、必要な場合を除いて引用符を付けません
• 特殊文字を含むサブグラフにはID／ラベル構文を使用します
• ノード ID とラベルを分けて記述します：NodeID[Display Label]

ステップ 4：テンプレートを使って図を作成する

• 適切なテンプレート（フローチャート、シーケンス図、状態図）から始めます
• 正しい構文でノードを追加します
• 適切な矢印の種類を使って関係／エッジを定義します
• 関連するノードをサブグラフにまとめます（必要な場合）
• すべてのノードを定義した後にスタイル設定の指示を追加します
• 複雑なセクションにはコメント（%%）を含めます

ステップ 5：検証とテスト

• ラベル内の入れ子になった引用符を確認します
• サブグラフ ID がスタイル参照と一致することを確認します
• すべてのノード ID が一意であることを確認します
• Mermaid Live Editor（https://mermaid.live）でテストします
• すべての関係が正しく解決されることを検証します
• エラーなしでレンダリングできることを確認します

エラーからの復旧：解析エラーが発生した場合は、下記の「トラブルシューティングガイド」セクションを参照してください。

Mermaid でよくある構文エラーと解決策

1. ノードラベル内の引用符

❌ 誤り — 引用符が入れ子になっていると解析エラーが発生します：

User[User: "What is the status?"] --> System
Response["Message: "Success""] --> User

✅ 正しい — 内側の引用符を削除するか、適切にエスケープします：

User[User: What is the status?] --> System
Response["Message: Success"] --> User

ルール： [] または () で囲まれたノードラベル内で引用符を入れ子にしないでください。次のいずれかを行います：

• 内側の引用符をすべて削除します
• <br/> タグを使用する場合は、ラベル全体を二重引用符で囲みます

2. 特殊文字を含む複数行のノード

❌ 誤り — 小数や特殊文字を引用符で囲んでいません：

Results[Top Results:<br/>1. system_arch.md (0.89)<br/>2. safety.yaml (0.84)]

✅ 正しい — 数値や小数とともに
を使用する場合は、二重引用符で囲みます：

Results["Top Results:<br/>1. system_arch.md (0.89)<br/>2. safety.yaml (0.84)"]

ルール： ノードラベルに次のいずれかが含まれる場合：

• <br/> タグと小数
• <br/> タグと特殊文字
• 複雑な内容を含む複数行

ラベル全体を二重引用符で囲みます：NodeID["label content"]

3. エッジラベル内の引用符

❌ 誤り — エッジラベル内に引用符があります：

A -->|"Execute"| B
A -->|"Cancel" or Timeout| C

✅ 正しい — エッジラベルから引用符を削除します：

A -->|Execute| B
A -->|Cancel or Timeout| C

ルール： エッジラベル（|...| 内のテキスト）には、絶対に必要な場合を除き、引用符を含めないでください。プレーンテキストを使用します。

4. スタイル指定内の特殊文字を含むサブグラフ名

❌ 誤り — スタイル参照内にアンパサンドや特殊文字があります：

subgraph "Audit & Compliance"
    Node1
end
style Audit & Compliance fill:#fff

✅ 正しい — サブグラフには ID／ラベル構文を使用します：

subgraph AuditCompliance["Audit & Compliance"]
    Node1
end
style AuditCompliance fill:#fff

ルール： 特殊文字を含むサブグラフにスタイルを適用する場合：

1. 特殊文字を含まない ID をサブグラフに付けます：subgraph ID["Display Name"]
2. スタイル指定では ID を参照します：style ID fill:#color

5. ノード ID と表示ラベル

✅ 正しい — ID とラベルを分けます：

UserNode[User: Query the system] --> ProcessNode[Processing Service]
ProcessNode --> DBNode[(Database)]

ルール：

• 最初の部分（[ の前）はノード ID です（スペースを使わず、キャメルケースを使用します）
• [] 内の内容は表示ラベルです（引用符で囲めば、スペースや特殊文字を使用できます）

Mermaid チャートのテンプレート

フローチャートのテンプレート（アーキテクチャ図）

flowchart TD
    %% Define nodes with clear IDs and labels
    User[User Input] -->|Action| Service[Processing Service<br/>FastAPI]

    Service -->|Validate| Validator{Validation Check}
    Validator -->|Invalid| ErrorNode["Error Response<br/>Status: 400"]
    Validator -->|Valid| Database[(Database<br/>PostgreSQL)]

    Database -->|Query Result| Transform[Transform Data]
    Transform -->|Response| User

    %% Group related components
    subgraph Backend["Backend Services"]
        Service
        Validator
        Transform
    end

    subgraph Storage["Data Storage"]
        Database
    end

    %% Apply styles AFTER all nodes defined
    style User fill:#e1f5ff
    style Backend fill:#f0f0f0
    style Storage fill:#fff4e1

シーケンス図のテンプレート

sequenceDiagram
    participant User
    participant API as API Gateway
    participant Auth as Auth Service
    participant DB as Database

    User->>API: Request with credentials
    API->>Auth: Validate token
    Auth-->>API: Token valid
    API->>DB: Query data
    DB-->>API: Return results
    API-->>User: Success response

    Note over User,DB: All communication encrypted via TLS

状態図のテンプレート

stateDiagram-v2
    [*] --> Idle
    Idle --> Processing: Start request
    Processing --> Success: Complete
    Processing --> Failed: Error occurs
    Success --> [*]
    Failed --> Retry: Auto retry
    Retry --> Processing: Attempt again
    Failed --> [*]: Max retries exceeded

品質ゲート（完了の定義）

構文検証ゲート

• 入れ子になった引用符なし：すべてのノードラベルで、引用符が入れ子になっていないことを確認済み
• 複数行の構文：<br/> を含むラベルを二重引用符で囲んでいる
• クリーンなエッジラベル：エッジラベル（|...| の間）に不要な引用符がない
• 有効なサブグラフ ID：特殊文字を含むサブグラフで ID／ラベル構文を使用している
• 一意なノード ID：図に重複したノード ID がない
• ノード ID の形式：すべての ID がスペースのないキャメルケースになっている

構造検証ゲート

• 図のレンダリング：Mermaid Live Editor で正常にレンダリングされる
• すべての関係を解決：ノード参照に破損がない
• 正しいフロー方向：TD、LR、RL、BT が適切に指定されている
• 整理されたサブグラフ：関連するノードが論理的にグループ化されている
• スタイルを適用：すべてのノードを定義した後にスタイル指定を追加している

品質保証ゲート

• 簡潔なラベル：表示ラベルが説明的でありながら、冗長ではない
• コメントを追加：複雑なセクションに %% コメントで説明を加えている
• 適切な図の種類：正しい種類（フローチャート、シーケンス図、状態図）を使用している
• 視覚的に明瞭：図が読みやすく、理解しやすい
• ドキュメントとの統合：ドキュメントに埋め込む場合、タイトル／キャプションを追加している

コミット前の検証

• 解析エラー：レンダラーで解析エラーがゼロ
• クロスブラウザー対応：GitHub、VS Code、ドキュメントサイトで正しくレンダリングされる
• ファイルサイズ：図の複雑さが妥当である（過度に複雑ではない）
• 標準への準拠：プロジェクトの図の命名規則に従っている

スキルの制約

してはいけないこと

• ノードラベルに入れ子の引用符を使用しないでください（解析エラーの原因になります）
• 絶対に必要な場合を除き、エッジラベルに引用符を入れないでください
• ID／ラベル構文を使わずに、サブグラフ ID に特殊文字を使用しないでください
• スタイル指定でサブグラフの表示名を参照しないでください（ID を使用してください）
• すべてのノードを定義する前に、スタイル指定を追加しないでください
• ラベル内にリテラルの改行を使用しないでください（代わりに <br/> タグを使用してください）
• 複雑すぎる図（50 ノード超）を作成しないでください（複数の図に分割してください）
• node1、node2 のような汎用的なノード ID を使用しないでください（説明的な ID を使用してください）
• コミット前に Mermaid Live Editor での検証を省略しないでください
• 非推奨の Mermaid 構文を使用しないでください（バージョンとの互換性を確認してください）

図の種類に関する制限

• 次の用途には Mermaid を使用しないでください：
  • データ可視化のチャート（棒グラフ、円グラフ、折れ線グラフにはチャートライブラリを使用してください）
  • プロジェクト管理用のガントチャート（専用の PM ツールを使用してください）
  • Git グラフ（Git の可視化ツールを使用してください）
  • 写真を含む組織図（組織図ツールを使用してください）
  • 複雑なデータテーブル（Markdown テーブルを使用してください）

ファイル整理のルール

• 図ファイルを作成する前に、必ず構文を検証してください
• 図の種類に応じたテンプレートを、必ず出発点として使用してください
• 埋め込む前に、必ず Mermaid Live Editor でテストしてください
• ファイル名またはドキュメントに、必ず図の種類を含めてください
• ノード ID には、必ずプロジェクトの命名規則に従ってください

使用例

例 1：新しいフローチャートを作成する

ユーザーのリクエスト：

「認証フローを示すフローチャートを作成してください。ユーザーが認証情報を送信し、システムが検証してデータベースを確認し、トークンまたはエラーを返す流れです」

スキルのアクション：

1. 種類を特定：フローチャート（判断を含むプロセスフロー）
2. ノードを計画：ユーザー、バリデーター、データベース、TokenService、エラー、成功
3. フローを計画：ユーザー → 検証 → 判断 → データベースまたはエラー → 成功またはエラー
4. 構文ルールを適用：
   • ノード ID：userInput、validator、dbCheck、tokenService、errorResponse、successResponse
   • すべてのラベルから入れ子の引用符を削除する
   • 検証チェックにはひし形の判断ノードを使用する
5. テンプレートから作成：フローチャートテンプレートを使用する
6. 検証：Mermaid Live Editor でテストする

結果：

flowchart TD
    userInput[User: Submit Credentials] -->|POST /auth| validator{Validate Format}
    validator -->|Invalid| errorResponse["Error Response<br/>Status: 400"]
    validator -->|Valid| dbCheck[(Database<br/>Verify User)]
    dbCheck -->|Not Found| errorResponse
    dbCheck -->|Found| tokenService[Generate JWT Token]
    tokenService -->|Return| successResponse["Success Response<br/>Token + Expiry"]

例 2：解析エラーを修正する

ユーザーのリクエスト：

「シーケンス図がレンダリングされません。エラー：'Expecting SQE, got STR'。コードはこちらです：User->>API: Request "data"」

スキルのアクション：

1. エラーを診断：「Expecting SQE, got STR」＝入れ子の引用符の問題
2. 問題箇所を特定：エッジラベルに入れ子の引用符がある：Request "data"
3. 修正を適用：内側の引用符を削除する：Request data
4. 検証：修正した構文を Mermaid Live Editor でテストする
5. 修正済みコードを返す

結果：

sequenceDiagram
    User->>API: Request data
    API-->>User: Response

説明：|...| の間、または : の後にあるエッジラベルには、引用符を含めないでください。

例 3：複雑なラベルを含む状態機械を作成する

ユーザーのリクエスト：

「注文処理の状態図を作成してください。Draft → Submitted → Processing → Completed または Failed の流れです。遷移条件も含めてください」

スキルのアクション：

1. 種類を特定：状態図（状態遷移）
2. 状態を計画：Draft、Submitted、Processing、Completed、Failed
3. 遷移を計画：ラベル付きの条件を含める
4. 構文ルールを適用：
   • stateDiagram-v2 構文を使用する
   • 状態 ID：Draft、Submitted、Processing、Completed、Failed
   • 条件付きの遷移ラベルを使用する（引用符は使わない）
5. テンプレートから作成：状態図テンプレートを使用する
6. 検証：Mermaid Live Editor でテストする

結果：

stateDiagram-v2
    [*] --> Draft
    Draft --> Submitted: User clicks Submit
    Submitted --> Processing: Payment verified
    Processing --> Completed: All items shipped
    Processing --> Failed: Payment declined
    Completed --> [*]
    Failed --> Draft: Retry allowed
    Failed --> [*]: Max retries exceeded

よくあるパターン

判断フローパターン

flowchart TD
    Input[Receive Input] --> Validate{Validate Input}
    Validate -->|Invalid| Reject["Reject with Error<br/>Return 400"]
    Validate -->|Valid| Process[Process Request]
    Process --> Output[Return Success]

複数ソース統合パターン

flowchart TD
    User[User Query] --> Router{Query Router}

    Router -->|Database| SQL[SQL Connector]
    Router -->|Cache| Redis[Redis Connector]
    Router -->|API| External[External API]

    SQL --> Merge[Merge Results]
    Redis --> Merge
    External --> Merge

    Merge --> Response[Formatted Response]
    Response --> User

エラー処理パターン

flowchart TD
    Start[Start Process] --> Try{Execute}
    Try -->|Success| Complete[Complete Successfully]
    Try -->|Error| Retry{Retry Count < 3?}
    Retry -->|Yes| Wait[Exponential Backoff]
    Wait --> Try
    Retry -->|No| Failed["Failed<br/>Log and Alert"]

トラブルシューティングガイド

エラー：「Expecting 'SQE', got 'STR'」

• 原因： ノードラベル内の入れ子の引用符
• 修正： 内側の引用符を削除するか、ラベル全体を引用符で囲んでください

エラー：「Expecting 'SPACE', got 'AMP'」

• 原因： スタイル指定に特殊文字（&、/ など）が含まれています
• 修正方法： サブグラフの ID／ラベル構文を使用します：subgraph ID["Name"]

エラー：「Parse error on line X」

• 原因： 通常は引用符に関連する問題、または構文の誤りです
• 修正方法： 引用符の入れ子を確認し、ノード／エッジの構文を検証します

チャートが描画されない

• 原因： 無効なノード ID、参照の破損、または構文エラーです
• 修正方法： Mermaid Live Editor で検証し、ノード ID の一貫性を確認します

実際のドキュメントの例

アーキテクチャフロー（ADR パターン）

flowchart TD
    User[User: Submit command] -->|1. Classify| Detector{Command Detector<br/>GPT-4 + Rules}

    Detector -->|Query| QueryPath[Execute Immediately]
    Detector -->|Command| SafetyPath[Safety Validation]

    SafetyPath -->|Check| Circuit{Circuit Breaker Status}
    Circuit -->|Active| Block["Block Command<br/>Display Reason"]
    Circuit -->|Inactive| Execute[Execute Command]

    Execute -->|Log| Audit[WORM Audit Storage]
    Execute -->|Response| User

    subgraph SafetyControls["Safety Controls"]
        Detector
        Circuit
        Audit
    end

    style User fill:#e1f5ff
    style SafetyControls fill:#fff4e1

データパイプラインフロー

flowchart LR
    Source[Data Source] -->|Ingest| Process[Processing Pipeline]

    Process -->|Transform| Transform[Transform Layer<br/>Validate & Clean]
    Transform -->|Load| Storage[(Data Warehouse)]

    Storage -->|Query| Analytics[Analytics Service]
    Analytics -->|Visualize| Dashboard[Dashboard UI]

    subgraph Pipeline["Data Pipeline"]
        Process
        Transform
    end

    style Pipeline fill:#f0f0f0

クイックリファレンスカード

要素	構文	例
ノード（長方形）	ID[Label]	Node1[Process Data]
ノード（角丸）	ID(Label)	Start(Begin Process)
ノード（データベース）	ID[(Label)]	DB[(PostgreSQL)]
ノード（円形）	ID((Label))	Point((A))
判断	ID{Label}	Check{Is Valid?}
矢印	-->	A --> B
ラベル付き矢印	-- text --> または `-->	text
サブグラフ	subgraph ID["Label"]	subgraph Sys["System"]
スタイル	style ID fill:#color	style Node1 fill:#e1f5ff
コメント	%% comment	%% This is a note
改行	ラベル内の <br/>	Node["Line 1<br/>Line 2"]

出力形式

生成される成果物

mermaid-gen スキルを使用する場合、主な出力は次のとおりです。

Mermaid 図のコードブロック：

• 形式：mermaid 言語識別子を指定した Markdown コードブロック
• 内容：構文的に有効な Mermaid 図のコード
• 検証：納品前に Mermaid Live Editor でテスト済み
• 構成：コメント、スタイル、適切なノード／エッジ構文を含みます

出力例：

```mermaid
flowchart TD
    %% Define nodes
    Start[Start Process] --> Process[Execute Task]
    Process --> End[Complete]

    %% Apply styling
    style Start fill:#e1f5ff
    style End fill:#c8e6c9
```

charts-flow スキルとの連携

スキル間の関係：

• mermaid-gen：構文的に正しい図のコードを作成します
• charts-flow：図のコードを受け取り、ファイル作成、SVG 生成、ドキュメントへの埋め込みを管理します

一般的なワークフロー：

1. ユーザーがドキュメント用の図をリクエストします
2. ファイル管理のために charts-flow スキルを呼び出します
3. charts-flow が図の生成のために mermaid-gen を内部で呼び出します
4. mermaid-gen が検証済みの Mermaid コードを返します
5. charts-flow が図のファイルを作成し、SVG を生成して、親ドキュメントに埋め込みます

単独での使用： ユーザーが図のコードのみを必要とする場合（ファイル管理は不要）：

• mermaid-gen を直接呼び出します
• 図のコードブロックを返します
• ユーザーが手動でドキュメントに埋め込みます

組み合わせての使用： ユーザーが図ファイルの作成ワークフロー全体を必要とする場合：

• charts-flow スキルを呼び出します（内部で mermaid-gen を使用します）
• 図のファイル、SVG、親ドキュメントの更新を返します

出力検証チェックリスト

mermaid-gen の出力はすべて、次の基準を満たす必要があります。

• ✅ Mermaid Live Editor でエラーなく描画される
• ✅ ラベル内に引用符の入れ子がない
• ✅ サブグラフ ID がスタイル参照と一致している
• ✅ すべてのノード ID が一意である
• ✅ コメントで複雑なセクションを説明している
• ✅ プロジェクトの命名規則に従っている

プロジェクトワークフローとの連携

他のスキルとの関係

charts-flow スキル：

• 目的：図ファイルの管理、SVG 生成、ドキュメントへの埋め込み
• 連携：図の内容を生成するために mermaid-gen を呼び出します
• 用途：diagrams/ サブディレクトリに個別の図ファイルを作成します

doc-flow スキル：

• 目的：仕様駆動開発ワークフロー（BRD → PRD → ADR → SYS → SPEC）
• 連携：mermaid-gen で作成した図は、ADR、SYS ドキュメント、アーキテクチャ仕様をサポートします
• 用途：ADR ドキュメントやシステム仕様にアーキテクチャ図を追加します

project-mngt スキル：

• 目的：MVP／MMP／MMR の実装計画
• 連携：図を使って、プロジェクトの依存関係や実装フローを可視化します
• 用途：ガントチャート形式のタイムラインや依存関係グラフを作成します（Mermaid が対応している場合）

ドキュメント標準との整合性

技術ガイドライン（CLAUDE.md に準拠）：

• マーケティング的な表現ではなく、技術的な実装に焦点を当てます
• コスト最適化を考慮します（軽量な SVG 形式）
• パフォーマンスを重視します（レンダリングを高速化するため、図を個別のファイルに分けます）
• セキュリティを考慮します（図に実行可能なコードを含めません）

ベストプラクティスの適用：

• 構文の正確性には mermaid-gen を使用します
• ファイル管理とパフォーマンスの最適化には charts-flow を使用します
• ノード ID にはプロジェクトの命名規則に従います
• バージョン管理にコミットする前に、すべての図を検証します

バージョン

• バージョン： 1.0
• 最終更新日： 2025-11-05
• 教訓の参照元： ADR アーキテクチャフロー図の修正

関連ドキュメント

• Mermaid 公式ドキュメント
• Mermaid ライブエディター
• GitHub の Mermaid サポート