mermaid-diagram

Mermaid 図の生成

ユーザーの要件に基づいて高品質な Mermaid 図のコードを生成し、ファイルに出力して検証します。

定数

• OUTPUT_DIR = figures/ — 生成したすべてのファイルの出力先ディレクトリ
• MAX_ITERATIONS = 3 — 構文エラーの修正を行う最大回数

ワークフロー：すべてのステップを必ず実行してください

Step 0: 事前確認

# Create output directory
mkdir -p figures

Step 1: 要件の把握と図の種類の選択

入力を解析します：$ARGUMENTS

1. ユーザーの説明を分析し、最適な図の種類を判断します
2. 該当する構文リファレンスドキュメントを読みます（以下の Step 2 を参照）
3. 図に数学的な表記（数式、方程式、ギリシャ文字、下付き文字、上付き文字、分数、行列など）が含まれる場合は、以下の 図での数式 セクションに記載された数式構文ルールを適用します
4. すべての構成要素、接続、データフローを特定します
5. 図の構造を計画します

Step 2: ドキュメントを読む

ユースケースに基づいて適切な図の種類を選択します。Mermaid 構文に関する組み込みの知識を使用するか、必要に応じて context7 MCP サーバー経由で最新のドキュメントを取得します。

種類	用途
フローチャート	プロセス、判断、手順
シーケンス図	インタラクション、メッセージング、API 呼び出し
クラス図	クラス構造、継承、関連
状態図	ステートマシン、状態遷移
ER 図	データベース設計、エンティティ間の関係
ガントチャート	プロジェクト計画、タイムライン
円グラフ	比率、分布
マインドマップ	階層構造、ナレッジグラフ
タイムライン	歴史的な出来事、マイルストーン
Git グラフ	ブランチ、マージ、バージョン
四象限チャート	四象限分析
要件図	要件のトレーサビリティ
C4 図	システムアーキテクチャ（C4 モデル）
サンキー図	フロー、変換
XY チャート	折れ線グラフ、棒グラフ
ブロック図	システムコンポーネント、モジュール
パケット図	ネットワークプロトコル、データ構造
カンバン	タスク管理、ワークフロー
アーキテクチャ図	システムアーキテクチャ
レーダーチャート	多次元比較
ツリーマップ	階層データの可視化
ユーザージャーニー	ユーザー体験のフロー
ZenUML	シーケンス図（コード形式）

設定とテーマ

• テーマ設定 - カスタムの色とスタイル
• ディレクティブ - 図レベルの設定
• レイアウト - レイアウトの方向と間隔
• 設定 - グローバル設定
• 数式 - LaTeX 数式のサポート（以下の「図での数式」セクションを参照）

Step 3: Mermaid コードを生成してファイルに保存

リファレンス仕様に従って Mermaid コードを生成し、次の 2 つのファイルを保存します。

File 1: figures/<diagram-name>.mmd — Mermaid ソースそのもの

.mmd ファイルには Mermaid コードのみを記述します（Markdown のコードフェンスは不要です）。例：

flowchart TD
    A[Start] --> B{Condition}
    B -->|Yes| C[Execute]
    B -->|No| D[End]
    C --> D

File 2: figures/<diagram-name>.md — Mermaid を埋め込んだ Markdown

.md ファイルには、プレビュー表示用の Mermaid コードブロックとタイトル、説明を含めます。例：

# Diagram Title

Brief description of what this diagram shows.

​```mermaid
flowchart TD
    A[Start] --> B{Condition}
    B -->|Yes| C[Execute]
    B -->|No| D[End]
    C --> D
​```

命名規則：ユーザーのリクエストに基づき、内容がわかる kebab-case の名前を使用します（例：auth-flow、system-architecture、database-er）。

Step 4: Mermaid 構文を検証する（必須）

Claude は Mermaid CLI（mmdc）を実行して、生成した Mermaid コードを必ず検証してください。

# Check if mermaid-cli is available
if command -v mmdc &> /dev/null; then
    # Render to PNG to verify syntax is correct
    mmdc -i figures/<diagram-name>.mmd -o figures/<diagram-name>.png -b transparent \
        && echo "✅ Syntax valid — PNG rendered to figures/<diagram-name>.png"
else
    # Try npx as fallback
    npx -y @mermaid-js/mermaid-cli@latest -i figures/<diagram-name>.mmd -o figures/<diagram-name>.png -b transparent \
        && echo "✅ Syntax valid — PNG rendered to figures/<diagram-name>.png"
fi

検証に失敗した場合：

