mermaid-graph-writer

Mermaid グラフライター

正確で構造の整った Mermaid 図を作成します。内容に最適な図の種類を選び、正しい構文を使用して、人間（レンダリング後）とエージェント（テキスト DSL）の両方が読みやすい図を生成します。

---

使用する場面

✅ 次の用途に使用します：

• 説明やデータをもとに Mermaid 図を作成する
• 可視化の目的に合った図の種類を選ぶ
• 文章で書かれた意思決定ツリーを Mermaid フローチャートに書き換える
• システムアーキテクチャ、プロトコル、状態機械、データモデルをモデル化する
• 時系列の知識をタイムライン図として表現する

❌ 次の用途には使用しません：

• Mermaid を PNG／SVG／PDF にレンダリングまたはエクスポートする（mermaid-graph-renderer を使用）
• ASCII アートや Unicode の罫線による図を作成する（diagramming-expert を使用）
• GUI ベースのデザインツール（Figma など）

---

図の種類の選択

flowchart TD
  A{What are you modeling?} -->|Branching logic| B[flowchart]
  A -->|Request/response over time| C[sequenceDiagram]
  A -->|States and transitions| D[stateDiagram-v2]
  A -->|Entities and relationships| E[erDiagram]
  A -->|Chronological evolution| F[timeline]
  A -->|Concept hierarchy| G[mindmap]
  A -->|Time-sequenced tasks| H[gantt]
  A -->|Proportions| I[pie]
  A -->|2-axis comparison| J[quadrantChart]
  A -->|Branch/merge history| K[gitGraph]
  A -->|Type hierarchy / OO| L[classDiagram]
  A -->|User experience steps| M[journey]
  A -->|Quantity flows| N[sankey-beta]
  A -->|Numeric data| O[xychart-beta]
  A -->|System components| P[block-beta]
  A -->|Infrastructure| Q[architecture-beta]
  A -->|Task board| R[kanban]
  A -->|Requirements traceability| S[requirementDiagram]
  A -->|System context / containers| T[C4Context]
  A -->|Protocol packets / headers| U[packet-beta]
  A -->|Multi-axis comparison| V[radar]
  A -->|Hierarchical proportions| W[treemap]
  A -->|Code-style sequences| X[zenuml]

クイックリファレンス

内容	種類	方向
意思決定ツリー／プロセス	flowchart TD	意思決定には上から下、プロセスには左から右
API プロトコル／エージェント間通信	sequenceDiagram	常に垂直（暗黙）
ライフサイクル／状態機械	stateDiagram-v2	自動レイアウト
データベース／データモデル	erDiagram	自動レイアウト
「いつ何が変わったか」	timeline	水平方向の時系列
分類体系／ブレインストーミング	mindmap	ルートから放射状
プロジェクトスケジュール	gantt	水平方向のタイムライン
カテゴリの比率	pie	円形
労力と効果	quadrantChart	2D 散布図
Git のブランチ戦略	gitGraph	水平方向
クラス／インターフェースの階層	classDiagram	自動レイアウト
満足度を含むユーザーフロー	journey	水平方向のセクション
カテゴリ間のフロー量	sankey-beta	左から右へのフロー
棒グラフ／折れ線グラフ	xychart-beta	標準的な軸
システムのブロックレイアウト	block-beta	グリッドベース
クラウド／インフラのトポロジー	architecture-beta	サービスをグループ化
タスクのステータス列	kanban	列ベース
要件のトレーサビリティ	requirementDiagram	自動レイアウト
システムコンテキスト／コンテナ	C4Context / C4Container	レイヤー構造（5 つのサブタイプ）
プロトコルのパケット／ヘッダー	packet-beta	水平方向のビットレイアウト
複数軸によるスコアリング	radar	放射状の軸
階層的な比率	treemap	入れ子の長方形
コード形式のシーケンス	zenuml	垂直方向（プラグイン）

---

フローチャートの詳細（最も一般的）

方向

• TD / TB — 上から下（意思決定ツリーに最適）
• LR — 左から右（プロセスやパイプラインに最適）
• BT — 下から上（まれ。依存関係グラフ向け）
• RL — 右から左（まれ）

ノードの形状

[text]       Rectangle (default action)
(text)       Rounded rectangle (soft step)
{text}       Diamond (decision/condition)
([text])     Stadium/pill (start/end)
[[text]]     Subroutine (subprocess)
[(text)]     Cylinder (database/storage)
((text))     Circle (event/trigger)
>text]       Flag (async/signal)
{{text}}     Hexagon (preparation)
[/text/]     Parallelogram (input/output)
[\text\]     Reverse parallelogram
[/text\]     Trapezoid
[\text/]     Reverse trapezoid

エッジのスタイル

