ドキュメントに正しいUML図を埋め込む
エージェントは「図を追加して」と頻繁に依頼されますが、モデリングを微妙に間違えたり(無効な多重度、矢印の逆転、継承の逆方向)、コードブロックを返すだけで画像にレンダリングされないことがよくあります。このスキルは正しいクラス図と実際に埋め込み可能な画像を生成します。
対象範囲
- クラス図のみ(当面)— クラス、属性、関連、多重度、継承。その他のUML図タイプ(ステートマシン、オブジェクト図、シーケンス図、アクティビティ図など)はこのスキルの対象外です。
- 常にBESSER B-UMLを経由 すべての図は最初にB-UMLの
DomainModelとして構築され、その後提供されます。モデルを経由することで、図が正しいだけでなくコードとして再利用可能になります。
開始可能な起点
- 説明文 — ユーザーがドメインを説明し、エージェントがモデルを作成します。
- 既存のコード — エージェントがソースを読み取り、その構造からB-UMLモデルを構築します(自動コードスキャナーはありません。エージェントが読み取った内容からモデリングを行います。ワンクリックインポーターではありません)。
- サポートされているB-UMLへの変換パス — PlantUML、Draw.io、またはUIモックアップ。
2つの提供方法
モデルは一度構築し、埋め込み可能なB-UMLコード(配信A)またはレンダリングされた画像(配信B)として提供します。どちらも同じモデルから生成されるため、矛盾が生じません。コンテキストに応じて選択します(設計ドキュメントで実行可能な状態を維持したい場合はコード、READMEで図を表示したい場合は画像)。または両方を提供することもできます。詳細は以下の配信セクションを参照してください。
出力先 ユーザーが対象ドキュメント(README、設計ドキュメントなど)を指定した場合は、そのファイルに埋め込みます。何も指定しない場合、またはリポジトリ/システムのスタンドアロン図を要求された場合は、デフォルトで新しい自己完結型の .md(例:docs/<モデル名>.md)を提供します。そこには、レンダリングされた画像(配信B)やB-UMLコード(配信A)、図が何を示しているかの説明文が含まれます。これにより、「リポジトリの図を描いて」という単なる要求が、コミット可能なドキュメントになります(単なるSVGファイルではありません)。新しいファイルを作成した場合は、その場所を明示し(また、ユーザーが希望するかもしれない場合は、既存のドキュメントに埋め込む代替案も提示します)。
ワークフロー
1. B-UMLモデルを構築 — 説明文、エージェントが読み取った既存のコード、またはサポートされているB-UMLへの変換パス(PlantUML / Draw.io / モックアップ)のいずれかから
2. model.validate() → 構造的に正しいことを確認
その後、以下のいずれか(または両方)を提供する:
A) コードを埋め込む: DomainModelのPythonコードを.md内のフェンスブロックに記述
B) 画像を埋め込む: モデルをBESSERのヘッドレスSVGエンドポイントにPOST(1回のHTTP呼び出し — ブラウザ不要)、返されたSVGを保存(例:docs/img/data-model.svg)、次のように埋め込む 
3. モデルが変更されたら、モデルを更新して再配信 — 単一の真実のソース
1. モデルを構築する
正しい図は正しいモデルから始まります。最小限の形は次のとおりです。
from besser.BUML.metamodel.structural import (
DomainModel, Class, Property, Multiplicity,
BinaryAssociation, Generalization, StringType, IntegerType,
)
publication = Class(name="Publication", attributes={Property(name="title", type=StringType)})
book = Class(name="Book", attributes={Property(name="pages", type=IntegerType)})
author = Class(name="Author", attributes={Property(name="name", type=StringType)})
book_is_a = Generalization(general=publication, specific=book) # Book is a Publication
# A Book is written by 1..* Authors; an Author writes 0..* Books
written_by = Property(name="writtenBy", type=author, multiplicity=Multiplicity(1, "*"))
writes = Property(name="writes", type=book, multiplicity=Multiplicity(0, "*"))
book_author = BinaryAssociation(name="book_author", ends={written_by, writes})
model = DomainModel(
name="Library",
types={publication, book, author},
associations={book_author},
generalizations={book_is_a},
)
assert model.validate()["success"]
命名規則:スペースやハイフンは使用しません。この最小限の形を超えるもの(列挙型、すべての多重度/構成パターン、関連クラス、汎化セット、メソッド、検証の詳細など)については、このスキルに同梱されている references/class-diagram.md を参照してください。クラス以外のモデルタイプ(オブジェクト、フィーチャー、デプロイメント、OCLなど)については、BESSERプラットフォームの besser-user スキルを参照してください。
インポート可能な形式 — 両方の配信パスで必須 すべての
Class(...)、BinaryAssociation(...)、Generalization(...)は、上記のように明示的なトップレベル代入として記述してください。BESSERのインポーター(SVGエンドポイントおよびエディタのインポートが使用)はファイルの構造を読み取ります。実行はしません。そのため、ヘルパー関数やループ内で構築された関係は見えません。クラスはインポートされますが、関連は静かに消えてしまいます。リレーションシップごとに1つのリテラルステートメントにしてください。インポーターはファイルを実行しないため、
model.validate()はレンダリングパスでは実行されません — エンドポイント経由でレンダリングするためにBESSERをインストールする必要はありません。validate()呼び出しは、BESSERをローカルに持っている場合(およびコード生成前)に使用してください。エンドポイントにとってはノーオペレーションであり、要件ではありません。
モデルの起点:
- 説明文から — 上記のように記述します。
- 既存のコードから — ソースを読み取り、その構造(クラス、フィールド、関係、継承)をB-UMLモデルに変換します。エージェントがモデリングを行います。自動コードスキャナーはありません。
- PlantUML / Draw.io / UIモックアップから — 対応するB-UML変換(BESSERプラットフォームで利用可能)を使用し、続行します。
次に、以下の2つの方法のいずれかで提供します。
配信A — B-UMLコードをドキュメントに埋め込む
モデルをそのまま .md 内のフェンスで囲まれた ```python ブロックに記述します。正しく、validate() で検証済み、再実行可能、エディタにインポート可能です。ドキュメント自体にモデルを保持したい場合(設計ドキュメントや仕様書など)に最適です。
## データモデル
```python
# (上記のDomainModel)
```
このB-UMLモデルはドメインの真実のソースです。`validate()` で検証済みであり、あらゆるBESSERジェネレーターへの入力となります。
配信B — レンダリングされた画像を埋め込む
モデルはBESSERのレンダラーを通じて実際の画像になります。そのため、画像は常にモデルと一致します。手間をかけずに済ませたいか、手動で調整したいかによって、2つの方法から選択できます。
B1. 自動レンダリング(デフォルト)— 1回のHTTP呼び出し、ブラウザ不要
BESSERはヘッドレスな B-UML → SVG エンドポイントを公開しています。エージェントはモデル .py ファイルをPOSTし、SVGを受け取ります。エディタや手動の手順は不要で、ユーザーがクリックする必要もありません。
curl -X POST https://editor.besser-pearl.org/besser_api/get-svg \
-F "[email protected];type=text/x-python" \
-o docs/img/data-model.svg
エンドポイントはB-UMLを解析し、自動レイアウトして image/svg+xml を返します。リポジトリに保存し、以下のように埋め込みます。

- モデルファイルはインポート可能な形式(§1の注釈を参照)である必要があります。これはエディタがインポートするのと同じ形式です。クラス図のみです。
- レイアウトは自動です。配置が重要な場合は、B2を使用して手動調整します。
.pyファイルはBOMなしのUTF-8で保存してください。先頭のバイトオーダーマークがあると、エンドポイントがファイルを拒否します(HTTP 400)。- ここでレンダリングするモデルでは、列挙型リテラルの
default_value=...を省略してください。現在、エンドポイントで失敗します(HTTP 500)。コード生成では問題ありません。属性タイプとして使用されるプレーンな列挙型は正常にレンダリングされます。 - 200以外の応答は、SVGではなく小さなJSONエラーです(
{ "detail": ... })。保存する前にステータスを確認してください。
B2. エディタからの手動調整エクスポート(レイアウトが重要な場合)
https://editor.besser-pearl.org を開き、.py ファイルをインポート(B-UML形式を選択)し、ボックスやルート線を好みに合わせてドラッグし、エクスポートして形式を選択します。
- SVG — どのサイズでも鮮明。ドキュメントやWebに最適。
- PNG — 透明背景。
- PNG(白背景) — 不透明な画像が必要な場合。
リポジトリに保存し、同じ方法で埋め込みます(エディタはモデルを B-UML または JSON としてエクスポートすることもできますが、これらは画像ではなくモデルです)。
どちらの方法でも、SVGとPNGはMarkdown画像がサポートされるすべての場所(GitHub、GitLab、ドキュメントサイト、Wiki、スライド)でレンダリングされ、プラグインは不要です。
乖離を防ぐ
どのモードを選択しても、モデルが真実のソースです。要件が変わったら、モデルを更新して再配信します(コードを貼り直すか、画像をエクスポートし直します)。エクスポートされたSVG/PNGを手動で編集しないでください。それは生成されたものです。
画像以上の価値
図は実際のB-UMLモデルであるため、同じ成果物から動作するコード(Pythonクラス、SQL、FastAPIバックエンド、Django、Reactなど)を生成できます。システムを説明するために描いた図が、システムそのものになる可能性があります。コードを生成するには、besser-generators スキルを参照してください。
関連スキルを使うべき場合
- モデルの詳細な構築(列挙型、継承、メソッド、OCL、オブジェクト/フィーチャー/デプロイメント/NN/量子モデル)→ besser-user スキル
- モデルからのコード生成 → besser-generators スキル
- エラー(インポート/検証/エディタの問題)→ besser-troubleshooting スキル