diagram-quality

agent-uml の図の品質に関するベストプラクティス

人間と Claude の設計に関する会話を、agent-uml キャンバス上でより速く収束させます。

適用するタイミング

• diagram_upsert を呼び出す前に毎回 — 構文の安全規則を確認し、適切な skinparam プリセットを適用します
• design_feedback の応答を受け取るたびに — バージョン管理の判断表を参照し、次に取るべきアクションを選択します
• 新しい設計セッションを開始するとき — 図を並べる際は段階的な詳細レイヤーに従います
• design_export を呼び出す前に — エクスポート準備チェックリストを実行します
• 図が空白で表示されたり、要素をクリックできなかったりするとき — 描画の安全規則を参照します

優先度別のルールカテゴリ

優先度	セクション	影響	参照先
1	描画の安全性	重大	syn-safety.md, _presets.md
2	会話の仕組み	高	_conversation.md
3	設計の有効性	中	_design.md

クイックリファレンス

1. 描画の安全性（重大）

キャンバスが空白になるのを防ぎ、操作可能な SVG を確実にする 18 のルールです。PlantUML ソースを書く前に syn-safety.md をお読みください。

主なルール：

• すべての要素に as Alias を付けます — 付けないと、キャンバス上で要素をクリックできません
• skinparam backgroundColor transparent — 白のデフォルト背景は #f4f1ec のキャンバスと衝突します
• _presets.md から適切なプリセットをコピーします — 図の種類ごとに 1 つのブロックを選び、キャンバスの CSS 変数に合わせます

2. 会話の仕組み（高）

フィードバックへの応答ループに関する 5 つの判断表です。次にどのツールを呼び出すかを決める際は、_conversation.md をお読みください。

主な表：

• 表 4：シグナル → アクション — 注釈、チャット、無応答、タイムアウトを適切なツール呼び出しに対応付けます
• 表 5：メッセージの内容 — message パラメーターに何を書くかを示します（変更点を説明し、焦点を絞った質問をします）

3. 設計の有効性（中）

具体的な基準値を含む 4 つのヒューリスティックです。図の順序を計画するときや、エクスポートの準備をするときは、_design.md をお読みください。

主なヒューリスティック：

• 段階的な詳細レイヤー — L1 コンテキスト → L2 コンテナー → L3 クラス → L4 振る舞い → L5 状態
• 相互参照の追跡可能性 — すべてのシーケンスの参加者をコンポーネントに対応付けます。すべてのインターフェースは、必ず 1 つのコンポーネント境界に属する必要があります
• 分割の基準値 — コンポーネントが 12 個超、クラスが 15 個超、シーケンスの参加者が 10 人超、またはメッセージが 20 件超の場合は分割します

使用方法

1. セッションの開始時： _conversation.md の表 3（図の種類の範囲）を読み、最初に作成する図を決めます
2. PlantUML の記述時： _presets.md の skinparam プリセットを適用し、続いて syn-safety.md で図の種類に該当するルールを確認します
3. フィードバックを受けた後： _conversation.md の表 4（シグナル → アクション）を参照し、新しいバージョンを送るか、質問で返信するかを決めます
4. エクスポートの前に： _design.md のヒューリスティック 4 にあるチェックリストを実行します

参照ファイル

ファイル	説明
references/_sections.md	セクションの定義と順序
references/syn-safety.md	描画の安全に関する 18 のルール（誤り／正しい例）
references/_presets.md	図の種類ごとにコピーして使える 5 つの skinparam プリセット
references/_conversation.md	会話ループに関する 5 つの判断表
references/_design.md	基準値を含む 4 つのヒューリスティック
assets/templates/_template.md	新しいルールを追加するためのテンプレート
metadata.json	バージョンと参照情報