FlowForge

FlowForge — Draw.io 図表スキル

draw.io XML ファイルとして、プロフェッショナルな図表を生成します。13 種類の図表に対応しています。フロー、比較、レイヤースタック、循環、ツリー、ハブアンドスポーク、列、マトリックス、ファネル、タイムライン、シーケンス図、スイムレーンなどがあります。

使い方

/FlowForge "OAuth 2.0 authorization code flow"
/FlowForge path/to/design-doc.md
/FlowForge "CI/CD pipeline" --type loop
/FlowForge "Monolith vs Microservices" --type compare --theme morandi
/FlowForge "System Architecture" --lang en

---

ワークフロー

ステップ 1：内容を把握して提案する（確認は 3 回ではなく 1 回）

ドキュメントが与えられた場合： 全体を読み、図表を入れると効果的な箇所を 1～3 つ特定します。それぞれについて、挿入位置、トピック（1 文）、推奨する種類（「図表の種類のリファレンス」を参照）を記します。

コンセプトが直接与えられた場合： 核となるメッセージを特定し、「選択ガイド」に従って種類を選びます。

提案を 1 つにまとめて提示し、確認を 1 回だけ求めます。提案には以下を含めます。

• 図表の種類とテーマ（デフォルト：tech-blue、その他の選択肢：morandi、mint、terracotta、indigo）
• ASCII スケッチ：すべてのノードとラベル、矢印の向きとラベル、グループ分け、色の役割タグ、レイアウトの方向

スケッチの例：

Direction: left-to-right | Nodes: 4 | Type: flow | Theme: tech-blue

[primary] Code Commit  →  [process] Build  →  [process] Test  →  [accent] Deploy
                                                    ↓ (fail)
                                              [error] Alert

リクエストですでにすべてが指定されている場合（ユーザーが --type／--theme を指定している、または曖昧さのない説明がある場合）、あるいは人間が応答できない場合（サブエージェント、バッチ、CI）は、確認を完全に省略します。その場合はデフォルトを使用し、最終レポートで前提を明記します。

ステップ 2：draw.io XML を生成する

1. references/layouts.md を読み、選択した種類のレイアウトアルゴリズムを確認して、その数式からすべての座標を計算します
2. themes.md のテーマカラーを適用します
3. xml-reference.md の要素テンプレートを使用します
4. 不慣れな種類の場合は、examples.md に記載された該当するサンプルファイルを読みます

ステップ 3：検証する（必須）

python3 {skill_dir}/scripts/validate.py <file.drawio> --theme <theme>

以下を決定的にチェックします。XML の整形式性、一意の ID、参照先のない矢印、直交エッジスタイル、キャンバスの範囲、ノードの重なり、Z 順序（コンテナを子要素より先に配置）、フォントサイズ、テキストの収まりの推定、テーマカラーへの準拠です。すべての ERROR を修正し、エラーがなくなるまで再実行します。 WARN はヒューリスティックな警告です。それぞれを判断し、実際に問題となるものを修正します。

ステップ 4：表示をセルフチェックする（draw.io CLI が利用できる場合）

bash {skill_dir}/scripts/render.sh <file.drawio>   # writes a .png next to the file

スクリプトで draw.io がインストールされていないと報告された場合は、このステップを省略します（ユーザーは brew install --cask drawio を一度実行すれば利用できます）。それ以外の場合は、PNG を読み込み、新鮮な視点で確認します。 ノードからはみ出したテキスト、混み合った領域、ノードと衝突する矢印、色のリズム、全体のバランスを確認します。適切に見えるまで修正して再レンダリングします。ルールでは見つけられない問題を検出できます。

ステップ 5：保存して納品する

.drawio ファイルを出力ディレクトリに保存します（「設定」を参照）。保存後、以下を報告します。

• ファイルパス（およびステップ 4 を実行した場合は、レンダリングされた PNG のパス）
• 開き方：draw.io デスクトップアプリまたは https://app.diagrams.net

反復

表示後にユーザーが変更を求めた場合：

1. 現在の .drawio ファイルを読みます
2. フィードバックに従って XML を変更します
3. {name}_v2.drawio として保存し（以前のバージョンは保持）、その後ステップ 3～4 を再実行します

---

設定

プロジェクトごとに任意の設定ファイル ./.flowforge.json を作成できます（作業ディレクトリ内。スキルディレクトリ内には作成しないでください。スキルディレクトリは読み取り専用、または複数のプロジェクトで共有されている場合があります）。

