Claude Codeで仕様書のPlantUML図を自動生成 — VS Codeプレビューで完結

1 PlantUMLもClaude Codeで書きたい
2 なぜPlantUMLなのか？
- 2.1 MermaidとPlantUMLの使い分け
- 2.2 PlantUML固有の強み
3 VS Code Preview設定方法
4 基本的な作業フロー
- 4.1 Claude Code連携の流れ
- 4.2 PlantUML公式エディタで確認する方法
5 実践①: アクティビティ図
6 実践②: ユースケース図
7 実践③: コンポーネント図
8 トラブルシューティング
9 プロンプトテンプレート集
10 まとめ
11 関連ブログ・参考リンク
- 11.1 関連ブログ
- 11.2 参考リンク

PlantUMLもClaude Codeで書きたい

ども！Claude Codeで仕様書を書く方法を模索している龍ちゃんです。

以前、ClaudeでMermaid図作成を自動化する記事を書きました。あの記事のおかげで図解作成がめちゃくちゃ楽になったんですが、しばらく使ってるうちに壁にぶつかりました。

アクティビティ図が作れない。ユースケース図も作れない。 PlantUMLなら作れる。確認はVS Code上のMarkdown Previewで完結する。今回はその設定方法と実践例を紹介します。

Mermaidは便利だけど、対応していない図の種類があるんです。仕様書を書いてると「ここはアクティビティ図で表現したい」「アクターの関係をユースケース図で見せたい」って場面が出てきます。Mermaidのフローチャートで無理やり代用しても、分岐やマージが不自然になる。

そこでPlantUMLの出番です。

今回は、Claude CodeでPlantUMLの図を生成して、VS Code上のMarkdown Previewでそのまま確認する方法を解説します。VS Code上に拡張機能を入れるだけですぐ確認できていたのですが、PlantUMLではちょっとしたコツが必要になったので紹介していきます。

この記事でわかること:

Mermaidでは作れないアクティビティ図・ユースケース図・コンポーネント図をPlantUMLで作る方法
VS Code上でPlantUML図をプレビュー表示する環境設定（Markdown Preview Enhanced + Kroki.io）
Claude Codeと組み合わせた実践的な作業フロー

前提環境: VS Code 1.85以上、インターネット接続必須（Kroki.ioサーバーとの通信に必要）

なぜPlantUMLなのか？

MermaidとPlantUMLの使い分け

全部PlantUMLに乗り換えろという話ではないです。Mermaidが得意な領域はMermaidを使えばいい。PlantUMLが必要になるのは、Mermaidでは作れない図を描くときだけです。

こういう図なら	こっちを使う	理由
フローチャート	Mermaid	記法がシンプル、学習コスト低い
シーケンス図（シンプル）	Mermaid	4参加者程度ならMermaidで十分
状態遷移図	Mermaid	stateDiagram-v2が使いやすい
ER図	Mermaid	erDiagramが直感的
パイチャート	Mermaid	Mermaid専用機能
アクティビティ図	PlantUML	Mermaid非対応。if/else分岐の自然な表現
ユースケース図	PlantUML	Mermaid非対応。UML標準のアクター記法
コンポーネント図	PlantUML	database/queue専用記号が使える
複雑なシーケンス図	PlantUML	==フェーズ分割==、ref over が使える
UML準拠が求められる設計書	PlantUML	UML 2.0標準に準拠

シンプルな結論: 迷ったらMermaid。アクティビティ図・ユースケース図・コンポーネント図の3パターンだけPlantUML。

PlantUML固有の強み

PlantUMLでしか使えない表現がいくつかあります。記事の後半で実際に使いますが、先に紹介しておきます。

database "名前" — ドラム型のデータベース記号。Mermaidでは汎用の四角になる
queue "名前" — キュー型の記号。メッセージキューの表現に最適
== フェーズ名 == — シーケンス図をフェーズで区切る。認証→データ取得のような段階を明示できる
left to right direction — ユースケース図の横向きレイアウト。縦長にならず収まりがいい
if/else/endif — アクティビティ図の条件分岐。ネストも可能