1. エラーメッセージを注意深く読みます
2. .mmd ファイルと .md ファイルの両方で構文の問題を修正します
3. 検証を再実行します
4. MAX_ITERATIONS（3）回まで繰り返します

Step 5: Claude による厳格な目視レビューとスコアリング（必須）

レンダリングに成功した後、Claude は生成された PNG を必ず読み込み、厳格にレビューしてください。

## Claude's STRICT Review of <diagram-name>

### What I See
[Describe the rendered diagram in DETAIL - every block, every arrow, every label]

### Files Generated
- `figures/<diagram-name>.mmd` — Raw Mermaid source
- `figures/<diagram-name>.md` — Markdown with embedded diagram
- `figures/<diagram-name>.png` — Rendered PNG (if mmdc available)

### ═══════════════════════════════════════════════════════════════
### STRICT VERIFICATION CHECKLIST (ALL must pass for score ≥ 9)
### ═══════════════════════════════════════════════════════════════

#### A. File Correctness
- [ ] `.mmd` file contains valid Mermaid syntax (no markdown fences)
- [ ] `.md` file has the mermaid code wrapped in ```mermaid``` fences
- [ ] `.mmd` and `.md` contain IDENTICAL Mermaid code
- [ ] Diagram renders without errors (via mmdc)

#### B. Arrow Correctness Verification (CRITICAL - any failure = score ≤ 6)
Check EACH arrow:
- [ ] Arrow 1: [Source] → [Target] — Does it point to the CORRECT target?
- [ ] Arrow 2: [Source] → [Target] — Does it point to the CORRECT target?
- [ ] ... (check ALL arrows)

#### C. Block Content Verification (any failure = score ≤ 7)
Check EACH block/node:
- [ ] Block 1 "[Name]": Has correct label? Content correct?
- [ ] Block 2 "[Name]": Has correct label? Content correct?
- [ ] ... (check ALL blocks)

#### D. Completeness
- [ ] All components from user requirements are present
- [ ] All connections/arrows are correct
- [ ] Node labels are meaningful and match requirements

#### E. Visual Quality
- [ ] Layout is clean and readable
- [ ] Color scheme is professional (not rainbow)
- [ ] Text is readable at normal zoom
- [ ] Proper spacing (not cramped, not sparse)
- [ ] Data flow is traceable in 5 seconds

### ═══════════════════════════════════════════════════════════════

### Issues Found (BE SPECIFIC)
1. [Issue 1]: [EXACTLY what is wrong] → [How to fix]
2. [Issue 2]: [EXACTLY what is wrong] → [How to fix]

### Score: X/10

### Score Breakdown Guide:
- **10**: Perfect. No issues. Publication-ready.
- **9**: Excellent. Minor issues that don't affect understanding.
- **8**: Good but has noticeable issues (layout, styling).
- **7**: Usable but has clear problems (wrong arrows, missing labels).
- **6**: Has arrow direction errors or missing major components.
- **1-5**: Major issues. Unacceptable.

### Verdict
[ ] ACCEPT (score ≥ 9 AND all critical checks pass)
[ ] FIX (score < 9 OR any critical check fails — list EXACT fixes needed)

FIX の場合：両方の .mmd ファイルと .md ファイルに修正を適用し、再レンダリングして再検証します。ACCEPT となるか、MAX_ITERATIONS に達するまで繰り返してください。

Step 6: 最終出力の概要

承認されたら、ユーザーに次の内容を提示します。

✅ Mermaid diagram generated successfully!

Files:
  figures/<diagram-name>.mmd  — Raw Mermaid source (use with mmdc, editors, CI)
  figures/<diagram-name>.md   — Markdown preview (renders on GitHub, VS Code, etc.)
  figures/<diagram-name>.png  — Rendered image (if mmdc was available)

To re-render manually:
  mmdc -i figures/<diagram-name>.mmd -o figures/<diagram-name>.png

アーキテクチャ図のベストプラクティス

architecture-beta 図を生成する際は、複雑な図に次のレイアウト手法を適用してください。

レイアウト制御にはジャンクションを使用する

図を目に見えないグリッドとして考えてください。junction ノードをグリッド上の仮想アンカーポイントとして使用すると、各コンポーネントの配置を正確に制御できます。これは、2 つのサービス間を直接エッジで結ぶと予期しない配置になる場合に特に便利です。

サービスを直接接続する代わりに：

lb:R --> L:scim
lb:R --> L:webapi

ジャンクションを経由させて、垂直・水平方向の配置を制御します。

