mermaid-diagram-specialist

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/loop ブロックが正しく使用されている

出力: シーケンス図

ステップ 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 ダイアグラム

Step 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 アーキテクチャ図

Step 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

検証:

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

出力: 状態図

Step 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. グループ化: subgraph を使って関連する要素をまとめる
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 ノード未満に抑える
• 関連するノードをまとめるには subgraph を使う
• コミット前に対象プラットフォームでレンダリングをテストする
• 図のソースは画像ではなく Markdown ファイルに保存する
• 図もコードと一緒にバージョン管理する
• コードレビュー中に図を更新する

---