VS Code Preview設定方法

ここが記事の核です。一度設定すれば、あとはMarkdownに書くだけでPlantUML図がプレビュー表示されます。

必要な拡張機能

Markdown Preview Enhanced を使います。

項目	詳細
拡張機能ID	`shd101wyy.markdown-preview-enhanced`
バージョン	0.8.20（2025年11月時点）
PlantUML対応	Kroki.ioサーバー経由で描画
Mermaid対応	ブラウザ内JSで描画（同時対応）

VS Code標準のMarkdownプレビューではPlantUMLは表示されません。Markdown Preview Enhancedの専用プレビューを使う必要があります。

PlantUMLサーバー設定

PlantUMLのコードを画像に変換するサーバーが必要です。Kroki.ioを使います。無料で登録不要です。

注意: Kroki.ioはパブリックサーバーなので、PlantUMLのコードがインターネット経由で送信されます。社内の機密情報を含む図を描く場合は、セルフホスト版のKrokiサーバー（Dockerで立てられる）を検討してください。個人のブログ執筆用途であれば問題ないです。

VS Codeの設定で以下を追加します:

{
    "markdown-preview-enhanced.plantumlServer": "https://kroki.io/plantuml/svg/"
}

これだけです。

devcontainer.jsonへの設定例

devcontainerを使っている場合は、devcontainer.jsonに書いておくとチーム全員が同じ設定で使えます。

{
    "customizations": {
        "vscode": {
            "extensions": [
                "shd101wyy.markdown-preview-enhanced",
                "bierner.markdown-mermaid"
            ],
            "settings": {
                "markdown-preview-enhanced.plantumlServer": "https://kroki.io/plantuml/svg/",
                "markdown-preview-enhanced.previewTheme": "github-dark.css",
                "markdown-preview-enhanced.mermaidTheme": "dark"
            }
        }
    }
}

自分のプロジェクトでは実際にこの設定を使っています。Markdown Preview Mermaid Support（bierner.markdown-mermaid）も入れておくと、VS Code標準プレビュー側でMermaidが表示できて便利です。

動作確認

設定が終わったら、以下の手順で確認します。

以下のコードブロックを書く:
Markdown Preview Enhanced のプレビューを開く
- コマンドパレット（Ctrl+Shift+P）→ Markdown Preview Enhanced: Open Preview to the Side
- ショートカット: Ctrl+K V
Markdownファイルを開く

@startuml
Alice -> Bob: Hello
Bob --> Alice: Hi!
@enduml

プレビューにシーケンス図が表示されたら設定完了です。表示されない場合は、後述のトラブルシューティングを確認してください。

注意: VS Code標準のMarkdownプレビュー（Ctrl+Shift+V）ではPlantUMLは表示されません。必ずMarkdown Preview Enhanced のプレビューを使ってください。アイコンが異なるので区別できます。

基本的な作業フロー

Claude Code連携の流れ

Claude Codeで作業する場合の具体的な流れです。

Markdownファイルを開いた状態でClaude Codeにプロンプトを入力
Claude Codeが plantuml コードブロックを含むMarkdownを生成
VS Code上でMarkdown Preview Enhancedのプレビューを確認
修正が必要なら「この図の〇〇を変更して」と追加指示
完成したらそのまま仕様書・設計書として使える

エディタとターミナルの行き来だけで完結するのが強みです。

PlantUML公式エディタで確認する方法

VS Code Previewが本記事のメインですが、ブラウザで手軽に確認したい場面もあります。PlantUMLには公式のWebエディタがあるので紹介しておきます。

PlantUML Web Editor

使い方はシンプルです。

上記URLにアクセス
左側のエディタにPlantUMLコードを貼り付ける
約1.5秒後に右側にプレビューが自動表示される
ツールバーからPNG/SVGでダウンロードできる

Mermaid版の記事で紹介した「Live Editor」のPlantUML版だと思ってください。URLがそのまま図の共有リンクになるので、チームメンバーに「この図見て」と送るときにも使えます。

