mermaid-diagram-generator

Mermaid 図生成スキル

目的

このスキルは、システムアーキテクチャ、モジュール仕様、ワークフロー文書、設計コンセプトのテキストによる説明を、有効な Mermaid 図の構文に自動変換します。複雑なシステムを明確に視覚化し、図を本番環境で利用できる状態にして、Markdown 文書に埋め込めるようにします。

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

• アーキテクチャの視覚化：アーキテクチャの説明をフローチャートやブロック図に変換します
• モジュール間の関係：ブリックモジュールがスタッド（公開コントラクト）を介してどのように接続されるかを示す図を作成します
• ワークフローの文書化：ワークフローの状態、判断、遷移（DDD のフェーズ、調査段階）を視覚化します
• システム設計：システムのコンポーネント、データフロー、相互作用を表示します
• シーケンス図：エージェント間の相互作用、リクエスト／レスポンスのパターン、呼び出しシーケンスを示します
• クラス階層：モジュール構造とクラス間の関係を文書化します
• 状態機械：ワークフローの状態と有効な遷移をモデル化します
• エンティティ関係：データモデルの構造と関係を表示します
• タイムライン計画：プロジェクトのフェーズやマイルストーンをガントチャートで作成します

対応する図の種類

1. フローチャート（デフォルト）

最適な用途：ワークフローの手順、決定木、プロセスフロー、モジュール間の関係

flowchart TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Action A]
    B -->|No| D[Action B]
    C --> E[End]
    D --> E

2. シーケンス図

最適な用途：エージェント間の相互作用、API 呼び出し、複数ステップのプロセス、リクエスト／レスポンスのパターン

sequenceDiagram
    participant User
    participant API
    participant Service
    User->>API: Request
    API->>Service: Process
    Service-->>API: Response
    API-->>User: Result

3. クラス図

最適な用途：モジュール構造、継承階層、データモデル、コンポーネント間の関係

classDiagram
    class Brick {
        +String responsibility
        +PublicContract studs
    }
    class Module {
        +init()
        +process()
    }
    Brick <|-- Module

4. 状態図

最適な用途：ワークフローの状態、状態機械、ワークフローのフェーズ、条件に基づく遷移

stateDiagram-v2
    [*] --> Planning
    Planning --> Design
    Design --> Implementation
    Implementation --> Testing
    Testing --> [*]

5. エンティティ関係図

最適な用途：データモデル、データベーススキーマ、エンティティ間の関係