junction j_lb_r
lb:R -- L:j_lb_r
junction j_scim_l
j_lb_r:T -- B:j_scim_l
j_scim_l:R --> L:scim
junction j_webapi_l
j_lb_r:B -- T:j_webapi_l
j_webapi_l:R --> L:webapi

コンポーネントの四方すべてにジャンクションを配置し、グリッド上で論理的に固定してください。

グループの外にエッジを出して、コンポーネントを浮かせる

他のノードとの論理的な接続がないサービス（デプロイツールや監視エージェントなど）には、ジャンクションと {group} 修飾子を組み合わせて使用します。これにより、意味的に誤ったエッジを追加せずに配置できます。

junction j_acd_t
j_algolia_proc_b{group}:B -- T:j_acd_t
j_acd_t:B -- T:acd

これにより、実際の関係を示唆することなく、acd を想定する隣の要素の下に固定できます。

CVPR/ICLR/NeurIPS スタイルガイド（学術図向け）

学術論文に掲載する図では、次のスタイル基準を適用してください。

ビジュアル基準

• すっきりとした白い背景 — 装飾的なパターンやグラデーションは使用しません（控えめなものを除く）。
• サンセリフフォント — Arial、Helvetica、または Computer Modern を使用し、最小サイズは 14pt とします。
• 控えめなカラーパレット — 虹色は避け、調和の取れた 3～5 色を使用します。
• 印刷に適した表示 — グレースケールでも読めるようにします（多くの査読者は論文を印刷します）。
• プロフェッショナルな枠線 — 細め（2～3px）で、単色かつ派手でないものにします。

レイアウト基準

• 水平方向の流れ — パイプラインでは左から右への配置が標準です。
• 明確なグループ化 — 関連するモジュールは、控えめな背景ボックスでまとめます。
• 一貫したサイズ — 類似するコンポーネントは、同じようなサイズにします。
• バランスの取れた余白 — 詰め込みすぎず、空きすぎないようにします。

矢印の基準（最も重要）

• 太い線 — 最低 4～6px とします（細い矢印は印刷すると見えなくなります）。
• 明確な矢印の先端 — 大きく塗りつぶされた三角形にします。
• 濃い色 — 黒または濃いグレー（#333333）を使用し、色付きの矢印は避けます。
• ラベル付き — すべての矢印に、どのデータが流れるかを示します。
• 交差なし — 矢印が交差しないようにレイアウトを再編成します。
• 正しい方向 — 矢印は正しい対象を指す必要があります。

カラーパレット（学術用途向け）

• 入力：緑（#10B981 / #34D399）
• エンコーダー：青（#2563EB / #3B82F6）
• 融合：紫（#7C3AED / #8B5CF6）
• 出力：オレンジ（#EA580C / #F97316）
• 矢印：黒または濃いグレー（#333333 / #1F2937）
• 背景：純白（#FFFFFF）

避けるべきもの

• 虹色の配色（色数が多すぎます）
• 細い線の矢印
• 強いドロップシャドウや発光効果
• 3D 効果や遠近法
• 装飾アイコンの多用
• 印刷すると読めなくなる小さな文字

図での数式（KaTeX）

Mermaid は KaTeX（v10.9.0 以降）による数式表現のレンダリングをサポートしています。図に数式（公式、方程式、ギリシャ文字、下付き文字・上付き文字、分数、行列、演算子など）が含まれる場合は、プレーンテキストで近似せず、KaTeX 表記を使用してください。

数式に対応している図の種類

$$...$$ を使った数式のレンダリングは、次の形式に対応しています。

• フローチャート（flowchart / graph） — ノードラベルとエッジラベル
• シーケンス図 — 参加者の別名、メッセージ、注釈

構文ルール

1. 引用符で囲んだ文字列内で、数式を $$ の区切り文字で囲みます。

   A["$$x^2$$"] -->|"$$\sqrt{x+3}$$"| B("$$\frac{1}{2}$$")
   

2. 数式を含むノードラベルは、必ず引用符で囲みます — ["$$...$$"] または ("$$...$$") を使用します。

   scaledDot["$$\text{softmax}\left(\frac{QK^T}{\sqrt{d_k}}\right)V$$"]
   

3. テキストと数式を混在させる場合は、数式部分だけを $$ で囲みます。

   layer1["Linear Layer $$W_1 x + b_1$$"]
   

4. $$ ブロック内の数式以外のテキストには、\text{} を使用します。

   node["$$\text{Attention}(Q, K, V)$$"]
   

ML／科学系ダイアグラムでよく使う数学表記

