Mermaid ダイアグラム：エンジニア向けAIネイティブなダイアグラム作成

要点

Miro の Structured Diagrams with Mermaid のプロダクトマネージャー、Hannah Knight です。ここでは Mermaid ダイアグラムとは何か、Miro にネイティブな Mermaid サポートを導入した理由、そして実際の使い方を説明します。この機能は公開ベータ段階にあるため、現時点で動作する点と、まだ対応中の点を率直にお伝えします。 実際の動作を見る：1つのプロンプトで、コードベースからインシデント全体をマップし、すべてのサービスとそれらの間の呼び出しを表示します。チームは色分けして障害箇所を示し、図に直接コメントして修正案を検討し、その後エージェントに戻して、エージェントが決定内容を GitHub のプルリクエストとして下書きします. 

Mermaidの正体

Mermaid ダイアグラムは、すべてテキストで記述された図です。A --> B のように書くと、A と B の2つのボックスが矢印でつながった図が得られます。それだけです。フローチャート、シーケンス図、クラス図、エンティティ・リレーションシップ図（ER図）など、ほとんどあらゆる種類の図を表現できます。

エンジニアは長年、図をコードベースに保管し、説明対象のコードのすぐ隣に置いてきました。しかし最近、この手法が注目を集め直している理由は単純です。大規模言語モデルが Mermaid 構文の記述を得意としているためです。AI コーディングエージェントにシステム図の作成を依頼すると、学習の結果、Mermaid 構文を返してくる可能性が高くなっています。

人間とAIの双方が読み書きできるコードというその組み合わせこそが、MiroにMermaidのサポートを直接組み込んだ理由です。

よく聞かれた課題

これを実装する前から、Mermaidは顧客との通話やユーザーインタビューで、特に促さなくても繰り返し話題に上っていました。エンジニアは、AIに図を生成させる際に画像ではなくMermaidを指定したほうが品質が高くなることにすでに気づいていました。図は常にエンジニアが複雑なシステムを簡潔に説明するための中核であり、MermaidとAIの組み合わせにより、手作業よりも短時間で高品質な図を生成できるようになりました。

「図を単なる画像ではなくコードとして扱う」という区別は、2つの理由で重要です。図が画像としてしか存在しない場合、エンジニアはコードと同じように変更を追跡できません。もう1つのより技術的な理由は、入力の処理方法により、大規模言語モデルは二次元の画像より一次元のテキストをはるかに理解しやすいという点です。図がコードであれば、AI エージェントは全体を一から再生成するのではなく、正確で目的に沿った編集ができます。

以前のツールでは、まさにこの状況を何度も目にしてきました。コードベースが変わると図が古くなり、Miroを開いて実際に変わった箇所に合わせて図形やボックスを手動で移動し、変更を記録します。それに数時間を費やすこともあります。

コーディングエージェント（例：Claude Code）にコードベースのダイアグラムの生成を依頼すると、Miroのボード上に自動で美しくレンダリングされます。コードの変更が頻繁な場合は、ボードを定期的に更新するスケジュールされたスキルを設定することもできます。

Mermaid を使った構造化ダイアグラムの開発理由

Structured Diagrams with Mermaid により、コードで定義する図（diagram-as-code）を直接 Miro に取り込めます。Mermaid 構文を記述または生成すると、実際の Miro の図形としてレンダリングされ、チームで共同編集して反復でき、作業が完了したら再びコードへエクスポートできます。完全なラウンドトリップ機能です。エージェントが Miro の MCP サーバーを通じて図を生成し、チームが視覚的に共同作業を行い、別のエージェントが MCP を介して読み取ってコードベースの同期を維持できます。