erDiagram
    MODULE ||--o{ FUNCTION : exports
    MODULE ||--o{ DEPENDENCY : requires
    FUNCTION }o--|| CONTRACT : implements

6. ガントチャート

最適な用途：プロジェクトのタイムライン、ワークフローのフェーズ、マイルストーンの計画

gantt
    title Project Timeline
    section Phase 1
    Planning :p1, 0, 30d
    Design :p2, after p1, 20d
    section Phase 2
    Implementation :p3, after p2, 40d
    Testing :p4, after p3, 25d

ステップごとの生成プロセス

ステップ 1：ソース資料を理解する

1. アーキテクチャの説明、仕様書、またはワークフロー文書を読みます
2. 主なエンティティまたはノードを特定します
3. それらの関係や流れを判断します
4. 適切な図の種類を選びます

ステップ 2：図の種類を特定する

ソース資料	最適な図の種類
ワークフローの手順、プロセスフロー	フローチャート
モジュール間の関係、ブリックの接続	フローチャートまたはクラス図
エージェント間の相互作用、呼び出しシーケンス	シーケンス図
状態と遷移	状態図
データモデル、エンティティ	クラス図または ERD
データベーススキーマ	ERD
プロジェクトのタイムライン	ガントチャート
複雑な階層	クラス図

ステップ 3：エンティティと関係を抽出する

1. ソースからすべてのノード／エンティティを列挙します
2. それらの間の接続を特定します
3. 接続の種類（データフロー、継承、呼び出しなど）を判断します
4. 判断箇所や条件があれば記録します

ステップ 4：Mermaid 構文を生成する

1. 適切な Mermaid 図の宣言を使用します
2. 説明的なラベルを付けてノードを作成します
3. 適切な構文で接続を描画します
4. 明確にする必要があればスタイルを追加します
5. Mermaid の構文が有効であることを確認します

ステップ 5：検証して改善する

1. すべてのエンティティが含まれていることを確認します
2. 接続が正確であることを検証します
3. 重要な要素にスタイルを追加します
4. 図を読みやすくし、煩雑にならないようにします
5. 構文が有効であることをテストします

ステップ 6：文書化して埋め込む

1. タイトルと説明を追加します
2. 図の説明を含めます
3. 必要であれば凡例を用意します
4. 適切な書式で Markdown に埋め込みます

使用例

例 1：アーキテクチャの説明からフローチャートを作成する

入力：

The authentication module handles JWT token validation. When a request arrives,
it first checks if a token exists. If not, it returns unauthorized. If it does,
it validates the token signature. If valid, it extracts the payload and continues.
If invalid, it returns forbidden. The payload is passed to the authorization
module for role-based access control.

出力：

flowchart TD
    A[Request Arrives] --> B{Token Exists?}
    B -->|No| C[Return Unauthorized]
    B -->|Yes| D{Token Valid?}
    D -->|No| E[Return Forbidden]
    D -->|Yes| F[Extract Payload]
    F --> G[Check Role-Based Access]
    G --> H{Authorized?}
    H -->|No| I[Return Access Denied]
    H -->|Yes| J[Allow Request]
    C --> K[End]
    E --> K
    I --> K
    J --> K

例 2：モジュール仕様からクラス図へ

入力：

Module: authentication
- Exports: validate_token, TokenPayload, AuthError
- Classes: TokenPayload (user_id, role, expires_at), AuthError (message, code)
- Functions: validate_token(token, secret) -> TokenPayload
- Internal: JWT (PyJWT library), Models (TokenPayload)

出力：

classDiagram
    class AuthenticationModule {
        +validate_token(token, secret)
        +TokenPayload
        +AuthError
    }
    class TokenPayload {
        +String user_id
        +String role
        +DateTime expires_at
        +to_dict()
    }
    class AuthError {
        +String message
        +Integer code
        +__str__()
    }
    AuthenticationModule -- TokenPayload
    AuthenticationModule -- AuthError

例 3：ワークフローから状態図へ

入力：

DDD Workflow: Phase 0 (Planning) -> Phase 1 (Documentation) ->
Approval Gate -> Phase 2 (Code Planning) -> Phase 3 (Implementation) ->
Phase 4 (Testing & Cleanup) -> Complete

出力：

stateDiagram-v2
    [*] --> Planning
    Planning --> Documentation
    Documentation --> ApprovalGate
    ApprovalGate --> CodePlanning
    CodePlanning --> Implementation
    Implementation --> Testing
    Testing --> [*]

例 4：エージェントのやり取りからシーケンス図へ

入力：

The prompt-writer agent clarifies requirements from the user. It then sends
the clarified requirements to the architect agent. The architect creates a
specification and sends it to the builder agent. The builder implements code
and sends it to the reviewer. The reviewer checks quality and sends feedback
back to the builder if issues are found, or to the user if complete.

出力：

sequenceDiagram
    actor User
    participant PromptWriter
    participant Architect
    participant Builder
    participant Reviewer

    User->>PromptWriter: Request Feature
    PromptWriter->>Architect: Clarified Requirements
    Architect->>Builder: Specification
    Builder->>Reviewer: Implementation
    Reviewer-->>Builder: Issues Found
    Builder->>Reviewer: Fixed Implementation
    Reviewer-->>User: Complete & Approved

例 5：システムアーキテクチャからフローチャートへ

入力：

Client requests flow through API Gateway to Services. Services can be
Authentication Service, User Service, or Data Service. All services
connect to a shared Database and Logger. Services return responses
through the API Gateway back to Client.

出力：

flowchart LR
    Client[Client]
    Gateway[API Gateway]
    Auth[Auth Service]
    User[User Service]
    Data[Data Service]
    DB[(Database)]
    Logger[Logger]

    Client <--> Gateway
    Gateway --> Auth
    Gateway --> User
    Gateway --> Data
    Auth --> DB
    User --> DB
    Data --> DB
    Auth --> Logger
    User --> Logger
    Data --> Logger

Mermaid 構文リファレンス

フローチャートのノード

A[Rectangle]
B(Rounded Rectangle)
C{Diamond/Decision}
D[(Database)]
E[/Parallelogram Right/]
F[\Parallelogram Left\]
G[[Subroutine]]
H((Circle))

フローチャートの接続

A --> B          # Arrow
A -- Text --> B  # Arrow with label
A ---|Yes| B     # Arrow with yes/no
A -->|Condition| B
A -.-> B         # Dotted line
A ==> B          # Bold arrow

スタイル設定

classDef className fill:#f9f,stroke:#333,stroke-width:2px,color:#000
class A,B className
style A fill:#f9f,stroke:#333,stroke-width:4px

品質チェックリスト

図を提示する前に、以下を確認してください。

• ソースに含まれるすべてのエンティティが含まれている
• 接続が関係を正確に表している
• 図の種類が内容に合っている（フローにはフローチャート、やり取りにはシーケンス図など）
• ラベルが明確で説明的である
• 循環ロジックや行き止まりがない（意図的な場合を除く）
• Mermaid の構文が有効である
• 図が読みやすく、複雑になりすぎていない
• 判断ポイントに明確な「はい／いいえ」の経路がある
• 理解に必要な場合は凡例がある
• わかりにくい要素にはコメントで説明がある

よくあるパターン

Brick モジュールの可視化

flowchart TD
    B1["Brick Module 1<br/>(Responsibility)"]
    B2["Brick Module 2<br/>(Responsibility)"]
    S1["Stud: public_function"]
    S2["Stud: public_class"]

    B1 --> S1
    B1 --> S2
    S1 -.depends on.-> B2
    B2 --> "Stud: get_data"

ワークフローの決定木

flowchart TD
    Start[Start] --> Q1{Condition 1?}
    Q1 -->|No| End1[End: Rejected]
    Q1 -->|Yes| Q2{Condition 2?}
    Q2 -->|No| End2[End: Review]
    Q2 -->|Yes| Q3{Condition 3?}
    Q3 -->|No| End3[End: Partial]
    Q3 -->|Yes| End4[End: Approved]

エラー処理フロー

flowchart TD
    A[Execute] --> B{Error?}
    B -->|No| C[Success]
    B -->|Yes| D{Recoverable?}
    D -->|No| E[Fail]
    D -->|Yes| F[Retry]
    F --> A
    C --> G[End]
    E --> G

ドキュメントとの統合

Markdown への埋め込み

## System Architecture

```mermaid
flowchart TD
    ...
```

主なコンポーネント：

• コンポーネント A は…を担当します
• コンポーネント B は…を処理します

### Using with Document-Driven Development
- Create diagrams during documentation phase
- Include architecture diagrams in spec docs
- Use sequence diagrams to explain workflows
- Add state diagrams to describe state machines

### Using with Investigation Workflow
- Visualize discovered architecture
- Show data flow between components
- Map discovered dependencies
- Display call sequences between services

## Tips for Effective Diagrams

1. **Keep It Simple**: One concept per diagram
2. **Use Clear Labels**: Names should describe purpose
3. **Follow Visual Conventions**: Diamonds for decisions, circles for states
4. **Avoid Crossing Lines**: Reorganize to reduce visual clutter
5. **Logical Flow**: Top-to-bottom or left-to-right
6. **Consistent Styling**: Similar elements should look similar
7. **Legend**: Include if symbols aren't obvious
8. **Test Syntax**: Ensure Mermaid renders without errors
9. **Add Comments**: Explain non-obvious relationships
10. **Iterate**: Refine based on feedback

## Common Pitfalls to Avoid

- **Too Complex**: Diagram has too many elements (break into multiple diagrams)
- **Unclear Labels**: Node names don't describe their purpose
- **Missing Connections**: Important relationships not shown
- **Invalid Syntax**: Mermaid errors prevent rendering
- **Ambiguous Decision Points**: Yes/no paths not clearly marked
- **Crossing Arrows**: Visual confusion from overlapping connections
- **No Legend**: Symbols or colors not explained
- **Wrong Diagram Type**: Using flowchart for sequence data
- **Inconsistent Style**: Different formatting for similar elements
- **No Context**: Diagram shown without explanation

## Success Criteria

A good Mermaid diagram:
- [ ] Shows all key entities from source material
- [ ] Accurately represents relationships and flow
- [ ] Uses appropriate diagram type for content
- [ ] Clear, descriptive labels on all nodes
- [ ] Valid Mermaid syntax (renders without error)
- [ ] Readable without excessive complexity
- [ ] Supports understanding of the system
- [ ] Could be embedded in documentation
- [ ] Decision points clearly marked
- [ ] Legend included if needed
- [ ] Purpose and scope clear from context

## Related Skills

- **module-spec-generator**: Generate specs that can be visualized as class diagrams
- **Document-Driven Development**: Use diagrams in specification documents
- **Investigation Workflow**: Create architecture diagrams from discovered systems

## Output Format

Diagrams are generated in Mermaid markdown format, ready to embed:

```markdown
    ```mermaid
    [Generated Mermaid Syntax]
    ```

図の前後に説明を記載してください。

フィードバックと改善

このスキルは、使用パターンに基づいて進化します。

• 最も役立つ図の種類は何ですか？
• 図をより明確にする機能は何ですか？
• どのようなエラーが発生し、どうすれば防げますか？
• 図をドキュメントのサポートにさらに活用するにはどうすればよいですか？

学んだことを記録し、~/.amplihack/.claude/context/DISCOVERIES.md への改善案を提示してください。