ただし自分は普段使いではVS Code Previewのほうを使っています。理由は2つあって、エディタから離れなくていいことと、Markdownファイルにそのまま残せること。公式エディタは「VS Codeの設定がまだの環境で急ぎ確認したい」「誰かに図だけ共有したい」ときの補助ツールという位置づけです。

実践①: アクティビティ図

アクティビティ図とは

ワークフローや処理の分岐を表現する図です。フローチャートに似ていますが、UMLの正式な図の1つで、条件分岐（if/else）とマージの表現が自然です。

Mermaidのフローチャートでも似たことはできますが、分岐とマージの接続が不自然になりがちです。PlantUMLのアクティビティ図なら、if/else/endifの構文でネストした分岐も綺麗に描けます。

プロンプト例

以下のワークフローをPlantUMLのアクティビティ図で作成してください。

【ワークフロー】ブログ記事の執筆〜公開プロセス
1. 記事のアウトラインを作成
2. Claude Codeで下書きを生成
3. 内容を確認・修正
4. 判定: 技術的に正確か？
   - YES → ライティングチェックへ
   - NO → 技術検証をやり直して下書き修正
5. 判定: 品質OK？
   - YES → サムネイル作成 → WordPress入稿 → 公開
   - NO → AIっぽい表現を修正 → 再チェック

```plantuml のコードブロック形式で出力してください。

PlantUMLコード例

@startuml
start
:記事のアウトラインを作成;
:Claude Codeで下書きを生成;
:内容を確認・修正;

if (技術的に正確？) then (はい)
  :ライティングチェック;
  if (品質OK？) then (はい)
    :サムネイル作成;
    :WordPressに入稿;
    :公開;
  else (いいえ)
    :AIっぽい表現を修正;
    :再チェック;
  endif
else (いいえ)
  :技術検証をやり直す;
  :下書きを修正;
endif

stop
@enduml

VS Code Previewで見ると、こんな感じで表示されます。

分岐のダイヤモンド記号とマージが自然に接続されます。ネストしたif/elseもインデントで表現されるので読みやすい。Mermaidのフローチャートで同じことをやろうとすると、ノード間の矢印を手動で繋ぐ必要があって面倒です。

実践②: ユースケース図

ユースケース図とは

システムの機能（ユースケース）と、それを使う人やシステム（アクター）の関係を表現する図です。要件定義の初期段階で「誰が何をするか」を整理するのに使います。

Mermaidにはユースケース図のサポートがないので、PlantUMLの独壇場です。

プロンプト例

以下のシステムのユースケース図をPlantUMLで作成してください。

【システム名】ブログ執筆システム

【アクター】
- エンジニア: 記事執筆、図の生成、コードレビュー
- Claude Code: 下書き生成、図の生成、サムネイル作成、SEOチェック、ライティングチェック
- レビュアー: コードレビュー

【関係】
- 図の生成と記事執筆にはinclude関係がある
- SEOチェックと記事執筆にもinclude関係がある

left to right direction で横向きレイアウトにしてください。
```plantuml のコードブロック形式で出力してください。

PlantUMLコード例

@startuml
left to right direction

actor "エンジニア" as Engineer
actor "Claude Code" as Claude
actor "レビュアー" as Reviewer

rectangle "ブログ執筆システム" {
  usecase "記事を執筆" as UC1
  usecase "図を生成" as UC2
  usecase "コードレビュー" as UC3
  usecase "サムネイル作成" as UC4
  usecase "SEOチェック" as UC5
  usecase "ライティングチェック" as UC6
}

Engineer --> UC1
Engineer --> UC2
Engineer --> UC3
Claude --> UC1 : 下書き生成
Claude --> UC2 : Mermaid/PlantUML生成
Claude --> UC4
Claude --> UC5
Claude --> UC6
Reviewer --> UC3
UC2 ..> UC1 : &lt;&lt;include>>
UC5 ..> UC1 : &lt;&lt;include>>
@enduml

VS Code Previewでの表示結果がこちらです。

