plantuml-skill

PlantUML 図作成スキル

概要

Kroki（curl 以外のローカルインストールが不要なクラウドレンダリング API）を使って、.puml の PlantUML 図ファイルを作成し、PNG／SVG にエクスポートします。

形式： .puml（PlantUML テキスト） レンダラー： Kroki API（https://kroki.io）— curl だけで利用でき、Java は不要です 出力： PNG、SVG 図の種類： シーケンス図、コンポーネント図、クラス図、ER 図、アクティビティ図、ユースケース図、状態図、C4 など

使用するタイミング

明示的なトリガー：

• 「PlantUML 図」、「シーケンス図」、「クラス図」、「コンポーネント図」
• 「UML」、「アクティビティ図」、「ユースケース図」、「ステートマシン」
• 「可視化」、「描画」、「図」、「フローチャート」、「アーキテクチャ図」

積極的に使用するトリガー：

• 3 つ以上のコンポーネントが連携するシステムを説明する場合
• API のフロー、認証シーケンス、メッセージの受け渡しを説明する場合
• クラス階層、データベーススキーマ、ER モデルを示す場合
• ステートマシンやライフサイクルのフローを図示する場合

使用しない場合 — 別のツールに振り分けます：

• Markdown に埋め込む一般的な UML 以外の簡易図 → mermaid。
• ピクセル単位の調整が必要な、自由形式でデザイン性が高い図やブランド化された図 → drawio。
• 手描き風の図 → excalidraw または tldraw。

モード

トリガーされたら、ユーザーが実際に求めている内容に応じて振り分け、その後、共通のレンダリング手順（ステップ 4～8）を実行します。

モード	ユーザーの要望…	開始手順
生成（デフォルト）	テキストによる説明から図を作成する	以下のステップ 1～8
コードから作成	既存のソースコードの図を作成する	references/from-source-code.md → ステップ 4～8
埋め込み	Markdown ドキュメント内の PlantUML を画像にレンダリングする	references/markdown-embed.md
修正	既存の図を変更する	.puml を読み込み、最小限の変更を適用し（ステップ 7）、再レンダリングします（ステップ 4～6）
レビュー	既存の図が読みやすいか、正確かを確認する	ステップ 6 の画像によるセルフチェックを実行します

前提条件

オプション A：Kroki API（推奨 — インストール不要）

# Just needs curl (pre-installed on macOS/Linux/Windows Git Bash)
curl --version

オプション B：Docker を使ったローカル Kroki（オフライン利用向け）

docker run -d -p 8000:8000 yuzutech/kroki
# Then replace https://kroki.io with http://localhost:8000 in commands

オプション C：ローカル PlantUML jar（従来方式）

# Requires Java + Graphviz
brew install graphviz   # macOS
sudo apt install graphviz  # Ubuntu
# Download plantuml.jar from https://plantuml.com/download
java -jar plantuml.jar diagram.puml

ワークフロー

ステップ 1：依存関係を確認する

curl --version

curl はすべての最新システムで利用できます。見つからない場合は、パッケージマネージャーからインストールしてください。

ステップ 2：図の種類を選ぶ

最も適した PlantUML の図の種類を選びます（以下のリファレンスを参照）。

ステップ 3：.puml ファイルを作成する

@startuml／@enduml マーカーを使って PlantUML のソースファイルを作成します。

ステップ 4：Kroki でエクスポートする（HTTP ステータスを取得する）

まずバックエンドを選択します。以下のデフォルト設定（パブリック Kroki）では、.puml ソースが kroki.io にアップロードされます。機密性の高い図には代わりにローカルバックエンドを使用し、黙ってフォールバックしないでください。references/rendering-backends.md を参照してください。ローカル Kroki の場合は、https://kroki.io を http://localhost:8000 に置き換えます。

# PNG (recommended) — keep the status code so Step 5 can verify it
http=$(curl -s -w "%{http_code}" -o diagram.png \
  -X POST https://kroki.io/plantuml/png \
  -H "Content-Type: text/plain" \
  --data-binary "@diagram.puml")
echo "HTTP $http"

# SVG
http=$(curl -s -w "%{http_code}" -o diagram.svg \
  -X POST https://kroki.io/plantuml/svg \
  -H "Content-Type: text/plain" \
  --data-binary "@diagram.puml")
echo "HTTP $http"

Step 5: 検証して自己修正する（ループ — 省略しないでください）

curl の結果だけで成功を報告してはいけません。出力を先に検証してください。以下のいずれかに当てはまる場合、エクスポートは失敗として扱います。

