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"

ステップ 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 の行を修正してください（よくある間違いを参照）。その後、ステップ 4 を再実行します。最大 3 回まで繰り返してください。 該当行の修正で解消しない場合は、次の順に簡略化し、それぞれの手順の後に再レンダリングしてください。レンダリングできた時点で終了します。

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

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

ステップ 6：セルフチェック（視覚確認）

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

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

• セルフチェックは最大 2 回です。2 回修正しても問題が残る場合は、そのままユーザーに表示してください。
• 修正のたびに 再レンダリング（ステップ 4）し、再検証（ステップ 5）してください。
• 視覚機能を利用できない場合は、セルフチェックを省略し、PNG をそのまま表示してください。

ステップ 7：レビューのループ

セルフチェックの後、エクスポートした画像を表示してフィードバックを受け取ります。依頼ごとに最小限の .puml 編集を行い、再レンダリングして再検証してください。

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

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

ステップ 8：ユーザーへの報告

ステップ 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 は問題のある行と理由をそこに書き込んでいます。修正して、Step 5 のループで再レンダリングしてください。https://www.plantuml.com/plantuml/uml/ で構文を検証してください
矢印の向きが想定と異なる	下向き／右向きには --> を使い、-up->、-down->、-left->、-right-> を明示的に使用してください
図が大きすぎる／混み合っている	複数の図に分割するか、package／rectangle でグループ化してください
@startuml／@enduml がない	図は必ずこれらのマーカーで囲んでください
ラベル内の特殊文字	"Label: value" のように引用符で囲んでください
C4 の include が見つからない	バンドルされた !include <C4/C4_Context> を使用してください（標準の plantuml エンドポイントと c4plantuml で解決されます）。リモートの !includeurl https://… は使用しないでください。Kroki は外部 URL を取得できません
コンポーネントが重なる	together { } または明示的なレイアウト指定（top to bottom direction）を使用してください
シーケンス参加者の順序が正しくない	希望する左から右への順序で、先頭に participant を明示的に宣言してください