left to right direction でアクターが左右に配置されて、横長のレイアウトになります。rectangle でシステム境界を囲って、..> + <<include>> でユースケース間の依存関係を表現しています。

棒人間のアクターアイコンはPlantUML固有のもので、UML標準に準拠しています。Mermaidでは表現できません。個人的にはこのアクターアイコンが出るだけで「ちゃんとした設計図」感が出るので気に入ってます。

実践③: コンポーネント図

コンポーネント図とは

システムのコンポーネント（サービス、データベース、キューなど）と、それらの依存関係を表現する図です。PlantUMLの database と queue の専用記号が使えるのがここで効いてきます。

Mermaidでもflowchartでシステム構成図を描けますが、データベースもキューも同じ四角形になります。PlantUMLならドラム型のDB記号やキュー記号で一目でわかる図が作れます。

プロンプト例

以下のシステム構成をPlantUMLのコンポーネント図で作成してください。

【システム名】ブログ執筆環境

【レイヤー構成】
- 開発環境: VS Code、Claude Code CLI、Playwright
- CLIツール: blog-scraper、html-to-png、svg-to-png、thumbnail-generator
- 外部サービス: WordPress（DB）、Kroki.io（キュー）、GitHub（DB）

database記号とqueue記号を使い分けてください。
packageでレイヤーを分けてください。
```plantuml のコードブロック形式で出力してください。

PlantUMLコード例

@startuml
package "開発環境（devcontainer）" {
  [VS Code] as VSCode
  [Claude Code CLI] as Claude
  [Playwright] as PW
}

package "CLIツール" {
  [blog-scraper] as Scraper
  [html-to-png] as H2P
  [svg-to-png] as S2P
  [thumbnail-generator] as Thumb
}

package "外部サービス" {
  database "WordPress" as WP
  queue "Kroki.io" as Kroki
  database "GitHub" as GH
}

VSCode --> Claude : コマンド実行
Claude --> Scraper : 記事取得
Claude --> H2P : 図のPNG変換
Claude --> Thumb : サムネイル生成
Scraper --> WP : スクレイピング
H2P --> PW : ブラウザ描画
VSCode --> Kroki : PlantUMLプレビュー
Claude --> GH : コミット・プッシュ
@enduml

VS Code Previewで表示するとこうなります。

WordPressとGitHubがドラム型のDB記号で、Kroki.ioがキュー型の記号で表示されます。package でレイヤーが囲まれるので、3層構造が一目でわかります。

[コンポーネント名] の記法はUMLコンポーネント記号（角に突起が付いた四角形）で表示されます。Mermaidの ["テキスト"] とは見た目が違って、設計図っぽさが出ます。実はこの図、自分が普段使ってるブログ執筆環境そのものなので、「こういう構成で動いてるんだ」と思いながら見てもらえると嬉しいです。

トラブルシューティング

Previewに図が表示されない

症状	原因	対策
コードブロックがそのまま表示される	VS Code標準のMarkdownプレビューを使っている	Markdown Preview Enhanced のプレビューに切り替える。コマンドパレットで「Markdown Preview Enhanced: Open Preview to the Side」を実行
「Loading…」で止まる	Kroki.ioサーバーに接続できない	ネットワーク接続を確認。プロキシ環境の場合はVS Codeのプロキシ設定を確認
図が真っ白	`plantumlServer` の設定値が間違っている	設定値が `https://kroki.io/plantuml/svg/` になっているか確認（末尾のスラッシュも必要）
エラーメッセージが表示される	PlantUMLの構文エラー	エラーメッセージをClaude Codeに貼り付けて「修正してください」と依頼

日本語が文字化けする

Kroki.ioサーバー側で描画されるため、ローカルのフォント設定は影響しません。Kroki.ioは日本語フォントに対応しているので、通常は文字化けしないです。

もし文字化けする場合は、skinparamでフォントを指定してみてください:

@startuml
skinparam defaultFontName "Noto Sans JP"
' 以下に図の内容
@enduml

図が大きすぎてプレビューに収まらない

2つの方法があります。

