MermaidとAIの組み合わせで発生した問題：図が正しく表示されなかった5つのパターンと対処

2026年6月22日

Shiori

この記事について

Mermaidは、テキストで記述するとフローチャートやシーケンス図などを自動生成してくれるツールです。MarkdownファイルにMermaid記法を書くだけで図が表示されるため、ドキュメントに図を入れる手段として使っています。

AIにMermaid記法を書いてもらうと、多くの場合は正しく動きますが、特定のパターンで図が正しく表示されないことがありました。この記事では、実際に発生した5つのパターンと対処方法を記録します。

ノードのラベルに括弧や記号（例：(optional) や API / SDK）を含めたところ、図が表示されなくなりました。Mermaidのパーサーが括弧を構文として解釈してしまうためです。

ラベルを引用符で囲みます。Mermaid記法では、ラベルを ["テキスト"] の形式で書くと、内部の文字列が文字としてそのまま扱われます。AIに依頼する際は「特殊文字を含む場合は引用符で囲んでください」と明示するか、生成後に確認して修正します。

処理の流れを表すフローチャートを作成したとき、矢印の向きが逆になっているノードが複数ありました。「AがBを呼び出す」という関係が「BがAを呼び出す」のように表示されていました。

AIは記法の構文は正しく書けますが、「どちらがどちらを呼び出すか」という関係の方向性は、説明が曖昧だと逆に解釈されることがあります。

依頼時に矢印の方向を「AからBへ」という形で明示します。また、生成された図を表示して確認し、方向が逆のものを個別に修正します。修正は記法の A --> B を B --> A に変えるだけなので、確認後に直す手順を取っています。

ノードのラベルに詳しい説明を入れようとして長い文章を書いたところ、図全体のレイアウトが横に広がりすぎて読みにくくなりました。

ノードのラベルは短く、補足は図の外のテキストに書くようにしました。AIへの依頼時に「ノードのラベルは10〜15文字程度にしてください」と指定すると、コンパクトな図が生成されやすくなります。

日本語のラベルを含むMermaid図で、一部の文字が正しく表示されないことがありました。特定の環境や描画エンジンによって、日本語の扱いに差がある場合があります。

まず、使用しているMermaidのバージョンと描画環境で日本語が動作するかを確認します。問題が再現する場合は、ラベルを英語に変えて日本語の説明を図の外に書く方法に切り替えました。AIに「ラベルは英語で書いてください」と指定することで、この問題を回避できます。

サブグラフ（グループ）を使って関連するノードをまとめようとしたとき、入れ子のグループが期待した構造にならないことがありました。外側のグループに入るべきノードが外に出てしまう、またはグループが重複して表示されるケースがありました。

Mermaidのサブグラフ記法は、インデントや end の位置によって解釈が変わります。AIが生成するコードは構文としては正しくても、グループの境界が意図と異なることがあります。

入れ子構造を使う場合は、生成されたコードを一度MermaidのオンラインエディタやLiveのプレビューで確認します。問題があれば、サブグラフの end の位置を修正します。複雑な入れ子が必要な場合は、最初に構造だけをシンプルに書いてもらい、段階的に追加していく方法が確認しやすいです。

AIがMermaid記法を書く際の問題は、記法の構文知識の不足ではなく、特殊文字の扱い、関係性の方向、文字量、文字コードの環境差、入れ子の境界など、細かい制約によって発生することが多いです。

生成後にプレビューで確認し、パターンに合わせた修正手順を持っておくと、対処の時間を短縮できます。