C4 コンテナ図ジェネレータは何をしますか？

C4 モデルに従ったコンテナ図を生成し、draw.io（デスクトップ版または Web 版）で直接開ける編集可能な .drawio XML ファイルとしてエクスポートします。

使用タイミング

明示的なトリガー:

ユーザーが C4 図、コンテナ図、アーキテクチャ図を依頼したとき
ユーザーが「アーキテクチャを描いて」「システム図」「コンポーネントを見せて」と言ったとき
ユーザーがドキュメントやプレゼンテーションのためにシステムアーキテクチャを可視化する必要があるとき
ユーザーが draw.io、drawio に言及したとき、または編集可能な図を希望したとき

プロアクティブなトリガー:

3 つ以上の相互作用するコンポーネントを持つシステムを説明しているとき
マイクロサービス、API、データベース、それらの関係について議論しているとき
システムアーキテクチャをレビューまたは設計しているとき

スキップすべき場合:

ユーザーが単純なフローチャートを希望する場合（代わりに Mermaid を使用）
ユーザーが UI ワイヤーフレームやモックアップを希望する場合
システムのコンポーネントが 3 つ未満の場合

プロセス

ステップ 1: 要件を収集する

会話から特定するか、ユーザーに質問します:

どのシステムを図示しますか？
ユーザー/アクター（Person）は誰ですか？
どのコンテナ（アプリ、サービス、データベース、キュー、ファイルストレージ）が存在しますか？
どの外部システムと相互作用しますか？
主要なデータフローとプロトコルは何ですか？

ユーザーが仕様、コードベースの説明、またはアーキテクチャ概要を提供した場合、自動的に要素を抽出し、生成前に確認します。

ステップ 2: 要素を分類する

すべての要素を C4 カテゴリにマッピングします:

カテゴリ	色	形状	説明
Person	`#08427B`（濃い青）	`shape=actor` + テキストラベル	ユーザー、アクター、役割
Container	`#438DD5`（青）	角丸長方形	アプリケーション、サービス、API
Database	`#438DD5`（青）	円柱	任意のデータストア（SQL、NoSQL、ファイル）
Queue/Broker	`#438DD5`（青）	ラベル付き角丸長方形	メッセージキュー、イベントバス
External System	`#999999`（グレー）	角丸長方形	サードパーティサービス、API
System Boundary	なし（透明）	破線の長方形	内部コンテナをグループ化

参考: 正確な draw.io XML テンプレートについては references/element-templates.md を参照してください。

ステップ 3: レイアウトを計画する

厳密な階層レイアウト（上から下）を適用します:

レイヤー 1 (y ~= 20):     Person 要素（アクター）
レイヤー 2 (y ~= 250):    内部コンテナを含む System Boundary
レイヤー 3 (y ~= 700+):   外部システム

レイアウトルール:

すべての要素に明示的な x, y 座標を指定（自動レイアウト禁止）
同じレイヤー内の要素間の水平方向の最小ギャップは 200px
レイヤー間の垂直方向の最小ギャップは 200px
System Boundary = すべての内部コンテナを 40px のパディングで囲む破線の長方形
主要なデータフローの方向に従って要素を左から右に配置
システムに明確なサブシステムがある場合は、関連するコンテナをサブ境界内にグループ化
読みやすさのため、図の幅を 1600px 未満に保つ
レイヤー内の要素を水平方向に中央揃え

線の交差を最小限にする:

頻繁に通信する要素を隣接して配置
可能な場合は接続を垂直にルーティング
他の要素を横切る対角線を避ける
無関係なコンテナを通る矢印は禁止: A が C に接続する場合、矢印が B を通過してはいけません。修正方法: (a) A と C を隣接して配置、(b) 明示的な出入口ポイントを使用、(c) レイアウトを再編成
矢印ラベルがコンテナテキストと重ならないようにする: すべてのエッジに labelBackgroundColor=#ffffff を使用し、mxGeometry の垂直オフセット（y）を使用してラベルをコンテナから遠ざける

ステップ 4: 接続を定義する

各接続について以下を指定:

