C4モデルとは？ソフトウェアチームのための完全ガイド - Archyl Blog

C4モデルはソフトウェアアーキテクチャを可視化するための最も実践的なフレームワークです。この完全ガイドでは4つのレベルすべて、各レベルの使い方、実例、そしてArchylのようなツールを使った現代的なチームのC4実践方法を解説します。

C4モデルとは？ソフトウェアチームのための完全ガイド

ソフトウェアアーキテクチャ図には評判の問題があります。抽象的すぎて役に立たないか、詳細すぎてメンテナンスできないか、どちらかです。おそらくどちらも見たことがあるでしょう——「The System」とラベル付けされた単一のボックスの図は何も教えてくれませんし、200クラスのUML図は実際に知りたいこと以外のすべてを教えてくれます。

Simon Brownが作成したC4モデルは、地図学からアイデアを借りてこの問題を解決しました。地図は複数のズームレベルで機能します。世界地図から始めて位置を把握し、国にズームイン、都市にズームイン、通りにズームインします。各レベルは、問いかけている質問に対して適切な量の詳細を表示します。C4モデルはこの同じ原則をソフトウェアアーキテクチャに適用しています。

このガイドでは、C4モデルについて知っておくべきすべてを解説します：各レベルが何を表すか、いつ使うか、よくある落とし穴、そして現代のチームが実践でC4をどのように実装しているか。

C4は何の略か？

C4は、モデルが定義する4つの抽象化レベルを表しています：

  1. Context（コンテキスト）——全体像。システムが世界にどう収まるか。
  2. Containers（コンテナ）——システムの高レベルな技術的ビルディングブロック。
  3. Components（コンポーネント）——各コンテナの内部構造。
  4. Code（コード）——実際の実装の詳細。

各レベルは異なるオーディエンスに対して異なる質問に答えます。プロダクトマネージャーはContextを気にします。プラットフォームエンジニアはContainersを気にします。特定のサービスで作業する開発者はComponentsを気にします。Codeレベルを手で描く必要がある人はほとんどいません——これについては後述します。

C4の力は、どの1つの図にもありません。階層構造にあります。あるレベルのすべての要素は、次のレベルの図に分解されます。Container図で「Backend API」とラベル付けされたボックスは、内部モジュールを示す独自のComponent図になります。これによりナビゲーション可能でズーム可能なアーキテクチャのビューが作られます。

レベル1：システムコンテキスト図

システムコンテキスト図は、あらゆるC4モデルの出発点です。1つの質問に答えます：あなたのシステムはより広い環境にどう収まるか？

表示するもの

  • 中央に1つのボックスとして表されるソフトウェアシステム
  • それを使う人々（アクター、ロール、ペルソナ）
  • 統合する外部システム
  • これらすべての間の関係

表示しないもの

  • システムの内部構造
  • 技術選択
  • データベース、キュー、インフラストラクチャ
  • デプロイメントの詳細

実例

eコマースプラットフォームをドキュメント化する場合を想像してください。システムコンテキスト図は以下を示します：

[Customer] --> [E-Commerce Platform] : Browses products, places orders
[Warehouse Staff] --> [E-Commerce Platform] : Manages inventory
[E-Commerce Platform] --> [Payment Gateway (Stripe)] : Processes payments
[E-Commerce Platform] --> [Shipping Provider (FedEx API)] : Creates shipments
[E-Commerce Platform] --> [Email Service (SendGrid)] : Sends notifications

5つのユーザーと外部システム。プラットフォーム全体を1つのボックスで。これだけです。

このレベルが重要な理由

システムコンテキスト図は境界について明確さを強制します。何を所有しているか？何に依存しているか？ユーザーは誰か？これらの質問は当たり前に思えますが、チームは一貫して答えることに苦労することがあります。

この図は非技術的なステークホルダーに見せるものでもあります。CEOはこれを見てシステムが何をするか、誰が使うか、どのサードパーティサービスに依存しているかを理解できます。UMLクラス図でそれを試してみてください。

良いシステムコンテキスト図のヒント

  • 1ページに収めましょう。収まらなければ、システム境界が間違っているかもしれません。
  • すべての関係に動詞フレーズでラベルを付けましょう：「sends emails via」「processes payments through」「reads inventory from」。
  • 当たり前と思っているものも含め、すべての外部システムを含めましょう（DNS、CDN、モニタリング）。
  • 内部の詳細を含めないでください。誘惑に抵抗しましょう。

レベル2：コンテナ図

コンテナ図はシステムにズームインし、高レベルな技術的ビルディングブロックを示します。C4用語では、「コンテナ」は個別にデプロイまたは実行可能なユニットであり、必ずしもDockerコンテナではありません。

