C4コンテナ図 ドキュメント作成ルール

C4 Container Diagram (CND) Documentation Rules

本ドキュメントは、アーキテクチャ設計のために C4コンテナ図と、その図を説明する文章を、統一した粒度・表現で作成するためのルールです。

この章の成果物は、次の2つをセットで扱います。

• C4コンテナ図（Mermaid）: 対象システムを主要コンテナ（実行/配備単位）に分割し、利用者・外部システム・データストアとの関係を俯瞰で合意する
• 説明（Markdown）: 図の要素（人/境界/コンテナ/DB/外部/関係）の意味を文章で合意する

Mermaid 記法そのもののルールは cnd-mermaid-rules.md を参照してください。

1. 全体方針

• CND は「対象システムが、どの実行/配備単位（コンテナ）で構成され、何とやり取りするか」を合意するための図である。
• 図に入れるのは コンテナ粒度までとし、コンポーネント/クラス等の内部構造や実装詳細は含めない。
• 1つの図には 対象システムを1つだけ置く（複数対象がある場合は図を分ける）。
• 図は「正確さ（過剰な詳細）」よりも「解釈が割れないこと（合意）」を優先する。

2. ファイル命名・ID規則

• ファイル名: cnd-<番号>-<短い日本語名>.md
  • 例: cnd-010-駄菓子屋きぬや販売管理システム-コンテナ.md
• Frontmatter:
  • id: 小文字ハイフン形式（例: cnd-candy-shop-sales-container）
  • title: 「〇〇のC4コンテナ図」のように対象が分かる表現

3. 推奨 Frontmatter 項目

Frontmatter の共通ルールは meta-document-metadata-rules.md に従います。

項目	説明	必須
id	ドキュメントID（小文字ハイフン）	○
type	architecture 固定	○
title	ドキュメント名	○
status	draft/ready/deprecated	○
part_of	上位ドキュメントID（分割している場合）	任意
based_on	根拠となる定義（用語集、外部IF、上位方針など）	任意
supersedes	置き換え関係（古い図→新しい図）	任意

3.1. based_on の考え方（例）

• 用語集（gl-...）や業務データ辞書（bdd-...）
• 外部システムIFの仕様（IF章のドキュメント）
• 参照する上位の方針（ADR、非機能要件など）

4. CNDで合意すること（スコープ）

4.1. 合意したいこと

• 対象システムの境界（System Boundary）と、責務の一言（何をするシステムか）
• 主要コンテナ（Container）の一覧と、それぞれの責務（1〜2文）
• 主要DB（Database）がある場合、その役割（何を永続化するか）
• 外部システム（External Software System）と、連携の意図（何をやり取りするか）
• 関係（Relationship）の向きと意味（誰が主に呼び出す/依存するか）

4.2. 合意しないこと（この図で扱わない）

• コンテナ内部の分解（コンポーネント/クラス、内部モジュール構成）
• APIエンドポイント、HTTPメソッド、リクエスト/レスポンスJSONなどのIF詳細
• 物理テーブル名・物理カラム名・SQL全文
• 実装クラス/関数名、ライブラリ名、具体的な技術選定の列挙
• 画面遷移やクリック手順の逐語列挙

5. CNDの要素定義（図と文章の両方で説明する）

この章では、図に描いた要素について 最低限の説明を併記し、レビュー可能にします。

5.1. Person（人/ロール）

Personは、対象システムに対して目的をもって関わる主体（人/役割/組織）です。

• 書くこと（推奨）:
  • ロール名（例: 店員、店主、経理担当）
  • どのコンテナを、何のために利用するか（例: Webアプリで売上登録を行う）
• 書かないこと:
  • 個人名、UI操作手順の逐語列挙

5.2. System Boundary（システム境界）

境界は「対象システムが責任を持つ範囲」を表します。

• 書くこと（推奨）:
  • 境界に含めるもの
  • 境界に含めないもの（外部システム/外部サービス等）

5.3. Container（コンテナ）

コンテナは、実行/配備単位（例: Webアプリ、API、バッチ）です。

• 書くこと（必須）:
  • コンテナ名
  • 責務（1〜2文）
