Community画像github.com

c4-diagrams

C4モデル(システムコンテキストL1、コンテナL2、コンポーネントL3、コードL4、システムランドスケープ、ダイナミック、デプロイメント図)を使用してソフトウェアアーキテクチャ図を作成、レビュー、更新、説明する際にトリガーされます。特にMarkdown/Mermaidでの利用に適しています。

c4-diagrams とは?

このスキルは、C4モデルに基づいたソフトウェアアーキテクチャ図の作成、レビュー、説明を支援します。C4モデルは、コンテキスト、コンテナ、コンポーネント、コードの4つのズームレベルで「コードの地図」を提供し、従来のアドホックなボックス・アンド・ライン図が抱える凡例の欠如、抽象度の混在、ラベルのない矢印、技術的な詳細の欠落といった問題を解決します。このスキルは、C4モデルの公式ドキュメントで定義された厳密なルール(抽象化の階層、表記規則、特殊なモデリングパターンなど)に従い、特にMarkdown/Mermaidでの図作成を推奨します。MermaidのネイティブC4構文は実験的でレンダリングに失敗することがあるため、代わりにフローチャートを使用し、システム境界、データベース、キューなどをサブグラフと特定のノード形状で表現します。このスキルは、Claude Code、Cursor、CodexなどのAIエージェントがソフトウェアアーキテクチャに関するクエリに応答する際に役立ち、図の作成だけでなく、既存の図のレビューやアーキテクチャ上の意思決定の説明を求められた場合にも適用されます。

対応~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/fsodano/writing-skills/tree/HEAD/skills/c4-diagrams

Installed? Explore more 画像 skills: steipete/songsee, affaan-m/frontend-design, mattpocock/improve-codebase-architecture · View all 6 →

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

C4図

出典: C4モデル公式サイト https://c4model.com/。C4図を作成、レビュー、説明する際には、以下のルールを適用してください。出力に散文(ADR、ドキュメント、PR説明)が含まれる場合は、`writing` スキルも読み込んでください。

1. 目的

C4は、コンテキスト、コンテナ、コンポーネント、コードの4つのズームレベルで構成される「コードの地図」のセットです。Simon Brown氏が、UMLと4+1ビューモデルに触発されて作成したもので、アドホックなボックス・アンド・ライン図を置き換えることを目的としています。C4が修正する典型的な問題: 凡例がない、抽象度が混在している、ラベルのない矢印、技術の欠落、「ビジネスロジック」などの曖昧なラベル。

C4は表記法やツールに依存しません。重要なのは、以下の抽象化とルールであり、形状ではありません。

2. 抽象化

階層: 人物 -> ソフトウェアシステム -> コンテナ -> コンポーネント -> コード。各レベルは、上のレベルの1つの要素にズームインします。

抽象化定義例
人物システムの人間のユーザー、アクター、ロール、ペルソナ顧客、サポートエージェント、管理者
ソフトウェアシステム最も高い抽象レベル。ユーザーに価値を提供する。通常、1つのチームが所有・構築する。プロダクトドメイン、境界づけられたコンテキスト、トライブ、スクワッドではないチケットプラットフォーム、支払いシステム
コンテナソフトウェアシステム内の、独立して実行/デプロイ可能なアプリケーションまたはデータストアサーバーサイドWebアプリ、SPA、デスクトップアプリ、モバイルアプリ、サーバーレス関数、バッチ/コンソールアプリ、マイクロサービスAPI、データベーススキーマ、S3/ブロブストア、CDN、ファイルシステム、シェルスクリプト
コンポーネントコンテナ内の、明確に定義されたインターフェースの背後にある関連機能のグループ。個別にデプロイ可能ではない: コンテナのすべてのコンポーネントは1つのプロセス空間を共有するOrderController、PaymentService、EmailSender
コードコンポーネント内のクラス、インターフェース、関数、またはDBテーブルclass OrderValidator、orders テーブル