コンテナに該当するもの

  • Webアプリケーション（React SPA、Next.jsアプリ）
  • モバイルアプリケーション（iOSアプリ、Androidアプリ）
  • バックエンドAPIサービス（Go API、Node.jsサーバー）
  • データベース（PostgreSQL、MongoDB、Redis）
  • メッセージブローカー（Kafka、RabbitMQ）
  • ファイルストレージシステム（S3、MinIO）
  • サーバーレス関数（AWS Lambda、Cloud Functions）

各コンテナは独自のプロセスで動作するか、独自のデータストレージを持ちます。それが区別要因です。一緒にデプロイされる2つのGoパッケージは同じコンテナの一部です。独立してデプロイされる2つのGoサービスは別々のコンテナです。

実例

eコマースプラットフォームにズームインすると：

[Single-Page Application (React)] --> [API Gateway (Kong)] : Makes API calls (HTTPS/JSON)
[API Gateway] --> [Order Service (Go)] : Routes requests
[API Gateway] --> [Product Service (Go)] : Routes requests
[API Gateway] --> [User Service (Go)] : Routes requests
[Order Service] --> [Order Database (PostgreSQL)] : Reads/writes orders
[Product Service] --> [Product Database (PostgreSQL)] : Reads/writes products
[User Service] --> [User Database (PostgreSQL)] : Reads/writes users
[Order Service] --> [Message Queue (Kafka)] : Publishes order events
[Notification Service (Go)] --> [Message Queue] : Consumes order events

これで技術選択、通信パターン、データストアが見えます。アーキテクトはOrderデータベースとProductデータベースの統合を議論できます。DevOpsエンジニアはデプロイメントトポロジーを計画できます。新しい開発者はReactフロントエンドがどこで終わりGoバックエンドがどこから始まるかを理解できます。

良いコンテナ図のヒント

  • テクノロジーを括弧内に含めましょう：「Order Service (Go)」「Database (PostgreSQL)」。
  • 関係に通信プロトコルを示しましょう：「HTTPS/JSON」「gRPC」「AMQP」。
  • 15-20以上のコンテナがある場合、異なるサブシステムごとに複数のコンテナ図を作成しましょう。
  • データベースとキューを含めましょう。それらもコンテナです。
  • ここではコンテナレベルより下に行かないでください。内部モジュールはComponent図に属します。

レベル3：コンポーネント図

コンポーネント図は単一のコンテナにズームインし、その内部構造的ビルディングブロックを示します。コンポーネントはコンテナ内の主要な抽象化——パッケージ、モジュール、サービス、レイヤーなどです。

コンポーネントに該当するもの

  • HTTPハンドラーまたはコントローラー
  • ビジネスロジックサービス
  • リポジトリまたはデータアクセスレイヤー
  • 外部APIクライアント
  • バックグラウンドジョブプロセッサー
  • ミドルウェアまたはインターセプター

コンポーネントは論理的なグループであり、必ずしも個別のファイルではありません。OrderHandlerコンポーネントは複数のファイルにまたがって実装されているかもしれませんが、概念的には1つのもの：注文に関連するHTTPリクエストを処理するシステムの部分です。

実例

Order Serviceコンテナにズームインすると：

[Order Handler] --> [Order Service] : Delegates business logic
[Order Service] --> [Order Repository] : Persists orders
[Order Service] --> [Payment Client] : Validates payment
[Order Service] --> [Inventory Client] : Checks stock availability
[Order Repository] --> [Order Database (PostgreSQL)] : SQL queries
[Payment Client] --> [Payment Gateway (Stripe)] : HTTPS/REST
[Inventory Client] --> [Product Service] : gRPC

このチームに加わる開発者は、Order Serviceの構造をすぐに把握できます：リクエストはハンドラーを通じて入り、ビジネスロジックはサービスに存在し、データアクセスはリポジトリを通じて行われ、外部呼び出しは専用クライアントを通じて行われます。

いつコンポーネント図を作成するか

すべてのコンテナにコンポーネント図が必要なわけではありません。以下の場合に作成しましょう：

  • コンテナが十分に複雑で、新しい開発者がナビゲートに苦労する場合
  • 重要なデザインパターン（ヘキサゴナルアーキテクチャ、CQRS）があり、図で明示化できる場合
  • 複数のチームが同じコンテナに貢献しており、構造の共通理解が必要な場合

以下の場合はコンポーネント図を省略しましょう：

  • コンテナがシンプルな場合（3つのエンドポイントを持つCRUDサービス）
  • コード構造がフォルダレイアウトから明らかな場合
  • コンテナがサードパーティツール（Redis、Kafka）で内部を制御できない場合

レベル4：コード図

