excalidraw-generator

Excalidraw 図表ジェネレーター

有効な Excalidraw JSON として、プロフェッショナルな図表を生成します。ファイルを書き込む前に、すべてのリクエストで Understand、Propose、Generate、Validate の 4 つのフェーズを実行します。エージェントのコンテキスト予算を尊重するため、本文は簡潔に保ち、詳細は references/ に記載しています。

diagram-generator スイートの一部です。draw.io で正確に編集できる出力が必要な場合は、代わりに drawio-generator を使用してください。diagram-generator の総合機能は、2 つの間で振り分けます。

使用するタイミング

フロントマターの description で、トリガーと除外条件を設定します。出力は .excalidraw ファイルです。リクエストがあった場合に限り、対応する .md ファイルも作成します。

環境の確認

Agent ツールが利用可能な場合は、大規模な図表の作成に Subagent Architecture に従ってサブエージェントを使用してください。新しいコンテキストで検証することで、1 回の実行でコンテキストがあふれるのを防げます。利用できない場合（例：Claude.ai）は、すべてのフェーズをその場で実行し、10 項目のチェックに照らして自己レビューしてください。

編集前のリポジトリ同期（必須）

次のいずれかのタイミングで、1 回実行します。既存の .excalidraw ファイルを読み込む前（Iteration）、それ以外の場合は Phase 4 で書き込む前です。同期先は出力ファイルのディレクトリです。

1. repo="$(git -C "<output dir>" rev-parse --show-toplevel)" を実行します。失敗した場合は同期をスキップし、sync: skipped (not a git repo) と記録します。
2. git -C "$repo" remote get-url origin を実行します。失敗した場合は手順 3〜7 をスキップし、sync: skipped (no origin) と記録します。
3. branch="$(git -C "$repo" rev-parse --abbrev-ref HEAD)" を実行します。出力が HEAD の場合は手順 4〜7 をスキップし、sync: skipped (detached HEAD) と記録します。
4. git -C "$repo" status --porcelain を実行します。出力が空の場合は、git -C "$repo" fetch origin && git -C "$repo" pull --rebase origin "$branch" を実行します。
5. 出力が空でない場合は、git -C "$repo" stash push -u -m "excalidraw-generator pre-sync" を実行してから、同じ fetch と pull を実行し、その後 git -C "$repo" stash pop を実行します。
6. rebase の開始前に fetch または pull が失敗した場合（ネットワーク、認証、リモートブランチが存在しないなど）、再試行しないでください。手順 5 で stash した場合は git -C "$repo" stash pop を実行し、sync: failed (<first error line>) と記録して続行します。最終レポートの Uncertainty: 行にも同じ内容を記載します。
7. rebase で競合が発生した場合は、git -C "$repo" rebase --abort を実行してから、手順 5 で stash した場合は git -C "$repo" stash pop を実行します。stash pop で競合が発生した場合は、stash を残してください。どちらの場合もファイルを書き込まず、作業を停止して、続行方法をユーザーに確認してください。回答がない場合、ステータスは BLOCKED です。

このスキルでは何もコミットしません。

基本ワークフロー

Phase 1: Understand

何かを生成する前に、描画する内容を確認します。

• 明確なリクエスト — 内容を 1 文で言い換え、可視化の種類を提案します。
• 曖昧な入力 — エンティティ、関係性、フローの方向、スタイルについて質問します。
• コード、データ、スキーマ、ファイル — 構造を抽出します（SQL → ER、手順 → フローチャート。全マッピングは references/diagram-types.md を参照）。

Phase 2: Propose

以下の番号付きプランを提示します。

• リクエストで図表の種類とすべての要素が指定されている場合、またはユーザーが「そのまま進めて」と言った場合は、選択したデフォルトを 1 行で示し、Phase 3 に進みます。デフォルト：手描き、roughness: 1、Virgil フォント（fontFamily: 1）、最適なレイアウト。
• それ以外の場合は、ユーザーがプランを確認または変更するまで待ちます。ユーザーの回答前に JSON を生成しないでください。