コンテナのルール (C4 FAQ)

  • C4のコンテナはDockerではありません。 パッケージング方法に関わらず、実行可能/デプロイ可能なアプリケーションまたはデータストアのことです。
  • サーバーレンダリングされたHTMLアプリは1つのコンテナです。サーバーとSPAまたはモバイルクライアントは、リモートAPIを介して通信する2つのコンテナです。
  • JAR、DLL、アセンブリ、モジュールはコンテナではありません。これらはコンテナ内のコードを整理するものです。
  • 管理されたデータサービス(S3、RDS、CDN)は、バケットやスキーマを所有または制御している場合、システム境界内のコンテナです。外部システムではありません。

コンポーネントのルール

  • コンポーネントはフォルダ、パッケージ、JARではありません。インターフェースを持つ機能的なグループです。
  • コンポーネントは個別にデプロイ可能ではありません。個別にデプロイされる場合は、コンテナです。

用語の適応

チームは、図またはそのドキュメントで用語を明示的に定義する場合、言語に固有の名前(関数型コードの Module や Function など)を使用しても構いません。各レベルが厳密に定義されていない限り、余分な抽象化レベルを発明しないでください。

3. 特別なモデリングパターン

キューとトピック

  • 間違い: すべてのサービスが接続された、中央に1つの巨大な「メッセージバス」コンテナ(ハブアンドスポーク)。誰が何を生成し、誰が何を消費するかが不明になります。
  • オプション1 (推奨): 各キューまたはトピックを独立したコンテナ(メッセージデータストア)としてモデル化します。プロデューサーが書き込み、コンシューマーが読み取り/サブスクライブします。
  • オプション2: 直接的なポイントツーポイント結合の場合、キューボックスを省略し、関係に 「キュー orders [AMQP] 経由で注文イベントを公開」 とラベル付けします。必要に応じて、これらの線をHTTP呼び出しとは異なるスタイルにします(凡例で説明)。

例: Order API --「OrderPlaced を [Kafka] に公開」--> [(orders topic)] --「OrderPlaced を [Kafka] から読み取り」--> Fulfilment Worker.

マイクロサービス (コンウェイの法則ルール)

  • 1つのチームがソフトウェアシステム全体を所有する: 各マイクロサービスを、そのシステム境界内のコンテナグループ(APIコンテナと、それ自体のデータベーススキーマコンテナ、または単一のステートレスLambdaコンテナ)としてモデル化します。
  • 別々のチームが各サービスを所有する: 独立して所有される各サービスを、独自のシステムコンテキスト図とコンテナ図を持つ独自のソフトウェアシステムに昇格させます。システム境界を越えて、キュー/トピックの所有権を明示的に示します。

4. 図のカタログ

コアの静的レベル

レベル図推奨範囲対象読者表示/省略
1システムコンテキストはい1つのソフトウェアシステム技術者および非技術者システムの周囲の人物と外部システム。低レベルの技術やプロトコルは省略
2コンテナはい1つのソフトウェアシステム技術者、運用主要な技術選択とプロセス間プロトコル。クラスタリング、ロードバランサー、フェイルオーバーは省略
3コンポーネントいいえ: 明確な価値が付加される場合のみ、理想的には自動生成1つのコンテナアーキテクト、開発者1つのコンテナ内のコンポーネントとそれらの相互作用
4コードいいえ: IDEでオンデマンド生成1つのコンポーネント開発者UMLクラス図またはERD

補助図

図推奨用途
システムランドスケープはい、組織やポートフォリオ向けすべてのシステムと人物のエンタープライズまたは部門マップ。単一のフォーカスシステムがないコンテキスト図
ダイナミックいいえ: 控えめに使用複雑なランタイムコラボレーション。番号付きコラボレーションスタイルまたはUMLシーケンススタイル
デプロイメントはい1つの環境(本番、ステージング、開発)。システム/コンテナインスタンスを含むネストされたデプロイメントノード(物理、VM、Docker、Kubernetes、ランタイム)、およびインフラストラクチャノード(DNS、ロードバランサー、ファイアウォール)

