Mermaid ダイアグラム専門家

概要

目的: ドキュメント作成、アーキテクチャ可視化、プロセスマッピング用の包括的な Mermaid ダイアグラム作成の専門家

カテゴリ: Tech 主要ユーザー: tech-writer、architecture-validator、product-technical、tech-lead

このスキルを使用する場合

• アーキテクチャドキュメント作成
• ワークフローとプロセスの可視化
• データモデル (ERD) のドキュメント化
• シーケンスフローの説明
• ステートマシンの作成
• コンポーネント関係のドキュメント化
• デシジョンツリーの作成
• ユーザージャーニーの可視化

前提条件

必須:

• ドキュメント化するシステム/プロセスの理解
• 技術仕様書へのアクセス
• 必要なダイアグラムタイプの知識

オプション:

• 一貫性のための設計システムカラー
• 参照する既存ドキュメント

入力

スキルが必要とするもの:

• プロセス/システムの説明
• エンティティと関係性 (ERD 用)
• コンポーネント間相互作用 (シーケンス図用)
• アーキテクチャレイヤー (C4 ダイアグラム用)
• 状態と遷移 (ステート図用)

ワークフロー

ステップ 1: ダイアグラムタイプの選択

目的: 要件に適したダイアグラムタイプを選択

利用可能なダイアグラムタイプ:

1. フローチャート: デシジョンフロー、アルゴリズム、プロセス
2. シーケンス図: API 相互作用、メッセージフロー
3. ERD: データベーススキーマ、エンティティ関係
4. クラス図: オブジェクト指向設計
5. ステート図: ステートマシン、ライフサイクル
6. ガントチャート: プロジェクトタイムライン、スケジュール
7. C4 ダイアグラム: 異なるレベルのアーキテクチャ
8. 円グラフ/棒グラフ: データ可視化
9. Git グラフ: バージョン管理フロー
10. ユーザージャーニー: ユーザーエクスペリエンスフロー

決定マトリックス:

• デシジョン付きプロセス → フローチャート
• API/システム相互作用 → シーケンス図
• データベース構造 → ERD
• システムアーキテクチャ → C4 ダイアグラム
• オブジェクト関係 → クラス図
• 状態遷移 → ステート図
• プロジェクトタイムライン → ガントチャート

検証:

• ダイアグラムタイプがコンテンツに適している
• 複雑性が適切である
• 対象者が考慮されている
• 目的が明確である

出力: 選択されたダイアグラムタイプ

ステップ 2: フローチャート作成

目的: プロセスとデシジョンフロー図を作成

構文:

flowchart TD
    Start([Start]) --> Input[/User Input/]
    Input --> Validate{Valid?}
    Validate -->|Yes| Process[Process Data]
    Validate -->|No| Error[Show Error]
    Error --> Input
    Process --> Save[(Save to DB)]
    Save --> Success[/Success Response/]
    Success --> End([End])

ノード形状:

• [Rectangle] - プロセスステップ
• ([Rounded]) - 開始/終了
• {Diamond} - デシジョン
• [/Parallelogram/] - 入力/出力
• [(Database)] - データストレージ
• ((Circle)) - コネクタ

方向オプション:

• TD - トップダウン
• LR - 左から右
• BT - ボトムアップ
• RL - 右から左

例 - ブッキングフロー:

flowchart TD
    Start([User Initiates Booking]) --> CheckDates[Check Date Availability]
    CheckDates --> Available{Dates Available?}
    Available -->|No| ShowError[/Show Unavailable Message/]
    ShowError --> End([End])
    Available -->|Yes| CreateBooking[Create Pending Booking]
    CreateBooking --> Payment[Process Payment]
    Payment --> PaymentSuccess{Payment Success?}
    PaymentSuccess -->|No| CancelBooking[Cancel Booking]
    CancelBooking --> ShowError
    PaymentSuccess -->|Yes| ConfirmBooking[Confirm Booking]
    ConfirmBooking --> SendEmail[/Send Confirmation Email/]
    SendEmail --> SaveDB[(Save to Database)]
    SaveDB --> Success[/Show Success/]
    Success --> End

