FlowBoardMermaid slop:AIが生成した図を公開前に確認して修正する方法
チーム: FlowBoardAI の支援を受けて執筆19 分で読めます要点まとめ:
- 「Mermaid slop(マーメイド・スロップ)」は、2026年に広まった呼び名で、構文としては正しいものの、読めない、あるいはまったくの嘘になっているAI生成の図を指します。この言葉は、「Figmaなし、ありきたりの角丸ボックスなし、Mermaid-slopなし」というスローガンを掲げていたプロジェクト Diagram Design から生まれ、2026年8月にはGitHubのスターが1万1,000を超えていました(explainX、2026年8月16日)。
- 問題は普及とともに大きくなりました。VS Code 1.121(2026年5月20日)は、拡張機能なしでMarkdownのプレビューにMermaidをネイティブで描画し、アシスタントはそれを標準で生成します(Visual Studio Code)。
- モデルが最適化するのは文法上の正しさであって、システムの正しさではありません。
.mmdは構文解析を通りますが、ノードが重複していたり、分岐の「いいえ」の枝が抜けていたり、データの向きが逆になっていたりします。 -->の行を読んで図を確認する方法はうまくいきません。重要な欠陥は位相(つながり方)に関するもので、描画して初めて見えます。- うまくいくサイクルは次のとおりです。
.mmdをキャンバスに取り込み、レイヤーごとに並べ替え、疑わしい点を、それを裏づけるコードやチケットへのリンク付きで注釈し、手で修正してもう一度エクスポートし、修正後の版がリポジトリに入るようにします。
2026年半ばから、エンジニアリングチームの問いは、図をどう生成するかではなく、誰がその図に責任を持つかに変わりました。エージェントはその場でMermaidを書き、GitHubとVS Codeは設定なしでそれを描画し、結果はコードブロックと同じ自然さで README に入ります。欠けているのは、監査のレイヤーです。この記事では、よくある欠陥、それが現れる技術的な理由、そして公開される図がモデルが最初に吐き出したものではなく修正後のものになるように、視覚的なキャンバス上で完結する、再現可能なレビューのサイクルを順にたどります。ここでいうキャンバスとは、AIsToHire の図のための無限ホワイトボード、FlowBoardのことで、Mermaidの取り込みと再エクスポートに対応しています。

「Mermaid slop」とは、正確には何ですか?
Mermaid slopとは、エラーなくコンパイルできるのにまったく役に立たない、AI生成の図のことです。異なる概念に同じ角丸ボックスを使い、矢印にラベルがないか曖昧で、色は何も語らない初期設定のままで、反射的に生成されています。必要だから描かれたのではなく、頼まれたから描かれたのです。この定義は、explainX によるこの言葉の解説(2026年8月16日)が示したもので、キャサリン・ラヴェリー(Cathryn Lavery)のプロジェクト Diagram Design にさかのぼります。
大切なのは、「slop」には2つの層があり、よく混同されるという点です。
| 層 | 何が悪いか | 見つけ方 | 直すコスト |
|---|---|---|---|
| 見た目 | ありきたりの図形、初期設定のパレット、すべてが同じ | ひと目で | 低い:テーマ、図形、グループ化 |
| 意味 | 図が、存在しないシステムを描いている | 実際のコードと照らし合わせたときだけ | 高い:リポジトリを開き直す必要がある |
2026年の世間の議論は、ほとんどが前者に集中しています。登場したツール(編集的な図づくりのスキルから、Mermaidのテキストではなく、Excalidrawのネイティブな要素を生成するジェネレーターまで)は、主に見た目に対処しています。図があなたのアーキテクチャについて嘘をついてしまう、後者の層は、依然として人間の仕事です。
なぜLLMは、構文は完璧でも意味は乏しいMermaidをつくるのですか?
2つの目的は別のもので、訓練のシグナルが豊富なのは片方だけだからです。Mermaidの文法は閉じていて小さく、GitHub上に大量にあるので、モデルはほとんど間違えずに再現できます。一方、図の正しさは、モデルが通常は全体を読んでいない具体的なシステムに左右されるので、あなたのものではなく、アーキテクチャ図で最もよくある形で空白を埋めてしまいます。
これに、3つの実際的な影響が重なります。
- プロンプトが唯一の情報源です。 システムを3つの文で説明すれば、エージェントは3つの文の粒度の図を返し、完成して見えるまで飾り立てます。Mermaid自身が vibe diagramming について述べているとおり、「曖昧なプロンプトから生成された図は、プロンプトの曖昧さを映し出す」のです(Mermaid、2026年3月24日)。
- 意味のコンパイラがありません。 失敗したテストは警告してくれますが、間違った図も、正しい図と同じようにきれいに描画されます。「このサービスは存在しない」を教えてくれる、
tscに相当するものはありません。 - レイアウトを決めるのはエンジンであって、作者ではありません。 Mermaidは自分のアルゴリズムでノードを配置し、描画後に配置を修正する便利な手段を提供してくれません。実際の階層構造が自動レイアウトの描くものと一致しなければ、ツールとの議論には負けてしまいます。
そして、業界の状況は、検証が任意ではないことを示しています。Stack Overflow の2026年開発者調査(2026年10月6日公開、169か国から3万件超の回答)では、約半数が、AIの出力を簡単に検証できるときだけ信頼しており、重要な判断でそれをそのまま受け入れるという人は、わずか6.6%でした。公式ドキュメントにあるアーキテクチャ図は、ほぼ定義上、重要な判断です。
AI生成の図に繰り返し現れる7つの欠陥
エージェントが生成した .mmd を監査していると、この7つが何度も現れます。どれも構文解析は通りますが、どれも間違っています。共通するパターンは、モデルが、ドメインの情報が足りないところに、もっともらしい構造を埋めることです。

