moai-library-mermaid

クイックリファレンス

Mermaid Diagram Expert v7.1.0 - Claude Code 向けの、MCP Playwright 統合による純粋なスキルベースの Mermaid レンダリングです。

このスキルでは、21 種類すべての図に対応した Mermaid 11.12.2 の構文一式、SVG および PNG 出力をレンダリングする MCP Playwright 統合、すぐに使えるサンプルとリファレンスドキュメント、ベストプラクティスを取り入れたエンタープライズ向けの図のパターンを提供します。

このスキルを呼び出すには、スキル名 moai-library-mermaid を指定して標準的なスキル呼び出しパターンを使用します。

対応する図の種類

このスキルは、5 つのカテゴリに分類された 21 種類の図に対応しています。

構造図には、プロセスフローと判断ツリーのフローチャート、インタラクションシーケンスとメッセージフローのシーケンス図、オブジェクト指向のクラス関係を示すクラス図、エンティティとリレーションシップを表すデータベースの ER 図、ブロック図構造を示すブロック図、ステートマシンと状態を持つフローを示す状態図があります。

タイムラインと追跡の図には、時系列イベントとマイルストーンのタイムライン、プロジェクトのスケジュールとタイムラインのガントチャート、Git のワークフローとブランチを視覚化する Gitgraph があります。

アーキテクチャと設計の図には、コンテキスト、コンテナ、コンポーネント、コードのアーキテクチャ図を示す C4、システムアーキテクチャ図を示すアーキテクチャ図、要件とトレーサビリティのドキュメントを示す要件図があります。

データ可視化の図には、円グラフとドーナツグラフの円グラフ、散布図と折れ線グラフの XY チャート、幅で比率を表すフロー図のサンキー図、複数の変数を比較するレーダーチャートがあります。

ユーザーとプロセスの図には、階層的なマインドマッピングのマインドマップ、ユーザー体験のフローを示すユーザージャーニー、ボードの状態を可視化するカンバン図、ネットワークパケットの構造を示すパケット図があります。

MCP Playwright 統合

このスキルは、図のレンダリングに MCP Playwright を統合しています。プロジェクトの mcp.json ファイルにある MCP 設定で Playwright サーバーを有効にできます。このサーバーは、anthropic-ai playwright-mcp パッケージを使うように npx で設定できます。

図をレンダリングするには、プロジェクトの MCP 設定で MCP Playwright サーバーが設定されている必要があります。また、システムに Node.js がインストールされ、npx から Playwright を利用できる必要があります。

---

実装ガイド

ダイアグラム構文のパターン

フローチャートでは、flowchart キーワードの後に、上から下への流れを表す TD や左から右への流れを表す LR などの方向インジケーターを指定します。ノードは図形を示す括弧で定義し、丸括弧は角丸の長方形、角括弧は標準的な長方形、中括弧はひし形の判断ノード、二重角括弧はスタジアム形のノードを作成します。接続には、二重ダッシュと山括弧を使った矢印構文を使用し、エッジの説明をパイプで囲んだラベルとして任意で指定できます。サブグラフでは、subgraph キーワード、タイトル、終端デリミターを使用して関連するノードをグループ化します。

シーケンス図では、まず participant キーワードで参加者を定義し、その後、矢印表記で相互作用を示します。二重山括弧を使った実線の矢印は同期呼び出しを表し、破線の矢印は応答または非同期メッセージを表します。アクティベーション矩形は、activate キーワードと deactivate キーワード、または矢印上のプラス記号とマイナス記号の省略表記を使って、参加者のアクティビティ期間を示します。参加者の右側、左側、または上部に注釈を追加できます。

C4 コンテキスト図では、C4Context キーワードを使用し、Enterprise_Boundary 関数または System_Boundary 関数でシステム境界を定義します。人物は、ID、名前、任意の説明を受け取る Person 関数で定義します。システムは、内部システムには System、外部システムには System_Ext を使用して定義します。関係には Rel 関数を使用し、ソース、ターゲット、説明、任意のテクノロジーを指定します。

