Mermaid Architect - 階層図とドキュメント生成スキル
Mermaid図とドキュメント生成システム。専門ガイドとコードから図への変換機能を備えています。
目次
- 決定木
- GitHub Wiki、WikiTicket、Confluence
- 利用可能なガイドとリソース
- 使用方法パターン
- レジリエントワークフロー
- Unicodeセマンティック記号
- Pythonユーティリティ
- 決定木の例
- ハイコントラストスタイリング
- ファイル構成
- ワークフローまとめ
- いつ何を使うか
- ベストプラクティス
- 学習パス
決定木
このスキルの動作方法:
- ユーザーがリクエスト → スキルが意図を分析
- スキルが図/ドキュメントの種類を判断 → 適切なガイドを読み込み
- AIが専門ガイドを読み込み → テンプレートを使用して図/ドキュメントを生成
- 結果を出力 → 検証とエクスポートオプション付き
ユーザー意図分析:
flowchart TD
Start([ユーザーリクエスト]) --> Analyze{意図を分析}
Analyze -->|"ワークフロー、プロセス、ビジネスロジック"| Activity[アクティビティ図ガイドを読み込み<br/>references/guides/diagrams/activity-diagrams.md]
Analyze -->|"インフラ、デプロイ、クラウド"| Deploy[デプロイ図ガイドを読み込み<br/>references/guides/diagrams/deployment-diagrams.md]
Analyze -->|"システムアーキテクチャ、コンポーネント"| Arch[アーキテクチャガイドを読み込み<br/>references/guides/diagrams/architecture-diagrams.md]
Analyze -->|"APIフロー、相互作用"| Sequence[シーケンス図ガイドを読み込み<br/>references/guides/diagrams/sequence-diagrams.md]
Analyze -->|"クラス、ER、状態、wiki、ウォークスルー"| WikiGuide[WikiTicket GitHubガイドを読み込み<br/>references/guides/wiki-ticket-and-github.md]
Analyze -->|"コードから図へ"| CodeToDiag[コード→図ガイドを読み込み<br/>references/guides/code-to-diagram/ + examples/]
Analyze -->|"設計書、完全なドキュメント"| DesignDoc[設計書テンプレートを読み込み<br/>assets/*-design-template.md]
Analyze -->|"unicode記号、アイコン"| Unicode[Unicode記号ガイドを読み込み<br/>references/guides/unicode-symbols/guide.md]
Analyze -->|"抽出、検証、変換"| Scripts[Pythonスクリプトを使用<br/>scripts/extract_mermaid.py<br/>scripts/mermaid_to_image.py]
Activity --> Generate[図を生成]
Deploy --> Generate
Arch --> Generate
Sequence --> Generate
WikiGuide --> Generate
CodeToDiag --> Generate
DesignDoc --> Generate
Unicode --> Generate
Scripts --> Execute[スクリプトを実行]
Generate --> Validate{検証する?}
Validate -->|はい| RunValidation[mmdc検証を実行]
Validate -->|いいえ| Output
RunValidation --> Output[結果を出力]
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アプリ | 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. タイプを特定] --> B[2. .mmd + 画像を保存]
B --> C{3. 有効?}
C -->|はい| D[4. Markdownに追加]
C -->|いいえ| E[5. エラー回復]
E --> F{修正見つかった?}
F -->|はい| A
F -->|いいえ| G[外部検索]
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に追加しないでください。 これにより、文書内の壊れた図を防ぎます。
スクリプトの使用(推奨)
# 完全なエラー回復で生成
python scripts/resilient_diagram.py \
--code "flowchart TD; A-->B" \
--markdown-file design_doc \
--diagram-num 1 \
--title "process_flow" \
--format png \
--json
出力: .mmdファイルと.pngファイルの両方が./diagrams/ディレクトリに生成されます。
ファイル命名規則
./diagrams/<markdown_file>_<num>_<type>_<title>.mmd
./diagrams/<markdown_file>_<num>_<type>_<title>.png
例: ./diagrams/api_design_01_sequence_auth_flow.png
エラー回復の優先順位
検証が失敗した場合、ワークフローは自動的に以下を実行します:
- トラブルシューティングガイドを確認 -
references/guides/troubleshooting.md(28の文書化されたエラー) - perplexityで検索 -
perplexity_askMCPで構文に関する質問 - braveで検索 -
brave_web_searchMCPで最近の解決策 - geminiに問い合わせ -
geminiスキルで別の視点 - 一般検索 -
WebSearchツールをフォールバックとして使用
手動フォールバック手順
スクリプトが使用できない場合:
- 最初の行から図のタイプを特定(flowchart, sequenceなど)
- リファレンスガイドを読み込む
references/guides/diagrams/から - 保存先:
./diagrams/<markdown_file>_<num>_<type>_<title>.mmd - 検証:
mmdc -i file.mmd -o file.png -b transparent - エラー時:
references/guides/troubleshooting.mdで一致するエラーを検索 - 見つからない場合: 上記の優先順位で検索ツールを使用
- 参照を追加:

パターン6: レジリエント図生成
ユーザー: "シーケンス図を作成して設計書に追加して"
スキルのアクション:
- 意図を特定: 図生成 + Markdown統合
- ワークフローガイドを読み込み:
references/guides/resilient-workflow.md - 図タイプを特定: シーケンス
- 図ガイドを読み込み:
references/guides/diagrams/sequence-diagrams.md - テンプレートを使用してMermaidコードを生成
- レジリエントワークフローを実行:
python scripts/resilient_diagram.py \ --code "[生成されたコード]" \ --markdown-file design_doc \ --diagram-num 1 \ --title "api_sequence" \ --json - 検証が失敗した場合 → トラブルシューティング修正を適用 → 再試行
- 成功した場合 →
をMarkdownに追加
Unicodeセマンティック記号
常にUnicode記号を使用して図の明確さを高めます。一般的なパターン:
インフラとデプロイ
graph TB
Client[👤 ユーザー] --> LB[🌐 ロードバランサー]
LB --> App1[⚙️ アプリサーバー1]
LB --> App2[⚙️ アプリサーバー2]
App1 --> DB[(💾 データベース)]
App1 --> Cache[(⚡ Redis)]
状態付きアクティビティフロー
flowchart TD
Start([🚀 開始]) --> Process[⚙️ データ処理]
Process --> Check{✓ 有効?}
Check -->|はい| Save[💾 保存]
Check -->|いいえ| Error[❌ エラー]
Save --> Complete([✅ 完了])
マイクロサービスアーキテクチャ
graph TB
API[🌐 APIゲートウェイ] --> Auth[🔐 認証サービス]
API --> Orders[📋 注文サービス]
Orders --> Queue[📬 メッセージキュー]
Queue --> Worker[⚙️ バックグラウンドワーカー]
Worker --> Storage[📦 オブジェクトストレージ]
完全な記号リファレンスについては、次を読み込んでください: references/guides/unicode-symbols/guide.md
Pythonユーティリティ
Mermaid図の抽出
# すべての図を一覧表示
python scripts/extract_mermaid.py document.md --list-only
# 個別ファイルに抽出
python scripts/extract_mermaid.py document.md --output-dir diagrams/
# すべての図を検証
python scripts/extract_mermaid.py document.md --validate
# 画像参照に置換(Confluenceアップロード用)
python scripts/extract_mermaid.py document.md --replace-with-images \
--image-format png --output-markdown output.md
画像に変換
# 単一変換
python scripts/mermaid_to_image.py diagram.mmd output.png
# カスタム設定
python scripts/mermaid_to_image.py diagram.mmd output.svg \
--theme dark --background white --width 1200
# ディレクトリを一括変換
python scripts/mermaid_to_image.py diagrams/ output/ --format png --recursive
# 標準入力から
echo "graph TD; A-->B" | python scripts/mermaid_to_image.py - output.png
レジリエント図
# フルワークフロー
python scripts/resilient_diagram.py \
--code "flowchart TD; A-->B" \
--markdown-file design_doc \
--diagram-num 1 \
--title "process_flow" \
--format png
# スタンドアロン
python scripts/resilient_diagram.py \
--code "sequenceDiagram; A->>B: Hello" \
--format svg
# 検証のみ
python scripts/resilient_diagram.py \
--code "graph TD; A-->B" \
--validate-only
テンプレートからの生成
# テンプレートを使用した新しい図
python scripts/generate_from_template.py \
--template sequence_api \
--output diagram.mmd \
--title "ユーザー認証" \
--actors "Client, Server, Database"
# 利用可能なテンプレートを一覧表示
python scripts/generate_from_template.py --list-templates
決定木の例
例1: システムアーキテクチャの文書化
ユーザー: "マイクロサービスアーキテクチャの図を作成して"
スキルのアクション:
- 意図を分析: システムアーキテクチャ
- ガイドを読み込み:
アーキテクチャ図ガイド+Unicode記号ガイド - 図を生成:
graph TB subgraph "API層" GW[🌐 APIゲートウェイ] end subgraph "サービス" Auth[🔐 認証サービス] User[👤 ユーザーサービス] Order[📋 注文サービス] end subgraph "データ" SQL[(💾 Postgres)] NoSQL[(🗃️ MongoDB)] Cache[(⚡ Redis)] end GW --> Auth & User & Order Auth --> SQL User --> NoSQL Order --> Cache --> SQL - 検証してファイルに保存
例2: CI/CDパイプライン
ユーザー: "デプロイパイプラインを文書化して"
スキルのアクション:
- 意図を分析: CI/CDワークフロー
- ガイドを読み込み:
アクティビティ図ガイド+デプロイ図ガイド - 図を生成:
flowchart LR Dev[💻 開発] --> PR[📝 PR作成] PR --> CI[⚙️ CIビルド] CI --> Test[🧪 テスト] Test -->|合格| Stage[☁️ ステージング] Stage --> Approval[👁️ 承認] Approval -->|承認済み| Prod[🚀 本番] Test -->|不合格| Dev - 検証してファイルに保存
ハイコントラストスタイリング
すべての図にアクセシブルなスタイリングを使用します。ハイコントラストスタイルの例:
flowchart TD
Start([🚀 開始]) --> Node[処理]
Node --> Decision{決定}
Decision -->|オプション1| Success[✅ 成功]
Decision -->|オプション2| Failure[❌ 失敗]
classDef start fill:#4CAF50,stroke:#2E7D32,color:white
classDef process fill:#2196F3,stroke:#1565C0,color:white
classDef decision fill:#FF9800,stroke:#E65100,color:black
classDef success fill:#4CAF50,stroke:#2E7D32,color:white
classDef failure fill:#F44336,stroke:#B71C1C,color:white
class Start start
class Node process
class Decision decision
class Success success
class Failure failure
アクセシブルな色の使用に関するガイドライン:
- 緑: 成功、コンプリート、アクティブ状態
- 青: プロセス、システム、ニュートラル
- オレンジ: 決定、警告、注意
- 赤: エラー、失敗、停止
- テキストとの十分なコントラストを確保するために、常に濃い色のテキスト(白または黒)を使用
ファイル構成
project/
├── assets/
│ ├── architecture-design-template.md
│ ├── api-design-template.md
│ ├── feature-design-template.md
│ ├── database-design-template.md
│ └── system-design-template.md
├── examples/
│ ├── spring-boot/
│ │ └── README.md
│ ├── fastapi/
│ │ └── README.md
│ ├── react/
│ │ └── README.md
│ ├── python-etl/
│ │ └── README.md
│ ├── node-webapp/
│ │ └── README.md
│ └── java-webapp/
│ └── README.md
├── references/
│ ├── guides/
│ │ ├── diagrams/
│ │ │ ├── activity-diagrams.md
│ │ │ ├── deployment-diagrams.md
│ │ │ ├── architecture-diagrams.md
│ │ │ └── sequence-diagrams.md
│ │ ├── code-to-diagram/
│ │ │ └── README.md
│ │ ├── unicode-symbols/
│ │ │ └── guide.md
│ │ ├── wiki-ticket-and-github.md
│ │ ├── troubleshooting.md
│ │ └── resilient-workflow.md
│ └── examples/
├── scripts/
│ ├── extract_mermaid.py
│ ├── mermaid_to_image.py
│ ├── resilient_diagram.py
│ └── generate_from_template.py
└── diagrams/
ワークフローまとめ
| ステップ | アクション | 使用ツール |
|---|---|---|
| 1. 受信 | ユーザーリクエストを受け取る | - |
| 2. 分析 | 意図を分析、図タイプを特定 | 決定木 |
| 3. ガイド読み込み | 関連ガイドを読み込み | ファイルシステム |
| 4. 生成 | Mermaidコードを生成 | AI + テンプレート |
| 5. 保存 | .mmdファイルに保存 | scripts/resilient_diagram.py |
| 6. 検証 | 構文とレンダリングを確認 | mmdc + Pythonスクリプト |
| 7. 修正 | 必要に応じてエラーを修正 | トラブルシューティングガイド + 検索 |
| 8. 出力 | 埋め込み画像とコードをMarkdownで提供 | 最終ドキュメント |
いつ何を使うか
図のタイプ
| ユーザーが言ったこと | 図タイプ | ガイド |
|---|---|---|
| "フローチャート", "ワークフロー", "プロセス", "フロー" | flowchart | アクティビティ図 |
| "シーケンス", "相互作用", "APIコール" | sequenceDiagram | シーケンス図 |
| "クラス図", "モデル", "エンティティ" | classDiagram | WikiTicketガイド |
| "ER図", "データベース", "リレーション" | erDiagram | WikiTicketガイド |
| "状態図", "ステートマシン", "状態" | stateDiagram-v2 | WikiTicketガイド |
| "アーキテクチャ", "C4", "システム" | C4Context/C4Container | アーキテクチャ図 |
| "デプロイ", "インフラ", "クラウド" | deployment | デプロイ図 |
| "ガント", "タイムライン", "スケジュール" | gantt | アクティビティ図 |
| "マインドマップ", "ブレインストーミング" | mindmap | アーキテクチャ図 |
| "タイムライン", "履歴", "ロードマップ" | timeline | アクティビティ図 |
| "Gitグラフ", "ブランチ", "コミット" | gitGraph | WikiTicketガイド |
| "円グラフ", "四分円", "データの視覚化" | pie/quadrantChart | アクティビティ図 |
| "要件図", "要件", "依存関係" | requirementDiagram | アーキテクチャ図 |
PlantUMLに送信するもの
以下の場合のみPlantUMLを使用します(PNG/SVGとして送信):
| タイプ | リクエスト例 |
|---|---|
| Saltワイヤーフレーム | "ワイヤーフレーム", "UIモックアップ" |
| ユースケース図 | "ユースケース", "アクター" |
| タイミング図 | "タイミング", "デジタルタイミング" |
| ArchiMate | "ArchiMate", "エンタープライズアーキテクチャ" |
| nwdiag | "ネットワーク図", "nwdiag" |
| WBS | "WBS", "作業分割構成" |
重要: 他のすべての図タイプはMermaidで処理してください。
ベストプラクティス
- 常に検証する: 追加前に図をレンダリング
- 明確なラベルを使用する: 各ノード/エッジには説明ラベルを付ける
- Unicode記号で強化する: ただし過度に使用しない(
⚠️は重要) - 一貫性を保つ: 同じプロジェクト内で同じスタイルと配色を使用
- 文書化する: 各図にその目的とコンテキストを説明するコメントを追加
- シンプルにする: 1つの図には5〜15個のノードが適切
- エラーから回復する: 失敗を診断して修正するためにレジリエントワークフローを使用
- 適切なものを使用する: 図のタイプはデータの性質に合わせる(プロセス用フローチャート、相互作用用シーケンス)
学習パス
- 初心者: 基本図(フローチャート、シーケンス、クラス)→ WikiTicketガイド
- 中級: コード→図変換、カスタムテーマ、一括エクスポート
- 上級: C4モデリング、レジリエントワークフロー、Pythonスクリプト自動化
- エキスパート: カスタムテンプレート、CI/CD統合、大規模文書生成