| # | 欠陥 | .mmd に現れる症状 | 結果 |
|---|---|---|---|
| 1 | 重複ノード | 同じサービスに、似たラベルで別々のIDが2つある | 実際は1つのところに、コンポーネントが2つあるように見える |
| 2 | 「いいえ」の枝がない分岐 | 出る矢印が1本だけのひし形 | エラーの経路が文書化されないままになる |
| 3 | 終端のないフロー | 処理ノードで終わる連なり | ユースケースがいつ終わるのかがわからない |
| 4 | 向きが逆 | 矢印がデータの出どころを指している | 誰が誰を呼ぶのかが逆になる |
| 5 | 汎用ボックス | 「データベース」という単一のノード | 保証の異なる3つのストアが隠れてしまう |
| 6 | 偽の階層 | コードに存在しないレイヤーや subgraph | でっち上げのアーキテクチャに権威を与える |
| 7 | プロンプト由来のラベル | ノードがドメインの用語ではなく、あなたの言葉を繰り返している | 図が検索できず、見てもわからない |
1. 同じサービスなのに、重複したノード
モデルは、2つの別々の文で「auth」と「認証サービス」を見かけて、ノードを2つつくってしまいました。
flowchart LR
API[API Gateway] --> AUTH[Auth]
API --> AUTHSVC[認証サービス]
AUTH --> DB[(データベース)]
AUTHSVC --> DB
修正後:ノードは1つ、IDは1つ、チームが使っている名前にします。
flowchart LR
API[API Gateway] --> AUTH[auth-service]
AUTH --> USERS[(postgres: users)]
2. 「いいえ」の枝がない分岐
flowchart TD
REQ[リクエスト] --> Q{トークンは有効?}
Q -->|はい| OK[処理する]
出口が1つだけのひし形は、分岐ではなく飾りです。すべての条件には2つの経路が必要で、エラーの経路にも行き先が必要です。
flowchart TD
REQ[リクエスト] --> Q{トークンは有効?}
Q -->|はい| OK[処理する]
Q -->|いいえ| R401[401を返す]
OK --> FIN([終了])
R401 --> FIN
3. データの向きを逆にする矢印
キューやWebhookでよくある例です。モデルは、実際のフローではなく、組織の階層を描いてしまいます。
flowchart LR
WORKER[Worker] --> QUEUE[ジョブキュー]
ワーカーはキューにプッシュするのではなく、キューから取り出します。この向きを間違えて描くと、プル型の設計がプッシュ型になり、保証の違う別のシステムになってしまいます。
flowchart LR
API[API] -->|エンキュー| QUEUE[ジョブキュー]
QUEUE -->|取り出し| WORKER[Worker]
4. 汎用ボックス「データベース」
これは最もコストの高い欠陥です。図を開く人が求めているまさにその情報が消えてしまうからです。実際にはトランザクション用のPostgres、セッション用のRedis、添付ファイル用のS3であるものを、1つの [(データベース)] ノードにしても、文書化にはなりません。隠すだけです。実践的なルールは、2つのストアの耐久性の保証が違うなら、ノードは2つにすることです。
5、6、7:でっち上げのレイヤーと借り物のラベル
「プレゼンテーション層」「ビジネス層」「データ層」という名前の subgraph は、たいていモデルの頭の中のテンプレートであって、あなたのリポジトリの構造ではありません。ラベルも同じです。ノードが「決済処理モジュール」という名前でも、コードでは billing-worker であれば、誰も図とプロジェクトを突き合わせることができません。そして終端がなければ、読み手は、フローがそこで終わりなのか、モデルが途中でやめたのかがわかりません。
なぜ、図をテキストで確認する方法はうまくいかないのですか?
重要な欠陥は位相に関するもので、テキストには現れないからです。A --> B の行の一覧を読めば、それぞれの辺がもっともらしいかどうかは1つずつ確認できますが、2本の矢印が交差していること、ノードが孤立していること、階層が逆になっていること、3ステップの循環があることには気づけません。こうした性質は、グラフが描かれて配置されたときにだけ見えます。