検証:

• すべてのパスがカバーされている
• デシジョンポイントが明確である
• 開始と終了が定義されている
• フロー方向が論理的である

出力: プロセスフローチャート

ステップ 3: シーケンス図作成

目的: API 相互作用とメッセージフローをドキュメント化

構文:

sequenceDiagram
    actor User
    participant Frontend
    participant API
    participant DB
    participant Payment

    User->>Frontend: Click "Book"
    Frontend->>API: POST /api/bookings
    API->>DB: Check availability
    DB-->>API: Available
    API->>Payment: Process payment
    Payment-->>API: Payment successful
    API->>DB: Create booking
    DB-->>API: Booking created
    API-->>Frontend: 201 Created
    Frontend-->>User: Show confirmation

参加者タイプ:

• actor - ユーザー
• participant - システム/サービス
• database - データベース

矢印タイプ:

• -> - 実線 (同期)
• --> - 点線 (レスポンス)
• ->> - 実矢印 (非同期メッセージ)
• -->> - 点矢印 (非同期レスポンス)

例 - 認証フロー:

sequenceDiagram
    actor User
    participant Frontend
    participant API
    participant Clerk
    participant DB

    User->>Frontend: Enter credentials
    Frontend->>Clerk: Login request
    Clerk->>Clerk: Validate credentials
    alt Credentials valid
        Clerk-->>Frontend: JWT token
        Frontend->>API: Request with token
        API->>Clerk: Verify token
        Clerk-->>API: Token valid
        API->>DB: Fetch user data
        DB-->>API: User data
        API-->>Frontend: User session
        Frontend-->>User: Logged in
    else Credentials invalid
        Clerk-->>Frontend: Auth error
        Frontend-->>User: Show error
    end

検証:

• すべての参加者が識別されている
• メッセージフローが論理的である
• 返信メッセージが表示されている
• Alt/ループブロックが正しく使用されている

出力: シーケンス図

ステップ 4: ERD 作成

目的: データベーススキーマと関係性をドキュメント化

構文:

