システム開発の現場で「設計書を書くのに時間がかかりすぎる」「図を更新するたびに画像を貼り直すのが面倒」と感じたことはないでしょうか。私自身、以前はPowerPointやExcelで図を作成し、画像として貼り付けるという作業に多くの時間を費やしていました。ある案件では、シーケンス図を1枚修正するだけで、PowerPointを開き、図形を調整し、画像に書き出し、Wikiに再アップロードするという一連の手順に15分以上かかっていたこともあります。「図の内容は3行変えただけなのに」と思うたびに、もっと良い方法はないかと模索していました。本記事では、VSCodeのMarkdownプレビューでUML図を描く方法をご紹介します。
なぜMarkdownでUML図を描くのか
システム開発において、設計書やドキュメントの作成は避けて通れない工程です。しかし、専用のUMLツールを導入するとなると、ライセンス費用やチーム全員への展開が課題になることも少なくありません。同じような悩みを抱えている経営者やマネージャーの方も多いのではないでしょうか。
MarkdownでUML図を描く最大の利点は、テキストベースで図を管理できることにあります。テキストであれば、Gitなどのバージョン管理システムで変更履歴を追跡できますし、コードレビューの対象にもなります。IPAの「DX白書2023」でも、ドキュメントとコードの一元管理が開発効率に寄与すると指摘されており、この手法はまさにその実践例といえます。
テキストベース管理がもたらす具体的なメリット
改めて整理すると、テキストベースでUML図を管理することには、以下のような実務上のメリットがあります。
差分の可視化が容易になることは、想像以上に大きな恩恵です。画像ファイルでは「何が変わったのか」をひと目で把握できませんが、テキストであればGitのdiffコマンドやプルリクエストの差分表示で、変更箇所が一行単位で明確になります。私たちのプロジェクトでも、設計レビューの際に「この矢印の向きが変わった理由は？」といった的確な指摘が増え、レビューの質が向上しました。
検索性の高さも見逃せないポイントです。たとえば「このクラスが登場する図はどれだろう」と思ったとき、テキストベースであればリポジトリ全体をgrepするだけで該当ファイルを特定できます。画像ベースの図では、こうした横断的な検索はほぼ不可能です。
ドキュメントの陳腐化を防ぎやすいという点も重要です。画像ファイルとして別管理されていた図は、コードを修正しても更新を忘れがちです。一方、Markdownファイルにテキストとして埋め込まれた図であれば、プルリクエストの中でコードと一緒にレビュー・更新する習慣が自然と根づきます。
私自身、最初は「テキストで図を描く」という発想にピンと来ていませんでした。しかし実際に導入してみると、図の修正がテキストの編集だけで完了するため、更新のハードルが大幅に下がることに気づかされました。
Mermaidで始める最も手軽なUML作成
まず最初にお勧めしたいのが、Mermaidを使った方法です。VSCodeの拡張機能「Markdown Preview Mermaid Support」をインストールするだけで、すぐに利用を開始できます。
インストール手順
導入はとてもシンプルです。VSCodeの拡張機能パネル（Ctrl+Shift+X / Cmd+Shift+X）を開き、「Markdown Preview Mermaid Support」と検索してインストールボタンを押すだけで完了します。JavaやDockerなどの外部依存がなく、拡張機能単体で動作するため、チーム全員への展開もスムーズです。インストール後は、Markdownファイル内に ```mermaid で囲んだブロックを記述すれば、プレビュー画面（Ctrl+Shift+V / Cmd+Shift+V）に図がレンダリングされます。
基本的な図の種類と記法
Mermaidの記法は非常にシンプルです。たとえば、業務フローを表すフローチャートは以下のように書けます。
graph TD A[お問い合わせ受付] --> B{内容の確認} B -->|技術相談| C[エンジニアへ割当] B -->|お見積もり| D[営業担当へ割当] C --> E[ヒアリング実施] D --> E E --> F[ご提案書作成]
graph TD の TD は「Top to Down（上から下へ）」を意味しており、LR（Left to Right）に変更すれば横方向のフローチャートになります。ノードの形状も、[ ] で四角、{ } でひし形（条件分岐）、(( )) で円形と、記号を変えるだけで表現を使い分けられます。
シーケンス図も直感的に記述できます。システム間の連携やAPIの呼び出しフローを可視化する際に重宝します。
sequenceDiagram participant U as ユーザー participant F as フロントエンド participant A as APIサーバー participant D as データベース U->>F: ログインリクエスト F->>A: 認証API呼び出し A->>D: ユーザー情報照会 D-->>A: 認証結果 A-->>F: トークン発行 F-->>U: ログイン完了
さらに、要件定義や企画段階で役立つのがガントチャートです。プロジェクトの各フェーズを俯瞰的に共有したいときに便利で、以下のように記述します。
gantt title プロジェクトスケジュール dateFormat YYYY-MM-DD section 要件定義 ヒアリング :a1, 2025-04-01, 10d 要件書作成 :a2, after a1, 7d section 設計 基本設計 :b1, after a2, 14d 詳細設計 :b2, after b1, 10d section 開発 実装 :c1, after b2, 30d
このほかにも、ER図（erDiagram）、状態遷移図（stateDiagram-v2）、円グラフ（pie）など、Mermaidが対応している図の種類は年々増えています。まずはフローチャートとシーケンス図から試してみて、慣れてきたら他の図にも挑戦してみてください。
Mermaid記法でつまずきやすいポイント
Mermaidの導入で最初に戸惑ったのは、記法のインデントや矢印の種類でした。--> と -->> の違いなど、細かな部分で試行錯誤が必要かもしれません。しかし、公式ドキュメントが充実しているため、慣れるまでにそれほど時間はかからないでしょう。
実際に私がつまずいた具体例を挙げると、ノード名に日本語の括弧「（）」を使った際にパースエラーが発生したことがありました。Mermaidの記法では半角記号に特別な意味があるため、ノードのラベルに記号を含める場合は " " で囲むのが安全です。こうした小さなハマりポイントを知っておくだけで、導入初期のストレスがかなり軽減されるはずです。
また、図が大きくなると一画面に収まりきらないことがあります。その場合は graph LR で横方向に展開したり、サブグラフ（subgraph）で関連するノードをグループ化したりすると、見通しが良くなります。
PlantUMLで本格的な設計図を描く
より複雑なUML図が必要な場合は、PlantUMLが強力な選択肢になります。クラス図やER図、ステートマシン図など、UML2.0で定義された幅広い図をサポートしている点が特長です。
VSCodeで利用するには、拡張機能「PlantUML」をインストールし、JavaランタイムまたはPlantUMLサーバーの設定が必要です。MermaidとPlantUMLのどちらを採用するか悩みましたが、結論としては「用途に応じて使い分ける」のが現実的でした。
簡易的なフロー図やシーケンス図はMermaidで素早く作成し、詳細なクラス設計やER図はPlantUMLで描く。この使い分けが、私たちのチームでは最も効率的だと感じています。
環境構築の手順
PlantUMLの環境構築は、Mermaidと比べるとひと手間かかります。以下の手順で進めるのがスムーズです。
- Javaランタイムのインストール: PlantUMLはJavaで動作するため、JDK（またはJRE）が必要です。すでにJava開発環境がある場合はこのステップは不要です。
- VSCode拡張機能「PlantUML」のインストール: 拡張機能パネルから「PlantUML」を検索してインストールします。
- レンダリング方式の選択: ローカルのJavaランタイムを使う方法と、PlantUMLサーバーを使う方法があります。チームで共通のサーバーを立てておくと、各メンバーのローカル環境に依存しなくなるため、環境差異によるトラブルを減らせます。
Docker環境がある場合は、docker run -d -p 8080:8080 plantuml/plantuml-server:jetty のようにPlantUMLサーバーを起動し、VSCodeの設定で plantuml.server にそのURLを指定する方法が手軽です。
PlantUMLの記法例
PlantUMLの記法例として、クラス図を見てみましょう。
@startuml class User { - id: String - name: String - email: String + login(): Boolean + updateProfile(): void } class Order { - orderId: String - amount: Decimal + calculate(): Decimal } User "1" -- "*" Order : places @enduml
アクセス修飾子を +（public）、-（private）、#（protected）で表現できるため、クラスの設計意図が一目で伝わります。また、クラス間の関連（関連、集約、コンポジション、継承など）もUMLの標準記法に沿って記述でき、詳細設計フェーズでの利用に適しています。
もう一つ実務で活躍する場面が多いのが、アクティビティ図です。業務プロセスの分岐や並行処理を表現する際に重宝します。
@startuml start :注文を受付; if (在庫あり?) then (はい) :出荷処理; :配送手配; else (いいえ) :入荷待ち通知; :仕入先へ発注; endif :顧客へステータス通知; stop @enduml
設定で少し手間がかかる部分はありますが、一度環境を整えてしまえば、チーム全体で統一的な設計図を効率よく作成できるようになります。
MermaidとPlantUMLの使い分けガイド
両方のツールに触れてきましたが、「結局どちらを使えばいいのか」と迷われる方もいらっしゃるかもしれません。私たちのチームで運用してきた経験から、使い分けの目安をまとめます。
| 観点 | Mermaid | PlantUML |
|---|---|---|
| 導入の手軽さ | 拡張機能のみで即利用可能 | Java環境またはサーバーが必要 |
| フローチャート | シンプルで書きやすい | 同等に対応 |
| シーケンス図 | 基本的な用途には十分 | 条件分岐やループなど高度な表現が可能 |
| クラス図 | 簡易的な記述に対応 | アクセス修飾子や関連の種類を詳細に表現可能 |
| ER図 | 対応（erDiagram） | 対応（より柔軟なカスタマイズ可） |
| GitHub/GitLab連携 | GitHubがネイティブ対応しておりプレビュー可能 | 別途画像生成の仕組みが必要 |
| テーマ・スタイル | CSSベースのカスタマイズ | スキンパラメータで詳細に調整可能 |
特筆すべきは、GitHubがMermaid記法をネイティブサポートしている点です。READMEやIssue、プルリクエストの本文にMermaidブロックを書くだけで図が表示されるため、GitHub中心のワークフローではMermaidの利便性が際立ちます。
一方で、UML仕様に厳密に準拠した図が求められる場合や、大規模なクラス図を描く場合にはPlantUMLの表現力が必要になる場面もあります。まずはMermaidから始めて、物足りなさを感じた時点でPlantUMLを検討する、という段階的なアプローチが現実的ではないでしょうか。
チーム開発での運用と実践的なポイント
ドキュメントをMarkdownとUML図で統一管理する場合、いくつか運用上のポイントがあります。
ドキュメント規約の整備
まず、プロジェクトのREADMEやdocsディレクトリにドキュメント規約を明文化しておくことをお勧めします。「どの図にはMermaidを使い、どの図にはPlantUMLを使うか」というルールをチームで決めておくと、記法の混在による混乱を防げます。一概には言えない部分もありますが、チーム規模が5名を超えるあたりからルールの明文化が効果を発揮すると感じました。
規約に含めておくと良い項目の例を挙げます。
- 図の種類ごとの使用ツール: フローチャートとシーケンス図はMermaid、クラス図とER図はPlantUMLなど
- ファイルの配置ルール:
docs/diagrams/配下に図を含むMarkdownを集約するか、各機能ディレクトリに併置するか - 命名規則:
seq-login-flow.md、class-user-domain.mdのように、図の種類と対象を名前に含める
こうした規約は完璧を目指す必要はなく、運用しながら育てていくものだと考えています。最初は最低限のルールから始めて、チームの中で「ここが困った」という声が上がったタイミングで追加していくのが無理のない進め方です。
CI/CDでの品質チェック
また、CI/CDパイプラインに図のレンダリングチェックを組み込むことも有効です。記法ミスによるビルドエラーを事前に検知できれば、ドキュメントの品質を常に保てます。GitHub ActionsやGitLab CIで、Mermaid CLIやPlantUMLのコマンドラインツールを使ったバリデーションを自動化している企業も増えてきています。
たとえばGitHub Actionsでは、Mermaid CLIの mmdc コマンドを使って、Markdownファイル内のMermaidブロックが正しくレンダリングされるかを検証できます。記法エラーがある場合はCIが失敗するため、壊れた図がmainブランチにマージされるのを防止できます。こうした自動化は最初の設定に少し時間がかかりますが、長期的には「図が壊れているのに誰も気づかない」という事態を防ぐ大きな安心材料になります。
推奨拡張機能の共有
さらに見落としがちなのが、VSCodeの設定共有です。.vscode/extensions.json に推奨拡張機能を記載しておけば、新しいメンバーが参加した際の環境構築がスムーズになります。振り返ると、この設定を後回しにしていた頃はオンボーディングのたびに同じ質問を受けており、遠回りだったと反省しています。
具体的には、以下のような extensions.json を用意しておくと便利です。
{ "recommendations": [ "bierner.markdown-mermaid", "jebbs.plantuml" ] }
VSCodeでプロジェクトを開いた際に「推奨拡張機能をインストールしますか？」という通知が表示されるため、新メンバーは迷うことなく必要な環境を整えられます。些細な工夫ですが、開発チームの立ち上がりを確実に加速させてくれます。
導入時によくある疑問とその解消法
実際にチームへ展開する際、いくつかの疑問や懸念が寄せられることがあります。導入を検討されている方に向けて、よくある質問とその考え方をまとめます。
「非エンジニアでも使えるのか」
結論から言えば、Mermaidの基本的なフローチャート程度であれば、エンジニア以外の方でも十分に扱えます。記法がシンプルで、プログラミングの知識がなくても「箱と矢印」の感覚で書けるためです。実際に、私たちのプロジェクトではディレクターの方がMermaidで業務フローの素案を作成し、それをエンジニアがレビューするという運用をしたことがあります。最初こそ記法を覚える時間が必要でしたが、数回書いてみると自然と手が動くようになったと聞いています。
「見た目のカスタマイズはどこまでできるのか」
MermaidはCSSベースのテーマ設定に対応しており、色やフォントを変更できます。Markdownファイルの先頭で init ディレクティブを使い、テーマカラーを指定することも可能です。PlantUMLはさらに柔軟で、skinparam コマンドによって線の色、背景色、フォントサイズなど細かな調整ができます。ただし、あまり見た目にこだわりすぎるとテキストベースの手軽さというメリットが薄れてしまうため、「内容が正しく伝わること」を優先するのが良いバランスだと感じています。
「既存の図をどう移行すればいいのか」
すでにPowerPointやVisioで大量の設計図がある場合、すべてを一度に移行するのは現実的ではありません。お勧めしたいのは「新規作成分から切り替え、既存図は更新タイミングで順次移行する」というアプローチです。無理に全量を移行しようとすると、移行作業自体がボトルネックになりかねません。更新頻度の高い図から優先的に移行していくと、投資対効果が高くなります。
まとめ：ドキュメント作成の効率化が開発全体を加速させる
VSCodeのMarkdownプレビューでUML図を描く手法は、専用ツールへの投資なしに、設計書やドキュメントの作成・管理を大幅に効率化できる実践的なアプローチです。Mermaidで手軽に始め、必要に応じてPlantUMLで本格的な設計図を作成する。この段階的な導入が、チームへの定着をスムーズにする鍵ではないでしょうか。
テキストベースの図管理は、単に「図を描く手間が減る」だけではありません。バージョン管理による変更追跡、コードレビューとの統合、CI/CDによる品質担保など、ソフトウェア開発のベストプラクティスをドキュメントにも適用できるという点にこそ、本質的な価値があります。
ドキュメントの品質と開発スピードの両立は、企業の競争力に直結する課題です。aduceでは、こうした開発プロセスの最適化からシステム設計まで、お客様の課題に合わせた技術支援を行っています。ドキュメント管理や開発効率化にお悩みの際は、ぜひaduceのお問い合わせはこちらからお気軽にご相談ください。