ソース要素とターゲット要素
ラベル: アクション + プロトコル（例: "Reads/writes [SQL/TCP]", "Sends events [AMQP]"）
スタイル: 実線 = 同期呼び出し、破線 = 非同期（イベント、キュー、ウェブフック）
方向: 常にソース -> ターゲット（データフローに従う）

接続ルール:

すべての矢印にラベルが必要（ラベルのない接続は禁止）- ラベルが重なる場合は、レイアウトを修正するかオフセットを調整し、ラベルを決して削除しない
接続スタイルに常に labelBackgroundColor=#ffffff を含める
[プロトコル] サフィックスを使用: [REST/JSON], [gRPC], [SQL], [AMQP], [WebSocket]
双方向フロー: 異なるラベルを持つ 2 つの個別の矢印を使用
自己参照: 避ける（代わりに図を再構成）

ステップ 5: .drawio XML を生成する

ベースとして references/drawio-template.md の XML 構造を使用します。

以下のルールに従って XML を構築:

<mxfile> ラッパーと適切な寸法の <mxGraphModel> で開始
ルートセル（id="0" および id="1"）を追加
最初に System Boundary 長方形を追加（含まれる要素の親になる）
明示的なジオメトリ（x, y, width, height）を持つすべての要素を追加
ソース/ターゲット参照を持つすべての接続を追加
右下隅に凡例を追加

要素のサイズ:

Person: 40 x 60px アクター + その下に 220 x 60px テキストラベル
Container: 240 x 120px
Database（円柱）: 240 x 120px
External System: 240 x 120px
System Boundary: 子を囲むように計算 + 各辺に 40px のパディング

ステップ 6: 凡例を追加する

すべての図には凡例が必須です。 右下隅に配置します。

凡例には以下を表示:

Person = 濃い青の棒人間（#08427B）
Container = 青の角丸長方形（#438DD5）
Database = 青の円柱（#438DD5）
External System = グレーの角丸長方形（#999999）
実線矢印 = 同期フロー
破線矢印 = 非同期フロー

参考: 正確な XML については references/legend-template.md を参照してください。

ステップ 7: 保存して検証する

ユーザーが指定したパスに保存するか、デフォルトでは ./c4_[システム名].drawio に保存します。

検証チェックリスト:

C4 モデルルール

C4 コンテナ図の制約に従います:

コンテナ図は、高レベルの技術選択とコンテナ間の通信方法を示します
各コンテナは個別にデプロイ/実行可能な単位です（クラスやモジュールではありません）
C4 レベルを混在させない: このスキルはコンテナレベルのみを生成します
コンテナ内のコンポーネントレベルの詳細については、別の図を作成します
Person 要素は役割を表し、個人を表すものではありません
外部システムは、チームが所有していないシステム境界外のすべてのものです

アンチパターン

自動レイアウト禁止 - 予測可能な結果を得るために、常に明示的な x, y 座標を使用
ラベルのない矢印禁止 - すべての接続にアクションとプロトコルが必要
凡例の欠落禁止 - すべての図に凡例が必須
窮屈なレイアウト禁止 - 要素間の最小ギャップを維持
C4 レベルの混在禁止 - コンテナレベルのみ（クラス、インフラストラクチャは含めない）
非表示テキスト禁止 - フォント色が背景とコントラストを持つことを確認
ハードコードされた寸法禁止 - 子から System Boundary のサイズを計算
mxgraph.c4.* 形状の使用禁止 - これらは draw.io でデフォルトでロードされない C4 形状ライブラリが必要です。代わりに組み込み形状を使用: Person には shape=actor、データベースには shape=cylinder3
無関係なコンテナを通る矢印禁止 - すべての矢印がソースとターゲットの間に明確なパスを持つようにレイアウトを再配置
labelBackgroundColor=#ffffff なしのラベル禁止 - ラベルが他の要素を横切るときに読めなくなる
重なりを修正するためのラベル削除禁止 - ラベルがコンテナと重なる場合は、レイアウトを修正するかオフセットを調整し、情報を決して削除しない

C4 コンテナ図ジェネレータ