{
  "defaultTheme": "tech-blue",
  "outputDir": "./diagrams",
  "language": "auto"
}

ファイルがない場合は、以下のデフォルトをそのまま使用します。ユーザーに質問してはいけません。"language": "auto" はユーザーの言語に合わせることを意味します。技術的な略語（API、LLM、CI/CD）は、いずれの場合も英語のままにします。呼び出しごとのフラグ（--theme、--lang）は設定を上書きします。

---

図表の種類のリファレンス

基本タイプ

タイプ	コード	適した用途	例
線形フロー	flow	A→B→C の順次ステップ	API 呼び出しフロー、データパイプライン
垂直フロー	flow-vertical	上から下へ進むプロセス	意思決定プロセス、承認フロー
比較	compare	A と B を横並びで比較	従来の方法と AI のアプローチ
レイヤースタック	layers	技術スタック、階層	システムアーキテクチャのレイヤー
サイクル	loop	反復プロセス	ML トレーニングループ、CI/CD
ツリー	tree	階層、分類体系	組織図、決定木
ハブ＆スポーク	hub	中心となる概念と分岐	製品機能マップ

拡張タイプ

タイプ	コード	適した用途
並列カラム	columns	3 つ以上の並列する概念
マトリクス	matrix	複数の次元での比較
ファネル	funnel	フィルタリング、コンバージョン
タイムライン	timeline	バージョンの変遷、履歴
シーケンス	sequence	コンポーネント間のやり取り
スイムレーン	swimlane	役割をまたぐプロセス（誰が何をするか）

選択ガイド

コンテンツのパターン	推奨タイプ
順次ステップ	flow または flow-vertical
2 つの対象の比較	compare
3 つ以上の並列する概念	columns または hub
階層化されたシステム	layers
反復／循環プロセス	loop
1 つの中心と多数の分岐（マインドマップ形式を含む）	hub または tree
コンポーネント間の通信	sequence
時間の経過に伴う変化	timeline
複数基準による評価	matrix
段階的なフィルタリング	funnel
異なる役割／システムが担当するステップ	swimlane

---

色の使用原則

ビジュアル品質にとって最も重要なセクションです。

4＋6 ルール

各テーマには基本色が 4 色（primary、process、accent、neutral）、拡張色が 6 色（success、warning、error、secondary、storage、group）あります。常にプライマリ系の色を主役にし、プライマリ以外のアクセントの数は図の規模に応じて増やします。

図の規模別の色数の目安

ノード数	色数の目安	ガイドライン
3～5 ノード	2～3 色	プライマリ系の色を主役にします。アクセント色のノードは最大 1 つにします。
6～8 ノード	3～4 色	プライマリ系を約 60％にします。意味的な転換点にプライマリ以外の色を 1～2 色加えます。
9 ノード以上	4～5 色	プライマリ系を約 50％にします。視覚的なリズムを生むよう、プライマリ以外の色を 2～3 色配置します。

図の規模にかかわらず、6 色以上はほとんどの場合見栄えがよくありません。

色の割り当て方針

1. プライマリを主役にする — primary と process は、視覚的に最も大きな領域と最も大きなノードに使用します。
2. アクセントは筆ではなくメスとして使う — 重要な箇所の強調は最大 1～2 か所にし、最も大きなノードには使いません。
3. 長さに応じて調整する — 4 ノードのフローなら 2 色でもすっきり見えますが、9 ノードのフローを 2 色だけで表すと単調な壁のようになります。自然な意味の区切りにプライマリ以外の色を加え、リズムを生み出します。
4. 連続 3 ノードの目安 — 同じ色のノードが 4 つ以上隣り合っていたら、意味的に最も特徴的なノードの色を変えます。
5. 空間的に分散する — プライマリ以外のノードは、1 つの領域に固めず、図全体に分散させます。

意味に基づく色選びの目安

ノードの種類	推奨色
ユーザー入力／開始地点	primary
標準的な処理ステップ	process
判断／分岐点	warning または accent
ドメイン固有のステップ／翻訳ステップ	secondary
重要な変換／強調箇所	accent
データソース／外部システム	neutral
エラーパス／フォールバック	accent または error
成功した出力／終点	success または primary
データベース／ストレージ	storage

色のリズムに関する良い例と悪い例は、themes.md の末尾にあります。

---

設計原則

