mermaid

Mermaid

構造、フロー、関係、時間的な順序を Mermaid 図に整理することに特化しています。

デザインパターン

このスキルでは主に、以下のパターンを採用します。

• Generator：ユーザーの要望や既存のテキストに基づいて、Mermaid 図を直接生成します
• Reviewer：まず適切な図の種類を判断し、次に必要最小限の情報を補う必要があるか判断します

注意点

• 最初から flowchart と決めつけず、シーケンス図、状態図、ER 図、ガントチャートのほうが適しているかを先に判断します
• 段落の原文をそのままノードに詰め込まず、ノードのテキストは短く、ざっと読めるようにします
• 「情報を網羅する」ために図を詰め込みすぎないようにします。必要に応じて、図を2つに分けるようユーザーに提案します
• 明らかにレンダリングできない Mermaid コードを出力しないようにします。提出前に括弧、接続線、インデント、サブグラフの閉じ方を確認します
• flowchart で、ノードのテキストに /plan-ceo-review のようなスラッシュを含む文字列がある場合、E1[/plan-ceo-review<br/>CEO视角审视产品] とは書かず、E1["/plan-ceo-review"<br/>CEO视角审视产品] と書きます。そうしないと、構文エラーが起きやすくなります
• ユーザーが「Mermaid 図を描いて」とだけ言い、資料が少ない場合は、まず現状の情報に基づいて妥当な初稿を作成し、質問しすぎないようにします
• 要望の本質が Mermaid 構文による図ではなく「見栄えのよいイラストを作ること」である場合は、対応範囲を明確に伝えます

ワークフロー

このチェックリストをコピーして進捗を記録します。

绘图进度：
- [ ] 步骤 1：理解目标
- [ ] 步骤 2：选择图类型
- [ ] 步骤 3：抽取关键节点与关系
- [ ] 步骤 4：生成 Mermaid 代码
- [ ] 步骤 5：自查可读性与语法
- [ ] 步骤 6：交付并说明

Step 1: 目的を理解する

まず、ユーザーが伝えたい核心を判断します。

• フローの進行：ある事柄がどのような手順で進むか
• 構造の階層：システム、モジュール、組織、ページがどのように構成されているか
• インタラクションの時系列：役割やサービスがどのように相互に通信するか
• 状態の変化：オブジェクトがさまざまな状態間をどのように切り替わるか
• データの関係：エンティティとフィールドがどのように関連しているか
• プロジェクトの計画：タスク、時間、依存関係がどのように配置されているか
• ユーザー体験の経路：ユーザーが一連の体験の中でどのような行動を取り、何を感じるか

ユーザーから記事、提案書、PRD、議事録、口頭での説明が提示された場合は、まず「ノード＋関係＋順序／階層」に整理します。

Step 2: 図の種類を選択する

表現したい内容に基づいて、適切な図の種類を選択します。必要に応じて references/diagram-selection.md を参照します。

簡単な判断基準：

• 手順や分岐を示す：flowchart
• サービスや役割間の呼び出し順序を示す：sequenceDiagram
• 状態の切り替えを示す：stateDiagram-v2
• データベースやビジネスエンティティの関係を示す：erDiagram
• スケジュール、マイルストーン、依存関係を示す：gantt
• ユーザー体験のプロセスを示す：journey
• オブジェクトやモジュールの静的な関係を示す：classDiagram
• git ブランチの関係を示す：gitGraph

ユーザーが図の種類を指定している場合は、明らかに不適切な場合を除き、その指定を優先します。不適切な場合は、代替案を説明します。

Step 3: 重要なノードと関係を抽出する

生成前に、簡潔に構造化します。

• 重要なノードを3〜9個列挙します
• ノード間の主な関係（順序、包含、依存、呼び出し、状態遷移、所有）を明確にします
• 主な流れを残し、重要度の低い修飾語を削除します
• ノード名には、短い中国語または安定した英語の用語を優先して使います

1つの図に重要なノードが12個を超える場合は、優先して内容を簡潔にする、グループ分けする、または図を分けるよう提案します。

Step 4: Mermaid コードを生成する

特に指定がない限り、次のような fenced code block を直接出力します。

flowchart TD
    A[开始] --> B[分析需求]
    B --> C{选择图类型}
    C -->|流程| D[输出 flowchart]
    C -->|时序| E[输出 sequenceDiagram]

生成時は、以下のルールに従います。

• ノード ID は A、svc_api、user のように短く安定したものにします
• ノードの文言は読みやすさを重視し、ID は構文上の用途に限定します。混同しないようにします
• 1つの図では、1つの核心的な問いだけを表現します
• サブグラフ、注釈の方向、グループ分けは適切に使いますが、技巧を詰め込みすぎないようにします
• 特に指定がなければ、フローチャートの方向には TD を使います
• 判断による分岐を強調する場合は、ひし形の条件ノードを使います
• システムの境界を強調する場合は、subgraph を使います

Step 5: 読みやすさと構文を確認する

提出前に、少なくとも以下の点を確認します。

• 図の種類の宣言が正しいか
• ノード ID が重複していないか
• 接続線の構文が正しく閉じているか
• 文言が長すぎないか
• flowchart のノードテキストに / で始まるパスやコマンドが含まれる場合、表示テキストを引用符で囲んでいるか
• 意味のない交差線や重複ノードがないか
• 中国語の内容が Mermaid で安定して表示されるか

図が複雑な場合は、細部を充実させるよりも、まず「レンダリングできること＋理解できること」を優先します。

Step 6: 提出して説明する

通常、以下の内容を提出します。

1. Mermaid コードブロック
2. 図が何を表しているかについての一文
3. 図が複雑な場合は、任意の改善案を一文

ユーザーが「Mermaid コードだけ」と指定した場合は、余計な説明を付けません。

出力要件

• コピーして使える Mermaid の fenced code block を直接出力することを優先します
• ユーザーが既存のテキストを提示した場合、必要に応じて「これを〇〇図に整理します」と一文添えてから出力します
• ユーザーが構文の学習を明確に求めている場合を除き、長々とした Mermaid のチュートリアルを出力しません
• 判断に迷う場合は、まず動作する簡潔なバージョンを提示し、さらに詳細化できることを説明します

参考資料

• references/diagram-selection.md：図の種類の選び方と、よく使われる基本形