1. 図表の種類 — references/diagram-types.md のカタログを参照します。複数の種類が適している場合は、番号付きの選択肢を提示します。
2. 主要な要素 — ノードと図形を列挙します。
3. レイアウト — 例：(A) 上から下、(B) 左から右、(C) 放射状。
4. スタイル — 描画スタイル（手描き、スケッチ風、すっきりした仕上がり）と、目的に合った配色を指定します。バリエーションは references/style-and-iteration.md を参照してください。固定のパレットはありません。
5. 推定される複雑さ — 小（要素 10 個未満）、中（10〜30 個）、大（30 個超）。

フェーズ 3：生成

.excalidraw ドキュメントをメモリ上に（ラッパーなしの生の JSON で）構成します。フェーズ 4 でファイルを書き込みます。

出力パス：ユーザーが指定したパスを使用します。指定がない場合は、現在の作業ディレクトリに、内容を表すケバブケースの名前で .excalidraw を末尾に付けたファイル（auth-flow.excalidraw など）を使用します。そのファイルが存在し、ユーザーが更新を依頼していない場合は、上書きする前にユーザーに確認します。更新する場合は、Iteration に従います。

references/excalidraw-format.md の Top-Level Structure にあるエンベロープ（type、version、source、elements、appState、files）を使用し、図に合うように theme と viewBackgroundColor を設定します。このファイルには、すべての要素のスキーマとフィールドのデフォルト値が記載されています。

すべての要素が従うべき重要なルール：

• references/validation-checks.md の Check 2 に記載された必須フィールドをすべて含めます。
• 説明的なケバブケースの ID を使用します（node-api-gateway）。
• 各コンテナーは、バインドされたテキストが収まるサイズにします（Check 10）。テキストサイズを fontSize: 16 未満にせず、図形を大きくしてください。
• テキストと矢印を双方向にバインドします（containerId ↔ boundElements、startBinding/endBinding ↔ boundElements）。

**Markdown への埋め込み：**依頼された場合に限り、まず .excalidraw ファイルを書き込み、次に同じ JSON を excalidraw タグ付きのフェンスコードブロックに含めた .md ファイルを作成します。

フェーズ 4：検証

ファイルを書き込む前に、メモリ上の JSON に対して 10 項目すべてのチェックを実行します。チェック項目、Check 10 の計算式、修正方法については references/validation-checks.md を参照してください。

1. 10 項目のチェックを実行します。すべて合格したら、Repo Sync を実行し、ファイルを書き込んで、ステータスを COMPLETE とする Final Report を提示します。
2. チェックに失敗した場合は修正し、10 項目すべてを再実行します。Check 1 または 8 の失敗はパッチではなく、フェーズ 3 での再生成が必要です。修正サイクルは 3 回で終了します。
3. Check 1～6 に合格しているものの、サイクル 3 の後も Check 7～10 のいずれかに失敗している場合は、Repo Sync を実行してファイルを書き込み、失敗したチェック番号を記載して PARTIAL と報告します。
4. サイクル 3 の後も Check 1～6 のいずれかに失敗している場合は、ファイルを書き込みません。失敗したチェックを記載して BLOCKED と報告します。

10 項目のチェック： (1) JSON エンベロープ、(2) 必須フィールド、(3) ID の一意性、(4) テキストのバインド、(5) 矢印のバインド、(6) 矢印の点、(7) 重なり、(8) 意味上の完全性、(9) テキストの可読性、(10) 図形とテキストの適合性 ― 最もよく発生する失敗です。

---

期待される出力

「ユーザーログインプロセスのフローチャートを描いて」という依頼の場合、ディスクに書き込まれた login-flow.excalidraw ファイル（生の JSON）と、その後の Final Report を出力します。図形とラベルのバインド例については、references/excalidraw-format.md の Minimal bound-text example を参照してください。

Final Report

実行を終了する場合は、停止時も含め、必ず末尾に次の簡潔なテキストブロックを記載します。フェーズ 1～2 で質問し、ユーザーの回答を待っている場合は実行を終了しません。ユーザーが回答せずに実行を終了した場合は、BLOCKED と報告します。ステータスは COMPLETE（ファイルを書き込み、10 項目すべてのチェックに合格）、PARTIAL（ファイルを書き込み、Check 7～10 のいずれかに失敗）、または BLOCKED（ファイルを書き込んでいない）です。記入ルール、PARTIAL と BLOCKED の例、読者向けチェックについては references/final-report.md を参照してください。例：