• 書くこと（推奨）:
  • 主な入出力の種類（例: 売上登録、在庫照会）
  • 関係するデータストア（例: 販売DBを更新する）
• 書かないこと:
  • 内部クラス/関数、モジュール階層の列挙

5.4. Database（データベース）

Database は、対象システム内の主要な永続データストアです。

• 書くこと（推奨）:
  • DBの論理名（例: 販売DB、在庫DB）
  • 何を永続化するか（例: 売上・在庫・仕入の記録）
• 書かないこと:
  • 物理テーブル名・物理カラム名・SQL

5.5. External Software System（外部システム）

対象システムの外側にあり、対象システムが連携する相手（既存の別システム、SaaS、決済、会計など）です。

• 書くこと（推奨）:
  • 外部システム名（一般名でよい）
  • 連携の目的（例: 決済を依頼する、仕訳を送る）
  • 連携の方向性（誰が主に呼び出す/依存するか）
• 書かないこと:
  • API仕様の詳細、データ項目一覧（それらはIF仕様へ）

5.6. Relationship（関係）

関係は「やり取りの意味」を合意するための線です。CNDでは すべての関係にラベルを付けます。

• 書くこと（必須）:
  • 方向（誰が主に利用/依存/送信するか）
  • ラベル（短い日本語。名詞句または短い動詞句）
• 書かないこと:
  • HTTP詳細、データ項目列挙、SQL、実装条件式

6. 本文構成（標準テンプレ）

各 CND 成果物は、以下見出しを順番に並べます。

1. 概要
2. C4コンテナ図（Mermaid）
3. 要素の説明
4. 補足

7. 記述ガイド詳細

7.1. 概要

• 「この図が何を表すか」「対象システム」「前提」を1〜3文で書きます。

7.2. C4コンテナ図（Mermaid）

• Mermaid のコードブロックで図を記述します。
• Mermaid 記法ルールは cnd-mermaid-rules.md に従います。
• 図には、少なくとも以下を含めます。
  • Person（いる場合）
  • 境界（System Boundary）
  • 主要コンテナ（2〜7個程度を目安）
  • 主要DB（ある場合）
  • 外部システム（ある場合）
  • 関係（Relationship。全矢印にラベル）

7.3. 要素の説明

• 図に登場する要素を、レビューしやすい粒度で説明します。
• 推奨スタイル:
  • ### レベルの小見出しで要素名（境界/人/コンテナ/DB/外部/関係）
  • 1〜3文で意味・前提・境界条件（含む/含まない）を説明

7.4. 補足

• 未確定な外部連携、境界が揺れている論点、図を分ける必要がありそうな論点を列挙します。

8. 命名・記述スタイル

• 用語はこの図の中で揺らさない（同じコンテナ/外部を別名で呼ばない）。
• ラベルは短くし、長い場合は改行（<br>）で読みやすくする（詳細はIF仕様へ）。
• コンテナは「責務が読める短い名前」を優先し、実装都合の命名（内部モジュール名など）に寄せすぎない。

9. 禁止事項

次の記述は、CNDの粒度を超えるため避けます。

項目	理由
物理テーブル名・物理カラム名・SQL全文	図の粒度を超える（DB設計に記述）
APIエンドポイント/HTTP/JSON等の詳細	IF仕様に記述する
実装クラス/関数名、内部モジュールの列挙	変更に弱い・合意の対象がずれる
画面遷移やクリック手順の逐語列挙	UI変更に弱い・図の目的から逸脱
コンポーネント/クラス等の内部構造の詳細	コンポーネント図/実装設計で表す
矢印ラベルなしの関係	何の関係か合意できない

10. レビュー観点（チェックリスト）

• 対象システムは1つに絞れているか
• 境界の内外が説明され、責任分界が曖昧でないか
• 主要コンテナが多すぎず（目安: 2〜7）、過不足なく俯瞰できるか
• Person/外部システム/DBがある場合、必要十分に含まれているか
• すべての関係にラベルがあり、意味が解釈一致するか
• 図が「コンポーネント/実装詳細」や「IF詳細」に踏み込んでいないか

11. サンプル（簡易）

---
id: cnd-candy-shop-sales-container
type: architecture
title: 駄菓子屋きぬや販売管理システムのC4コンテナ図
status: draft
part_of: []
based_on: []
---