• $http が 200 ではありません。Kroki は構文エラーで 400 を返し、エラーのテキストを出力ファイルに書き込みます。そのため、.png が存在していても壊れている場合があります。
• ファイルが空です。[ -s diagram.png ] は失敗します。
• バイト列が実際の画像ではありません。file diagram.png は PNG image data を報告する必要があります。SVG の場合、ファイルは <svg または <?xml で始まる必要があります。

if [ "$http" != "200" ] || [ ! -s diagram.png ]; then
  echo "Render failed — Kroki said:"
  cat diagram.png    # the 400 body holds the offending line + reason
fi

失敗した場合は、出力ファイルを cat して Kroki のエラーを確認し、指摘された .puml の行を修正してください（よくある間違いを参照）。その後、Step 4 を再実行します。**最大3回まで繰り返してください。**対象の行を修正しても解決しない場合は、次の順序で内容を簡略化し、各手順の後に再レンダリングしてください。レンダリングに成功した時点で停止します。

1. 特殊な形状を削除し、標準の rectangle／component／node に置き換える
2. skinparam／!theme を削除する（まず標準の設定でレンダリングする）
3. note 行を削除する
4. ラベルを簡潔にし、"…" で囲む
5. エッジを減らす
6. 現在の図の種類に固執せず、よりシンプルな図の種類に切り替える

図の種類ごとのエラーカタログと Kroki で安全に使えるサブセットについては、references/kroki-troubleshooting.md を参照してください。3回試しても失敗する場合は停止し、Kroki の生のエラーをユーザーに表示してください。図を生成できたと主張してはいけません。

Step 6: 自己チェック（画像認識）

Step 5 のループで確認できるのは、Kroki が有効な画像を返したことだけです。図が読みやすいことまでは確認できません。レンダリング後、エージェントの画像認識機能を使って PNG を読み取り、自動レイアウト（Graphviz）では防げない問題を見つけてください。PlantUML はすべての要素を自ら配置するため、ここで確認するのは座標ではなく読みやすさに関する問題です。

確認項目	確認する内容	修正方法
ラベルの切り詰め／はみ出し	テキストが切れている、またはボックスからはみ出している	ラベルを短くする、"…" で囲む、または \n で改行する
コンポーネントの重なり／詰まり	ボックスが接触または密集して読みにくい	together { } やレイアウトヒントを追加する、または図を分割する
向き／縦横比の誤り	図が横または縦に長すぎて読みづらい	left to right direction ↔ top to bottom direction を切り替える
エッジの混線	多数の関係が交差していて追いにくい	宣言の順序を入れ替える、package／together でグループ化する、またはレイアウト用の非表示エッジを追加する
図の種類の誤り	内容に適した図の種類ではない	図の種類を切り替える（シーケンス図、状態図、C4 など）
コントラスト不足	テキストが塗りつぶし／テーマに溶け込んでいる	テキストと塗りつぶしのコントラストが高くなるように skinparam／!theme を調整する

• 自己チェックは最大2ラウンドです。2回修正しても問題が残る場合は、そのままユーザーに表示してください。
• 修正のたびに再レンダリング（Step 4）し、再検証（Step 5）してください。
• 画像認識を利用できない場合は自己チェックを省略し、PNG をそのまま表示してください。

Step 7: レビューループ

自己チェック後、エクスポートした画像を表示し、フィードバックを収集してください。各リクエストに対して最小限の .puml 編集を行い、その後、再レンダリングして再検証してください。

ユーザーのリクエスト	編集内容
ラベルを変更する	.puml の要素／メッセージのテキストを編集する
要素または関係を追加／削除する	該当する行を追加または削除する
色を変更する	skinparam、!theme、または要素のインライン #color を使用する
レイアウトの向きを変更する	left to right direction ↔ top to bottom direction を入れ替える
構造を変更／グループ化する	関連要素を package／together { } で囲むか、再生成する

• 各ラウンドで同じ diagram.puml／出力ファイルを上書きしてください。v1、v2 などのファイルは作成しないでください。
• **安全策：**5ラウンド後は、ユーザーに .puml を直接編集するか、plantuml.com で微調整するよう提案してください。

Step 8: ユーザーへの報告

Step 5〜7 を通過した後にのみ、ユーザーに以下を伝えてください。

• .puml ソースファイルのパス
• エクスポートした PNG／SVG のパス
• 生成したものの簡単な説明
• レンダリングに使用したバックエンドと、ソースがマシンの外部に送信されたかどうか（例：「パブリック Kroki 経由（kroki.io にアップロード）」または「ローカル Kroki 経由（ローカルに留まりました）」）

---

ワークフローのインポート

デフォルト以外の 2 つのモードです。実行時にリンク先のプレイブックを読み込み、同じ Step 4–8 のループを実行します。