Result: COMPLETE. Wrote login-flow.excalidraw (6 shapes, 6 text labels, 5 arrows).
Evidence: /abs/path/login-flow.excalidraw. Validation 10/10 checks passed (inline, 1 cycle). sync: skipped (not a git repo)
Uncertainty: Rendering in Excalidraw untested. Assumed top-to-bottom flow; the request gave no direction.
Decision: No approval needed.

受け入れ基準

すべての実行で、次の項目を確認してください。

• ステータスが BLOCKED の場合を除き、.excalidraw ファイルがディスクに書き込まれ、その JSON がトップレベルの type、version、elements、appState、files を含んでいて、正しく解析できる。
• references/validation-checks.md の Check 1～7、9、10 に合格している。または、Final Report に失敗した各チェックが記載されている。
• ユーザーの依頼に含まれるすべての実体と関係が出力に反映されている（Check 8）。
• Final Report は Result: とステータスで始まり、Evidence:、Uncertainty:、Decision: の各行を含む。Evidence: には実行したチェックのみを記載し、10/10 は 10 項目すべてに合格した場合に限り使用する。
• Final Report が references/final-report.md の 4 つの読者向けチェック（結果の見つけやすさ、事実と前提の区別、主張の追跡可能性、次の判断の明確さ）に合格している。人間のレビュアーから回答を得ていない場合、人間が内容を理解したことは確認されていないものとします。

エッジケース

• 入力が空または曖昧な場合（「図を作成して」など）：生成する前に、的を絞った確認質問をします。プレースホルダーは決して生成しません。
• 大きな図（要素数が 30 を超える場合）：Subagent Architecture のループを実行します。修正サイクルは最大 3 回です。
• 非常に大きな図（要素数が 50 を超える場合）：1 つのキャンバスでは混み合うことを伝え、フレーム、複数ファイル、または最初に概要を作成する案を提示して、選択を待ちます。
• 関係が曖昧な場合：生成する前に、方向と多重度を確認します。
• 未対応の図の種類（例：実際の軸スケールが必要なグラフ）：制約を説明し、references/diagram-types.md にある最も近い対応済みの種類を提案します。
• ユーザーが既存の .excalidraw ファイルを提供した場合：Iteration に従います。最初から再生成してはいけません。

その他のエッジケース：references/style-and-iteration.md。

---

フェーズ完了レポート

各フェーズの後、そのフェーズのチェック項目を含む短いステータスレポートを出力します。テンプレートとフェーズごとのチェック項目は references/step-reports.md にあります。Validate レポートは Final Report の前に出力します。これは Final Report の代わりにはなりません。

イテレーション

既存の図を反復処理する場合は、ファイルを読み込み、メモリ上で JSON を変更します。変更されていない要素 ID は保持します（リクエストのパターン：references/style-and-iteration.md → Iteration）。ファイルを書き換える前に、結果に対してフェーズ 4 を実行します。結果が BLOCKED の場合、元のファイルには手を加えません。

---

サブエージェントアーキテクチャ

大きな図（要素数が 30 を超える場合）ではこのループを実行し、それ以外はインラインで処理します。詳細：references/style-and-iteration.md → Subagent Architecture。

1. 生成 — 確定した計画を使用して agents/json-generator.md を起動します。
2. 検証 — agents/json-validator.md を起動します。10 項目すべてのチェックについて PASS/FAIL を報告します。
3. 修正 — NEEDS_FIX の場合は agents/json-fixer.md を起動し、再生成せずにパッチを適用します。ready_for_validation: false が返された場合（チェック 1 または 8）、代わりにジェネレーターを再度起動します。修正または再生成を 1 サイクルとして数え、最大 3 サイクルで停止します。
4. メインエージェントは、返された JSON と最後のバリデーターのレポートに対して、フェーズ 4 の手順 1～4 を適用します。