方法1: scaleで縮小

@startuml
scale 0.8
' 80%に縮小して表示
@enduml

方法2: skinparam dpiで調整

@startuml
skinparam dpi 150
' デフォルト（200程度）より小さくする
@enduml

ノード数が多い場合は、図を分割するのが根本的な解決策です。

プロンプトテンプレート集

コピペして使えるテンプレートです。

アクティビティ図用

以下のワークフローをPlantUMLのアクティビティ図で作成してください。

【ワークフロー名】
[ワークフローの名前]

【ステップ】
1. [ステップ1の内容]
2. [ステップ2の内容]
3. 判定: [条件分岐の内容]
   - YES → [処理A]
   - NO → [処理B]

```plantuml のコードブロックで出力してください。
skinparamは不要です。

ユースケース図用

以下のユースケース図をPlantUMLで作成してください。

【システム名】
[システムの名前]

【アクター】
- [アクター1]: [役割の説明]
- [アクター2]: [役割の説明]

【ユースケース】
- [UC1]: [機能の説明]
- [UC2]: [機能の説明]

【関係】
- [UC間のinclude/extend関係があれば記述]

left to right direction で横向きレイアウトにしてください。
```plantuml のコードブロックで出力してください。

コンポーネント図用

以下のシステム構成をPlantUMLのコンポーネント図で作成してください。

【システム名】
[システムの名前]

【レイヤー構成】
- [レイヤー1]: [コンポーネント一覧]
- [レイヤー2]: [コンポーネント一覧]
- [データ層]: [DB、キャッシュ、キュー等]

database記号とqueue記号を適切に使い分けてください。
packageでレイヤーを分けてください。
```plantuml のコードブロックで出力してください。

修正依頼用

先ほどのPlantUML図を以下の点で修正してください:

【修正内容】
- [修正点1]
- [修正点2]
- [修正点3]

```plantuml のコードブロック形式を維持してください。

まとめ

Mermaidで作れない図はPlantUMLで作る。確認はVS Code上のMarkdown Previewで完結する。

この記事のポイント:

使い分け: 迷ったらMermaid。アクティビティ図・ユースケース図・コンポーネント図の3パターンだけPlantUML
環境設定: Markdown Preview Enhanced + Kroki.ioサーバー。devcontainer.jsonに数行設定するだけ
作業フロー: Claude Code → PlantUMLコード生成 → VS Code Preview確認。エディタから離れない
PlantUML固有の強み: database/queue専用記号、if/else分岐、ユースケースのアクター記法

Mermaid版の記事では「Live Editorでブラウザに切り替えて確認」でしたが、PlantUML版は「VS Codeのプレビューで確認」です。エディタとターミナルの行き来だけで図の作成が完結するのは地味に楽です。仕様書のMarkdownにそのまま埋め込めるので、図の管理も別ファイルにする必要がありません。

自分はこの仕組みを使って、仕様書や設計書の図解を全部Markdownに集約しています。

ほなまた。

PlantUMLもClaude Codeで書きたい

なぜPlantUMLなのか？

MermaidとPlantUMLの使い分け

PlantUML固有の強み

VS Code Preview設定方法

必要な拡張機能

PlantUMLサーバー設定

devcontainer.jsonへの設定例

動作確認

基本的な作業フロー

Claude Code連携の流れ

PlantUML公式エディタで確認する方法

実践①: アクティビティ図

アクティビティ図とは

プロンプト例

PlantUMLコード例

実践②: ユースケース図

ユースケース図とは

プロンプト例

PlantUMLコード例

実践③: コンポーネント図

コンポーネント図とは

プロンプト例

PlantUMLコード例

トラブルシューティング

Previewに図が表示されない

日本語が文字化けする

図が大きすぎてプレビューに収まらない

プロンプトテンプレート集

アクティビティ図用

ユースケース図用

コンポーネント図用

修正依頼用

まとめ

関連ブログ・参考リンク

関連ブログ

参考リンク

コメントを残す コメントをキャンセル

コメントを残すコメントをキャンセル