1. 説明的なタイトル — 「OAuth 2.0 図」ではなく、「OAuth 2.0 によるユーザーの認証」のようなタイトルを使います。
2. 二言語のラベル — ユーザーの言語を使います。技術的な略語（API、LLM、CI/CD）は言語にかかわらず英語のままにします。
3. 直交するフロー矢印 — ノード間のすべての矢印に edgeStyle=orthogonalEdgeStyle; を含め、水平または垂直にのみ進むようにします。例外として、装飾用コネクタで endArrow=none を指定する場合（ハブからの放射線、タイムラインの軸／目盛り）は、直線にしてもかまいません。

---

注意点 — よくある失敗

バリデーター（ステップ 3）でほとんどのジオメトリや参照の誤りを事後に検出できますが、以下を把握しておけば修正の手間を省けます。

1. リッチノードのタイトル重複 — タイトルは独立したテキストセルにあります。背景の矩形では value="" のままにしてください。そうしないと、タイトルが二重に表示されます。
2. 矢印が退出点／進入点を無視する — 必ず exitX/exitY/entryX/entryY を指定してください。指定しないと draw.io が自動でルートを設定し、たいてい不適切な結果になります。
3. value 属性内の HTML エンティティ — value は XML 属性内の HTML です。<、>、& を使い、箇条書きには • を使います。エスケープが 1 つでも抜けると、ファイル全体が壊れます（バリデーター：解析エラー）。
4. 子要素の後に描画した塗りつぶしボックスが子要素を隠す — レーンの帯や塗りつぶしのコンテナーは、その内側のノードより先に定義します（バリデーター：重なり順チェック）。
5. キャンバスが小さすぎる — レイアウトの計算式から pageWidth／pageHeight を算出します：max(x + w) + CANVAS_PAD（バリデーター：境界チェック）。
6. parent="1" の指定漏れ — 意図的にグループ化している場合を除き、すべてのコンテンツ要素に指定する必要があります（バリデーター：親要素チェック）。
7. ひし形のテキストがはみ出す — ひし形の図形で使用できる幅は約 60％です。ラベルは短い語句 2～3 個にとどめ、フォントサイズは 11 にします。
8. 蛇行レイアウトの折り返し矢印 — 折り返し矢印は、ある行の最後のノードの下側から出て、次の行の最初のノードの上側に入ります。横向きにはしません。
9. サイクルの戻り矢印 — loop 図では、最後から最初への矢印を長方形の外側に沿って配置し、中央を通さないでください。
10. 幅のオフバイワン — ノードが n 個なら、間隔は n-1 個です：キャンバス幅 = PAD×2 + n×NODE_W + (n-1)×GAP_H（バリデーター：境界／重なりチェック）。
11. 分岐／合流の矢印が斜めになる — 退出点と進入点が揃っていない場合、直交を保つには edgeStyle=orthogonalEdgeStyle; のみが有効です。すべてのフロー矢印に含めてください（バリデーター：スタイルチェック）。

---

補助ファイル

ワークフローの各ステップで必要になったら読み込みます。最初にすべてを読み込まないでください。

ファイル	読み込むタイミング
references/layouts.md	ステップ 2。座標計算の前 — 共通定数と 13 種類すべてのレイアウトアルゴリズム
themes.md	ステップ 2。色の適用時 — 5 種類のテーマ × 10 種類のセマンティックカラー + 7 種類のテキストカラー、色のリズムの例
xml-reference.md	ステップ 2。XML の作成時 — キャンバスのひな形、要素のテンプレート、矢印の方向表
examples.md	ステップ 2 — 座標計算の手順例とサンプルファイルの一覧
scripts/validate.py	ステップ 3 — 生成したファイルすべてに対して実行します（内容を読むのではなく、実行してください）
scripts/render.sh	ステップ 4 — 目視によるセルフチェック用に PNG をエクスポートします

サンプルの .drawio ファイル（examples/ 内）

同じ種類のものを生成する際の参考として使える、実際に動作するファイルです。

• examples/flow-cicd.drawio — 直線フロー、ノード 4 個、tech-blue
• examples/compare-monolith-vs-micro.drawio — 比較、2 列 × 3 行、morandi
• examples/loop-ml-training.drawio — 時計回りのサイクル、ノード 4 個、mint
• examples/tree-storage-decision.drawio — ひし形を使った決定木、mint
• examples/hub-agent-capabilities.drawio — ハブ＆スポーク、放射線 6 本、indigo
• examples/timeline-llm-history.drawio — 軸と目盛りのあるタイムライン、terracotta