コードレベルは実際の実装の詳細を示します：クラス、インターフェース、関数、そしてそれらの関係。これは本質的にUMLクラス図またはER図です。

レベル4についての正直な見解

Simon Brown自身がコード図を手動で作成することに反対しています。理由は以下です：

  • 変更が頻繁すぎます。すべてのリファクタリングで無効になります。
  • メンテナンスが高コストです。クラス図を手で描くのは退屈です。
  • コードにすでに存在する情報を複製しています。
  • 最新のIDEはオンデマンドで生成できます。

コードレベルの図が必要な場合は、言語をサポートするツールを使用してソースコードから生成しましょう。手で描かないでください。

コード図が実際に役立つ場合

例外はあります：

  • ビジュアルウォークスルーが有益な複雑なアルゴリズム
  • 構造が興味深い部分であるデザインパターン（Strategy、Observer、State Machine）
  • コントラクトをドキュメント化したいパブリックAPIサーフェス
  • パターンを教えている面接やオンボーディングマテリアル

実践では、ほとんどのチームはC4の3つのレベル（Context、Container、Component）を使用し、CodeレベルはIDE生成のビューに任せています。

補足図

4つのコアレベルの他に、Simon BrownはC4階層を補完するいくつかの補足図を定義しています：

システムランドスケープ図

システムコンテキスト図をさらにズームアウトしたものです。企業内のすべてのソフトウェアシステムとそれらの関係を示します。システムのポートフォリオを管理するエンタープライズアーキテクトに有用です。

デプロイメント図

コンテナをインフラストラクチャにマッピングします。どのコンテナがどのサーバーで、どのクラウドリージョンで、どのロードバランサーの背後で動作しているかを示します。DevOpsやプラットフォームチームに不可欠です。

動的図

特定のユースケースを実現するために、要素が実行時にどのように連携するかを示します。UMLシーケンス図に似ていますがC4表記法を使用します。「ユーザーが注文した際に何が起こるか」のような複雑なフローのドキュメント化に有用です。

C4モデルと他のアプローチの比較

C4 vs. UML

UMLは14種類の図を定義しています。ほとんどのチームはそのうち2-3種類を使い、しかも一貫性がないことが多いです。C4は明確な目的を持つ4つのレベルを提供します。学習がシンプル、使用がシンプル、メンテナンスがシンプルです。

とはいえ、C4とUMLは排他的ではありません。レベル4ではUMLクラス図を、動的図としてはUMLシーケンス図を使用できます。C4は階層を提供し、UMLは必要な場合に具体的な表記法を提供します。

C4 vs. Arc42

Arc42はアーキテクチャドキュメントのテンプレートです。単なる図以上のものをカバーします：品質要件、制約、リスク、デプロイメントビューなど。C4は階層的な図に特化しています。多くのチームは両方を使います：Arc42をドキュメント構造として、C4をその中の図のアプローチとして。

C4 vs.「ホワイトボードでいい」

ホワイトボードは探索やブレインストーミングには素晴らしいです。ドキュメントとしてはひどいです。ホワイトボードの図は消され、写真の画質が悪く、更新されません。C4はホワイトボードでの探索を永続的なドキュメントに変えるための構造を提供します。

C4導入時のよくある間違い

すべてを一度に見せようとする

C4の核心は段階的な詳細開示です。Container図に個々のクラスが表示されているなら、階層が崩壊しています。各図は1つのズームレベルの要素のみを表示すべきです。

関係を無視する

矢印のないボックスはインベントリであり、アーキテクチャではありません。関係——誰が誰を呼ぶか、どのプロトコルを使うか、どんなデータが流れるか——はボックス自体よりも価値があることが多いです。必ず関係にラベルを付けましょう。

一人だけの活動にする

アーキテクチャドキュメントはチームスポーツです。一人だけが図を作成し維持すると、その人の理解（または誤解）を反映したものになります。C4図をチームでレビューしましょう。理想的にはアーキテクチャレビュープロセスの一部として。

他のドキュメントにリンクしない

C4図は他のアーティファクトと接続されたときに力を発揮します。コンテナをデプロイメントランブックにリンクしましょう。コンポーネントをアーキテクチャ決定記録（ADR）にリンクしましょう。外部システムをそのAPIドキュメントにリンクしましょう。孤立した図は接続された図よりも価値が低いです。

図を古くさせる

あらゆるドキュメントアプローチの最大の敵は陳腐化です。昨年のアーキテクチャを記述する図は、積極的にミスリードするため、図がない方がまだましです。図の更新をワークフローに組み込みましょう——プルリクエストのチェックリスト、スプリントレビュー、またはアーキテクチャミーティングの一部として。

ArchylにおけるC4モデルの実装