クラス図では、classDiagram キーワードを使用し、クラスとその属性およびメソッドを定義します。関係には、山括弧とパイプ記号による継承、アスタリスクによるコンポジション、円による集約、ダッシュによる関連があります。可視性修飾子には、パブリックを表すプラス記号、プライベートを表すマイナス記号、保護を表すハッシュ記号を使用します。

ステート図では、新しい構文を使用するために stateDiagram-v2 キーワードを使用します。状態は state キーワードと括弧で定義します。遷移には、任意のラベルを付けた矢印表記を使用します。複合状態には、状態ブロック内にネストされた状態を含めます。

ダイアグラムのカテゴリ

プロセスとフローのダイアグラムには、Flowchart、Sequence、State、Timeline、Gitgraph、User Journey の各種ダイアグラムが含まれます。これらのダイアグラムは、動的なプロセスと時間的なシーケンスを表します。

構造と設計のダイアグラムには、Class、ER、Block、Architecture、C4 の各種ダイアグラムが含まれます。これらのダイアグラムは、静的な構造とシステムの構成を表します。

データと分析のダイアグラムには、Pie Chart、XY Chart、Sankey、Radar の各種ダイアグラムが含まれます。これらのダイアグラムは、定量データと比較指標を視覚化します。

計画と整理のダイアグラムには、Gantt、Mindmap、Kanban、Requirement の各種ダイアグラムが含まれます。これらのダイアグラムは、プロジェクト管理と要件追跡を支援します。

ネットワークと技術のダイアグラムには、現在、Packet タイプが含まれており、追加のタイプは今後の拡張用に確保されています。

ベストプラクティス

明瞭さと読みやすさに関するガイドラインでは、すべてのノードに説明的なラベルを付けること、ダイアグラムの複雑さを中程度に保ち、ノード数を最大 20 ～ 30 個にすること、ダイアグラム全体で一貫したスタイルと配色を使用することを推奨しています。

パフォーマンスに関する考慮事項には、複雑なダイアグラムを複数の小さなダイアグラムに分割すること、大きなフローチャートの整理にサブグラフを使用すること、レンダリングパフォーマンスを維持するためにノード内のテキストを短くすることが含まれます。

アクセシビリティ要件には、すべてのダイアグラムにテキストによる代替情報を用意すること、色だけでなく色と形の両方で区別すること、文脈が分かる説明的なタイトルと凡例を含めることが含まれます。

整理の実践として、関連するダイアグラムをディレクトリにまとめること、ダイアグラムファイルに一貫した命名規則を使用すること、ソースファイル内のコメントにダイアグラムの目的を記載することを推奨します。

---

高度なパターン

MoAI-ADK との統合

このスキルは、さまざまな開発フェーズで Claude Code 内で使用できるよう設計されています。

アーキテクチャフェーズでは、moai:1-plan コマンドを使用してシステム設計図を作成し、提案するソリューションやコンポーネント間の関係を可視化します。

ドキュメント作成フェーズでは、moai:3-sync コマンドを使用して、フローチャート、シーケンス図、アーキテクチャの概要などのビジュアルドキュメントを生成します。

コードレビューの各フェーズでは、図を使ってシステム設計を視覚的に伝え、懸念事項や変更案を明確にします。

オンボーディングのプロセスでは、新しいチームメンバーがアーキテクチャ、データフロー、システムの境界を理解するための図を作成します。

よくあるアーキテクチャパターン

API アーキテクチャのパターンでは通常、C4 図を使用して、API ゲートウェイ、バックエンドサービス、データベースレイヤー、キャッシュレイヤーの関係を含むシステムコンテキストを示します。

マイクロサービスのフローパターンでは、シーケンス図を使用して、クライアントからのリクエストが API ゲートウェイを通じて各サービスやデータストアへ流れる様子を示します。