互換性

  • arc42: コンテキストとスコープ -> L1; ビルディングブロックレベル1 -> L2; ビルディングブロックレベル2 -> L3; ビルディングブロックレベル3 -> L4。
  • UML: ワークフロー、ステートマシン、データモデルについては、C4をUMLステート図、シーケンス図、ERDで補完します。

スケーリングルール

図が乱雑になった場合は、1つのキャンバスに何十ものボックスを詰め込まないでください。同じ抽象レベルで、ビジネス領域、境界づけられたコンテキスト、機能、または単一サービスフォーカス(フォーカスサービスとそのインバウンド/アウトバウンドネイバー)で分割します。

5. 表記規則

図

  • タイトルには図の種類と範囲を記載: 支払いチェックアウトシステムのコンテナ図。
  • 形状、色、境界線、線種、矢印、頭字語を説明する凡例を必ず含める。
  • 厳密な抽象化の純度を維持: 抽象化レベルを決して混在させない(例: L2コンテナ図に コンポーネント ボックスを入れない)。また、L1システムコンテキスト図にプロトコルや内部実装手順([HTTPS]、masked packet、tool_runner)を決して入れない。
  • 競合するアーキテクチャや過去のアーキテクチャを比較する場合は、境界タイトルを明示的にラベル付けする(オプションA (廃止) vs. オプションB (現行))。要件や前提が変更されるたびに、ドキュメント内のすべての図を更新する。

要素

  • 名前、明示的な要素タイプ(人物、ソフトウェアシステム、コンテナ、コンポーネント、データベース、デプロイメントノード)、および簡潔な責務の説明。
  • すべてのコンテナ、コンポーネント、デプロイメントノードに明示的な技術を記載。

関係

  • 単方向矢印のみ。 <--> は絶対に使用しない。データが双方向に流れる場合は、開始側の方向を示し、ラベルで応答を説明する。
  • 具体的な能動的動詞のラベル。単なる「使用する」は避ける。に注文を送信する、から座席マップを読み取る と記述する。
  • コンテナ間の関係にはプロトコル/技術を記載: [JSON/HTTPS]、[SQL]、[gRPC]、[AMQP]。

6. MarkdownでのMermaid

デフォルトは flowchart (flowchart TB または LR)。Mermaidネイティブの C4Context/C4Container は使用しないでください。ネイティブC4構文は実験的であり、Markdownビューアでレンダリングに失敗することがよくあります。ユーザーが明示的に要求し、レンダラーのサポートを確認した場合にのみ出力します。

フローチャートの規則:

  • システム境界(コンテナ/コンポーネント)またはデプロイメントノードには subgraph を使用。
  • データベース、データストア、キュー、トピックには [(...)] を使用。
  • 引用符で囲まれたHTMLラベル: "<b>名前</b><br/>«コンテナ: 技術»<br/>簡単な責務"。
  • 引用符で囲まれたラベルを持つ矢印: A -->|"アクション [プロトコル]"| B。
  • 要素タイプごとに1つの classDef を一貫して適用。
  • 色、円筒形状、または複数の線種を使用する場合は、コンパクトな 凡例 サブグラフ(接続されていないノード。Dagreが上部に配置する場合、不可視の bottomNode ~~~ 凡例 リンクで下部に固定)が必須。タイトルは見出しとして、またはコードブロックの真上の Title: ... 行として配置。
  • ダイナミック図: sequenceDiagram、または番号付き矢印ラベル(1. 注文を送信 [JSON/HTTPS])を持つ flowchart。
  • デプロイメント図: flowchart 内のネストされた subgraph。
  • 括弧、角括弧、コロンを含むラベルは常に引用符で囲む。
  • sequenceDiagram または stateDiagram-v2 ラベル内にエスケープされていないセミコロン (;) を決して入れない(Mermaidは ; をステートメントターミネータとして扱い、残りのテキストを無意味なステートまたはパースエラーに分割します)。sequenceDiagram 内の長い Note ブロックは <br/> でラップし、テキストがビューポートの端でクリップされないようにする。