Mermaid が一元的な情報源です。Miro 上で図を視覚的に編集すると、背後にある Mermaid コードも更新されるため、コードと図が乖離することはありません。ボードに配置された図を別物として扱い（リンクを切り）、そのまま独立したオブジェクトにすることも可能で、いくつかの他ツールはその方法を採用していますが、本機能ではそうしていません。Mermaid を一元的な情報源として維持することで、AI エージェントが常に図を理解して正確に編集でき、GitHub、VS Code、Obsidian、または Mermaid を読み取れる他の任意の場所へエクスポートできます。

これは Miro マーケットプレイスの旧来の Mermaid アプリを完全に置き換えます。 そのアプリは自由形式の図形を生成するだけで、Mermaid 本来の形式ではなく、ラウンドトリップ（往復同期）もできませんでした：エージェントが図を生成しても、その編集内容を読み取ることができませんでした。 Structured Diagrams with Mermaid は両方を実現します。

図を生成したときの流れ

簡単に言うと、ラウンドトリップの流れは次のとおりです：Mermaid の構文を Miro ボードに貼り付けると、図がすぐに描画されます。 Claude Code、Claude Cowork、Codex、Cursor などの AI エージェントに図の生成を依頼すると、Miro の MCP サーバーを通じて同じ Mermaid 構文がボード上に直接書き込まれます。 どちらの場合も、図はレンダリング済みの完成形で表示され、手直しが必要な下書きとして出てくることはありません。

ネイティブの Miro 図形として描画されるダイアグラムの種類

現在、4 種類のダイアグラムがネイティブの Miro 図形として描画されます。

• フローチャートはワークフロー、決定木、プロセスを可視化し、どこで処理が停滞する可能性があるかを正確に把握できます。
• シーケンス図はシステムやコンポーネントが時間経過に沿ってどのようにやり取りするかを示し、マイクロサービス間の通信やAPI呼び出しの順序を把握するのに便利です。
• クラス図はオブジェクトとその属性、そして相互の関係性を可視化します。
• エンティティ・リレーションシップ（ER）図はデータベースのスキーマとテーブル間の関連を表します。

これら4種類は初期状態で見栄えが良くなるよう重点的に調整しており、余分な書式作業なしでプレゼン用の体裁が整った図が得られます。

Mermaid は、システムアーキテクチャ向けのガントチャートや C4 ダイアグラムを含む多くのダイアグラムタイプをサポートしています。これらは現在、ネイティブな Miro 図形ではなく、Mermaid.js による SVG としてレンダリングされます。ボードに追加し、AI で編集してエクスポートすることは可能ですが、見た目がそのままプレゼンに使えるレベルにはならず、フローチャートのようにクリックして視覚的に編集することはできません。チームで評価する場合、その違いは重要です。現在ネイティブ編集に対応しているダイアグラムと、主に閲覧やエクスポート用になるダイアグラムを把握しておいてください。

Miro での Mermaid ダイアグラムの始め方

実際の利用イメージは次のとおりです。

1. 作成バーを開き、フォーマットを選択してからダイアグラムを選び、「コードで作成」をクリックします。
2. 既存のMermaidコードを貼り付けるか、テンプレートを選ぶか、エージェントにプロンプトを1つ送ってコードベースからダイアグラムを生成させ、数秒でサービスとそれらの間のすべての呼び出しをマッピングします。
3. ネイティブなMiro図形としてレンダリングされ、自動で整列されるため、線が交差しないように図形の間隔を手動で調整する必要がありません。
4. フォーカスモードでダイアグラムを開き、編集します。図形、線、テキストラベルを選択して直接調整したり、レイアウトの方向（上から下、左から右など）を変更したり、間隔を狭くしたり広くしたりできます。コードパネルを開いてMermaid記法を直接編集することも、ダイアグラムのリンクをAIツールに貼り付けてエージェントに変更を依頼することもできます。どの方法で編集しても、Mermaidコードとダイアグラムは同期したままです。
5. 図に意味を持たせます。ステータスやインシデントを色分けで示すか、エージェントに変更を依頼できます。エージェントが図を編集すると、追加・削除・変更した箇所を示す凡例を付けることもできます。
6. チームを招待して、現在の状態や提案している修正・変更の文脈で図上に直接コメントしてもらえます。別の場所で別スレッドを立てる必要はありません。
7. 作業を完結させます。Mermaid の構文をコードベースにコピーしたり、図を画像（JPG、SVG、PDF）としてエクスポートしたり、コラボレーターとフォーカスモードのリンクを共有したり、エージェントに図とチームのコメントを MCP 経由で読み取らせて、アーキテクチャ決定記録のようなドキュメントを下書きし、プルリクエストとして開ける状態にすることもできます。