データパイプラインのパターンでは、フローチャートを使用して、抽出、変換、読み込み、検証、レポートの各段階におけるデータの流れを示します。

Context7 との統合

最新の Mermaid ドキュメントを参照するには、Context7 のライブラリ解決機能とドキュメントツールを使用してください。2025 年 12 月時点の最新安定版は Mermaid 11.12.2 です。

公式ドキュメントは、全般的なドキュメントが mermaid.js.org/intro に、API リファレンスが mermaid.js.org/config/setup/modules/mermaidAPI.html にあります。

リリースノートと移行ガイドは、Mermaid GitHub リポジトリのリリースセクションにあります。

学習リソース

公式 Mermaid サイトは mermaid.js.org にあります。図のテストに使えるインタラクティブなライブエディターは mermaid.live にあります。完全な構文ガイドは mermaid.js.org/syntax/ にあります。

21 種類すべての図の実用例については、このスキルディレクトリにある examples.md ファイルを参照してください。詳細なリファレンスドキュメントについては reference.md を、最適化の手法については optimization.md を、複雑な図のパターンについては advanced-patterns.md を参照してください。

---

相性のよいツール

このスキルは、複数のエージェントやほかのスキルと連携します。

このスキルと相性のよいエージェントには、図を用いたドキュメント作成向けの workflow-docs、SPEC 図や要件の可視化向けの workflow-spec、アーキテクチャの可視化やインターフェイスのドキュメント作成向けの design-uiux があります。

このスキルを補完するスキルには、包括的なドキュメント生成向けの moai-docs-generation、図の検証とドキュメント作成のワークフロー向けの moai-workflow-docs、アーキテクチャのドキュメントサイト向けの moai-library-nextra があります。

このスキルを活用するコマンドには、図を埋め込んだドキュメント作成向けの moai:3-sync と、ビジュアルなアーキテクチャ図を使った SPEC 作成向けの moai:1-plan があります。

重点：スキルベースの Mermaid レンダリングと MCP Playwright の統合

よくある誤った理由づけ

誤った理由づけ	実際のところ
「ASCII 図でもドキュメントには十分です」	ASCII 図はプロポーショナルフォントで崩れ、コードの変更とともにバージョン管理できません。Mermaid ならどこでも一貫してレンダリングされます。
「図を見ればわかるので、ラベルは必要ありません」	ラベルのないエッジやノードがあると、読者は関係性を推測しなければなりません。誤解を招くより、ラベルを付けるほうが簡単です。
「コードが安定してから図を追加します」	図は設計上の意思決定に役立ちます。コードが安定するまで待つと、設計した内容ではなく、実際に起きたことを図に記録することになります。
「このアーキテクチャは複雑すぎて、1 つの図には収まりません」	複雑なアーキテクチャには、1 つの巨大な図ではなく、分解した図（コンテキスト、コンテナー、コンポーネント）が必要です。
「Mermaid の構文では必要な表現ができません」	Mermaid はフローチャート、シーケンス図、クラス図、状態図、ER 図、ガントチャートに対応しています。どれも合わない場合、問題なのはツールではなく図の種類です。

注意すべき兆候

• アーキテクチャが視覚的な図なしで文章のみで説明されている
• 図のノードに、意味のある名前ではなく、1文字のラベル（A、B、C）が付けられている
• シーケンス図にエラー／失敗時の経路が含まれていない
• アーキテクチャの変更後に図が更新されていない
• コミット前に Mermaid の構文エラーが検証されていない

検証

• 図が構文エラーなしで表示される（Mermaid ライブエディターまたは Playwright で検証）
• すべてのノードに説明的なラベルが付いている（1文字や略語ではない）
• 図が現在のアーキテクチャと一致している（コード構成と照合）
• シーケンス図にエラー／失敗時の経路が含まれている
• 図が関連ドキュメントに埋め込まれている、または関連ドキュメントからリンクされている