-->          Solid arrow (main flow)
---          Solid line (association)
-.->         Dotted arrow (optional/async)
==>          Thick arrow (emphasis/critical path)
--text-->    Labeled edge
~~~          Invisible link (layout control only)

サブグラフ

flowchart TD
  subgraph Backend
    A[API] --> B[DB]
  end
  subgraph Frontend
    C[UI] --> D[State]
  end
  C -->|fetch| A

---

シーケンス図の基本

メッセージ

->>    Solid arrow (sync request)
-->>   Dotted arrow (async response)
-)     Open arrow (async fire-and-forget)
-x     Cross (failed/rejected)

ブロック

activate / deactivate    Lifeline activation
alt / else / end         Conditional branching
loop / end               Repetition
par / and / end          Parallel execution
critical / end           Critical section
break / end              Break-out flow
rect rgb(...)  / end     Background highlight

番号付け

最初の行の後に autonumber を追加すると、すべてのメッセージに自動で番号が付きます。

---

状態図の基本

[*] --> State1           Start transition
State1 --> State2        Named transition
State1 --> State2: event Labeled transition
State2 --> [*]           End transition

state State1 {          Nested states
  [*] --> SubA
  SubA --> SubB
}

state fork <<fork>>      Fork pseudostate
state join <<join>>      Join pseudostate
state choice <<choice>>  Choice pseudostate

---

ER 図の基本

多重度

||--||    Exactly one to exactly one
||--o{    One to zero-or-many
}o--o{    Zero-or-many to zero-or-many
||--|{    One to one-or-many

属性

erDiagram
  USER {
    int id PK
    string name
    string email UK
  }
  ORDER {
    int id PK
    int user_id FK
    date created_at
  }
  USER ||--o{ ORDER : places

---

作成の原則

1. コードではなく、内容がわかるラベルを使う

• ✅ A[Check if tests pass]
• ❌ A[Step 2.3]

2. 方向を統一する

図全体で方向を統一します。同じフローチャート内で TD と LR を混在させないでください。

3. ノードは最大 15 個にする

15 個を超える場合は、複数の図に分割するか、サブグラフを使用します。図がごちゃごちゃしているより、図がないほうがましです。

4. グループ化にはサブグラフを使う

図に自然なまとまり（フロントエンド／バックエンド、フェーズ、チームなど）がある場合は、サブグラフを使って視覚的にグループ化します。

5. 意思決定エッジにはすべてラベルを付ける

ひし形（{decision}）ノードから出るすべてのエッジにラベルを付ける必要があります。

• ✅ A{Ready?} -->|Yes| B と A -->|No| C
• ❌ A{Ready?} --> B と A --> C（どちらが「はい」で、どちらが「いいえ」ですか？）

6. 適切なエッジのスタイルを使う

• メインのフローには実線の矢印
• 任意／非同期の経路には点線の矢印
• 重要な経路や強調箇所には太い矢印
• 不可視リンク（~~~）はレイアウトの調整にのみ使用

---

アンチパターン

誤った図の種類

初心者: プロトコル、状態機械、データモデルまで、あらゆる用途にフローチャートを使います。 エキスパート: 内容の構造に合った図の種類を選びます。プロトコルにはシーケンス図、ライフサイクルには状態図、データモデルにはER図を使います。それぞれの図の種類があるのは、フローチャートではその構造をうまく表現できないためです。

図が複雑すぎる

初心者: 30個のノードと交差するエッジを含む図を1つだけ作ります。 エキスパート: 概要図と詳細図に分けます。サブグラフを使います。図あたりのノード数は最大約15個にします。

判断のエッジにラベルがない

初心者: {Decision} --> A と {Decision} --> B — どの条件でどちらに進むのでしょうか？ エキスパート: 判断のひし形から伸びるエッジには、必ずラベルを付けます。-->|Yes| と -->|No|（または -->|Success| と -->|Failure| など）を使います。

図にすべき説明文

初心者: 「まずXかどうかを確認します。XならAを実行し、そうでなければBを実行します。次に、Aが成功したらCを実行し、そうでなければAを再試行します。」 エキスパート: これはフローチャートにすべきです。フローチャートで表しましょう。正式なグラフのほうが正確で、読みやすくなります。

---

参考資料

• references/diagram-types.md — 23種類すべてのMermaid図（タイムライン、マインドマップ、象限図、サンキー図、XYチャート、ブロック図、アーキテクチャ図、カンバン図、円グラフ、Gitグラフ、クラス図、ジャーニー図、requirementDiagram、C4（5つのサブタイプ）、packet-beta、レーダーチャート、ツリーマップ、zenuml）について、包括的な構文、機能、例を参照してください。
• scripts/validate_mermaid.py — 任意のファイル内のMermaid構文を検証します。図の種類の宣言、フェンスの対応、構造上の正しさを確認します。