Mermaid ダイアグラミング

Mermaid のテキストベースの構文を使用して、プロフェッショナルなソフトウェアダイアグラムを作成します。Mermaid はシンプルなテキスト定義からダイアグラムをレンダリングするため、ダイアグラムをバージョン管理可能にし、更新が容易で、コードと共に保守できます。

コア構文構造

すべての Mermaid ダイアグラムは次のパターンに従います:

diagramType
  definition content

主な原則:

• 最初の行でダイアグラムの種類を宣言します (classDiagram、sequenceDiagram、flowchart など)
• コメントには %% を使用します
• 改行とインデントは可読性を向上させますが、必須ではありません
• 不明な単語はダイアグラムを破壊します。パラメータはサイレントに失敗します

ダイアグラムタイプ選択ガイド

適切なダイアグラムタイプを選択してください:

1. クラスダイアグラム - ドメインモデリング、OOP設計、エンティティ関係

   • ドメイン駆動設計のドキュメンテーション
   • オブジェクト指向クラス構造
   • エンティティ関係と依存関係

2. シーケンスダイアグラム - 時系列インタラクション、メッセージフロー

   • API リクエスト/レスポンスフロー
   • ユーザー認証フロー
   • システムコンポーネント間のインタラクション
   • メソッド呼び出しシーケンス

3. フローチャート - プロセス、アルゴリズム、決定木

   • ユーザージャーニーとワークフロー
   • ビジネスプロセス
   • アルゴリズムロジック
   • デプロイメントパイプライン

4. エンティティリレーションシップダイアグラム (ERD) - データベーススキーマ

   • テーブル関係
   • データモデリング
   • スキーマ設計

5. C4 ダイアグラム - 複数レベルでのソフトウェアアーキテクチャ

   • システムコンテキスト (システムとユーザー)
   • コンテナ (アプリケーション、データベース、サービス)
   • コンポーネント (内部構造)
   • コード (クラス/インターフェースレベル)

6. ステートダイアグラム - ステートマシン、ライフサイクルの状態

7. Git グラフ - バージョン管理のブランチング戦略

8. ガントチャート - プロジェクトタイムライン、スケジューリング

9. 円グラフ/棒グラフ - データ可視化

クイックスタート例

クラスダイアグラム (ドメインモデル)

classDiagram
    Title -- Genre
    Title *-- Season
    Title *-- Review
    User --> Review : creates

    class Title {
        +string name
        +int releaseYear
        +play()
    }

    class Genre {
        +string name
        +getTopTitles()
    }

シーケンスダイアグラム (API フロー)

sequenceDiagram
    participant User
    participant API
    participant Database

    User->>API: POST /login
    API->>Database: Query credentials
    Database-->>API: Return user data
    alt Valid credentials
        API-->>User: 200 OK + JWT token
    else Invalid credentials
        API-->>User: 401 Unauthorized
    end

フローチャート (ユーザージャーニー)

flowchart TD
    Start([User visits site]) --> Auth{Authenticated?}
    Auth -->|No| Login[Show login page]
    Auth -->|Yes| Dashboard[Show dashboard]
    Login --> Creds[Enter credentials]
    Creds --> Validate{Valid?}
    Validate -->|Yes| Dashboard
    Validate -->|No| Error[Show error]
    Error --> Login

ERD (データベーススキーマ)

erDiagram
    USER ||--o{ ORDER : places
    ORDER ||--|{ LINE_ITEM : contains
    PRODUCT ||--o{ LINE_ITEM : includes

    USER {
        int id PK
        string email UK
        string name
        datetime created_at
    }

    ORDER {
        int id PK
        int user_id FK
        decimal total
        datetime created_at
    }

詳細リファレンス

特定のダイアグラムタイプについての詳しいガイダンスは、以下を参照してください:

• references/class-diagrams.md - ドメインモデリング、関係 (関連、合成、集約、継承)、多重度、メソッド/プロパティ
• references/sequence-diagrams.md - アクター、参加者、メッセージ (同期/非同期)、アクティベーション、ループ、alt/opt/par ブロック、ノート
• references/flowcharts.md - ノード形状、接続、判定ロジック、サブグラフ、スタイリング
• references/erd-diagrams.md - エンティティ、関係、カーディナリティ、キー、属性
• references/c4-diagrams.md - システムコンテキスト、コンテナ、コンポーネントダイアグラム、境界
• references/architecture-diagrams.md - クラウドサービス、インフラストラクチャ、CI/CD デプロイ
• references/advanced-features.md - テーマ、スタイリング、設定、レイアウトオプション

ベストプラクティス

1. シンプルなものから始める - コアエンティティ/コンポーネントから始めて、詳細を段階的に追加します
2. 意味のある名前を使用する - 明確なラベルはダイアグラムを自己説明的にします
3. 広範にコメントする - %% コメントを使用して複雑な関係を説明します
4. フォーカスを保つ - 1 つのダイアグラムに 1 つの概念。大きなダイアグラムは複数のフォーカスされたビューに分割します
5. バージョン管理 - .mmd ファイルをコードと共に保存して、簡単に更新できます
6. コンテキストを追加する - タイトルとノートを含めてダイアグラムの目的を説明します
7. 反復する - 理解が進むにつれてダイアグラムを洗練させます

設定とテーマ

フロントマターを使用してダイアグラムを設定します:

---
config:
  theme: base
  themeVariables:
    primaryColor: "#ff6b6b"
---
flowchart LR
    A --> B

利用可能なテーマ: default, forest, dark, neutral, base

レイアウトオプション:

• layout: dagre (デフォルト) - クラシックバランスレイアウト
• layout: elk - 複雑なダイアグラム用の高度なレイアウト (統合が必要)

ルックオプション:

• look: classic - 従来の Mermaid スタイル
• look: handDrawn - スケッチのような外観

エクスポートとレンダリング

ネイティブサポート:

• GitHub/GitLab - Markdown で自動的にレンダリング
• VS Code - Markdown Mermaid 拡張機能
• Notion, Obsidian, Confluence - ビルトインサポート

エクスポートオプション:

• Mermaid Live Editor - PNG/SVG エクスポート機能付きのオンラインエディター
• Mermaid CLI - npm install -g @mermaid-js/mermaid-cli その後 mmdc -i input.mmd -o output.png
• Docker - docker run --rm -v $(pwd):/data minlag/mermaid-cli -i /data/input.mmd -o /data/output.png

よくある落とし穴

• 破壊文字 - コメント内で {} を避ける。特殊文字には適切なエスケープシーケンスを使用します
• 構文エラー - スペルミスはダイアグラムを破壊します。Mermaid Live で構文を検証します
• 過度な複雑さ - 複雑なダイアグラムは複数のフォーカスされたビューに分割します
• 関係の欠落 - エンティティ間のすべての重要な接続をドキュメント化します

ダイアグラムを作成すべき時

常にダイアグラムを作成する場合:

• 新しいプロジェクトまたはフィーチャーを開始する場合
• 複雑なシステムをドキュメント化する場合
• アーキテクチャの決定を説明する場合
• データベーススキーマを設計する場合
• リファクタリングの取り組みを計画する場合
• 新しいチームメンバーをオンボーディングする場合

ダイアグラムを使用して:

• 技術的な決定について関係者を一致させる
• ドメインモデルを協力的にドキュメント化する
• データフローとシステムインタラクションを可視化する
• コーディング前に計画する
• コードとともに進化するリビングドキュメンテーションを作成する