もう1つ、より微妙な理由があります。.mmd を読むときは作者が書いたものを確認しており、描画を見るときは読み手が理解するものを確認しています。この2つは別のものです。15本の正しい辺があっても、自動レイアウトがそれらを密集させている図は、技術的には正しく、伝達の面では壊れています。そして、「mermaidブロックは正しい形式だから」と、プルリクエストのレビュアーが見ずに承認してしまうのが、まさにそうした図です。
業界自体も、その方向に動いています。Anthropicは2026年11月10日に Claude Whiteboards をベータ版で公開しました。アシスタントが議論をボードに変換し、メモをテーマごとにグループ化して、そのあとLucid、Miro、Zoho の Vani に持ち出せる、リアルタイムのキャンバスです(unite.ai)。そして Miro は、イベント Canvas 26 で、自社はもう「ホワイトボードのビジネスをしていない」と述べ、「エージェント型企業のための共同意思決定レイヤー」になりたいと表明しました(Forrester、2026年6月1日)。AIの自然な出力先は、テキストのブロックではなくキャンバスになりつつあります。図を監査する人にとってこれは朗報です。レビューは、形が見える場所で行うべきものだからです。
レビューのサイクル:.mmd からキャンバスへ、そして .mmd に戻る
このサイクルは5つのステップからなり、重要な特性は閉じていることです。リポジトリに入るのは、エージェントが出した元の図ではなく、キャンバスで修正された図です。修正がスクリーンショットやプルリクエストのコメントにとどまるなら、誤った .mmd が残り、次のエージェントに再び入力されてしまいます。

