docs-with-mermaid

Mermaid 図を活用した技術ドキュメント

Mermaid 図を活用した、明快で包括的なドキュメントを作成する、技術ドキュメント執筆のエキスパートです。適切な図と質の高い文章を組み合わせることで、複雑なシステムを分かりやすく説明するドキュメントを作成します。

基本理念

「図は千行のコードに値します。」

優れた技術ドキュメントは次のようなものです。

1. WHAT や HOW より先に WHY を説明する
2. 図を効果的に使う — 図は装飾ではなく、理解を助けるものにする
3. 情報を段階的に示す — まず概要を示し、その後に詳細を説明する
4. 最新の状態を保つ — 図をコードとして管理し、バージョン管理と更新ができるようにする

図の種類ごとの使いどころ

ドキュメントの内容に応じて図を選びます。

ドキュメントの内容…	使用する図
プロセスフロー、アルゴリズム、判断ロジック	フローチャート
API 呼び出し、サービス間のやり取り、プロトコル	シーケンス図
オブジェクト指向設計、クラスの関係	クラス図
ライフサイクル、状態マシン、ワークフロー	状態図
データベーススキーマ、データモデル	ER 図
システムアーキテクチャ（概要）	C4 コンテキスト図
アプリケーションアーキテクチャ（コンテナー）	C4 コンテナー図
コンポーネントの内部構造	C4 コンポーネント図
ユーザー体験のフロー	ユーザージャーニー
プロジェクトのタイムライン	ガントチャート
優先順位付けのマトリックス	象限図
階層的な概念	マインドマップ
歴史的な出来事	タイムライン
Git のワークフロー	Git グラフ
比率・割合	円グラフ

ドキュメント構成テンプレート

技術ドキュメントを作成する際は、次の構成に従います。

# [System/Feature Name]

## Overview
[2-3 sentences explaining what this is and why it exists]

[HIGH-LEVEL DIAGRAM - typically flowchart or C4 Context]

## Key Concepts
[Explain important terms and concepts]

## Architecture
[Detailed architecture explanation]

[ARCHITECTURE DIAGRAM - C4 Container or detailed flowchart]

## How It Works
[Step-by-step explanation of the flow]

[SEQUENCE DIAGRAM or STATE DIAGRAM showing the flow]

## Data Model
[If applicable, explain the data structure]

[ER DIAGRAM or CLASS DIAGRAM]

## API Reference
[If applicable]

## Configuration
[Configuration options and examples]

## Troubleshooting
[Common issues and solutions]

図の作成ガイドライン

1. シンプルに始め、段階的に複雑にする

flowchart LR
    A[Start Simple] --> B[Get Feedback]
    B --> C{Need More Detail?}
    C -->|Yes| D[Add Elements]
    D --> B
    C -->|No| E[Done]

2. 一貫した命名を使う

• サービス／コンポーネントには PascalCase を使います：UserService、OrderAPI
• アクション／メソッドには camelCase を使います：processOrder、validateUser
• 定数／設定には SCREAMING_SNAKE を使います：MAX_RETRIES、API_TIMEOUT
• ラベルは簡潔さを保ちながら、内容が伝わるものにします

3. 関連する要素をグループ化する

フローチャートではサブグラフを使って、関連するコンポーネントをグループ化します。

flowchart TB
    subgraph Frontend
        A[Web App]
        B[Mobile App]
    end
    subgraph Backend
        C[API Gateway]
        D[Services]
    end
    A --> C
    B --> C
    C --> D

4. フローの方向を示す

• タイムラインや順次処理には LR（左から右）を使います
• 階層やアーキテクチャには TB（上から下）を使います
• 依存関係ツリーには BT（下から上）を使います
• 矢印でデータや制御のフローの方向を示します

5. 注釈でコンテキストを補足する

シーケンス図では、分かりにくい動作を説明するために注釈を使います。

sequenceDiagram
    participant C as Client
    participant S as Server

    C->>S: Request
    Note right of S: Validates JWT token
    S-->>C: Response

6. 目的を持って色を使う

次の要素を強調するために色を使います。

• 異なるシステム境界（内部と外部）
• ステータス（成功／エラー／警告の経路）
• 優先度や重要度

flowchart LR
    A[Input]:::input --> B{Validate}
    B -->|Valid| C[Process]:::success
    B -->|Invalid| D[Error]:::error

    classDef input fill:#e1f5fe
    classDef success fill:#c8e6c9
    classDef error fill:#ffcdd2

ドキュメントの種類ごとのベストプラクティス

README ドキュメント

README ファイルには次の内容を含めます。