erDiagram
    USER ||--o{ BOOKING : creates
    ACCOMMODATION ||--o{ BOOKING : "booked for"
    USER {
        uuid id PK
        string email UK
        string name
        timestamp created_at
    }
    BOOKING {
        uuid id PK
        uuid user_id FK
        uuid accommodation_id FK
        date check_in
        date check_out
        enum status
    }
    ACCOMMODATION {
        uuid id PK
        string name
        text description
        decimal price_per_night
    }

関係性タイプ:

• ||--|| - 1 対 1
• ||--o{ - 1 対多
• }o--o{ - 多対多
• ||--o| - 1 対 0 または 1

カーディナリティシンボル:

• || - 正確に 1
• o| - 0 または 1
• }o - 0 以上
• }| - 1 以上

例 - 完全な Hospeda ERD:

erDiagram
    USER ||--o{ BOOKING : creates
    USER ||--o{ REVIEW : writes
    USER ||--o{ ACCOMMODATION : owns
    ACCOMMODATION ||--o{ BOOKING : "has bookings"
    ACCOMMODATION ||--o{ REVIEW : "has reviews"
    ACCOMMODATION }o--o{ AMENITY : includes
    BOOKING ||--|| PAYMENT : "has payment"

    USER {
        uuid id PK
        string clerk_id UK
        string email UK
        string name
        enum role
        timestamp created_at
    }

    ACCOMMODATION {
        uuid id PK
        uuid owner_id FK
        string name
        text description
        decimal price_per_night
        int max_guests
        enum status
    }

    BOOKING {
        uuid id PK
        uuid user_id FK
        uuid accommodation_id FK
        date check_in
        date check_out
        int guests
        enum status
        decimal total_price
    }

    REVIEW {
        uuid id PK
        uuid user_id FK
        uuid accommodation_id FK
        int rating
        text comment
        timestamp created_at
    }

    PAYMENT {
        uuid id PK
        uuid booking_id FK
        string mercadopago_id UK
        decimal amount
        enum status
        timestamp processed_at
    }

    AMENITY {
        uuid id PK
        string name
        string icon
    }

検証:

• すべてのエンティティが定義されている
• 関係性が正確である
• カーディナリティが正しい
• プライマリキー/外部キーが標示されている

出力: ERD ダイアグラム

ステップ 5: C4 アーキテクチャダイアグラム

目的: 異なるレベルのシステムアーキテクチャをドキュメント化

コンテキストレベル (環境内のシステム):

C4Context
    title System Context - Hospeda Platform

    Person(guest, "Guest", "Tourist looking for accommodation")
    Person(owner, "Owner", "Accommodation owner")
    System(hospeda, "Hospeda Platform", "Tourism booking platform")

    System_Ext(clerk, "Clerk", "Authentication provider")
    System_Ext(mercadopago, "Mercado Pago", "Payment processor")
    System_Ext(email, "Email Service", "Transactional emails")

    Rel(guest, hospeda, "Searches and books", "HTTPS")
    Rel(owner, hospeda, "Manages listings", "HTTPS")
    Rel(hospeda, clerk, "Authenticates users", "API")
    Rel(hospeda, mercadopago, "Processes payments", "API")
    Rel(hospeda, email, "Sends notifications", "SMTP")

コンテナレベル (アプリケーションとデータストア):

C4Container
    title Container - Hospeda Platform

    Person(user, "User")

    Container(web, "Web App", "Astro + React", "Public-facing website")
    Container(admin, "Admin Panel", "TanStack Start", "Management interface")
    Container(api, "API", "Hono", "Backend services")
    ContainerDb(db, "Database", "PostgreSQL", "Stores all data")

    Rel(user, web, "Uses", "HTTPS")
    Rel(user, admin, "Manages", "HTTPS")
    Rel(web, api, "Calls", "JSON/HTTPS")
    Rel(admin, api, "Calls", "JSON/HTTPS")
    Rel(api, db, "Reads/Writes", "SQL")

コンポーネントレベル (内部構造):

C4Component
    title Components - API Application

    Container(api, "API", "Hono")

    Component(routes, "Routes", "Hono Router", "HTTP endpoints")
    Component(services, "Services", "Business Logic", "Domain operations")
    Component(models, "Models", "Data Access", "DB operations")
    Component(middleware, "Middleware", "Cross-cutting", "Auth, logging, errors")

    Rel(routes, middleware, "Uses")
    Rel(routes, services, "Calls")
    Rel(services, models, "Uses")
    Rel(models, db, "Queries")

検証:

• 適切なレベルが選択されている
• すべてのシステム/コンテナが表示されている
• 関係性が明確である
• 外部システムが識別されている

出力: C4 アーキテクチャダイアグラム

ステップ 6: ステート図作成

目的: ステートマシンとライフサイクルをドキュメント化

構文:

stateDiagram-v2
    [*] --> Pending
    Pending --> Confirmed : Payment Success
    Pending --> Cancelled : Payment Failed
    Pending --> Cancelled : User Cancels
    Confirmed --> CheckedIn : Check-in Date
    Confirmed --> Cancelled : Cancellation Request
    CheckedIn --> CheckedOut : Check-out Date
    CheckedOut --> Reviewed : User Submits Review
    CheckedOut --> [*] : 30 Days Elapsed
    Reviewed --> [*]
    Cancelled --> [*]

例 - ブッキングライフサイクル:

stateDiagram-v2
    [*] --> Draft : Create Booking

    state "Pending Payment" as Pending
    state "Payment Processing" as Processing

    Draft --> Pending : Submit Booking
    Pending --> Processing : Initiate Payment

    Processing --> Confirmed : Payment Approved
    Processing --> PaymentFailed : Payment Declined

    PaymentFailed --> Pending : Retry Payment
    PaymentFailed --> Cancelled : Max Retries

    Confirmed --> Active : Check-in Date Reached
    Active --> Completed : Check-out Date Reached

    Confirmed --> CancelRequested : Cancellation Request
    CancelRequested --> RefundProcessing : Approve Cancellation
    RefundProcessing --> Cancelled : Refund Complete

    Completed --> [*]
    Cancelled --> [*]

    note right of Confirmed
        Owner notified
        Calendar blocked
    end note

    note right of Completed
        Review requested
        Payment released
    end note

検証:

• すべての状態が定義されている
• 遷移が論理的である
• 開始/終了状態が標示されている
• 注釈が重要な状態を説明している

出力: ステート図

ステップ 7: スタイリングとカスタマイズ

目的: 一貫したスタイリングをダイアグラムに適用

テーマ適用:

%%{init: {'theme':'base', 'themeVariables': {
  'primaryColor':'#3B82F6',
  'primaryTextColor':'#fff',
  'primaryBorderColor':'#2563EB',
  'lineColor':'#6B7280',
  'secondaryColor':'#10B981',
  'tertiaryColor':'#F59E0B'
}}}%%
flowchart TD
    A[Start] --> B[Process]
    B --> C[End]

クラススタイリング:

flowchart TD
    A[Normal] --> B[Success]
    B --> C[Error]

    classDef successClass fill:#10B981,stroke:#059669,color:#fff
    classDef errorClass fill:#EF4444,stroke:#DC2626,color:#fff

    class B successClass
    class C errorClass

検証:

• 色がブランドに適している
• コントラストが十分である
• スタイリングが一貫している
• 両方のテーマで読める

出力: スタイル付きダイアグラム

出力

生成されるもの:

• Markdown 形式の Mermaid ダイアグラムコード
• 必要に応じて複数のダイアグラムタイプ
• スタイル設定およびテーマ付きダイアグラム
• ドキュメント対応のビジュアライゼーション

成功基準:

• ダイアグラムがシステムを正確に表現している
• すべての要素に適切なラベルが付いている
• 関係性が明確かつ正確である
• スタイリングがブランドと一貫している
• Markdown で正しくレンダリングされる

ベストプラクティス

1. シンプリシティ: ダイアグラムをフォーカスし、整然とした状態を保つ
2. ラベル: すべての要素に明確で説明的なラベルを付ける
3. 方向: 一貫したフロー方向 (通常はトップダウンまたは左から右)
4. グループ化: サブグラフを使用して関連要素をグループ化
5. 色: 重要な要素をハイライトするために色を使用
6. 注釈: 複雑なロジックを説明するために注釈を追加
7. レベル: 対象者に適した抽象化レベルを使用
8. 更新: ダイアグラムをコードと同期させたままにする
9. コメント: 保守性のために Mermaid コードにコメントを追加
10. テスト: ターゲットプラットフォームでダイアグラムがレンダリングされることを確認

一般的なパターン

API リクエストフロー

sequenceDiagram
    Client->>+API: GET /resource
    API->>+Service: fetchResource()
    Service->>+Model: findById()
    Model->>+DB: SELECT query
    DB-->>-Model: Row data
    Model-->>-Service: Entity
    Service-->>-API: DTO
    API-->>-Client: JSON response

エラーハンドリングフロー

flowchart TD
    Request[Incoming Request] --> Validate{Valid?}
    Validate -->|No| ValidationError[Validation Error]
    ValidationError --> ErrorHandler[Error Handler]
    Validate -->|Yes| Process[Process Request]
    Process --> DB{DB Success?}
    DB -->|No| DBError[Database Error]
    DBError --> ErrorHandler
    DB -->|Yes| Success[Success Response]
    ErrorHandler --> LogError[Log Error]
    LogError --> ErrorResponse[Error Response]

注釈

• Mermaid は GitHub、GitLab、Notion、およびほとんどの Markdown ビューアでレンダリングされます
• ライブエディタは mermaid.live で利用可能です
• 最大複雑性: 可読性のため 20 ノード未満に保つ
• 関連ノードのグループ化にはサブグラフを使用
• コミット前にターゲットプラットフォームでレンダリングをテスト
• ダイアグラムソースを画像ではなく Markdown ファイルに保存
• ダイアグラムをコードでバージョン管理
• コードレビュー中にダイアグラムを更新