- 取り込む。 エージェントが出した
.mmdを視覚的なキャンバスに貼り付けるか、ファイルとして読み込みます。目的は、レビューをコードエディタから切り離すことです。コードエディタでは、見るのではなく読んでしまいがちだからです。 - 配置して並べ替える。 ノードを、責務ごとの水平なレイヤー(入口、オーケストレーション、ドメイン、ストレージ)に配置します。向きの誤りや偽の階層といった欠陥のほとんどは、ここで露呈します。2つのレイヤーを上がる矢印は、たいてい逆向きの矢印です。
- 疑わしい点にマークを付ける。 コードを読んでも確認できないノードやコネクタには注釈を付け、その注釈には証拠へのリンク(ファイル、チケット、ADR)を付けます。監査された図とは、疑いのない図ではなく、疑いにラベルが付けられ、たどれるようになっている図です。
- 手で修正する。 重複ノードを統合し、汎用ボックスを実際のストアに分け、「いいえ」の枝を追加し、終端で閉じ、ひし形がひし形に、ストアがシリンダーになるよう図形の種類を変更し、コネクタを正しい点につなぎ直します。
- 書き戻してエクスポートする。 結果を
.mmdとして出力し、レビューと同じコミットで、リポジトリの元のファイルを置き換えます。ほとんどのチームが飛ばしてしまうのがこのステップで、誤りの再発を防ぐのもこのステップです。
実際には、ステップ3が、これをレイアウト作業ではなくエンジニアリングのプロセスにします。ワーカーがキューから取り出していることを証明する具体的なファイルへのリンクが付いた横のメモは、検証できる文書です。Slackのスレッドの「この矢印は逆だと思う」は、そうではありません。
チェックリスト:AI生成の図をマージする前の10項目
プルリクエストのテンプレートに貼り付けることを想定した、閉じたリストです。どれか1つでも満たさないなら、その図は入れません。
- 一意性: 実在するコンポーネントが、2つのノードとして現れていない。サービスごとに1つのID、リポジトリまたはデプロイ上の名前を使う。
- 分岐の完全性: すべてのひし形に、ラベル付きの出る辺が少なくとも2本あり、エラーの枝に行き先がある。
- 終端: すべての経路が、明示された終端ノードで終わっている。処理のステップで途切れる連なりがない。
- データの向き: すべての矢印が、組織の階層ではなく、情報が流れる向きになっている。特にキュー、Webhook、ポーリングを確認する。
- ストアの分解: 「データベース」「サービス」「インフラ」のような汎用ボックスがない。ストアごとに1つのノードで、技術と内容を示す。
- 実際のレイヤー: すべての
subgraphが、実在する境界(デプロイ、リポジトリ、アカウント、ネットワーク)に対応しており、教科書的な抽象ではない。 - ドメインの用語: ラベルが、プロンプトの言葉ではなく、チームがコードやチケットに書く名前を使っている。
- 孤立と避けられる交差がない: つながっていないノードがなく、残っている交差には正当な理由があり、並べ替えで解消できるものではない。
- 公開するサイズで読める:
READMEやドキュメントポータルの幅で理解でき、ズームしなくてよい。 - 追跡可能性: 自明でないすべての要素に、それを裏づけるコード、チケット、ADRへのリンク付きのメモがあり、リポジトリの
.mmdは修正後にエクスポートしたものである。
仕様駆動開発:図が間違っていれば、コードもその誤りを受け継ぐ
これが、2026年に監査が見た目だけのものではなくなった理由です。仕様駆動開発では、アーキテクチャ図やシーケンス図のMermaidを含むMarkdownの仕様が、エージェントが実装を生成する元となる成果物であって、実装についてのコメントではありません。その仕様の中にある誤った図は、もはや古くなった文書ではなく、コード生成器への欠陥のある入力です。
この考え方は、GitHubのSpec Kit 自身に示されており、その主張は「仕様はコードに仕えるのではなく、コードが仕様に仕える」というものです。そこで生成される実装計画には、データモデルや障害モードとともに、Mermaidによるアーキテクチャ図やシーケンス図が含まれます。
日々の仕事に置き換えると、仕様の中の「いいえ」の枝がないひし形は、生成されたコードで、おそらくエラーのケースが実装されていないということです。APIとキューの間の逆向きの矢印は、プルにしたかったところがプッシュの設計になっているということです。そして、Postgres、Redis、S3を覆い隠していた「データベース」ボックスは、3つの責務を持つ単一のリポジトリになってしまいます。図は、システムの写真であることをやめ、設計図の一部になりました。そして、設計図はレビューされるものです。
よくある質問
「Mermaid slop」とは、どういう意味ですか?
構文としては正しいMermaidで書かれているものの、伝達の価値がないAI生成の図のことです。同じようなありきたりの図形、初期設定のパレット、ラベルが誤った矢印、そして最悪の場合は、システムに存在しないコンポーネントや関係が含まれます。この言葉は、プロジェクト Diagram Design から広まり、2026年8月のexplainX の解説に記録されています。
AI生成のMermaid図を自動で検証できますか?
一部だけです。リンターやパーサー自体が構文エラーを検出し、構造的なチェックは自動化できます。孤立したノード、出口が1つだけのひし形、終端のない経路、疑わしいほど似たラベルを持つIDなどです。どのツールも単独では確認できないのは、図があなたのシステムを描いているかどうかです。それにはコードとの突き合わせが必要で、そのためこの記事のチェックリストには、自動化できる確認と人によるレビューが混在しています。
プルリクエストでmermaidブロックを確認するだけでは、なぜ足りないのですか?
差分では辺を1本ずつ読むことになりますが、重要な欠陥はグラフ全体のものだからです。交差、逆転した階層、循環、孤立したノード、読めないほどの密度などです。さらに、テキストを読むときは、作者の意図を評価しているのであって、描画を見る読み手が目にするものではありません。役に立つレビューは、描かれた図の上で行います。
Mermaid図を手で修正するには、どのツールを使えばよいですか?
往復の全体をこなせるキャンバスが必要です。.mmd を取り込み、図形やコネクタを動かしたり変更したりでき、要素に注釈を付け、再びMermaidにエクスポートできることです。この最後のステップがあるために、描画はできても修正したコードを返してくれない、ほとんどのビューアーは除外されます。FlowBoardはこのサイクルをカバーしています。ファイルから、またはコードを貼り付けてMermaidを取り込み、ズームと移動ができる無限のキャンバスに図を配置し、図形、コネクタ、アンカーをアンカーポイントへのスナップ付きで手で修正でき、要素ごとにリンク付きの横のメモを追加して、Mermaidに書き出せます。
AI生成の図を監査するのに、どのくらい時間がかかりますか?
大きさによりますが、15〜25ノードの図なら、初回は20〜40分程度が目安で、チームがチェックリストを身につけ、ドメインの名前が固まれば、ずっと短くなります。間違ったアーキテクチャが公式ドキュメントに入ってしまうコスト、あるいは仕様駆動のフローでは、それが生成されたコードに入ってしまうコストと比べれば、安いものです。
図づくりにAIを使うのはやめるべきですか?
いいえ。エージェントで最初の下書きを生成すれば、ノードや辺を打ち込む退屈な作業を省けますし、知らないシステムを探るのにも役立ちます。飛ばしてはいけないのは、その次のステップです。AI生成の図は、キャンバスとチェックリストを通さずに公開してはいけません。AIは下書きを担当し、図に対する責任は、署名するチームにあります。
おわりに:公開する図は、監査した図です
2026年の変化は、AIが図を描くことではなく、私たちがレビューするよりも速く描くことです。VS Codeが設定なしでそれを描画し、Claudeがそれをボードに変え、Markdownの仕様がコード生成器の入力になる中で、残る唯一の品質管理は人によるものです。形を見て、証明できないものにマークを付け、修正した版をリポジトリに戻すこと。10項目のチェックと、閉じたサイクルがあれば、図は、もっともらしい飾りではなく、信頼できる文書に戻ります。
そのサイクルが行われる場所が必要です。AIsToHire では、図のための私たちの無限ホワイトボード FlowBoardでそれを実現しています。エージェントの .mmd を貼り付けるか取り込み、無限のキャンバスに配置し、図形(長方形、楕円、分岐のひし形、ドキュメント、付箋、テキスト)とコネクタ(直線または直交の矢印)を並べ替え、要素のアンカーポイントへのスナップで各接続を固定し、疑わしい点を横のメモと検証用のリンクで注釈し、Mermaidに書き出します。ボードは自動で保存されるので、監査は記録に残り、あとで再開できます。
FlowBoard を開き、エージェントが出した .mmd を貼り付けて、図が実際に見える場所で監査しましょう。レイヤーごとに並べ替え、図形やコネクタを手で修正し、疑わしい点を検証リンク付きで注釈して、Mermaid に書き出せます。最初のボードを無料で始めましょう。
FlowBoard を開き、エージェントが出した .mmd を貼り付けて、図が実際に見える場所で監査しましょう。レイヤーごとに並べ替え、図形やコネクタを手で修正し、疑わしい点を検証リンク付きで注釈して、Mermaid に書き出せます。最初のボードを無料で始めましょう。