概念	KaTeX 構文	表示例
下付き文字	$$W_Q$$	W_Q
上付き文字	$$x^2$$	x²
分数	$$\frac{QK^T}{\sqrt{d_k}}$$	QK^T / sqrt(d_k)
ギリシャ文字	$$\alpha, \beta, \gamma$$	α, β, γ
平方根	$$\sqrt{d_k}$$	√d_k
総和	$$\sum_{i=1}^{n} x_i$$	Σx_i
行列	$$\begin{bmatrix} a & b \\ c & d \end{bmatrix}$$	2x2 行列
ソフトマックス	$$\text{softmax}(z_i)$$	softmax(z_i)
ノルム	$$||x||_2$$	‖x‖₂
ハット／チルダ	$$\hat{y}, \tilde{x}$$	ŷ, x̃

例：数学表記を使ったアテンション機構

flowchart TD
    Q["$$Q \in \mathbb{R}^{n \times d_k}$$"]
    K["$$K \in \mathbb{R}^{n \times d_k}$$"]
    V["$$V \in \mathbb{R}^{n \times d_v}$$"]
    scores["$$\frac{QK^T}{\sqrt{d_k}}$$"]
    softmax["$$\text{softmax}(\cdot)$$"]
    output["$$\text{Attention}(Q,K,V)$$"]

    Q --> scores
    K --> scores
    scores --> softmax
    softmax --> weighted["$$\alpha V$$"]
    V --> weighted
    weighted --> output

数学表記とプレーンテキストの使い分け

• 数学表記を使う：ダイアグラムの対象が学術・技術分野の読者で、正確さが重要な場合（論文、講義、技術文書）
• プレーンテキストを使う：一般向けのダイアグラムの場合や、明瞭さが増さず見た目が煩雑になる場合（改行には<br/>を使用）
• デフォルトの動作：ユーザーのリクエストに数学表記、数式、ギリシャ文字が含まれている場合は、KaTeX 数式レンダリングを自動的に使用します。それ以外の場合は、プレーンテキストのラベルを使用します。

注意点

• $$ 区切り文字は引用符で囲まれた文字列の中に置く必要があります。引用符で囲まれていない $$ は解析エラーの原因になります。
• KaTeX 内のバックスラッシュ（\frac、\sqrt など）は、Mermaid の文字列内で通常どおり機能します。
• 非常に長い数式はノードのボックスからはみ出すことがあります。\\（KaTeX での改行）を使って分割するか、簡略化してください。
• 必ず mmdc でレンダリングを確認してください。一部の KaTeX 表現は環境によってレンダリングされない場合があります。

コード品質ルール

生成する Mermaid コードは、以下の条件を必ず満たす必要があります。

1. そのままレンダリングできる正しい構文にする
2. 適切な改行とインデントで、明確な構造にする
3. 意味がわかるノード名を使う（A、B、C ではなく、authServer、userDB などを使う）
4. 見た目を改善する必要がある場合は、スタイルを含める
5. ノードラベル内の改行には<br/>を使う。リテラルテキストとして表示される\nは使用しない
6. Mermaid の解析を妨げる特殊文字をラベルに使用しない（必要に応じて引用符で囲む）

出力構成

figures/
├── <diagram-name>.mmd    # Raw Mermaid source (no markdown fences)
├── <diagram-name>.md     # Markdown with embedded mermaid block
└── <diagram-name>.png    # Rendered PNG (if mmdc available)

重要なルール（必ず守ること）

1. ファイルは必ずfigures/ディレクトリに保存する — チャットにコードを出力するだけにしない
2. .mmdファイルと.mdファイルの両方を必ず生成する — 両方に同一の Mermaid コードを含める
3. ダイアグラムの種類に応じたコードを生成する前に、必ず参照ドキュメントを読む
4. 構文を必ず確認する — mmdc を実行するか、手動で検証してから受け入れる
5. レンダリングされた PNG を必ず確認する — 画像を読み込み、厳密に採点する
6. スコアが9未満のものは絶対に受け入れない — 優れた品質になるまで改善を続ける
7. 矢印の向きをすべて確認する — 向きが間違っていれば自動的に不合格（スコア≤6）
8. ブロックの内容をすべて確認する — 内容が間違っていれば自動的に不合格（スコア≤7）
9. フィードバックは具体的にする — 「矢印が間違っている」ではなく、「A から B への矢印の向きが間違っている」と伝える
10. 受け入れる前にエラーを修正する — 壊れたダイアグラムを納品しない
11. 説明的なファイル名を付ける — ダイアグラムの内容に基づいた kebab-case を使う

---

ユーザーの要件：$ARGUMENTS