はじめに：なぜ私たちは「お絵描き」に時間を溶かすのか
仕様書の図解作成において、PowerPointや作図ツールでの表現に苦労するケースは少なくありません。
頭の中には「ここでAPIを叩いて、レスポンスを待って、DBに書き込む」といった完璧なシーケンス図があっても、それをツールで表現しようとした瞬間、泥沼にはまることがあります。
「矢印が微妙にずれている」「箱のサイズが揃わない」「レイアウトを調整していたら、肝心のロジック修正を忘れた」
気付けば、コードを書くべき貴重な時間の半分を「四角形と直線の整列」に費やしている。そして苦労して作った図も、仕様変更のたびに「またパワポを開いて修正するのか……」という心理的ハードルから放置され、いつしか実態と乖離した「嘘のドキュメント」が出来上がる。
開発の現場において、似たような光景は頻繁に見受けられます。
「図解が必要なのは痛いほど分かっている。でも、メンテナンスコストが高すぎる」
このジレンマへの回答が、今回ご紹介する「Mermaid.js × LLM」による図解自動生成パイプラインです。
画像生成AIに絵を描かせるのではなく、図を「コード」として生成し、Gitでバージョン管理と改善のサイクルを回すのです。
本記事では、対話AIの設計やシステム開発の実務で活用されている、「ユーザーの要件や言葉による説明」を「構造化されたコード」へ自動変換するワークフローを解説します。抽象的な概念をエンジニアリング可能な形に落とし込み、チーム全体の「説明コスト」を劇的に下げる仕組みを構築していきましょう。
1. 図解解説パイプラインの全体像と導入メリット
まず、本ガイドで目指すゴールの全体像を共有します。なぜ今、多くの開発組織が直感的なUIを持つ描画ツールから、あえてテキストベースの「Diagrams as Code」へシフトしているのか。その戦略的意義を理解することが、導入成功の第一歩です。
なぜ「画像生成」ではなく「コード生成」なのか
生成AIの活用というと、Midjourneyの最新版やChatGPTの画像生成機能を使って華麗な図版を作成することを想像するかもしれません。確かに、最新の画像生成モデルではテキスト描画能力が向上し、ドラフトモードによる試行錯誤も効率化されています。しかし、技術ドキュメントや厳密な業務フロー図において、画像生成AIのアプローチは依然として以下の課題を抱えています。
- 文字情報の制御難度: 画像内のテキスト修正や微調整には、再生成や画像編集ソフトでの加工が必要となり、手軽ではありません。
- メンテナンスの断絶: 「処理Aと処理Bの間に処理Cを追加したい」といった構造的な変更が発生した際、画像全体を再生成する必要があり、以前のレイアウトを完全に維持することが困難です。
- 検索性の欠如: 画像化された情報はgrep（テキスト検索）の対象外となり、ナレッジベース内での検索性が低下します。
対して、Mermaid.jsのような作図ライブラリを使用し、LLMにその「ソースコード」を書かせるアプローチには、エンジニアリング組織にとって計り知れないメリットがあります。
- 完全な再現性と修正容易性: コードを1行書き換えるだけで、レイアウトや文言を即座に修正できます。
- Git管理が可能: 図の変更履歴（Diff）をコードとして追跡できるため、「いつ、誰が、なぜ図を変更したか」が明確になります。
- スタイルの統一: CSSやテーマ設定により、個人のセンスに依存せず、組織のトーン＆マナーに沿った図が自動的に出力されます。
LLM×Mermaid.js×ナレッジベースの統合アーキテクチャ
今回構築するフローはシンプルですが、強力なパイプラインです。
- Input: エンジニアやPMが「用語」や「概念」、「対話フロー」などを自然言語で入力。
- Processing (LLM): ChatGPTやClaudeの最新モデルが、概念を構造化し、Mermaid記法に変換。
- Output (Code): Mermaidのテキストコードが出力される。
- Rendering: Notion、GitHub、VSCode、Confluenceなどの対応ツールがコードを読み取り、自動的に図として描画。
この流れを作ることで、専用の作図ツールを立ち上げる手間すら不要になります。エディタから離れることなく、思考の流れをそのまま図解化できるのです。
期待されるROI：作成時間90%削減とメンテナンス性の確保
手作業で対話フローやシーケンス図を作成する場合、レイアウト調整（箱の配置や線の重なりの解消）に多くの時間を費やしていませんか？ 一般的に、作図時間の約7割はこの「整える作業」に費やされていると言われます。
Mermaid.jsは自動レイアウト機能を持っているため、論理構造さえ記述すれば、見た目は自動的に最適化されます。LLMを使えば、その記述すら自動化できるため、人間が行うのは「生成された図の論理チェック」だけになります。
これにより、1枚あたり30分かかっていた作図作業が、わずか3分（生成1分＋確認2分）程度に短縮されることが期待できます。さらに重要なのは、仕様変更があった際に「図を書き直すのが面倒だから古いまま放置する」という事態を防げる点です。コードを数行直すだけで最新化できる環境こそが、生きたドキュメントを維持する秘訣なのです。
2. 前提環境とツールチェーンの準備
概念は理解いただけたと思います。ここからは、このパイプラインを手元で動かすための「道具」を揃えていきましょう。特別な高額ツールは必要ありませんが、ツールの選び方一つで効率が大きく変わります。
必要なAPIとアカウント設定（OpenAI / Claude 等）
まず、図解コードを生成するための「頭脳」となるLLMです。ここでの選定基準は「論理的整合性」と「構文の正確さ」です。
- 推奨モデル: ChatGPT または Claude の最新上位モデル
- これらは複雑なMermaid構文を正確に出力する能力に長けています。特にClaudeの最新モデルでは、「Artifacts」機能により、生成されたMermaidコードをチャット画面上で即座に図としてレンダリング（描画）して確認できます。コードをコピペして別のツールで確認する手間が省けるため、試行錯誤のスピードが段違いです。
- GitHub Copilotの活用: 開発者の皆さんには、GitHub Copilotも強力な選択肢です。特に「Copilot Chat」の最新機能では、
@workspaceコマンドを使ってプロジェクト内の仕様書やコード全体をコンテキストとして読み込ませ、「この仕様変更を図に反映して」と指示を出すことが可能です。エディタから離れずに完結するフローは、開発効率を大きく高めます。 - 注意点として、無料版や軽量モデル（miniモデルなど）は、複雑な図になると構文エラー（Syntax Error）を起こしやすい傾向があります。業務で安定した出力を求めるなら、推論能力の高い上位モデルの利用を強く推奨します。
作図レンダリング環境の選定（VSCode, Notion, GitHub）
生成されたMermaidコードを「見る」ための環境です。組織ですでに使っているツールが対応しているか確認してください。最近は標準対応しているツールが増えています。
- Visual Studio Code (VSCode)
- エンジニアなら必須の環境です。拡張機能「Markdown Preview Mermaid Support」を導入すれば、Markdownファイル内のコードをリアルタイムでプレビューできます。
- さらに、前述のGitHub Copilotと組み合わせることで、「コード生成」→「プレビュー」→「修正指示」のサイクルをVSCode内で完結させるワークフローが構築できます。
- Notion
- コードブロックを追加し、言語を「Mermaid」に設定するだけで自動描画されます。仕様書やドキュメント管理としてNotionを利用している組織には最適です。
- GitHub / GitLab
- Markdownファイル（README.mdなど）に記述すれば、リポジトリ上でそのまま図として表示されます。プルリクエストの概要欄でも機能するため、レビュー時の説明図としても重宝します。
- LLMのネイティブ機能（Artifacts / Canvas）
- ClaudeのArtifactsや、ChatGPTのCanvas機能のように、LLMのインターフェース自体がプレビュー機能を持つケースが増えています。とりあえず図を作ってみたい、という段階では最も手軽な選択肢です。
セキュリティとデータプライバシーの考慮事項
社内の機密情報（具体的なサーバー構成図や未発表の仕様など）を図解させる場合、パブリックな環境に入力するのはリスクがあります。
- エンタープライズ / チームプランの利用: ChatGPT EnterpriseやTeamプラン、あるいはClaudeの組織向けプランなど、入力データが学習に使われない設定になっているか必ず確認しましょう。
- API利用とポリシー確認: 自社でUIを用意しAPI経由で利用する場合も、各社のデータ保持ポリシー（APIデータは学習に使われない等）を確認の上、社内のセキュリティ規定に沿って利用してください。また、最近注目されているMCP（Model Context Protocol）などを利用してローカルファイルと連携させる場合も、データの送信範囲を理解しておくことが重要です。
3. 抽象概念を構造化するプロンプト設計の核心
ここからが本記事のハイライトです。単に「〇〇を図にして」と頼むだけでは、期待通りの図は出てきません。LLMに対して、「どのような視点で」「どの図解形式を選び」「どう表現するか」を指示するプロンプトエンジニアリングが必要です。
「比喩」と「関係性」を定義するシステムプロンプト
難解なIT用語を解説する場合、ただ構造を並べるだけでなく、「比喩（メタファー）」を用いると理解度が格段に上がります。例えば「API」を説明する際、「レストランのウェイター」に例えるのは古典的ですが効果的です。
プロンプトには、以下の要素を含める必要があります。
- Role（役割）: 技術図解の専門家として振る舞う。
- Target（読者）: 誰に向けた図解か（非エンジニア向けか、実装者向けか）。
- Format（形式）: Mermaidのどの記法を使うか（フローチャート、シーケンス図など）。
- Analogy（比喩）: 必要に応じて身近な例に例える。
難解用語を5つの図解パターンに分類するロジック
実務の現場では、ユーザーの発話パターンや解説したい用語の性質を分析し、以下の5つのパターンからLLMに選択させるアプローチが有効です。これをプロンプト内で定義することで、AIの迷いをなくします。
- プロセス型（Flowchart）: 手順、処理の流れ（例：対話フロー、承認プロセス）
- 相互作用型（Sequence Diagram）: システム間の通信、時系列のやり取り（例：ユーザーとボットの対話、APIコール）
- 構造型（Class Diagram / ER Diagram）: データの構造、オブジェクトの関係（例：DBスキーマ、クラス設計）
- 状態遷移型（State Diagram）: ステータスの変化（例：注文ステータス、ライフサイクル）
- 内訳・構成型（Pie Chart / Mindmap）: 構成要素の比率や分類（例：インフラ構成要素、技術スタック）
Few-Shotプロンプティングによる出力精度の向上
以下は、実務で活用できるプロンプトのテンプレートです。これをChatGPTのCustom Instructionsや、プロンプトの冒頭に貼り付けて使用してください。
【コピペ推奨】技術図解生成プロンプトテンプレート
# Role
あなたは熟練したテクニカルライター兼システムアーキテクトです。
難解なIT用語や技術概念を、Mermaid.jsを用いた図解コードで分かりやすく解説することに特化しています。
# User Input
解説対象の用語: {用語}
ターゲット読者: {読者層（例: 新入社員、非エンジニアの経営層、シニアエンジニア）}
# Steps
1. 概念分析: 入力された用語の核心的な機能、構造、またはプロセスを特定してください。
2. 図解形式の選定: 最も適切なMermaid図解タイプ（flowchart, sequenceDiagram, classDiagram, stateDiagram, mindmap）を選定してください。
- プロセスや手順なら `flowchart TD`
- 通信ややり取りなら `sequenceDiagram`
- 構造や関係性なら `classDiagram`
3. 比喩の適用（ターゲットが初心者の場合）: 読者が非エンジニアの場合、適切な比喩（例: サーバー=店員）を用いてノードのラベルを工夫してください。
4. コード生成: 文法的に正しいMermaidコードを生成してください。
# Constraints
- Mermaidコードは必ずコードブロック（```mermaid）で囲むこと。
- 日本語を使用する場合、文字化けを防ぐためにダブルクォートで囲むなどの対策を考慮すること（基本はそのまま使えるが、記号を含む場合は注意）。
- 図は複雑にしすぎず、主要なパスや要素に絞ること。
- 配色やスタイルは見やすくシンプルにすること。
# Output Example (Flowchart)
```mermaid
flowchart TD
User[ユーザー] -->|リクエスト| LB[ロードバランサー]
LB -->|振り分け| Web1[Webサーバー1]
LB -->|振り分け| Web2[Webサーバー2]
Web1 --> DB[(データベース)]
Web2 --> DB
このテンプレートを使うことで、LLMは「どの図を使うべきか」から思考をスタートし、文法エラーの少ないコードを出力してくれるようになります。
---
## 4. 実践：用語解説自動生成ワークフローの構築
では、実際にこのプロンプトを使ってワークフローを回してみましょう。ここでは例として、非エンジニアのPM向けに「リバースプロキシ」という用語を図解解説するケースを想定します。
### ステップ1：入力フェーズ（用語とターゲット読者の指定）
ChatGPTに以下のプロンプトを入力します。
```text
解説対象の用語: リバースプロキシ
ターゲット読者: 非エンジニアのプロジェクトマネージャー
（※前述のシステムプロンプトが設定されている前提です）
ステップ2：変換フェーズ（概念の構造化とコード生成）
LLMは以下のように思考し、出力を生成します。
- 概念分析: リバースプロキシは、クライアントとWebサーバーの間に立ち、セキュリティや負荷分散を担う「仲介役・窓口」。
- 形式選定: リクエストの流れを示すため
flowchart LR(左から右へのフロー) またはsequenceDiagramが適切。 - 比喩: 会社の「受付」や「秘書」に例えると分かりやすい。
そして、以下のようなコードが出力されます。
ステップ3：出力・検証フェーズ（レンダリングと微調整）
AIが出力したMermaidコード:
flowchart LR
Client[クライアントPC] -- "1. アクセス要求" --> RP[リバースプロキシ<br/>(会社の受付)]
subgraph InternalNetwork [社内ネットワーク]
direction TB
RP -- "2. 安全確認して転送" --> AppServer[Webサーバー<br/>(担当者)]
AppServer -- "3. データ返却" --> RP
end
RP -- "4. 応答" --> Client
style RP fill:#f9f,stroke:#333,stroke-width:4px
style InternalNetwork fill:#e1f5fe,stroke:#333,stroke-dasharray: 5 5
解説テキスト（AI生成）:
「リバースプロキシ」は、外部からのアクセスを一手に引き受ける「会社の受付」のような存在です。クライアント（来客）はいきなり担当者（Webサーバー）の席には行けず、必ず受付を通します。これにより、担当者の場所（IPアドレス）を隠したり、怪しい来客をブロックしたりできます。
このように、図解コードと解説テキストがセットで出力されます。これをNotionやVSCodeに貼り付ければ、即座に視覚的な解説が完成します。もし「受付の色を赤にしたい」と思えば、コード内の style を書き換えるだけです。画像編集ソフトを開く必要はありません。
5. 品質管理と運用ルール
ツールとプロンプトがあっても、無秩序に使えば「間違った図」が大量生産されるリスクがあります。組織として運用するためのルールを定めておきましょう。
ハルシネーション（嘘の図解）を防ぐ検証フロー
AIはもっともらしく嘘をつく（ハルシネーション）ことがあります。特に技術的な関係図においては、矢印の向きが逆だったり、存在しないコンポーネントを描いたりすることがあります。
- Human-in-the-loop（人間による確認）: 生成された図は必ずエンジニアがレビューしてください。「コードレビュー」と同じ感覚で、Mermaidの記述が正しいか、論理構造が合っているかを確認します。
- ソースの明示: 図解の下に「Generated by AI, Verified by [Reviewer Name]」といった署名を入れる運用を推奨します。責任の所在を明確にすることで、品質への意識が高まります。
図解コードのバージョン管理と共同編集
これがDocs as Codeの真骨頂です。
- Gitでの管理: ドキュメントリポジトリに
.mdファイルとして保存し、Pull Requestベースで更新します。 - Diffの活用: 図を変更した際、画像ファイルだと「何が変わったか」を目視で探す必要がありますが、Mermaidなら
git diffで変更箇所（例: 矢印のラベル変更、ノードの追加）が一目瞭然です。レビュー効率が格段に向上します。
社内用語集としてのライブラリ化戦略
作成した図解コードは、使い捨てにせず蓄積しましょう。
- スニペット登録: よく使う構成（例: フォールバック設計のフロー、認証フローのテンプレート）は、VSCodeのスニペットやチームの共有Wikiに「テンプレート」として登録しておきます。
- コンポーネント化: 社内システム固有のMermaid定義（色使いやサブグラフの定義など）を共通化し、チーム全体でデザインを統一します。「当社のシステム図では、DBは必ず黄色にする」といったルールをコードで強制できるのも強みです。
6. トラブルシューティングとFAQ
最後に、導入時によく直面する課題とその解決策をまとめます。これらは実際の運用において頻繁に直面するポイントです。
Mermaid構文エラーが出た場合の対処法
生成されたコードを貼り付けたら「Syntax Error」と表示されることがあります。
- カッコや記号の干渉: ノード名に
()[]{}などの記号が含まれているとエラーになりやすいです。Node["ノード名(詳細)"]のようにダブルクォートで囲むことで回避できます。 - AIへの修正指示（Self-Correction）: エラーが出た場合、そのエラーメッセージとコードをそのままChatGPTに投げ返し、「このMermaidコードでエラーが出ました。修正してください」と指示すれば、9割方解決します。AIは自分のミスの修正が得意です。
複雑すぎる図を簡略化するテクニック
AIは張り切って詳細すぎる図を描くことがあります。要素が多すぎてスパゲッティ状態になった場合は、以下のプロンプトで修正させます。
- 「詳細な処理は省略し、メインのハッピーパス（正常系）のみを描画してください」
- 「サブグラフを使って、関連する要素をグルーピングしてください」
- 「この図を3つのステップに分割し、それぞれ別の図として出力してください」
セキュリティ懸念への回答例
情報システム部門から「社内情報をAIに入れるな」と言われた場合。
- 抽象化して入力: 固有名詞（プロジェクト名や具体的なIPアドレス）は「ProjectA」「Server1」のように抽象化して入力し、出力されたコードを手元で置換するフローを提案します。
- ローカルLLMの活用: どうしても機密性が高い場合、Ollamaなどでローカル環境で動作するLLM（Llamaモデルなど）を使用し、オフラインでコード生成を行う方法もあります。VSCode上で完結できるため、セキュリティポリシーの厳しい現場でも導入可能です。
まとめ：図解を「スキル」から「仕組み」へ
これまで、分かりやすい図解を作れるかどうかは、個人のセンスやツールの習熟度に依存していました。しかし、Mermaid.jsとLLMを組み合わせることで、図解はエンジニアリング可能な「仕組み」へと変わります。
- Docs as Codeの実現: 図をコードとして管理し、Gitワークフローに乗せる。
- 属人化の解消: 誰でも一定品質の図解を、数分で生成できる。
- 説明コストの削減: 言葉で説明する時間を減らし、本質的な開発や議論に時間を使う。
まずは、手元のChatGPTで「このコードの処理フローをMermaidで書いて」と試してみてください。その便利さを実感したら、ぜひチーム全体のドキュメント標準化に向けて動き出しましょう。
「開発プロセスに合わせた図解生成ボットを作りたい」「社内Wikiと連携したナレッジベースを構築したい」といった具体的な課題がある場合、専門家に相談することをおすすめします。それぞれの環境に最適なDocs as Codeの導入や、対話AIの設計ノウハウを活用したカスタムGPTの構築を進めることが重要です。
チームが「説明」の苦労から解放され、「創造」に集中できる未来を、技術の力で実現しましょう。
コメント