• 既存のソースコードから図を生成する — モジュールのクラス図、リクエストハンドラーからのシーケンス図、リポジトリのコンポーネントマップ、ORM モデルからの ER 図を作成します。コードを読み、実際のエンティティと関係を抽出し、実在するものだけを描画します。→ references/from-source-code.md
• Markdown に埋め込まれた PlantUML をレンダリングする — ```plantuml / ```puml ブロック（およびリンクされた .puml）を抽出し、それぞれを画像にレンダリングして、画像リンクを使うよう Markdown を書き換えます（フェンス付き PlantUML をレンダリングできない Confluence / Notion などで公開する場合に便利です）。→ references/markdown-embed.md

---

図の種類

種類	キーワード	用途
シーケンス	@startuml + シーケンス構文	API 呼び出し、プロトコルのフロー、メッセージの受け渡し
コンポーネント	@startuml + コンポーネント	サービスアーキテクチャ、モジュールの依存関係
クラス	@startuml + クラス構文	OOP モデル、データ構造
ER / エンティティ	@startuml + エンティティ構文	データベーススキーマ
アクティビティ	@startuml + アクティビティ構文	ワークフロー、ビジネスプロセス
ユースケース	@startuml + アクター／ユースケース	システム要件、ユーザーストーリー
状態	@startuml + 状態構文	ステートマシン、ライフサイクル
C4 コンテキスト	@startuml + C4 インクルード	システムの概要を示すコンテキストマップ
マインドマップ	@startmindmap	トピックの分類、概念マップ
ガント	@startgantt	プロジェクトのタイムライン、スケジュール

---

構文リファレンス

コンポーネント／アーキテクチャ図

@startuml
!theme plain

title Microservices Architecture

actor "Client" as client
rectangle "API Gateway" as gateway #LightBlue

rectangle "Services" {
  component "User Service" as user
  component "Order Service" as order
}

database "User DB" as userdb
database "Order DB" as orderdb
queue "Kafka" as kafka

client --> gateway
gateway --> user
gateway --> order
user --> userdb
order --> orderdb
order --> kafka : events

@enduml

形状の種類：

• actor "Name" as id — 棒人間（ユーザー、外部アクター）
• component "Name" as id — [角括弧]付きのコンポーネントボックス
• rectangle "Name" as id — 通常の長方形（グループ／レイヤー用）
• database "Name" as id — 円柱（データベース）
• queue "Name" as id — キューの記号
• cloud "Name" as id — 雲形（外部サービス）
• node "Name" as id — サーバー／ノードのボックス
• frame "Name" as id — グループ化するフレーム
• package "Name" { } — パッケージのグループ化

矢印：

• A --> B — 実線の矢印
• A -> B — 細い矢印
• A ..> B — 破線の矢印
• A --> B : label — ラベル付きの矢印
• A <--> B — 双方向

色：

• #LightBlue、#LightGreen、#LightYellow、#Pink、#Violet
• #AED6F1（青）、#A9DFBF（緑）、#FAD7A0（オレンジ）、#F1948A（赤）
• #D7BDE2（紫）、#F9E79F（黄）、#D3D3D3（グレー）

---

シーケンス図

@startuml
!theme plain
title Login Flow

participant "Client" as C
participant "API Gateway" as G
participant "Auth Service" as A
database "User DB" as D

C -> G : POST /login
G -> A : validateCredentials(user, pass)
A -> D : SELECT * FROM users WHERE email = ?
D --> A : user record
A --> G : 200 OK + JWT token
G --> C : { token: "..." }

@enduml

矢印の種類：