ArchylはC4モデルをファーストクラスの概念として構築されています。各レベルがプラットフォームの機能にどのように対応するかを紹介します：

Archylのシステムコンテキスト

Archylでプロジェクトを作成すると、システムと外部アクターとの関係を定義します。システムコンテキストビューはモデルから自動的にレンダリングされ、手動での描画は不要です。システムを追加し、外部アクターを追加し、関係を描くと、図がリアルタイムで更新されます。

Archylのコンテナ図

各システム内でコンテナと技術スタックを定義します。Archylはコンテナ図をレンダリングし、任意のコンテナをドリルダウンしてコンポーネントを確認できます。コンテナ間の関係は通信プロトコルとデータフローを示します。

Archylのコンポーネント図

各コンテナ内でコンポーネントを定義します。ArchylはCode Elements機能を通じてこれらを実際のコードにマッピングし、コンポーネントをリポジトリ内の特定のファイルやディレクトリにリンクします。この図とコードの接続がドリフト検出を可能にします。

AI搭載ディスカバリー

Archylが描画ツールと異なるのは、モデルを手動で構築する必要がないことです。リポジトリを接続し、AIディスカバリーを実行すると、Archylがコードベースからドラフトのc4モデルを生成します。AIはコード構造、設定ファイル、依存関係グラフを分析してシステム、コンテナ、コンポーネント、関係を特定します。

提案をレビューし、承認または修正すれば、数週間ではなく数分でC4モデルが完成します。

ドリフト検出

C4モデルが作成されると、Archylはそれが現実を反映しているか継続的にチェックします。ドリフトスコアは、ドキュメント化されたアーキテクチャの何パーセントがコードベースに実際に存在するかを示します。誰かがサービスの名前を変更したりコンポーネントを削除したりすると、ドリフトスコアが下がり、ドキュメントの更新が必要であることがわかります。

これはほとんどのC4ツールが見落としているギャップです。図を作成するのは簡単な部分です。正確に保つのが難しい部分です。Archylのドリフト検出がそのギャップを埋めます。

C4入門：ステップバイステップのアプローチ

チームがC4モデルに初めて取り組む場合、ここに実践的な導入パスがあります：

第1週：システムコンテキスト

チームを集めて1時間のワークショップを行いましょう。システムを1つのボックスとして描きます。すべてのユーザーロールと外部システムを特定します。関係を描きます。このシンプルな演習がどれだけの議論を生み、どれだけの認識の統一を生み出すか驚くでしょう。

第2週：コンテナ図

Context図のシステムボックスをコンテナに分解します。デプロイ可能なユニットは何か？どんなデータベースがあるか？どんなメッセージブローカーやキャッシュが使われているか？ここで技術選択を可視化します。

第3-4週：主要コンテナのコンポーネント図

最も複雑な2-3個のコンテナを選びます。それぞれをコンポーネントに分解します。新しい開発者が最も時間を費やす場所なので、理解が最も難しいコンテナを優先しましょう。

継続的：メンテナンスと進化

最初の作成は簡単な部分です。図を最新に保つ規律が、C4から価値を得るチームと1ヶ月後に放棄するチームを分けます。自動化できるものは自動化しましょう。ドリフトを検出するツールを使いましょう。図のレビューを開発ワークフローの一部にしましょう。

C4が機能する理由

C4モデルは技術的に画期的なものではありません。階層的分解と抽象化レベルは1960年代からコンピュータサイエンスに存在しています。Simon Brownがしたことは、これらのアイデアを明確なルールと最小限の表記法を持つシンプルで覚えやすいフレームワークにパッケージしたことです。

機能する理由：

  • 学習が簡単。 4つのレベル。ボックスと矢印。UML認定は不要。
  • スケールする。 週末プロジェクトからエンタープライズプラットフォームまで、同じ4つのレベルが適用される。
  • 複数のオーディエンスに対応。 エグゼクティブ、アーキテクト、開発者がそれぞれ自分の言語で話す図を得られる。
  • ツール非依存。 ホワイトボード、描画ツール、テキストベースのフォーマット、またはArchylのような専用プラットフォームを使用できる。
  • 正しいことに焦点を当てる。 実装の詳細ではなく、構造と関係に焦点を当てる。

チームのアーキテクチャドキュメントが古いVisioファイル、Slackのホワイトボード写真、部族知識で構成されているなら、C4モデルはより良いものへの最も実践的な道です。

C4モデルを構築する準備はできましたか？Archylを無料で試す——コードから数分で最初のアーキテクチャ図を生成しましょう。さらに詳しく：AI搭載アーキテクチャディスカバリー | Architecture as Code: YAMLでC4モデルを定義 | アーキテクチャドリフトスコア。