11.1. 概要

この図は「駄菓子屋きぬや販売管理システム」を主要コンテナに分割し、利用者・外部システム・DBとの関係を俯瞰します。

11.2. C4コンテナ図（Mermaid）

11.3. 要素の説明

11.3.1. 境界（System Boundary）

境界には販売管理システム本体（Webアプリ/API/販売DB）を含みます。会計や決済の処理そのものは境界の外側です。

11.3.2. Person（人/ロール）

店員が売上登録などの業務のために Webアプリを利用します。

11.3.3. Container（コンテナ）

Webアプリは店舗業務の入力・参照を担い、APIは販売/在庫の主要ロジックと外部連携の窓口を担います。

11.3.4. Database（データベース）

販売DBは売上などの主要記録を永続化します（詳細な物理設計はDB設計に記載）。

11.3.5. 外部システム（External Software System）

APIは会計システムへ仕訳相当情報を連携し、決済サービスへ決済を依頼して結果を受信します（詳細はIF仕様に記載）。

11.4. 補足

• 会計連携の頻度（リアルタイム/日次）を確定する。

12. 生成AIへの指示テンプレート

生成AIにCND成果物（図＋説明）を作らせるときは、以下のような指示を与えます（このテンプレート内に禁止事項を含め、参照前提にしません）。

• 以下のルールに従って、C4コンテナ図（CND）のドキュメントを 1 ファイル作成してください。出力は Markdown とします。
• 対象システム（System Boundary）は 1つだけにしてください（複数対象がある場合は分割する前提で、今回は1つに絞る）。
• 先頭に YAML Frontmatter を付けてください（項目は以下を必須とする）：
  • id: 小文字ハイフン（例: cnd-candy-shop-sales-container）
  • type: architecture
  • title: 図の対象が分かる日本語タイトル
  • status: draft
  • part_of: []
  • based_on: []
  • implements: []
  • tests: []
• 本文構成は、次の見出し（日本語）をこの順序で必ず出力してください：
  1. 概要
  2. C4コンテナ図（Mermaid）
  3. 要素の説明
  4. 補足
• 「C4コンテナ図（Mermaid）」は以下のルールに従って作成してください：
  • Mermaid の flowchart 構文で、C4コンテナ図（Container Diagram）を作成してください。
  • 対象システムは subgraph 境界["対象システム"] ... end で囲ってください。
  • 境界内には、主要なコンテナ（例: Webアプリ / API / バッチ等）と、必要なら主要DBを置いてください（2〜7個程度）。
  • Person（人/ロール）や外部システム（External Software System）がある場合は含めてください（該当がない場合は理由を明記）。
  • 関係は --> で表現し、すべての矢印にラベル（短い日本語）を付けてください。
  • 色分け（必須）:
    • Personノードに person、境界内（Container/DB）に system、外部システムに external を付けてください。
    • 境界（subgraph）は破線枠にしてください。
    • 以下の定義をそのまま図に含めてください（値は変更しない）：
      • classDef person fill:#fff3bf,stroke:#f08c00,color:#000;
      • classDef system fill:#d0ebff,stroke:#1c7ed6,color:#000;
      • classDef external fill:#e9ecef,stroke:#495057,color:#000;
      • style 境界 fill:#ffffff,fill-opacity:0,stroke:#868e96,stroke-width:1px,stroke-dasharray: 5 5;
  • 出力は Mermaid のコードブロック形式（```mermaid で開始し、 ``` で終了）で提示してください。
• 「要素の説明」は、図に登場する要素（境界/人/コンテナ/DB/外部/関係）を ### 小見出しで列挙し、各要素を 1〜3文で説明してください。
• 禁止: 物理テーブル名・カラム名・SQL全文、APIエンドポイントやHTTP詳細、実装クラス/関数名、コンポーネント/クラス等の内部構造、UI操作手順の逐語列挙

このテンプレートをコピーして、生成 AI のプロンプトに貼り付けて利用してください。なお、cnd-instruction.mdとして別ファイルに保存しています。

13. 参照

• Mermaid 記法（CND）: cnd-mermaid-rules.md
• 生成AI向けテンプレ（CND）: cnd-mermaid-instruction.md