• A -> B — 同期呼び出し
• A --> B — 戻り値／破線
• A ->> B — 非同期メッセージ
• A -[#red]-> B — 色付きの矢印
• activate A / deactivate A — アクティベーションボックスを表示

---

クラス図

@startuml
!theme plain

class User {
  +int id
  +String name
  +String email
  +login() : bool
  +logout()
}

class Order {
  +int id
  +Date createdAt
  +float total
  +place()
  +cancel()
}

class Product {
  +int id
  +String name
  +float price
}

User "1" --> "*" Order : places
Order "*" --> "*" Product : contains

@enduml

関係：

• A --> B — 関連
• A --|> B — 継承
• A ..|> B — インターフェースの実装
• A *-- B — コンポジション
• A o-- B — 集約
• A "1" --> "*" B : label — 多重度付き

---

ER 図

@startuml
!theme plain

entity "USER" as user {
  * id : int <<PK>>
  --
  name : varchar
  email : varchar
  created_at : datetime
}

entity "ORDER" as ord {
  * id : int <<PK>>
  --
  * user_id : int <<FK>>
  total : decimal
  status : varchar
}

entity "PRODUCT" as prod {
  * id : int <<PK>>
  --
  name : varchar
  price : decimal
}

user ||--o{ ord : places
ord }o--|{ prod : contains

@enduml

---

アクティビティ図／フローチャート

@startuml
!theme plain

start

:Receive Order;

if (Payment valid?) then (yes)
  :Process Payment;
  :Send Confirmation Email;
  :Update Inventory;
  :Ship Order;
  :Mark as Delivered;
else (no)
  :Send Payment Failed Email;
  :Cancel Order;
endif

stop

@enduml

---

状態図

@startuml
!theme plain

[*] --> Pending

Pending --> Processing : payment_received
Processing --> Shipped : packed
Shipped --> Delivered : confirmed
Processing --> Cancelled : cancel
Pending --> Cancelled : cancel

Delivered --> [*]
Cancelled --> [*]

@enduml

---

C4 コンテキスト図

C4 は、バンドルされた C4-PlantUML 標準ライブラリを !include <C4/...> で使用します。Kroki および最近のローカル jar では、ネットワークから取得しなくても解決できます。標準の plantuml エンドポイントを使ってエクスポートしてください（Kroki の c4plantuml タイプも使用できます）。

@startuml
!include <C4/C4_Context>

title System Context — Internet Banking

Person(customer, "Banking Customer", "A customer of the bank")
System(banking, "Internet Banking System", "Lets customers view their accounts")
System_Ext(mail, "E-mail System", "The internal Microsoft Exchange system")

Rel(customer, banking, "Uses", "HTTPS")
Rel(banking, mail, "Sends e-mail via", "SMTP")
@enduml

その他のレベル：<C4/C4_Container>（Container、ContainerDb）、<C4/C4_Component>（Component）。一般的なマクロ：Person、System、System_Ext、Container、Rel、Boundary。リモートの !includeurl https://… は使用しないでください。Kroki は外部 URL を取得できないため、常にバンドルされた <C4/…> 形式を使用してください。

---

エクスポートコマンド

レンダラーの各種バリエーションのクイックリファレンスです。Kroki のコマンドは簡潔にするためステータスの取得を省略しています。実際にエクスポートする場合は、Step 4 の形式を使用し、Step 5 の検証ループを実行してください。

# PNG via Kroki API (recommended)
curl -s -X POST https://kroki.io/plantuml/png \
  -H "Content-Type: text/plain" \
  --data-binary "@diagram.puml" \
  -o diagram.png

# SVG via Kroki API
curl -s -X POST https://kroki.io/plantuml/svg \
  -H "Content-Type: text/plain" \
  --data-binary "@diagram.puml" \
  -o diagram.svg

# Via local Kroki Docker (offline)
curl -s -X POST http://localhost:8000/plantuml/png \
  -H "Content-Type: text/plain" \
  --data-binary "@diagram.puml" \
  -o diagram.png

# Via local PlantUML jar (if installed)
java -jar plantuml.jar diagram.puml
# Output: diagram.png in same directory

---

テーマ

!theme plain       ← clean, minimal (recommended)
!theme cerulean    ← blue-tinted
!theme blueprint   ← dark blue background
!theme aws-orange  ← AWS style
!theme vibrant     ← vivid colors

または、skinparam を使ってカスタムスタイルを設定します。

skinparam backgroundColor #FAFAFA
skinparam componentBorderColor #555555
skinparam ArrowColor #333333
skinparam FontName Arial

---

よくあるミス

早見表を以下に示します。図の種類ごとのエラーカタログ、Kroki の安全なサブセット、障害時の縮退手順については、references/kroki-troubleshooting.md を参照してください。

ミス	修正方法
curl の POST が HTML のエラーページを返す	ネットワークを確認し、curl -v を試してエラーの詳細を確認します
Kroki が 400 Bad Request を返す	出力ファイルを cat で表示します。Kroki が問題の行と理由を書き込んでいるため、修正してステップ 5 のループで再レンダリングします。https://www.plantuml.com/plantuml/uml/ で構文を検証します
矢印の向きが予想と異なる	下向き／右向きには --> を使い、-up->、-down->、-left->、-right-> を明示的に使います
図が大きすぎる／混み合っている	複数の図に分割するか、package／rectangle によるグループ化を使います
@startuml／@enduml がない	必ずこれらのマーカーで図を囲みます
ラベルに特殊文字が含まれている	"Label: value" のように引用符で囲みます
C4 のインクルードが見つからない	バンドルされた !include <C4/C4_Context> を使います（標準の plantuml エンドポイントおよび c4plantuml で解決されます）。リモートの !includeurl https://… は使わないでください。Kroki は外部 URL を取得できません
コンポーネントが重なる	together { } または明示的なレイアウトヒント（top to bottom direction）を使います
シーケンスの参加者が順不同になっている	希望する左から右の順に、上部で participant を明示的に宣言します