テンプレート: L1 システムコンテキスト

タイトル: チケットプラットフォームのシステムコンテキスト図

flowchart TB
    customer["<b>顧客</b><br/>«人物»<br/>イベントのチケットを購入する"]
    ticketing["<b>チケットプラットフォーム</b><br/>«ソフトウェアシステム»<br/>顧客がイベントを閲覧し、チケットを購入できるようにする"]
    payments["<b>決済プロバイダー</b><br/>«ソフトウェアシステム、外部»<br/>カードに請求する"]
    email["<b>メールサービス</b><br/>«ソフトウェアシステム、外部»<br/>確認メールを配信する"]

    customer -->|"を使用してイベントを閲覧し、チケットを購入する"| ticketing
    ticketing -->|"からカード請求を要求する"| payments
    ticketing -->|"を使用して確認メールを送信する"| email
    email -->|"に確認メールを配信する"| customer

    classDef person fill:#08427b,stroke:#052e56,color:#fff
    classDef system fill:#1168bd,stroke:#0b4884,color:#fff
    classDef external fill:#999,stroke:#6b6b6b,color:#fff
    class customer person
    class ticketing system
    class payments,email external

    subgraph 凡例
        direction LR
        l1["人物"]:::person
        l2["ソフトウェアシステム (スコープ内)"]:::system
        l3["ソフトウェアシステム (外部)"]:::external
    end

テンプレート: L2 コンテナ(キューコンテナ付き)

タイトル: チケットプラットフォームのコンテナ図

flowchart TB
    customer["<b>顧客</b><br/>«人物»<br/>イベントのチケットを購入する"]
    payments["<b>決済プロバイダー</b><br/>«ソフトウェアシステム、外部»<br/>カードに請求する"]

    subgraph boundary["チケットプラットフォーム [ソフトウェアシステム]"]
        spa["<b>Webアプリ</b><br/>«コンテナ: React SPA»<br/>イベント閲覧とチェックアウトUI"]
        api["<b>注文API</b><br/>«コンテナ: Java, Spring Boot»<br/>注文を検証し、発行する"]
        db[("<b>注文DB</b><br/>«コンテナ: PostgreSQL»<br/>注文とチケットを保存する")]
        topic[("<b>注文トピック</b><br/>«コンテナ: Kafkaトピック»<br/>OrderPlacedイベント")]
        worker["<b>フルフィルメントワーカー</b><br/>«コンテナ: Python»<br/>チケットを発行し、メールを送信する"]
    end

    customer -->|"を使用して閲覧および購入する [HTTPS]"| spa
    spa -->|"に注文を送信する [JSON/HTTPS]"| api
    api -->|"に注文を書き込む [SQL/TCP]"| db
    api -->|"OrderPlaced を公開する [Kafka]"| topic
    worker -->|"OrderPlaced を読み取る [Kafka]"| topic
    worker -->|"のチケットステータスを更新する [SQL/TCP]"| db
    api -->|"からカード請求を要求する [JSON/HTTPS]"| payments

    classDef person fill:#08427b,stroke:#052e56,color:#fff
    classDef container fill:#438dd5,stroke:#2e6295,color:#fff
    classDef store fill:#2e6da4,stroke:#1b4f72,color:#fff
    classDef external fill:#999,stroke:#6b6b6b,color:#fff
    class customer person
    class spa,api,worker container
    class db,topic store
    class payments external

    subgraph 凡例
        direction LR
        l1["人物"]:::person
        l2["コンテナ"]:::container
        l3[("データストア / キュー / トピック")]:::store
        l4["外部システム"]:::external
    end

凡例注記: 矢印は開始側からターゲットを指します。ラベルはアクションと [プロトコル] を示します。

テンプレート: デプロイメント

タイトル: チケットプラットフォームのデプロイメント図(本番)

