c4-diagrams

C4 図

概要

詳細設計の前に、C4 図を使ってソフトウェアアーキテクチャを明確にします。境界、責任、アクター、依存関係、データフローに焦点を当て、価値をもたらすレベルだけを図示します。

最初に確認すること

図を作成する前に、以下の項目を確認します。ユーザーがすでに指定している場合は、それに従います。複数の選択肢が曖昧な場合は、簡潔な質問をまとめて一つ尋ねます。

選択項目	選択肢	デフォルトの動作
目的	既存のコード、新規システム、設計レビュー	既存のコードでは、まずコードベースを調査します。新規システムでは、前提を明示する必要があります。
形式	ASCII、Mermaid	ユーザーに尋ねます。Mermaid は、C4 専用の Mermaid ではなく、プレーンな Mermaid 構文を指します。
厳密さ	厳密な C4、軽量な C4 に着想を得た形式、ハイブリッド	ユーザーに尋ねます。黙って決めてはいけません。

ユーザーが時間短縮のために質問を省くよう求めた場合も、未解決の選択肢は明示的な前提として残し、最初の図は軽量なものにします。

ワークフロー

1. 目的、形式、厳密さを確認します。
2. 既存のコードでは、図を描く前にエントリーポイント、実行時の境界、連携先、永続化の仕組みを調べます。手早く確認する場合は、言語やフレームワーク、起動エントリーポイント、主なディレクトリ、外部連携、データストアを特定できる程度に調査し、それ以外は不明として記載します。
3. 必要最小限で役立つ図のセットを選びます。システムコンテキスト図またはコンテナー図から始め、実際の疑問に答える場合にのみ、コンポーネント図、動的図、デプロイメント図を追加します。
4. ASCII またはプレーンな Mermaid を使って図を描きます。
5. 境界、責任、主な関係、前提、未解決の質問を、3～6 個の箇条書きで説明します。
6. ユーザーが図を承認し、続行を求めない限り、詳細設計に進まずに終えます。

C4 のレベル選択

レベル	使用する場面	避ける場面
システムコンテキスト	ユーザー、外部システム、対象範囲の特定	対象範囲がすでに明らかで、局所的な場合。
コンテナー	デプロイ可能／実行可能な単位、データストア、API、CLI、キューの表示	コードレベルの呼び出しフローだけが必要な場合。
コンポーネント	1 つのコンテナー内部の説明	コンテナーに意味のある内部要素がほとんどない場合。
コード	重要なクラス／モジュールに限り、まれに使用	通常のコンポーネント図で十分な場合。
動的	リクエスト、イベント、ワークフローのシーケンスの表示	静的な構造が実際の質問である場合。
デプロイメント	インフラストラクチャ、ノード、ネットワーク、実行環境の配置の表示	デプロイ方法が不明、または無関係な場合。

小規模なシステムでは、C4 の 4 つのレベルすべてを求める依頼に対し、より小さなセットを提案します。それでもユーザーが 4 つすべてを希望する場合は作成しますが、価値の低いレベルは軽量なスケッチとして示し、維持する価値が低い理由を説明します。

出力ルール

• Mermaid 図は、移植性を確保するため、プレーンな flowchart または sequenceDiagram 構文を使います。
• ASCII 図では、装飾的な複雑さより、読みやすいボックスと矢印を優先します。
• ラベルは具体的にします。アクター、システム、コンテナー、コンポーネント、データベース、キュー、外部サービスなどを使います。
• レベルを誤って混在させないでください。コンテナーは実行可能／デプロイ可能な単位であり、コンポーネントは 1 つのコンテナー内にあります。
• 将来のシステムや不完全なコードベースを図示する場合は、必ず前提を記載します。
• 境界、所有権、データフロー、デプロイ方法が不明な場合は、必ず未解決の質問を記載します。

テンプレート

簡潔な ASCII および Mermaid の出発点として、このスキルのディレクトリにある templates.md を使います。

よくある間違い

間違い	修正方法
デフォルトですべての C4 レベルを描く	現在の質問に答えるレベルだけを描きます。
すぐに詳細設計へ進む	まずコンテキストとコンテナーの境界を確認します。
C4 専用の Mermaid 構文を使う	プレーンな Mermaid の flowchart または sequenceDiagram を使います。
モジュールをコンテナーとして扱う	コンテナーは実行可能／デプロイ可能な単位であり、モジュールは通常コンポーネントです。
不確実な点を隠す	図の後に前提と未解決の質問を記載します。