design-doc-mermaid

Mermaid Architect - 階層型図とドキュメントのスキル

Mermaid の図とドキュメントを作成するシステムです。専門ガイドとコードから図を生成する機能を備えています。

目次

• 意思決定ツリー
• GitHub wiki、WikiTicket、Confluence
• 利用可能なガイドとリソース
• 使用パターン
• 回復性のあるワークフロー
• Unicode の意味的な記号
• Python ユーティリティ
• 意思決定ツリーの例
• 高コントラストのスタイル設定
• ファイル構成
• ワークフローの概要
• 使い分け
• ベストプラクティス
• 学習パス

Decision Tree

このスキルの仕組み：

1. ユーザーがリクエストする → スキルが意図を分析します
2. スキルが図やドキュメントの種類を判断する → 適切なガイドを読み込みます
3. AI が専門ガイドを読み込む → テンプレートを使って図やドキュメントを生成します
4. 結果を提示する → 検証とエクスポートのオプションを含みます

ユーザーの意図の分析：

flowchart TD
    Start([User Request]) --> Analyze{Analyze Intent}

    Analyze -->|"workflow, process, business logic"| Activity[Load Activity Diagram Guide<br/>references/guides/diagrams/activity-diagrams.md]
    Analyze -->|"infrastructure, deployment, cloud"| Deploy[Load Deployment Diagram Guide<br/>references/guides/diagrams/deployment-diagrams.md]
    Analyze -->|"system architecture, components"| Arch[Load Architecture Guide<br/>references/guides/diagrams/architecture-diagrams.md]
    Analyze -->|"API flow, interactions"| Sequence[Load Sequence Diagram Guide<br/>references/guides/diagrams/sequence-diagrams.md]
    Analyze -->|"class, ER, state, wiki, walkthrough"| WikiGuide[Load WikiTicket GitHub Guide<br/>references/guides/wiki-ticket-and-github.md]
    Analyze -->|"code to diagram"| CodeToDiag[Load Code-to-Diagram Guide<br/>references/guides/code-to-diagram/ + examples/]
    Analyze -->|"design document, full docs"| DesignDoc[Load Design Document Template<br/>assets/*-design-template.md]
    Analyze -->|"unicode symbols, icons"| Unicode[Load Unicode Symbols Guide<br/>references/guides/unicode-symbols/guide.md]
    Analyze -->|"extract, validate, convert"| Scripts[Use Python Scripts<br/>scripts/extract_mermaid.py<br/>scripts/mermaid_to_image.py]

    Activity --> Generate[Generate Diagram]
    Deploy --> Generate
    Arch --> Generate
    Sequence --> Generate
    WikiGuide --> Generate
    CodeToDiag --> Generate
    DesignDoc --> Generate
    Unicode --> Generate
    Scripts --> Execute[Execute Script]

    Generate --> Validate{Validate?}
    Validate -->|Yes| RunValidation[Run mmdc validation]
    Validate -->|No| Output
    RunValidation --> Output[Output Result]
    Execute --> Output

    classDef decision fill:#FFD700,stroke:#333,stroke-width:2px,color:black
    classDef guide fill:#90EE90,stroke:#333,stroke-width:2px,color:darkgreen
    classDef action fill:#87CEEB,stroke:#333,stroke-width:2px,color:darkblue

    class Analyze,Validate decision
    class Activity,Deploy,Arch,Sequence,WikiGuide,CodeToDiag,DesignDoc,Unicode,Scripts guide
    class Generate,Execute,RunValidation,Output action

利用可能なガイドとリソース

図の種類別ガイド（references/guides/diagrams/）

ガイド	フルパス	ユーザーが求めている内容	例
アクティビティ図	references/guides/diagrams/activity-diagrams.md	ワークフロー、プロセス、ビジネスロジック、ユーザーフロー、意思決定ツリー	「チェックアウトのフローを示す」「ETL パイプラインを文書化する」「承認ワークフローを作成する」
デプロイ図	references/guides/diagrams/deployment-diagrams.md	インフラストラクチャ、クラウドアーキテクチャ、K8s、サーバーレス、ネットワークトポロジー	「AWS アーキテクチャを示す」「GCP のデプロイを文書化する」「K8s の図を作成する」
アーキテクチャ図	references/guides/diagrams/architecture-diagrams.md	システムアーキテクチャ、コンポーネント設計、上位レベルの構造	「システムのコンポーネントを示す」「マイクロサービスを文書化する」「アーキテクチャの概要」
シーケンス図	references/guides/diagrams/sequence-diagrams.md	API のやり取り、サービス間通信、リクエスト／レスポンスのフロー	「API 呼び出しのシーケンスを示す」「認証フローを文書化する」「サービス間のやり取り」
WikiTicket／GitHub／Confluence	references/guides/wiki-ticket-and-github.md	設計ドキュメント、ウォークスルー、要件、Wiki への公開、Confluence の画像	「アーキテクチャ文書」「コードのウォークスルー」「Wiki」「Confluence」

WikiTicket と GitHub wiki の既定はこのスキルです。classDiagram、erDiagram、stateDiagram-v2 も含まれます。これらを PlantUML に送らないでください。GitHub で C4／architecture-beta／block-beta のレンダリングに失敗した場合は、flowchart TD に切り替えてください。

コードから図を作成するためのガイドと例

リソース	フルパス	提供内容
マスターガイド	references/guides/code-to-diagram/README.md	あらゆるコードベースを分析し、図を抽出するための完全なワークフロー
Spring Boot	examples/spring-boot/README.md	Controller→Service→Repository のアーキテクチャ、デプロイ設定、メソッドからのシーケンス図、ビジネスロジックからのアクティビティ図
FastAPI	examples/fastapi/README.md	Python の非同期パターン、Pydantic モデル、依存性注入、クラウドへのデプロイ
React	examples/react/README.md	コンポーネント階層、状態管理、データフロー、ビルドパイプライン
Python ETL	examples/python-etl/README.md	データパイプライン、変換ステップ、エラー処理、スケジューリング
Node/Express	examples/node-webapp/README.md	ミドルウェアチェーン、ルートハンドラー、非同期パターン、デプロイ
Java Web App	examples/java-webapp/README.md	従来型 MVC、サーブレットコンテナー、WAR のデプロイ

設計ドキュメントのテンプレート

テンプレート	フルパス	用途	次の場合に読み込む
アーキテクチャ設計	assets/architecture-design-template.md	システム全体のアーキテクチャ	「アーキテクチャドキュメントを作成」「システム設計を文書化」
API 設計	assets/api-design-template.md	API 仕様	「API 設計ドキュメント」「REST API を文書化」
機能設計	assets/feature-design-template.md	機能の計画	「機能設計」「新機能を計画」
データベース設計	assets/database-design-template.md	データベーススキーマ	「データベース設計」「スキーマを文書化」
システム設計	assets/system-design-template.md	システム全体	「システム設計ドキュメント」「システム全体を文書化」

Unicode 記号ガイド

フルパス: references/guides/unicode-symbols/guide.md

ユーザーが次の内容に言及したときに読み込む: 「Unicode 記号」「図の絵文字」「意味を表すアイコン」「記号を追加」

クイックリファレンス:

• 📦 インフラストラクチャ: ☁️ 🌐 🔌 📡 🗄️
• ⚙️ コンピューティング: ⚙️ ⚡ 🔄 ♻️ 🚀 💨
• 💾 データ: 💾 📦 📊 📈 🗃️ 🧊
• 📨 メッセージング: 📨 📬 📤 📥 🐰 📢
• 🔐 セキュリティ: 🔐 🔑 🛡️ 🚪 👤 🎫
• 📝 モニタリング: 📝 📊 🚨 ⚠️ ✅ ❌

Python スクリプト（scripts/）

スクリプト	用途	次の場合に読み込む
extract_mermaid.py	Markdown から図を抽出し、構文を検証して、画像に置き換える	「図を抽出」「Mermaid を検証」「すべての図を探す」
mermaid_to_image.py	.mmd を PNG/SVG に変換し、一括変換やカスタムテーマにも対応する	「画像に変換」「図をレンダリング」「PNG を作成」
resilient_diagram.py	.mmd の保存、画像の生成、検証、エラー回復を行う一連のワークフロー	「図を生成」「検証付きで図を作成」「堅牢な図」

GitHub wiki、WikiTicket、Confluence

WikiTicket の設計ドキュメント、コードの解説、要件、GitHub wiki、または Confluence については、references/guides/wiki-ticket-and-github.md を読み込みます。

対象	提供するもの
GitHub wiki / GFM	フェンス付きの mermaid ブロック。GitHub はクラス図、ER 図、状態図、シーケンス図、フローチャート、C4 図をレンダリングします。
Confluence / Notion / Word / PDF	PNG または SVG（scripts/resilient_diagram.py または mmdc）もレンダリングして、画像をアップロードします。Confluence の Mermaid レンダリングには依存しないでください。

PlantUML は、Salt のワイヤーフレーム、ユースケース図、タイミング図、ArchiMate、nwdiag、WBS でのみ任意に使用できます。これらは必ず PNG または SVG として提供します。

使用パターン

よくあるリクエストのパターンと、選ぶガイドを示します。完全な対応表は用途別ガイドを参照してください。

パターン	リクエストの例	読み込むガイド
単一の図	「ログインフローのアクティビティ図を作成」	図の種類のガイド + Unicode 記号
コードから図を作成	「application.yml からデプロイメント図を生成」	フレームワークの例 + デプロイメントガイド
設計ドキュメント	「API 設計ドキュメントを作成」	assets/ のテンプレート + 関連する図のガイド
抽出／検証	「design.md から図を抽出」	scripts/extract_mermaid.py を使用
一括変換	「すべての .mmd を PNG に変換」	scripts/mermaid_to_image.py を使用

堅牢なワークフロー

重要: これは、あらゆる図の生成に推奨される方法です。検証、エラー回復、一貫したファイル整理を実現します。

完全ガイド: references/guides/resilient-workflow.md

ワークフローの概要

flowchart LR
    A[1. Identify Type] --> B[2. Save .mmd + Image]
    B --> C{3. Valid?}
    C -->|Yes| D[4. Add to Markdown]
    C -->|No| E[5. Error Recovery]
    E --> F{Fix Found?}
    F -->|Yes| A
    F -->|No| G[Search External]
    G --> A

    classDef step fill:#90EE90,stroke:#333,color:darkgreen
    classDef decision fill:#FFD700,stroke:#333,color:black
    class A,B,D,E,G step
    class C,F decision

基本原則

検証に合格するまで、図を Markdown に追加しないでください。 これにより、ドキュメント内の図が壊れるのを防げます。

スクリプトの使用（推奨）

# Generate with full error recovery
python scripts/resilient_diagram.py \
    --code "flowchart TD; A-->B" \
    --markdown-file design_doc \
    --diagram-num 1 \
    --title "process_flow" \
    --format png \
    --json

出力: ./diagrams/ ディレクトリに .mmd ファイルと .png ファイルの両方が生成されます。

ファイル名の規則

./diagrams/<markdown_file>_<num>_<type>_<title>.mmd
./diagrams/<markdown_file>_<num>_<type>_<title>.png

例: ./diagrams/api_design_01_sequence_auth_flow.png

エラー復旧の優先順位

検証に失敗すると、ワークフローは自動的に次の手順を実行します。

1. トラブルシューティングガイドを確認 - references/guides/troubleshooting.md（エラーを28件記録）
2. perplexityで検索 - 構文に関する質問には perplexity_ask MCP を使用
3. braveで検索 - 最近の解決策には brave_web_search MCP を使用
4. geminiに質問 - 別の視点を得るために gemini スキルを使用
5. 一般検索 - フォールバックとして WebSearch ツールを使用

手動でのフォールバック手順

スクリプトが利用できない場合：

1. 1行目から図の種類を特定します（フローチャート、シーケンス図など）
2. references/guides/diagrams/ からリファレンスガイドを読み込みます
3. ./diagrams/<markdown_file>_<num>_<type>_<title>.mmd に保存します
4. 検証します： mmdc -i file.mmd -o file.png -b transparent
5. エラーが発生した場合： references/guides/troubleshooting.md で該当するエラーを検索します
6. 見つからない場合： 上記の優先順位に従って検索ツールを使用します
7. 参照を追加します： ![Description](./diagrams/filename.png)

パターン6：復元力のある図の生成

ユーザー：「シーケンス図を作成して、設計ドキュメントに追加してください」

スキルのアクション：

1. 意図を特定：図の生成 + Markdownへの統合
2. ワークフローガイドを読み込み：references/guides/resilient-workflow.md
3. 図の種類を特定：シーケンス図
4. 図のガイドを読み込み：references/guides/diagrams/sequence-diagrams.md
5. テンプレートを使用してMermaidコードを生成
6. 復元力のあるワークフローを実行：

   python scripts/resilient_diagram.py \
       --code "[generated code]" \
       --markdown-file design_doc \
       --diagram-num 1 \
       --title "api_sequence" \
       --json
   

7. 検証に失敗した場合 → トラブルシューティングの修正を適用 → 再試行
8. 成功した場合 → Markdownに ![API Sequence](./diagrams/design_doc_01_sequence_api_sequence.png) を追加

Unicodeの意味を持つシンボル

図を分かりやすくするため、常にUnicodeシンボルを使用します。一般的なパターン：

インフラストラクチャとデプロイ

graph TB
    Client[👤 User] --> LB[🌐 Load Balancer]
    LB --> App1[⚙️ App Server 1]
    LB --> App2[⚙️ App Server 2]
    App1 --> DB[(💾 Database)]
    App1 --> Cache[(⚡ Redis)]

状態を含むアクティビティフロー

flowchart TD
    Start([🚀 Start]) --> Process[⚙️ Process Data]
    Process --> Check{✓ Valid?}
    Check -->|Yes| Save[💾 Save]
    Check -->|No| Error[❌ Error]
    Save --> Complete([✅ Complete])

マイクロサービスアーキテクチャ

graph TB
    API[🌐 API Gateway] --> Auth[🔐 Auth Service]
    API --> Orders[📋 Order Service]
    Orders --> Queue[📬 Message Queue]
    Queue --> Worker[⚙️ Background Worker]
    Worker --> Storage[📦 Object Storage]

シンボルの完全なリファレンスを確認するには、次を読み込みます： references/guides/unicode-symbols/guide.md

Pythonユーティリティ

Mermaid図の抽出

# List all diagrams
python scripts/extract_mermaid.py document.md --list-only

# Extract to separate files
python scripts/extract_mermaid.py document.md --output-dir diagrams/

# Validate all diagrams
python scripts/extract_mermaid.py document.md --validate

# Replace with image references (for Confluence upload)
python scripts/extract_mermaid.py document.md --replace-with-images \
  --image-format png --output-markdown output.md

画像への変換

# Single conversion
python scripts/mermaid_to_image.py diagram.mmd output.png

# With custom settings
python scripts/mermaid_to_image.py diagram.mmd output.svg \
  --theme dark --background white --width 1200

# Batch convert directory
python scripts/mermaid_to_image.py diagrams/ output/ --format png --recursive

# From stdin
echo "graph TD; A-->B" | python scripts/mermaid_to_image.py - output.png

判断ツリーの例

例1：ユーザーがワークフロー図を求める場合

入力：「チェックアウト処理のワークフローを表示してください」

スキルの判断経路：

1. Analyze: workflow, process → ACTIVITY DIAGRAM
2. Load guide: guides/diagrams/activity-diagrams.md
3. Find pattern: E-commerce checkout (template exists in guide)
4. Generate using template + Unicode symbols
5. Output activity diagram with decision points

**出力：**カート、支払い、注文の状態を表すUnicodeシンボルを使用した、完全なアクティビティ図。

例2：ユーザーがSpring Bootのコードを提示する場合

入力：「Spring Bootのコントローラーを載せます。図を作成してください」

スキルの判断経路：

1. Analyze: Spring Boot, code provided → CODE-TO-DIAGRAM + SPRING BOOT
2. Load guides:
   - examples/spring-boot/README.md
   - guides/diagrams/architecture-diagrams.md (for structure)
   - guides/diagrams/sequence-diagrams.md (for method calls)
   - guides/diagrams/activity-diagrams.md (for business logic)
3. Generate multiple diagrams:
   a. Architecture diagram from @RestController/@Service/@Repository annotations
   b. Sequence diagram from method call chain
   c. Activity diagram from business logic flow
4. Output all diagrams with explanations

**出力：**Spring Bootアプリケーションをさまざまな視点から示す3～4点の図。

例3：ユーザーがインフラストラクチャのドキュメント化を求める場合

入力：「AlloyDBを使用したGCP Cloud Runのデプロイを文書化してください」

スキルの判断経路：

1. Analyze: infrastructure, GCP, Cloud Run → DEPLOYMENT DIAGRAM
2. Load guides:
   - guides/diagrams/deployment-diagrams.md
   - examples/spring-boot/ or examples/fastapi/ (if code provided)
3. Check for IaC files (Pulumi, Terraform, docker-compose)
4. Generate deployment diagram with:
   - Cloud Run services with specs
   - VPC connector
   - AlloyDB cluster
   - Security (IAM, Secret Manager)
   - Monitoring
5. Apply Unicode symbols for clarity
6. Output with resource specifications

**出力：**すべてのリソースにラベルを付けた、GCPデプロイの完全な図。

高コントラストのスタイル設定

すべての図で高コントラストの色を使用する必要があります：

graph TB
    classDef primary fill:#90EE90,stroke:#333,stroke-width:2px,color:darkgreen
    classDef secondary fill:#87CEEB,stroke:#333,stroke-width:2px,color:darkblue
    classDef database fill:#E6E6FA,stroke:#333,stroke-width:2px,color:darkblue
    classDef error fill:#FFB6C1,stroke:#DC143C,stroke-width:2px,color:black

    %% Every classDef MUST have color: property

ルール：

• 明るい背景 → 暗い文字色
• 暗い背景 → 明るい文字色
• すべての classDef で必ず color: を指定

ファイル構成

design-doc-mermaid/
├── SKILL.md                          # This file - Main orchestrator
├── README.md                         # User documentation
├── CLAUDE.md                         # Claude Code instructions
│
├── references/                       # Reference materials
│   ├── mermaid-diagram-guide.md     # Legacy general guide
│   └── guides/                       # Specialized guides (load on-demand)
│       ├── diagrams/
│       │   ├── activity-diagrams.md      # Workflows, processes
│       │   ├── deployment-diagrams.md    # Infrastructure, cloud
│       │   ├── architecture-diagrams.md  # System architecture
│       │   └── sequence-diagrams.md      # API interactions
│       ├── code-to-diagram/
│       │   └── README.md                 # Master guide for code analysis
│       ├── unicode-symbols/
│       │   └── guide.md                  # Complete symbol reference
│       └── troubleshooting.md        # Common syntax errors & fixes
│
├── assets/                           # Design document templates
│   ├── architecture-design-template.md
│   ├── api-design-template.md
│   ├── feature-design-template.md
│   ├── database-design-template.md
│   └── system-design-template.md
│
├── scripts/                          # Python utilities
│   ├── extract_mermaid.py           # Extract & validate diagrams
│   └── mermaid_to_image.py          # Convert to PNG/SVG
│
├── examples/                         # Language-specific patterns
│   ├── spring-boot/                 # Spring Boot patterns
│   ├── fastapi/                     # FastAPI patterns
│   ├── react/                       # React patterns
│   ├── python-etl/                  # Data pipeline patterns
│   ├── node-webapp/                 # Express.js patterns
│   └── java-webapp/                 # Traditional Java patterns
│
└── references/                       # General Mermaid reference
    └── mermaid-diagram-guide.md     # Complete Mermaid syntax guide

ワークフローの概要

1. ユーザーの意図を分析 → 図の種類、ドキュメントの種類、または必要なアクションを判断
2. 適切なガイドを読み込み → 必要な内容だけを読む（トークン効率を重視）
3. テンプレートとパターンを適用 → ガイドの例を使用
4. 出力を生成 → 図またはドキュメントを作成
5. 検証（任意）→ スクリプトを使用して確認
6. 変換（任意）→ 必要に応じて画像にエクスポート

用途に応じた選択

ユーザーのリクエスト	読み込むもの
"activity diagram", "workflow", "process flow"	references/guides/diagrams/activity-diagrams.md
"deployment", "infrastructure", "cloud", "k8s"	references/guides/diagrams/deployment-diagrams.md
"architecture", "system design", "components"	references/guides/diagrams/architecture-diagrams.md + 設計テンプレート
"API", "sequence", "interactions", "flow"	references/guides/diagrams/sequence-diagrams.md
"class diagram", "ER", "state machine", "wiki", "walkthrough", "architecture doc"	references/guides/wiki-ticket-and-github.md と対応する種類のガイド
"Confluence", "upload image", "PNG", "SVG"	scripts/resilient_diagram.py または scripts/mermaid_to_image.py
"Spring Boot code"	examples/spring-boot/ + 関連する図のガイド
"FastAPI code", "Python API"	examples/fastapi/ + 関連する図のガイド
"React app", "frontend"	examples/react/ + アーキテクチャガイド
"ETL", "data pipeline", "Python batch"	examples/python-etl/ + アクティビティ図のガイド
"symbols", "unicode", "emoji"	references/guides/unicode-symbols/guide.md
"syntax error", "diagram won't render", "troubleshoot"	references/guides/troubleshooting.md
"extract diagrams"	scripts/extract_mermaid.py
"convert to image", "PNG", "SVG"	scripts/mermaid_to_image.py
"create diagram", "generate diagram", "add diagram to markdown"	scripts/resilient_diagram.py + references/guides/resilient-workflow.md
"design document", "full docs"	assets/*-design-template.md + 図のガイド

ベストプラクティス

1. 単一責任：1つの図につき1つの概念を表します
2. Unicode による強化：明確さを高めるため、常に意味に沿った記号を使います
3. 高いコントラスト：スタイルで color: プロパティを省略しないでください
4. 早期に検証：スクリプトを使って構文エラーを検出します
5. テンプレートの再利用：既存のテンプレートと例を活用します
6. 必要に応じて読み込む：特定のリクエストに必要なガイドのみを読みます
7. トークン効率：すべてを読むのではなく、階層的に読み込みます

学習の進め方

Mermaid を初めて使いますか？ こちらから始めましょう：

1. 記号の意味について references/guides/unicode-symbols/guide.md を読みます
2. 基本パターンについて references/guides/diagrams/activity-diagrams.md を読みます
3. examples/spring-boot/ または examples/fastapi/ の例を試します
4. scripts/extract_mermaid.py --validate を使って作業を確認します

コードを文書化する必要がありますか？ 次の手順に従います：

1. フレームワークを特定 → 該当する examples/{framework}/ を読み込みます
2. コードのパターンを図の種類に対応させます
3. ガイドのテンプレートを使います
4. スクリプトで検証します

設計ドキュメントを作成しますか？ 次の手順に従います：

1. ドキュメントの種類を選択 → assets/ からテンプレートを読み込みます
2. テキスト部分を埋めます
3. 各セクションで必要に応じて図のガイドを読み込みます
4. 全体を通して Unicode 記号を使います
5. タイムスタンプを付けて docs/design/ に保存します

---

バージョン： 2.0（階層型アーキテクチャ） 最終更新日： 2025-01-13 メンテナンス担当： Claude Code Skills