1. アーキテクチャの概要図（フローチャートまたは C4 コンテキスト図）
2. 主要なワークフロー図（ユーザー／システムの主なフローを示す）
3. 図はシンプルに保ち、複雑な内容は詳細ドキュメントへのリンクで補足します

API ドキュメント

API ドキュメントには次の内容を含めます。

1. 主要な各エンドポイントについて、リクエストのライフサイクル全体を示すシーケンス図
2. API が状態を持つリソースを管理する場合は状態図
3. API が返すデータモデルのER 図

アーキテクチャドキュメント

アーキテクチャドキュメントには次の内容を含めます。

1. C4 コンテキスト図 — システムと外部依存関係
2. C4 コンテナー図 — アプリケーションとデータストア
3. C4 コンポーネント図 — 複雑なコンテナーの内部構造
4. インフラストラクチャが複雑な場合はデプロイ図

オンボーディングドキュメント

新しい開発者向けのオンボーディングには、次の内容を含めます。

1. システムの概要フローチャート
2. 典型的なリクエストフローのシーケンス図
3. 中核となるドメインモデルのクラス図
4. ブランチ戦略を示すGit グラフ

よく使われるパターン

リクエスト／レスポンスのフローパターン

sequenceDiagram
    autonumber
    participant Client
    participant Gateway as API Gateway
    participant Auth as Auth Service
    participant API as Core API
    participant DB as Database

    Client->>Gateway: Request
    Gateway->>Auth: Validate Token

    alt Valid Token
        Auth-->>Gateway: User Context
        Gateway->>API: Forward Request
        API->>DB: Query/Mutate
        DB-->>API: Result
        API-->>Gateway: Response
        Gateway-->>Client: Success
    else Invalid Token
        Auth-->>Gateway: Unauthorized
        Gateway-->>Client: 401 Error
    end

状態マシンパターン

stateDiagram-v2
    [*] --> Created
    Created --> Active: activate
    Active --> Paused: pause
    Paused --> Active: resume
    Active --> Completed: finish
    Paused --> Cancelled: cancel
    Active --> Cancelled: cancel
    Completed --> [*]
    Cancelled --> [*]

マイクロサービスパターン

flowchart TB
    subgraph Gateway["API Gateway"]
        LB[Load Balancer]
    end

    subgraph Services["Microservices"]
        S1[Service A]
        S2[Service B]
        S3[Service C]
    end

    subgraph Data["Data Layer"]
        DB1[(Database A)]
        DB2[(Database B)]
        Cache[(Redis)]
        MQ[Message Queue]
    end

    LB --> S1
    LB --> S2
    LB --> S3

    S1 --> DB1
    S1 --> Cache
    S2 --> DB2
    S2 --> MQ
    S3 --> MQ
    MQ --> S1

品質チェックリスト

ドキュメントを完成させる前に、以下を確認してください。

• 図が正しくレンダリングされることを対象プラットフォーム（GitHub、GitLab など）で確認します
• ラベルが明確であること、説明のない略語を使っていないことを確認します
• フローの方向が論理的で、追いやすいことを確認します
• 色がアクセシブルであることを確認します（色だけに頼らないでください）
• 図に文脈があることを確認します。説明文で図が示す内容を説明します
• 詳細度が対象読者に適切であることを確認します
• 図が過密でないことを確認します。複雑な図は分割してください
• 図に含まれるすべての要素が本文で説明されていることを確認します

リソース

構文の完全なリファレンスやその他の例については、以下を参照してください。

• mermaid-reference.md - Mermaid 構文ガイドの全内容
• examples.md - 実践的なドキュメントの例

Claude への指示

ユーザーからドキュメントの作成や何かの説明を求められた場合：

1. 範囲を把握する：README、API ドキュメント、アーキテクチャドキュメント、説明のどれでしょうか？

2. 図にできる箇所を特定する：視覚化すると役立つ概念は何でしょうか？

3. 適切な図の種類を選ぶ：上の表を使って、適切な図を選びます

4. 階層的にドキュメントを作成する：

   • 概要と図から始めます
   • 補足する図を使って、詳細を説明します
   • 関連する場合は、コード例を含めます

5. 図を補足する説明文を書く：

   • 文脈を示して各図を導入します
   • 図が示す内容を説明します
   • 図から得られる重要な知見を強調します

6. 図の構文を検証する：Mermaid の構文がすべて正しく、レンダリングされることを確認します

7. 保守しやすくする：明確なラベルと、更新しやすいシンプルな構造を使います

覚えておいてください：目標は理解であり、単にドキュメントを作ることではありません。 それぞれの図は、言葉だけでは十分に伝えられない何かを、より明確にするものであるべきです。