flowchart TB
    users["<b>顧客ブラウザ</b><br/>«デプロイメントノード: Chrome»"]

    subgraph aws["AWS «デプロイメントノード: クラウド, us-east-1»"]
        dns["<b>Route 53</b><br/>«インフラストラクチャノード: DNS»"]
        lb["<b>ロードバランサー</b><br/>«インフラストラクチャノード: ALB»"]
        subgraph eks["EKS «デプロイメントノード: Kubernetesクラスター»"]
            subgraph pod["order-api ポッド «デプロイメントノード: Docker, x3»"]
                api["<b>注文API</b><br/>«コンテナインスタンス: Java, Spring Boot»"]
            end
        end
        subgraph rds["RDS «デプロイメントノード: PostgreSQL 16»"]
            db[("<b>注文DB</b><br/>«コンテナインスタンス: PostgreSQLスキーマ»")]
        end
    end

    users -->|"を使用してホスト名を解決する [DNS]"| dns
    users -->|"にリクエストを送信する [HTTPS]"| lb
    lb -->|"にリクエストを転送する [HTTP]"| api
    api -->|"で注文を読み書きする [SQL/TCP]"| db

デフォルト以外の色やスタイルを使用する場合は、凡例サブグラフを追加します。

テンプレート: ダイナミック(シーケンス)

タイトル: チケットプラットフォームの注文チェックアウトのダイナミック図(シーケンススタイル)

sequenceDiagram
    autonumber
    actor customer as 顧客
    participant spa as Webアプリ (React SPA)
    participant api as 注文API (Spring Boot)
    participant payments as 決済プロバイダー
    participant db as 注文DB (PostgreSQL)
    participant topic as 注文トピック (Kafka)

    customer->>spa: 「注文する」をクリック
    spa->>api: POST /orders [JSON/HTTPS]
    api->>payments: カードに請求 [JSON/HTTPS]
    payments-->>api: 支払い承認済み
    api->>db: 注文行を挿入 [SQL/TCP]
    api->>topic: OrderPlaced を公開 [Kafka]
    api-->>spa: 201 Created (注文確認)
    spa-->>customer: 注文領収書を表示

最大限のMarkdownビューア互換性を得るために、sequenceDiagram の参加者およびメッセージラベルには、引用符で囲まれていないスラッシュ、セミコロン(;、Mermaidはステートメントターミネータとして解析します)、または生の改行を含めないでください。

7. 図の作成手順

  1. スコープと目的を定義: 図の種類(システムコンテキスト、コンテナなど)、範囲(どのソフトウェアシステムまたはコンテナが対象か)、および対象読者を決定します。
  2. すべての要素をリストアップ: 関連する人物、ソフトウェアシステム、コンテナ、コンポーネントを特定します。C4の抽象化ルールに従って正しく分類されていることを確認します。
  3. 関係を特定: 要素間のすべての相互作用を特定します。方向、ラベル(能動的な動詞を使用)、プロトコル/技術を決定します。
  4. 図を描画: 選択した表記法(推奨: Mermaidフローチャート)で図を描画します。凡例を含めることを忘れないでください。
  5. レビューと改善: 図がC4ルール(抽象化の純度、単方向矢印、具体的なラベルなど)に準拠していることを確認します。明確で不要な詳細がないかどうかを確認します。

8. 追加のヒント

  • 図はシンプルに保つ: 1つの図に7±2個以上の主要要素を含めないようにします。それ以上の場合は、分割を検討します。
  • 一貫性を保つ: 同じプロジェクト/ドキュメント内で、色、形状、凡例のスタイルを一貫して使用します。
  • 凡例は常に含める: これは交渉の余地がありません。凡例がないと、図は誤解されやすくなります。
  • 図に日付を付ける: 時間の経過とともに変化するアーキテクチャを扱う場合、バージョン管理に役立ちます。
  • 最新の状態に保つ: コードベースが進化するにつれて、図を更新します。理想的には、コード駆動の図生成(Structurizr DSL など)を使用します。

Individual skills in this repo

This repo contains 2 individual skills — each has its own dedicated page.

関連スキル