Communitygithub.com

spillwavesolutions/design-doc-mermaid

テキストやソースコードからMermaid図(フローチャート、シーケンス、クラス、ER、状態、C4、アーキテクチャ)を作成します。GitHub Wikiでデフォルト使用。図の作成、Mermaid生成、アーキテクチャ文書化、コードから図への変換を求められたときに使用します。PlantUMLは残りのタイプのみ。ConfluenceではPNG/SVGとコードフェンスの両方が必要です。

design-doc-mermaid とは?

Mermaid Architectは、テキストやソースコードから多様なMermaid図(フローチャート、シーケンス図、クラス図、ER図、状態遷移図、C4図、アーキテクチャ図など)を生成するAIエージェントスキルです。主にClaude CodeやCline等のAIエージェントで動作し、ユーザーのリクエスト意図を分析して適切な図のタイプを判断し、専門ガイドを読み込んで正確な図を生成します。GitHub WikiやConfluenceへの公開にも対応し、図の検証とエラー回復機能を備えたレジリエントワークフローを採用。さらに、Unicode記号による図の視覚的強化、Pythonスクリプトによる図の抽出・変換・検証、Spring BootやFastAPI、Reactなどのフレームワーク別のコード→図変換ガイドも提供します。

対応✓Claude Code~Codex CLI~Cursor✓Gemini CLI
npx skills add spillwavesolutions/design-doc-mermaid

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

プレビュー

スキル README より

説明
API シーケンス

ドキュメント

Mermaid Architect - 階層図とドキュメント生成スキル

Mermaid図とドキュメント生成システム。専門ガイドとコードから図への変換機能を備えています。

目次

決定木

このスキルの動作方法:

  1. ユーザーがリクエスト → スキルが意図を分析
  2. スキルが図/ドキュメントの種類を判断 → 適切なガイドを読み込み
  3. AIが専門ガイドを読み込み → テンプレートを使用して図/ドキュメントを生成
  4. 結果を出力 → 検証とエクスポートオプション付き

ユーザー意図分析:

