ダイアグラム
視覚的な議論とネイティブソースをそれぞれ独立して正しく保ちながら、ダイアグラムを設計、作成、レビュー、変換します。
機械可読なオンボーディング契約に、外部の前提条件がリストされています。
2つの決定を解決する
まず、関係性を表現するビュー（フローチャート、シーケンス図、状態図、アーキテクチャ図、データモデル、階層図、タイムライン、比較図、またはその他のサポートされているビュー）を選択します。次に、配信形式を選択します。使い慣れたファイル形式にダイアグラムの種類を決定させないでください。
明示的な形式は、必要な構造を表現できる場合に優先されます。それが重大な制限を生み出す場合は、制限を説明し、暗黙的に成果物を変更せずに代替案を提案します。
形式が未確定の場合は、以下のマトリックスを使用します。
| 制約 | Excalidraw | Mermaid | draw.io |
|---|---|---|---|
| 手動座標制御 | 強 | 弱；レイアウトは自動 | 強 |
| 協調的なビジュアル編集 | Excalidrawで強 | ホストに依存 | diagrams.netで強 |
| テキスト差分とコードレビュー | 不良 | 強 | 非圧縮XMLで中程度 |
| 自動レイアウト | 手動優先 | 強 | 利用可能だが、手動ジオメトリは明示的に残る |
| 自由な空間構成 | 強 | 制限あり | 強 |
| ページ、レイヤー、コンテナ、シェイプライブラリ | 制限あり | 制限あり、レンダラー依存 | 強 |
| 直接的なMarkdown/チャットレンダリング | 稀 | サポートされている場合に強 | 稀 |
| ハンドオフ後のネイティブ編集可能性 | .excalidraw | 互換性のあるエディタ内のMermaidソース | .drawio XML |
| 信頼性の高い検証とレンダリング | チェッカーと忠実なレンダラーが必要 | ターゲットパーサーとレンダラーが必要 | XMLチェックと互換性のあるエディタ/エクスポーターが必要 |
ネイティブエディタ、バリデーター、レンダラーが配信環境で利用可能な形式を優先します。どれも視覚的な証明を提供できない場合は、それでも有用な場合にのみ要求されたネイティブソースを生成し、結果にDEGRADEDというラベルを付けます。
視覚的な議論を所有する
1つの質問、オーディエンス、配信ビューポート、エントリポイント、および支配的な読み取り方向を決定します。説明的なラベルを短縮しながら、正確な事実と識別子を保持します。構文や座標の前に、セマンティックノード、境界、関係をモデル化します。
ダイアグラムを作成または大幅に改訂する前に、共有設計メソッドを読んでください。そのメソッドは、トポロジー、階層、密度、グループ化、境界、ルーティング、セマンティックシェイプ/色/線の使用、分割基準、およびビジュアルアクセプタンスを所有します。
1つの形式アダプタを使用する
- ネイティブの
.excalidrawJSONについては、Excalidrawアダプタを読んでください。そのバンドルされたチェッカーを実行し、忠実なレンダリングを検査します。 - Mermaidソースまたはチャット内のMermaidブロックについては、Mermaidアダプタを読んでください。実際のターゲットまたは互換性のある既存のツールでパースしてレンダリングします。
- ネイティブの
.drawioXMLについては、draw.ioアダプタを読んでください。XML構造を検証し、互換性のあるdiagrams.netツールで開くかエクスポートし、結果を検査します。
形式アダプタは、シリアライゼーション、エスケープ、識別子、バインディング、ジオメトリ、テーマ、ページ、レイヤー、およびレンダラー固有の制限を所有します。不安定なメカニズムをこのコアにコピーしないでください。
ネイティブソースを保持する
新しい名前付きパスの成果物の場合、要求されたパスは最初に書き込まれたときに正規のものになります。改訂の場合、変更が候補に存在する間、既存のソースは正規のままです。エディタとレンダラーはこれらのアーティファクトを消費します。他の場所へのエクスポートが暗黙的に正規のソースを置き換えることはありません。
改訂候補は、完了ゲートを満たした場合にのみ、既存のソースを置き換えます。それ以外の場合はDEGRADEDを報告し、既存のソースを変更せずに残し、候補を未完了として識別します。
変換とレビュー
変換全体でセマンティックな同一性（ノードの意味、関係の方向、シーケンス、包含、境界、カーディナリティ、および正確な技術トークン）を保持します。ソースとターゲットの両方がサポートしている場合は、ページ、レイヤー、およびコンテナの同一性を保持します。自動レイアウトの変更、サポートされていないシェイプライブラリ、またはフラット化されたスタイリングなどの損失を明記します。ピクセル単位のパリティを決して約束しないでください。
レビュー専用の作業の場合は、書き換えずに検査して報告します。ネイティブ構造をレンダリング構成とは別にチェックします。パースの成功は可読性を証明せず、もっともらしい画像は編集可能性を証明しません。
トリガー境界
このスキルは、明示的なx9-diagrams呼び出し、形式選択、形式間変換、共有ビジュアルメソッド、および構造的検証とビジュアル検証を組み合わせたものを所有します。通常のMermaid構文のみに限定されたリクエストは、インストールされている専門のmermaid-diagramsスキルに任せることができます。このスキルは、そのサードパーティスキルを持たないユーザー向けに自己完結型のままです。
トリガーの所有権があいまいな場合、タスクがより広範な決定または検証契約を必要とする場合にのみx9-diagramsを使用します。リクエストにMermaidが含まれているという理由だけで両方のスキルを呼び出さないでください。
完了ゲート
完了のエビデンスを要求されたアクションに一致させます。
- 形式選択: ビューと配信形式を指定し、選択をユーザーの制約に結び付け、重要な制限を述べ、互換性のあるバリデーター、レンダラー、またはエディタが利用可能かどうかを識別します。
- 作成または大幅な改訂: 選択されたビューが述べられた質問に答えること。ネイティブソースがパースまたは開かれ、編集可能なままであること。エージェントが自身で完了できないネイティブファイルまたはディレクトリチューザーをトリガーしていないこと。該当する場合、形式固有のロード後レイアウトが安定していること。互換性のあるレンダラーまたはエディタが、最後の実質的な変更後の最終的な正規ソースから実際のビューを生成したこと。そのビューが宣言された配信モードで、可読性、階層、交差、クリッピング、および誤解を招く構造について検査されたこと。
- 変換: 作成のエビデンスを満たし、重要なセマンティクスが維持されたことを確認すること。レイアウト、スタイリング、ページ、レイヤー、コンテナ、または表記法における損失を明記すること。
- レビューのみ: ネイティブ構造の所見をレンダリング構成の所見から区別し、アーティファクトを書き換えずに検査されたエビデンスを引用すること。
アクティブなアクションに必要なエビデンスが取得できない場合は、不足しているチェック、バリデーター、レンダラー、エディタ、またはソースアーティファクトを正確に示してDEGRADEDを報告します。Excalidrawチェッカーの回帰テストはscripts/test_check_scene.pyにあります。