mermaid

Mermaid

ユーザーのソース資料と意図に基づいて、妥当で構造の整った Mermaid 図を作成します。適切な図の種類を選び、読みやすさを保ち、フェンス付きの mermaid コードブロックで出力します。

参考ファイル

ファイル	読み込むタイミング
references/diagram-selection.md	デフォルト：適切な図の種類を選ぶとき。各種類の1行サンプルもあります
references/common-diagrams.md	フローチャート、シーケンス図、クラス図、状態図、ER 図、C4 図を作成するとき
references/specialized-diagrams.md	マインドマップ、ガントチャート、タイムライン、ジャーニー、gitGraph、円グラフ、クアドラント、要件図、xychart、サンキー図、ブロック図、アーキテクチャ図を作成するとき
references/generation-guidelines.md	あらゆる図で使用：ラベルの制限、構造ルール、ソースの種類別の方針、アンチパターン
references/styling-and-output.md	テーマ設定、classDef のスタイル設定、フロントマター設定、エクスポート、レンダリング先

ワークフロー

進捗を追跡するため、このチェックリストをコピーしてください。

Mermaid progress:
- [ ] Step 1: Pick diagram type
- [ ] Step 2: Gather source material
- [ ] Step 3: Draft structure
- [ ] Step 4: Generate Mermaid syntax
- [ ] Step 5: Validate
- [ ] Step 6: Present output

ステップ 1：図の種類を選ぶ

ユーザーが種類を指定した場合（例：「シーケンス図」）、その種類を使います。指定がない場合は、references/diagram-selection.md を読み込み、一覧表から選びます。一般的なデフォルトは次のとおりです。

内容	図
判断や分岐ロジックを含むプロセス	flowchart
時間の経過に伴うアクター／システム間のメッセージ	sequenceDiagram
状態と遷移（注文のライフサイクル、ワークフロー）	stateDiagram-v2
データベース／ドメインのエンティティと関係	erDiagram
階層別のシステムアーキテクチャ	C4Context / C4Container / C4Component
概念の階層、ブレインストーミング、概要	mindmap

2 種類が同じくらい適している場合に限り、ユーザーに確認してください。

ステップ 2：ソース資料を集める

トピックや仕様について、範囲が曖昧な場合（例：「概要ですか、詳細な内訳ですか？」）は、確認の質問を 1 つ行ってから作成を進めます。コードベース、ファイル、会話については、ノードと関係に名前を付けるのに必要なものだけを確認し、必要以上に調べないでください。

ステップ 3：構造を下書きする

構文を書く前に、図の骨組みを作成します。

• ノード／エンティティ／ステップを列挙します。
• 関係／メッセージ／遷移を列挙します。
• フローチャート、シーケンス図、状態図では開始と終了を特定します。ER 図、クラス図では多重度を特定します。C4 図では適切なレベルを選びます。
• references/generation-guidelines.md のサイズとラベルのルールを適用します。読みやすさを保つには、通常 5～20 個のノードが目安です。

ステップ 4：Mermaid 構文を生成する

選択した種類に該当する参考ファイルを開き、フェンス付きの mermaid コードブロック内に図を記述します。構文は最小限にし、スタイル設定はユーザーから依頼された場合にのみ追加します（references/styling-and-output.md を参照）。

ステップ 5：検証する

以下の共通チェックと、該当する参考ファイルにある種類別のチェックを実行します。失敗項目があれば修正し、再確認します。

共通チェック：

• 1 行目で正しい図の種類を宣言している（例：flowchart TD、sequenceDiagram）
• 通常のテキストラベル内に、エスケープされていない ()[]{} や余分なコロンがない
• 図のブロック内に空行がない（一部のレンダラーで問題が発生します）
• 必要な箇所では、参照されるすべてのノード／参加者／エンティティが使用前に定義されている
• 方向と流れに一貫性がある（上から下、または左から右のいずれかで、両方を混在させない）
• ラベルのテキストがレンダリングに十分短い（6 語未満を目安にします。種類別のルールを参照）
• 図の合計サイズが種類ごとの読みやすい上限内にある（フローチャート／クラス図は 15～20 個、マインドマップは最大 40 個）

ステップ 6：出力を提示する

フェンス付きの mermaid コードブロックで図を出力します。レンダリング先として、GitHub／GitLab の Markdown、Mermaid Live Editor（mermaid.live）、Notion、Obsidian、Mermaid プレビュー拡張機能を備えた VS Code を案内します。

ユーザーからファイルの作成を依頼された場合は、フェンス付きブロックを含む .md ファイルに書き込みます。画像へのエクスポートについては、Mermaid Live Editor または @mermaid-js/mermaid-cli を案内します（references/styling-and-output.md を参照）。

翻訳例

一般的なソース資料を図にする方法です。パターン：まず種類を特定し、次に名詞（ノード）と動詞（エッジ／遷移）を抽出します。

散文 → sequenceDiagram

ソース：「ユーザーがチェックアウトを実行します。サーバーはカートを検証し、在庫を確保して、Stripe に請求します。成功すると、注文が保存され、確認メールがキューに追加されます。」

sequenceDiagram
    actor User
    participant Server
    participant Stripe
    participant Email
    User->>+Server: POST /checkout
    Server->>Server: Validate cart
    Server->>Server: Reserve stock
    Server->>+Stripe: Charge
    Stripe-->>-Server: Success
    Server->>Server: Save order
    Server->>+Email: Queue confirmation
    Email-->>-Server: Queued
    Server-->>-User: 200 Order confirmed

仕様 → stateDiagram

ソース：「注文は Pending として開始します。支払いが成功すると Paid に移行し、失敗すると Cancelled に移行します。Paid の注文は発送され、その後完了します。Cancelled の注文は終端状態です。」

stateDiagram-v2
    [*] --> Pending
    Pending --> Paid : payment success
    Pending --> Cancelled : payment failed
    Paid --> Shipped : ship
    Shipped --> Completed : deliver
    Completed --> [*]
    Cancelled --> [*]

スコアリングマトリックス → quadrantChart

ソース：「キャンペーンをリーチ（低／高）とエンゲージメント（低／高）で評価します。A はリーチが高く、エンゲージメントは中程度です。B はリーチが低く、エンゲージメントも低いです。C はリーチとエンゲージメントがともに高いです。」

quadrantChart
    title Campaign reach vs engagement
    x-axis Low Reach --> High Reach
    y-axis Low Engagement --> High Engagement
    quadrant-1 Expand
    quadrant-2 Promote
    quadrant-3 Re-evaluate
    quadrant-4 Improve
    A: [0.8, 0.5]
    B: [0.2, 0.2]
    C: [0.8, 0.8]

アンチパターン

• すべてを1つの図に押し込むこと。代わりに、焦点を絞った複数の図に分けます。
• ラベルに文章を使うこと。キーワードを抽出するか、詳細を子ノードや注記に移します。
• 1つのコードフェンス内で2種類の図を混在させること（サポートされていません）。
• 描画先がサポートしていないアイコンや Font Awesome の参照を使うこと。
• 構造を検証する前に過度に装飾すること。
• 構文を推測すること。選択した種類のリファレンスファイルを読み込みます。

関連スキル

• 図を含むスライドデッキには presentation-creator
• ビジュアル図の範囲を超える詳細なアーキテクチャの決定には define-architecture
• 技術ドキュメントへの図の埋め込みには docs-writing