flowchart TD
    Start([ユーザーリクエスト]) --> Analyze{意図を分析}

    Analyze -->|"ワークフロー、プロセス、ビジネスロジック"| Activity[アクティビティ図ガイドを読み込み<br/>references/guides/diagrams/activity-diagrams.md]
    Analyze -->|"インフラ、デプロイ、クラウド"| Deploy[デプロイ図ガイドを読み込み<br/>references/guides/diagrams/deployment-diagrams.md]
    Analyze -->|"システムアーキテクチャ、コンポーネント"| Arch[アーキテクチャガイドを読み込み<br/>references/guides/diagrams/architecture-diagrams.md]
    Analyze -->|"APIフロー、相互作用"| Sequence[シーケンス図ガイドを読み込み<br/>references/guides/diagrams/sequence-diagrams.md]
    Analyze -->|"クラス、ER、状態、wiki、ウォークスルー"| WikiGuide[WikiTicket GitHubガイドを読み込み<br/>references/guides/wiki-ticket-and-github.md]
    Analyze -->|"コードから図へ"| CodeToDiag[コード→図ガイドを読み込み<br/>references/guides/code-to-diagram/ + examples/]
    Analyze -->|"設計書、完全なドキュメント"| DesignDoc[設計書テンプレートを読み込み<br/>assets/*-design-template.md]
    Analyze -->|"unicode記号、アイコン"| Unicode[Unicode記号ガイドを読み込み<br/>references/guides/unicode-symbols/guide.md]
    Analyze -->|"抽出、検証、変換"| Scripts[Pythonスクリプトを使用<br/>scripts/extract_mermaid.py<br/>scripts/mermaid_to_image.py]

    Activity --> Generate[図を生成]
    Deploy --> Generate
    Arch --> Generate
    Sequence --> Generate
    WikiGuide --> Generate
    CodeToDiag --> Generate
    DesignDoc --> Generate
    Unicode --> Generate
    Scripts --> Execute[スクリプトを実行]

    Generate --> Validate{検証する?}
    Validate -->|はい| RunValidation[mmdc検証を実行]
    Validate -->|いいえ| Output
    RunValidation --> Output[結果を出力]
    Execute --> Output

    classDef decision fill:#FFD700,stroke:#333,stroke-width:2px,color:black
    classDef guide fill:#90EE90,stroke:#333,stroke-width:2px,color:darkgreen
    classDef action fill:#87CEEB,stroke:#333,stroke-width:2px,color:darkblue

    class Analyze,Validate decision
    class Activity,Deploy,Arch,Sequence,WikiGuide,CodeToDiag,DesignDoc,Unicode,Scripts guide
    class Generate,Execute,RunValidation,Output action

利用可能なガイドとリソース

図タイプ別ガイド (references/guides/diagrams/)

ガイドフルパスユーザーが求めたときに読み込む例
アクティビティ図references/guides/diagrams/activity-diagrams.mdワークフロー、プロセス、ビジネスロジック、ユーザーフロー、決定木"チェックアウトフローを表示", "ETLパイプラインを文書化", "承認ワークフローを作成"
デプロイ図references/guides/diagrams/deployment-diagrams.mdインフラ、クラウドアーキテクチャ、K8s、サーバーレス、ネットワークトポロジ"AWSアーキテクチャを表示", "GCPデプロイを文書化", "K8s図を作成"
アーキテクチャ図references/guides/diagrams/architecture-diagrams.mdシステムアーキテクチャ、コンポーネント設計、高レベル構造"システムコンポーネントを表示", "マイクロサービスを文書化", "アーキテクチャ概要"
シーケンス図references/guides/diagrams/sequence-diagrams.mdAPI相互作用、サービス間通信、リクエスト/レスポンスフロー"API呼び出しシーケンスを表示", "認証フローを文書化", "サービスの相互作用"
WikiTicket / GitHub / Confluencereferences/guides/wiki-ticket-and-github.md設計書、ウォークスルー、要件、Wiki公開、Confluence画像"アーキテクチャ文書", "コードウォークスルー", "wiki", "Confluence"

WikiTicketとGitHub Wikiのデフォルトはこのスキルです。classDiagram、erDiagram、stateDiagram-v2が含まれます。これらをPlantUMLに送信しないでください。GitHubでC4 / architecture-beta / block-betaのレンダリングに失敗した場合は、flowchart TDにフォールバックします。

コード→図ガイドと例

リソースフルパス提供内容
マスターガイドreferences/guides/code-to-diagram/README.md任意のコードベースを分析して図を抽出する完全なワークフロー
Spring Bootexamples/spring-boot/README.mdController→Service→Repositoryアーキテクチャ、デプロイ設定、メソッドからのシーケンス、ビジネスロジックからのアクティビティ
FastAPIexamples/fastapi/README.mdPython非同期パターン、Pydanticモデル、依存性注入、クラウドデプロイ
Reactexamples/react/README.mdコンポーネント階層、状態管理、データフロー、ビルドパイプライン
Python ETLexamples/python-etl/README.mdデータパイプライン、変換手順、エラーハンドリング、スケジューリング
Node/Expressexamples/node-webapp/README.mdミドルウェアチェーン、ルートハンドラー、非同期パターン、デプロイ
Java Webアプリexamples/java-webapp/README.md従来のMVC、サーブレットコンテナ、WARデプロイ

設計書テンプレート

テンプレートフルパス用途読み込み条件
アーキテクチャ設計assets/architecture-design-template.mdシステム全体のアーキテクチャ"アーキテクチャ文書を作成", "システム設計を文書化"
API設計assets/api-design-template.mdAPI仕様"API設計書", "REST APIを文書化"
機能設計assets/feature-design-template.md機能計画"機能設計", "新機能を計画"
データベース設計assets/database-design-template.mdデータベーススキーマ"データベース設計", "スキーマを文書化"
システム設計assets/system-design-template.md完全なシステム"システム設計書", "システム全体の文書化"

Unicode記号ガイド

フルパス: references/guides/unicode-symbols/guide.md

ユーザーが以下のようなことを言ったら読み込みます: "unicode記号", "図の中の絵文字", "意味アイコン", "記号を追加"

クイックリファレンス:

  • 📦 インフラ: ☁️ 🌐 🔌 📡 🗄️
  • ⚙️ 計算: ⚙️ ⚡ 🔄 ♻️ 🚀 💨
  • 💾 データ: 💾 📦 📊 📈 🗃️ 🧊
  • 📨 メッセージング: 📨 📬 📤 📥 🐰 📢
  • 🔐 セキュリティ: 🔐 🔑 🛡️ 🚪 👤 🎫
  • 📝 監視: 📝 📊 🚨 ⚠️ ✅ ❌

Pythonスクリプト (scripts/)

スクリプト用途読み込み条件
extract_mermaid.pyMarkdownから図を抽出、構文検証、画像に置換"図を抽出", "mermaidを検証", "すべての図を検索"
mermaid_to_image.py.mmdをPNG/SVGに変換、一括変換、カスタムテーマ"画像に変換", "図をレンダリング", "PNGを作成"
resilient_diagram.py完全ワークフロー:.mmd保存、画像生成、検証、エラー回復"図を生成", "検証付き図を作成", "レジリエント図"

GitHub Wiki、WikiTicket、Confluence

WikiTicketの設計書、コードウォークスルー、要件、GitHub Wiki、Confluenceにはreferences/guides/wiki-ticket-and-github.mdを読み込みます。

ターゲット提供するもの
GitHub Wiki / GFMフェンスで囲まれたmermaidブロック。GitHubはクラス、ER、状態、シーケンス、フローチャート、C4をレンダリングします。
Confluence / Notion / Word / PDFPNGまたはSVGもレンダリング(scripts/resilient_diagram.pyまたはmmdc)し、画像をアップロードします。ConfluenceがMermaidをレンダリングすることに依存しないでください。

PlantUMLは、Saltワイヤーフレーム、ユースケース、タイミング、ArchiMate、nwdiag、WBSに対してオプトインです。これらは常にPNGまたはSVGとして提供します。

使用方法パターン

一般的なリクエストパターンとガイドの選択。完全なマッピングについてはいつ何を使うかを参照してください。

パターンリクエスト例読み込むガイド
単一図"ログインフローのアクティビティ図を作成"図タイプガイド + Unicode記号
コード→図"application.ymlからデプロイ図を生成"フレームワーク例 + デプロイガイド
設計書"API設計書を作成"assets/からテンプレート + 該当する図ガイド
抽出/検証"design.mdから図を抽出"scripts/extract_mermaid.pyを使用
一括変換"すべての.mmdをPNGに変換"scripts/mermaid_to_image.pyを使用

レジリエントワークフロー

重要: これはすべての図生成で推奨されるアプローチです。検証、エラー回復、一貫性のあるファイル構成を保証します。

完全ガイド: references/guides/resilient-workflow.md

ワークフロー概要

flowchart LR
    A[1. タイプを特定] --> B[2. .mmd + 画像を保存]
    B --> C{3. 有効?}
    C -->|はい| D[4. Markdownに追加]
    C -->|いいえ| E[5. エラー回復]
    E --> F{修正見つかった?}
    F -->|はい| A
    F -->|いいえ| G[外部検索]
    G --> A

    classDef step fill:#90EE90,stroke:#333,color:darkgreen
    classDef decision fill:#FFD700,stroke:#333,color:black
    class A,B,D,E,G step
    class C,F decision

主要原則

検証に合格するまで、図をMarkdownに追加しないでください。 これにより、文書内の壊れた図を防ぎます。

スクリプトの使用(推奨)

# 完全なエラー回復で生成
python scripts/resilient_diagram.py \
    --code "flowchart TD; A-->B" \
    --markdown-file design_doc \
    --diagram-num 1 \
    --title "process_flow" \
    --format png \
    --json

出力: .mmdファイルと.pngファイルの両方が./diagrams/ディレクトリに生成されます。

ファイル命名規則

./diagrams/<markdown_file>_<num>_<type>_<title>.mmd
./diagrams/<markdown_file>_<num>_<type>_<title>.png

例: ./diagrams/api_design_01_sequence_auth_flow.png

エラー回復の優先順位

検証が失敗した場合、ワークフローは自動的に以下を実行します:

  1. トラブルシューティングガイドを確認 - references/guides/troubleshooting.md(28の文書化されたエラー)
  2. perplexityで検索 - perplexity_ask MCPで構文に関する質問
  3. braveで検索 - brave_web_search MCPで最近の解決策
  4. geminiに問い合わせ - geminiスキルで別の視点
  5. 一般検索 - WebSearchツールをフォールバックとして使用

手動フォールバック手順

スクリプトが使用できない場合:

  1. 最初の行から図のタイプを特定(flowchart, sequenceなど)
  2. リファレンスガイドを読み込む references/guides/diagrams/から
  3. 保存先: ./diagrams/<markdown_file>_<num>_<type>_<title>.mmd
  4. 検証: mmdc -i file.mmd -o file.png -b transparent
  5. エラー時: references/guides/troubleshooting.mdで一致するエラーを検索
  6. 見つからない場合: 上記の優先順位で検索ツールを使用
  7. 参照を追加: ![説明](./diagrams/filename.png)

パターン6: レジリエント図生成

ユーザー: "シーケンス図を作成して設計書に追加して"

スキルのアクション:

  1. 意図を特定: 図生成 + Markdown統合
  2. ワークフローガイドを読み込み: references/guides/resilient-workflow.md
  3. 図タイプを特定: シーケンス
  4. 図ガイドを読み込み: references/guides/diagrams/sequence-diagrams.md
  5. テンプレートを使用してMermaidコードを生成
  6. レジリエントワークフローを実行:
    python scripts/resilient_diagram.py \
        --code "[生成されたコード]" \
        --markdown-file design_doc \
        --diagram-num 1 \
        --title "api_sequence" \
        --json
    
  7. 検証が失敗した場合 → トラブルシューティング修正を適用 → 再試行
  8. 成功した場合 → ![API シーケンス](./diagrams/design_doc_01_sequence_api_sequence.png) をMarkdownに追加

Unicodeセマンティック記号

常にUnicode記号を使用して図の明確さを高めます。一般的なパターン:

インフラとデプロイ

graph TB
    Client[👤 ユーザー] --> LB[🌐 ロードバランサー]
    LB --> App1[⚙️ アプリサーバー1]
    LB --> App2[⚙️ アプリサーバー2]
    App1 --> DB[(💾 データベース)]
    App1 --> Cache[(⚡ Redis)]

状態付きアクティビティフロー

flowchart TD
    Start([🚀 開始]) --> Process[⚙️ データ処理]
    Process --> Check{✓ 有効?}
    Check -->|はい| Save[💾 保存]
    Check -->|いいえ| Error[❌ エラー]
    Save --> Complete([✅ 完了])

マイクロサービスアーキテクチャ

graph TB
    API[🌐 APIゲートウェイ] --> Auth[🔐 認証サービス]
    API --> Orders[📋 注文サービス]
    Orders --> Queue[📬 メッセージキュー]
    Queue --> Worker[⚙️ バックグラウンドワーカー]
    Worker --> Storage[📦 オブジェクトストレージ]

完全な記号リファレンスについては、次を読み込んでください: references/guides/unicode-symbols/guide.md

Pythonユーティリティ

Mermaid図の抽出

# すべての図を一覧表示
python scripts/extract_mermaid.py document.md --list-only

# 個別ファイルに抽出
python scripts/extract_mermaid.py document.md --output-dir diagrams/

# すべての図を検証
python scripts/extract_mermaid.py document.md --validate

# 画像参照に置換(Confluenceアップロード用)
python scripts/extract_mermaid.py document.md --replace-with-images \
  --image-format png --output-markdown output.md

画像に変換

# 単一変換
python scripts/mermaid_to_image.py diagram.mmd output.png

# カスタム設定
python scripts/mermaid_to_image.py diagram.mmd output.svg \
  --theme dark --background white --width 1200

# ディレクトリを一括変換
python scripts/mermaid_to_image.py diagrams/ output/ --format png --recursive

# 標準入力から
echo "graph TD; A-->B" | python scripts/mermaid_to_image.py - output.png

レジリエント図

# フルワークフロー
python scripts/resilient_diagram.py \
    --code "flowchart TD; A-->B" \
    --markdown-file design_doc \
    --diagram-num 1 \
    --title "process_flow" \
    --format png

# スタンドアロン
python scripts/resilient_diagram.py \
    --code "sequenceDiagram; A->>B: Hello" \
    --format svg

# 検証のみ
python scripts/resilient_diagram.py \
    --code "graph TD; A-->B" \
    --validate-only

テンプレートからの生成

# テンプレートを使用した新しい図
python scripts/generate_from_template.py \
    --template sequence_api \
    --output diagram.mmd \
    --title "ユーザー認証" \
    --actors "Client, Server, Database"

# 利用可能なテンプレートを一覧表示
python scripts/generate_from_template.py --list-templates

決定木の例

例1: システムアーキテクチャの文書化

ユーザー: "マイクロサービスアーキテクチャの図を作成して"

スキルのアクション:

  1. 意図を分析: システムアーキテクチャ
  2. ガイドを読み込み: アーキテクチャ図ガイド + Unicode記号ガイド
  3. 図を生成:
    graph TB
        subgraph "API層"
            GW[🌐 APIゲートウェイ]
        end
        subgraph "サービス"
            Auth[🔐 認証サービス]
            User[👤 ユーザーサービス]
            Order[📋 注文サービス]
        end
        subgraph "データ"
            SQL[(💾 Postgres)]
            NoSQL[(🗃️ MongoDB)]
            Cache[(⚡ Redis)]
        end
        GW --> Auth & User & Order
        Auth --> SQL
        User --> NoSQL
        Order --> Cache --> SQL
    
  4. 検証してファイルに保存

例2: CI/CDパイプライン

ユーザー: "デプロイパイプラインを文書化して"

スキルのアクション:

  1. 意図を分析: CI/CDワークフロー
  2. ガイドを読み込み: アクティビティ図ガイド + デプロイ図ガイド
  3. 図を生成:
    flowchart LR
        Dev[💻 開発] --> PR[📝 PR作成]
        PR --> CI[⚙️ CIビルド]
        CI --> Test[🧪 テスト]
        Test -->|合格| Stage[☁️ ステージング]
        Stage --> Approval[👁️ 承認]
        Approval -->|承認済み| Prod[🚀 本番]
        Test -->|不合格| Dev
    
  4. 検証してファイルに保存

ハイコントラストスタイリング

すべての図にアクセシブルなスタイリングを使用します。ハイコントラストスタイルの例:

flowchart TD
    Start([🚀 開始]) --> Node[処理]
    Node --> Decision{決定}
    Decision -->|オプション1| Success[✅ 成功]
    Decision -->|オプション2| Failure[❌ 失敗]

    classDef start fill:#4CAF50,stroke:#2E7D32,color:white
    classDef process fill:#2196F3,stroke:#1565C0,color:white
    classDef decision fill:#FF9800,stroke:#E65100,color:black
    classDef success fill:#4CAF50,stroke:#2E7D32,color:white
    classDef failure fill:#F44336,stroke:#B71C1C,color:white

    class Start start
    class Node process
    class Decision decision
    class Success success
    class Failure failure

アクセシブルな色の使用に関するガイドライン:

  • 緑: 成功、コンプリート、アクティブ状態
  • 青: プロセス、システム、ニュートラル
  • オレンジ: 決定、警告、注意
  • 赤: エラー、失敗、停止
  • テキストとの十分なコントラストを確保するために、常に濃い色のテキスト(白または黒)を使用

ファイル構成

project/
├── assets/
│   ├── architecture-design-template.md
│   ├── api-design-template.md
│   ├── feature-design-template.md
│   ├── database-design-template.md
│   └── system-design-template.md
├── examples/
│   ├── spring-boot/
│   │   └── README.md
│   ├── fastapi/
│   │   └── README.md
│   ├── react/
│   │   └── README.md
│   ├── python-etl/
│   │   └── README.md
│   ├── node-webapp/
│   │   └── README.md
│   └── java-webapp/
│       └── README.md
├── references/
│   ├── guides/
│   │   ├── diagrams/
│   │   │   ├── activity-diagrams.md
│   │   │   ├── deployment-diagrams.md
│   │   │   ├── architecture-diagrams.md
│   │   │   └── sequence-diagrams.md
│   │   ├── code-to-diagram/
│   │   │   └── README.md
│   │   ├── unicode-symbols/
│   │   │   └── guide.md
│   │   ├── wiki-ticket-and-github.md
│   │   ├── troubleshooting.md
│   │   └── resilient-workflow.md
│   └── examples/
├── scripts/
│   ├── extract_mermaid.py
│   ├── mermaid_to_image.py
│   ├── resilient_diagram.py
│   └── generate_from_template.py
└── diagrams/

ワークフローまとめ

ステップアクション使用ツール
1. 受信ユーザーリクエストを受け取る-
2. 分析意図を分析、図タイプを特定決定木
3. ガイド読み込み関連ガイドを読み込みファイルシステム
4. 生成Mermaidコードを生成AI + テンプレート
5. 保存.mmdファイルに保存scripts/resilient_diagram.py
6. 検証構文とレンダリングを確認mmdc + Pythonスクリプト
7. 修正必要に応じてエラーを修正トラブルシューティングガイド + 検索
8. 出力埋め込み画像とコードをMarkdownで提供最終ドキュメント

いつ何を使うか

図のタイプ

ユーザーが言ったこと図タイプガイド
"フローチャート", "ワークフロー", "プロセス", "フロー"flowchartアクティビティ図
"シーケンス", "相互作用", "APIコール"sequenceDiagramシーケンス図
"クラス図", "モデル", "エンティティ"classDiagramWikiTicketガイド
"ER図", "データベース", "リレーション"erDiagramWikiTicketガイド
"状態図", "ステートマシン", "状態"stateDiagram-v2WikiTicketガイド
"アーキテクチャ", "C4", "システム"C4Context/C4Containerアーキテクチャ図
"デプロイ", "インフラ", "クラウド"deploymentデプロイ図
"ガント", "タイムライン", "スケジュール"ganttアクティビティ図
"マインドマップ", "ブレインストーミング"mindmapアーキテクチャ図
"タイムライン", "履歴", "ロードマップ"timelineアクティビティ図
"Gitグラフ", "ブランチ", "コミット"gitGraphWikiTicketガイド
"円グラフ", "四分円", "データの視覚化"pie/quadrantChartアクティビティ図
"要件図", "要件", "依存関係"requirementDiagramアーキテクチャ図

PlantUMLに送信するもの

以下の場合のみPlantUMLを使用します(PNG/SVGとして送信):

タイプリクエスト例
Saltワイヤーフレーム"ワイヤーフレーム", "UIモックアップ"
ユースケース図"ユースケース", "アクター"
タイミング図"タイミング", "デジタルタイミング"
ArchiMate"ArchiMate", "エンタープライズアーキテクチャ"
nwdiag"ネットワーク図", "nwdiag"
WBS"WBS", "作業分割構成"

重要: 他のすべての図タイプはMermaidで処理してください。

ベストプラクティス

  1. 常に検証する: 追加前に図をレンダリング
  2. 明確なラベルを使用する: 各ノード/エッジには説明ラベルを付ける
  3. Unicode記号で強化する: ただし過度に使用しない(⚠️は重要)
  4. 一貫性を保つ: 同じプロジェクト内で同じスタイルと配色を使用
  5. 文書化する: 各図にその目的とコンテキストを説明するコメントを追加
  6. シンプルにする: 1つの図には5〜15個のノードが適切
  7. エラーから回復する: 失敗を診断して修正するためにレジリエントワークフローを使用
  8. 適切なものを使用する: 図のタイプはデータの性質に合わせる(プロセス用フローチャート、相互作用用シーケンス)

学習パス

  1. 初心者: 基本図(フローチャート、シーケンス、クラス)→ WikiTicketガイド
  2. 中級: コード→図変換、カスタムテーマ、一括エクスポート
  3. 上級: C4モデリング、レジリエントワークフロー、Pythonスクリプト自動化
  4. エキスパート: カスタムテンプレート、CI/CD統合、大規模文書生成

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

関連スキル