すでに Mermaid の構文に慣れている場合は、そのまますぐに書き始められます。Mermaid を触ったことがない場合は、テンプレートから始める、図形を視覚的に編集する、あるいは AI エージェントに望む内容を伝えて構文を書かせるなどで試してみてください。補足として、Enterprise プランを利用している場合は、チーム内の誰もが AI ツールを接続できるようにするために、会社の管理者が事前に Miro MCP を有効にしておく必要があります。

導入初期に陥りがちな誤り

通常の Miro キャンバスのように図形を自由にドラッグして移動しようとしても、うまく動作しません。これらはコードで裏付けられているため「structured」ダイアグラムと呼んでおり、Miro が自動的にレイアウトしてくれることが大きな利点の一つです。もし本当に図形を増やしたり完全に自由な移動が必要な場合は、ダイアグラムをフリーフォーム編集に切り替えることができますが、これは一度切り替えると元に戻せない変更です。一度フリーフォームにすると、そのダイアグラムは Mermaid コードと同期しなくなり、MCP 経由で編集することもできなくなります。まだ判断がつかない場合は、まず Structured Diagrams の多くの機能を試すか、元の図を変換する代わりにコピーをフリーフォームで編集して試してみてください。

Mermaid の書き方に「これが正解」という唯一の方法はありません。最初のダイアグラムは悩みすぎずにまず形にし、それから反復して改善するとよいです。編集は手作業でもチームメンバーによる修正でも、エージェントが引き継いで更新する流れでも構いません。

大規模での性能

Mermaidファイルは最大30,000行までサポートしており、複雑なフローチャートで500以上のノードを含む図でもパフォーマンスに低下は見られないことを確認しています。ボード上に配置できるMermaid図の数に厳密な上限はありません。

既存ツールとの連携

他のツールがMermaid構文をエクスポートできる場合、そのままMiroのボードに貼り付けできます。図をバージョン管理したい場合は、Markdownまたは.mmdファイルとしてエクスポートしてリポジトリにコミットすれば、他のコードと同じようにバージョン管理できます。エージェントが図を生成してエクスポート、コミットし、コードの変更に応じて自動的に更新するワークフローを構築でき、手作業を介さず運用できます。

Mermaid図の事例と活用

抽象的な説明だけでは役に立たないため、実際にチームがどのように活用しているかを以下に示します：

アーキテクチャのオンボーディング

先四半期から更新されていない Wiki ページを新しいエンジニアに渡す代わりに、エージェントにコードベースから現在のマイクロサービス アーキテクチャを図示させます。実際に稼働している構成を反映した図が得られ、半年前の状態とは異なります。

スキーマ変更のレビュー

大規模な移行の前に、新しいスキーマの ER 図を生成し、レビュアーがテキスト差分を読み解く代わりに構造的な変更を一目で把握できるようにします。

インシデントの一連の振り返り

障害発生時に、影響を受けたサービスをコードベースから直接図示します。失敗箇所やその理由を色分けや注釈で示し、チームに図上で直接コメントしてもらって対応を詰めます。チームで合意したら、エージェントにMCP経由で図とコメントを読み取らせ、アーキテクチャ決定記録（ADR）のような決定文書の下書きを作成してプルリクエストとして提出できる状態にします。

API のドキュメント化

サービス呼び出しのシーケンス図を生成し、Mermaid のソースをリポジトリに保管しておけば、API が変更されるたびにエージェントに更新させることで、毎回のリリースで手作業で描き直す必要がなくなります。

構築前のデータモデル設計

データモデルがまだ構想段階にあるうちに、ER 図やクラス図を早期にスケッチしておくとよいです。マイグレーションを書いた後で問題ある関連付けに気づくより、図で早めに見つけるほうがはるかにコストが低く済みます。

プルリクエストのレビュー

プルリクエストをレビューする際は、エージェントにコードの変更前後を示す Mermaid 図を生成させて、素早く把握できるようにしましょう。AI の導入によりエンジニアはこれまで以上に多くのコード変更をレビューするようになっており、視覚化によりそのプロセスを高速化できます。

Mermaid 図のベストプラクティス

AI による初稿作成

エージェントが既にコードベース、要件、または既存のドキュメントなどのコンテキストを持っている場合は、Mermaid の構文を手で書くよりも図を生成するよう依頼してください。そこから調整してください。

視覚的に編集できる範囲の見極め

フローチャートが現時点で最も柔軟な図種です。シーケンス図、クラス図、ER図はネイティブに描画され見映えも良いですが、視覚的編集がそれらに対応するまではコード優先で扱ってください。

フィードバックを図上に集約

Slack やメールで別スレッドを立てるのではなく、図に直接コメントしてください。意思決定と文脈が一箇所にまとまり、エージェントがMCPを通じて会話全体を読み取れるようになります。

図のバージョン管理（コードと同様）

Markdown または .mmd としてエクスポートしてコミットしてください。小さな習慣ですが、図の履歴がコードの履歴と同じだけ信頼できるものになります。

不足点の報告

レンダリングの問題に遭遇した場合、あるいはまだ視覚的に編集できない図の種類が必要な場合は、その旨をお知らせください。これはベータ版で、そうしたフィードバックが今後のリリースに反映されることを目的としています。

ベータ版の現状

これは公開ベータであり、現状を正直にお伝えします。現時点で視覚的編集が機能するのはフローチャートのみです。シーケンス図、クラス図、ER図はネイティブ図形として表示されますが、同じクリックして編集する視覚的ワークフローにはまだ対応していません。視覚的編集とコードパネルは、キャンバス上の分割表示ではなく、フォーカスモードでのみ動作します。図形のドラッグ＆ドロップはまだ導入中のため、現時点では既存の図形のプラスボタンで図形を追加するか、コピー、貼り付け、複製で追加してください。

今後、特に期待していること：

• サイドキックやフローを通じて Mermaid 図を直接生成・反復し、ボード上のフリーフォーム図をそのまま Mermaid として読み取る機能
• ER 図とクラス図の視覚的編集
• ネイティブな Mermaid ファイルへのエクスポート
• コードのエラーを検出・修正しやすくする改善と、より快適なコード作成体験
• エージェントが実際に読み取れるコメントや注釈
• スイムレーンを含む、より幅広いレイアウト対応

全体像

これは単なる図の話にとどまりません。エージェントが静的な出力を渡して去るだけ、という形ではなく、AIエージェントと人間が同じキャンバス上で共同作業する実例です。Mermaidが可搬性を保っているため、Miroで行った編集はエージェントが読み取り、それを基に作業を続けられます。エージェントは既に人が微調整した図を受け取り、全体を再生成して追加した詳細を失うのではなく、必要な箇所だけを正確に変更できます。

1年後には、エンジニアがMiroを単に一度作成された図を保管する場所としてではなく、技術アーキテクチャの共有・協働・洗練に実際に組み込まれたワークフローの一部として利用している状態を目指しています。

結論は一つです：コードベースから数秒で図を生成できるようになると、手で描き直す作業には戻れなくなります。

試す準備はできましたか？作成バーを開き、ダイアグラム作成を選択して、最初のMermaid ダイアグラムを今すぐ作成してみてください。