mcpField
C
c4-architecture-c4-architecture

c4-architecture-c4-architecture

github.com/rmyndharis開発1.9k43 回インストール2 週間前に更新
リポジトリ

c4-architecture-c4-architecture について

既存リポジトリの C4 アーキテクチャ文書を作成するワークフロースキルです。コードからシステムコンテキストへボトムアップで分析し、成果物を `C4-Documentation/` にまとめます。

主な機能

  1. 01ボトムアップのコードベース分析
  2. 02コード、コンポーネント、コンテナ、コンテキストの文書化
  3. 03コンポーネント関係図の作成
  4. 04コンテナと API の文書化
  5. 05成果物を `C4-Documentation/` に整理

活用シーン

  1. 01既存コードベースの文書化
  2. 02コンポーネントとデプロイ先コンテナの対応付け
  3. 03技術・非技術関係者向けのアーキテクチャ資料作成

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/rmyndharis/antigravity-skills --skill c4-architecture-c4-architecture

インストール後、Claude Code で/c4-architecture-c4-architectureを入力して読み込まれたか確認します。

詳細

C4 アーキテクチャドキュメント作成ワークフロー

ボトムアップ分析のアプローチを使用して、既存のリポジトリ／コードベースの包括的な C4 アーキテクチャドキュメントを生成します。

[Extended thinking: このワークフローでは、C4 モデル（Context、Container、Component、Code）に沿った包括的な C4 アーキテクチャドキュメント作成プロセスを実施します。最も深い階層のコードディレクトリから開始し、上位へと進むボトムアップ方式を採用することで、上位レベルの抽象化へ統合する前に、すべてのコード要素を確実にドキュメント化します。このワークフローでは、4 つの専門 C4 エージェント（Code、Component、Container、Context）が連携し、技術者と非技術者の両方を対象とした、完全なアーキテクチャドキュメント一式を作成します。]

このスキルを使用する場面

  • C4 アーキテクチャドキュメント作成ワークフローのタスクやワークフローに取り組む場合
  • C4 アーキテクチャドキュメント作成ワークフローに関するガイダンス、ベストプラクティス、チェックリストが必要な場合

このスキルを使用しない場面

  • タスクが C4 アーキテクチャドキュメント作成ワークフローに関係しない場合
  • この範囲外の別の分野やツールが必要な場合

手順

  • 目標、制約、必要な入力を明確にします。
  • 関連するベストプラクティスを適用し、成果を検証します。
  • 実行可能な手順と検証方法を提示します。

概要

このワークフローでは、公式の C4 モデルに沿った包括的な C4 アーキテクチャドキュメントを、次の手順で作成します。

  1. コードレベル：すべてのサブディレクトリをボトムアップで分析し、コードレベルのドキュメントを作成します
  2. コンポーネントレベル：コードのドキュメントを統合し、コンテナ内の論理コンポーネントを整理します
  3. コンテナレベル：コンポーネントをデプロイメントコンテナに対応付け、API ドキュメントを作成します（技術選択の概要を示します）
  4. コンテキストレベル：ペルソナとユーザージャーニーを含むシステムの概要コンテキストを作成します（技術ではなく、人とソフトウェアシステムに焦点を当てます）

注：C4 モデルによると、4 つすべてのレベルの図を使用する必要はありません。ほとんどのソフトウェア開発チームでは、システムコンテキスト図とコンテナ図で十分です。このワークフローでは完全性のためにすべてのレベルを生成しますが、チームは使用するレベルを選択できます。

すべてのドキュメントは、リポジトリのルートに新しく作成する C4-Documentation/ ディレクトリに書き込まれます。

フェーズ 1：コードレベルのドキュメント（ボトムアップ分析）

1.1 すべてのサブディレクトリを検出する
  • コードベースを検索して、リポジトリ内のすべてのサブディレクトリを特定します
  • ボトムアップで処理するため、ディレクトリを階層の深い順に並べ替えます
  • 一般的なコード以外のディレクトリ（node_modules、.git、build、dist など）を除外します
  • 処理対象のディレクトリ一覧を作成します
1.2 各ディレクトリを処理する（ボトムアップ）

各ディレクトリについて、最も深い階層から順に実行します:

  • subagent_type="c4-architecture::c4-code" を指定して Task ツールを使用します

  • プロンプト: | 次のディレクトリ内のコードを分析してください: [directory_path]

    以下の構造に従って、包括的な C4 コードレベルのドキュメントを作成してください:

    1. 概要セクション:
      • 名前: [このコードディレクトリを表す説明的な名前]
      • 説明: [このコードが何を行うかの短い説明]
      • 場所: [リポジトリルートからの相対パスで、実際のディレクトリへのリンク]
      • 言語: [使用されている主要なプログラミング言語]
      • 目的: [このコードが達成すること]
    2. コード要素セクション:
      • すべての関数/メソッドを完全なシグネチャとともに記述します:
        • 関数名、パラメータ（型を含む）、戻り値の型
        • 各関数が何を行うかの説明
        • 場所（ファイルパスと行番号）
        • 依存関係（この関数が依存するもの）
      • すべてのクラス/モジュールを記述します:
        • クラス名、説明、場所
        • メソッドとそのシグネチャ
        • 依存関係
    3. 依存関係セクション:
      • 内部依存関係（このリポジトリ内の他のコード）
      • 外部依存関係（ライブラリ、フレームワーク、サービス）
    4. 関係セクション:
      • 関係が複雑な場合は任意で Mermaid 図

    出力は次のように保存してください: C4-Documentation/c4-code-[directory-name].md ファイル名にはサニタイズしたディレクトリ名を使用してください（/ を - に置換し、特殊文字を削除）。

    ドキュメントに以下が含まれるようにしてください:

    • すべてのパラメータと型を含む完全な関数シグネチャ
    • 実際のソースコードの場所へのリンク
    • すべての依存関係（内部および外部）
    • 明確で説明的な名前と説明

  • 期待される出力: C4-Documentation/ 内の c4-code-.md ファイル

  • コンテキスト: そのディレクトリとそのサブディレクトリ内のすべてのファイル

すべてのサブディレクトリについて繰り返し、すべてのディレクトリに対応する c4-code-*.md ファイルが作成されるまで行います。

フェーズ 2: コンポーネントレベルの統合

2.1 すべてのコードレベルのドキュメントを分析する
  • フェーズ 1 で作成されたすべての c4-code-*.md ファイルを収集します
  • コード構造、依存関係、関係を分析します
  • 以下に基づいて論理的なコンポーネントの境界を特定します:
    • ドメイン境界（関連するビジネス機能）
    • 技術境界（共有されるフレームワーク、ライブラリ）
    • 組織境界（チームの担当範囲、明確な場合）
2.2 コンポーネントドキュメントの作成

特定された各コンポーネントについて：

  • subagent_type="c4-architecture::c4-component" を指定して Task ツールを使用します

  • プロンプト: | 以下の C4 コードレベルのドキュメントファイルを、論理的なコンポーネントに統合してください：

    分析対象のコードファイル: [c4-code-*.md ファイルパスのリスト]

    次の構造に従って、包括的な C4 コンポーネントレベルのドキュメントを作成してください：

    1. 概要セクション:
      • 名前: [コンポーネント名 - 説明的で意味のあるもの]
      • 説明: [コンポーネントの目的の簡単な説明]
      • 種類: [アプリケーション、サービス、ライブラリなど]
      • テクノロジー: [主に使用される技術]
    2. 目的セクション:
      • このコンポーネントが何を行うかの詳細な説明
      • どのような問題を解決するか
      • システムにおける役割
    3. ソフトウェア機能セクション:
      • このコンポーネントが提供するすべてのソフトウェア機能を列挙
      • 各機能とその簡単な説明
    4. コード要素セクション:
      • このコンポーネントに含まれるすべての c4-code-*.md ファイルを列挙
      • 各ファイルへのリンクと簡単な説明
    5. インターフェースセクション:
      • すべてのコンポーネントインターフェースを文書化:
        • インターフェース名
        • プロトコル（REST、GraphQL、gRPC、イベントなど）
        • 説明
        • オペレーション（関数シグネチャ、エンドポイントなど）
    6. 依存関係セクション:
      • 使用するコンポーネント（このコンポーネントが依存する他のコンポーネント）
      • 外部システム（データベース、API、サービス）
    7. コンポーネント図:
      • このコンポーネントとその関係を示す Mermaid 図

    出力を次のように保存します: C4-Documentation/c4-component-[component-name].md ファイル名にはサニタイズされたコンポーネント名を使用してください。

  • 期待される出力: 各コンポーネントの c4-component-.md ファイル

  • コンテキスト: このコンポーネントに関連するすべての c4-code-*.md ファイル

2.3 マスターコンポーネントインデックスの作成

  • subagent_type="c4-architecture::c4-component" を指定して Task ツールを使用します

  • プロンプト: | システム内のすべてのコンポーネントを列挙するマスターコンポーネントインデックスを作成してください。

    作成されたすべての c4-component-*.md ファイルに基づいて、次を生成してください：

    1. システムコンポーネントセクション:
      • すべてのコンポーネントを次の情報とともに列挙:
        • コンポーネント名
        • 簡単な説明
        • コンポーネントドキュメントへのリンク
    2. コンポーネント関係図:
      • すべてのコンポーネントとその関係を示す Mermaid 図
      • コンポーネント間の依存関係を示す
      • 外部システムの依存関係を示す

    出力を次のように保存します: C4-Documentation/c4-component.md

  • 期待される出力: マスター c4-component.md ファイル

  • コンテキスト: すべての c4-component-*.md ファイル

フェーズ 3: コンテナレベルの統合

3.1 コンポーネントとデプロイ定義の分析
  • すべての c4-component-*.md ファイルを確認します
  • デプロイ/インフラストラクチャの定義を検索します:
    • Dockerfile
    • Kubernetes マニフェスト（デプロイメント、サービスなど）
    • Docker Compose ファイル
    • Terraform/CloudFormation 設定
    • クラウドサービスの定義（AWS Lambda、Azure Functions など）
    • CI/CD パイプラインの定義
3.2 コンポーネントをコンテナにマッピングする

  • subagent_type="c4-architecture::c4-container" を指定して Task ツールを使用します

  • プロンプト: | デプロイ定義に基づいて、コンポーネントをコンテナに統合します。

    コンポーネントのドキュメント: [すべての c4-component-*.md ファイルパスのリスト]

    検出されたデプロイ定義: [デプロイ設定ファイルのリスト: Dockerfile、K8s マニフェストなど]

    次の構成に従って、C4 コンテナレベルの包括的なドキュメントを作成します:

    1. コンテナセクション (各コンテナについて):
      • 名前: [コンテナ名]
      • 説明: [コンテナの目的とデプロイの簡単な説明]
      • 種類: [Web アプリケーション、API、データベース、メッセージキューなど]
      • テクノロジー: [主要なテクノロジー: Node.js、Python、PostgreSQL など]
      • デプロイ: [Docker、Kubernetes、クラウドサービスなど]
    2. 目的セクション (各コンテナについて):
      • このコンテナが何を行うかの詳細な説明
      • どのようにデプロイされるか
      • システムにおける役割
    3. コンポーネントセクション (各コンテナについて):
      • このコンテナにデプロイされているすべてのコンポーネントをリスト化
      • コンポーネントのドキュメントへのリンク
    4. インターフェースセクション (各コンテナについて):
      • すべてのコンテナ API とインターフェースを文書化:
        • API/インターフェース名
        • プロトコル (REST、GraphQL、gRPC、イベントなど)
        • 説明
        • OpenAPI/Swagger/API 仕様ファイルへのリンク
        • エンドポイント/操作のリスト
    5. API 仕様:
      • 各コンテナ API について、OpenAPI 3.1+ 仕様を作成
      • 保存先: C4-Documentation/apis/[container-name]-api.yaml
      • 含める内容:
        • メソッド (GET、POST など) を含むすべてのエンドポイント
        • リクエスト/レスポンスのスキーマ
        • 認証要件
        • エラーレスポンス
    6. 依存関係セクション (各コンテナについて):
      • 使用するコンテナ (このコンテナが依存する他のコンテナ)
      • 外部システム (データベース、サードパーティ API など)
      • 通信プロトコル
    7. インフラストラクチャセクション (各コンテナについて):
      • デプロイ設定 (Dockerfile、K8s マニフェストなど) へのリンク
      • スケーリング戦略
      • リソース要件 (CPU、メモリ、ストレージ)
    8. コンテナ図:
      • すべてのコンテナとその関係を示す Mermaid 図
      • 通信プロトコルを示す
      • 外部システムの依存関係を示す

    出力の保存先: C4-Documentation/c4-container.md

  • 期待される出力: すべてのコンテナと API 仕様を含む c4-container.md

  • コンテキスト: すべてのコンポーネントドキュメントとデプロイ定義

フェーズ 4: コンテキストレベルのドキュメント

4.1 システムドキュメントを分析する
  • コンテナとコンポーネントのドキュメントを確認する
  • システムドキュメントを検索する:
    • README ファイル
    • アーキテクチャドキュメント
    • 要件ドキュメント
    • 設計ドキュメント
    • テストファイル (システムの動作を理解するため)
    • API ドキュメント
    • ユーザードキュメント
4.2 コンテキストドキュメントの作成

  • subagent_type="c4-architecture::c4-context" を指定して Task ツールを使用します

  • プロンプト: | システムの包括的な C4 コンテキストレベルのドキュメントを作成します。

    コンテナドキュメント: C4-Documentation/c4-container.md コンポーネントドキュメント: C4-Documentation/c4-component.md システムドキュメント: [README、アーキテクチャドキュメント、要件などのリスト] テストファイル: [システムの動作を示すテストファイルのリスト]

    次の構造に従って、包括的な C4 コンテキストレベルのドキュメントを作成します:

    1. システム概要セクション:
      • 簡単な説明: [システムが何を行うかを一文で説明]
      • 詳細な説明: [システムの目的、機能、解決する問題の詳細な説明]
    2. ペルソナセクション:
      • 各ペルソナ（人間のユーザーおよびプログラム上の「ユーザー」）について:
        • ペルソナ名
        • タイプ（人間のユーザー / プログラム上のユーザー / 外部システム）
        • 説明（誰であるか、何を必要としているか）
        • 目標（何を達成したいか）
        • 使用する主な機能
    3. システム機能セクション:
      • 各高レベル機能について:
        • 機能名
        • 説明（この機能が何を行うか）
        • ユーザー（この機能を使用するペルソナ）
        • ユーザージャーニーマップへのリンク
    4. ユーザージャーニーセクション:
      • 各主要機能とペルソナについて:
        • ジャーニー名: [機能名] - [ペルソナ名] ジャーニー
        • ステップバイステップのジャーニー:
          2. ...
        • すべてのシステムタッチポイントを含める
      • プログラム上のユーザー（外部システム、API）について:
        • ステップバイステップのプロセスを含む統合ジャーニー
    5. 外部システムと依存関係セクション:
      • 各外部システムについて:
        • システム名
        • タイプ（データベース、API、サービス、メッセージキューなど）
        • 説明（何を提供するか）
        • 統合タイプ（API、イベント、ファイル転送など）
        • 目的（システムがこれに依存する理由）
    6. システムコンテキスト図:
      • 次を示す Mermaid C4Context 図:
        • システム（中央のボックスとして）
        • その周囲のすべてのペルソナ（ユーザー）
        • その周囲のすべての外部システム
        • 関係とデータフロー
        • 適切な C4 図のために C4Context 記法を使用する
    7. 関連ドキュメントセクション:
      • コンテナドキュメントへのリンク
      • コンポーネントドキュメントへのリンク

    出力を次のように保存します: C4-Documentation/c4-context.md

    ドキュメントが次の条件を満たすようにしてください:

    • 非技術系のステークホルダーにも理解できる
    • システムの目的、ユーザー、外部関係に焦点を当てている
    • 包括的なユーザージャーニーマップを含んでいる
    • すべての外部システムと依存関係を特定している

  • 期待される出力: 完全なシステムコンテキストを含む c4-context.md

  • コンテキスト: すべてのコンテナ、コンポーネント、システムドキュメント

設定オプション

  • target_directory: 分析するルートディレクトリ（デフォルト: 現在のリポジトリルート）
  • exclude_patterns: 除外するパターン（デフォルト: node_modules、.git、build、dist など）
  • output_directory: C4 ドキュメントを書き込む場所（デフォルト: C4-Documentation/）
  • include_tests: コンテキストのためにテストファイルを分析するかどうか（デフォルト: true）
  • api_format: API 仕様のフォーマット（デフォルト: openapi）

成功基準

  • ✅ すべてのサブディレクトリに、対応する c4-code-*.md ファイルがある
  • ✅ すべてのコードレベルのドキュメントに、完全な関数シグネチャが含まれている
  • ✅ コンポーネントが明確な境界とともに論理的にグループ化されている
  • ✅ すべてのコンポーネントにインターフェースのドキュメントがある
  • ✅ 関係図を含む、コンポーネントのマスターインデックスが作成されている
  • ✅ コンテナーが実際のデプロイ単位に対応している
  • ✅ すべてのコンテナー API が OpenAPI/Swagger 仕様で文書化されている
  • ✅ コンテナー図にデプロイアーキテクチャが示されている
  • ✅ システムコンテキストにすべてのペルソナ（人間およびプログラム）が含まれている
  • ✅ すべての主要機能のユーザージャーニーが文書化されている
  • ✅ すべての外部システムと依存関係が特定されている
  • ✅ コンテキスト図にシステム、ユーザー、外部システムが示されている
  • ✅ ドキュメントが C4-Documentation/ ディレクトリに整理されている

出力構成

C4-Documentation/
├── c4-code-*.md              # Code-level docs (one per directory)
├── c4-component-*.md          # Component-level docs (one per component)
├── c4-component.md            # Master component index
├── c4-container.md            # Container-level docs
├── c4-context.md              # Context-level docs
└── apis/                      # API specifications
    ├── [container]-api.yaml   # OpenAPI specs for each container
    └── ...

調整に関する注意事項

  • ボトムアップ処理：最も深い階層から浅い階層へとディレクトリを処理します
  • 段階的な統合：各階層は、前の階層のドキュメントを基に構築します
  • 完全な網羅性：統合の前に、すべてのディレクトリのコードレベルのドキュメントを作成する必要があります
  • リンクの整合性：すべてのドキュメントファイルが適切に相互リンクされます
  • API ドキュメント：コンテナー API には OpenAPI/Swagger 仕様が必要です
  • ステークホルダーに配慮：コンテキストのドキュメントは、技術者以外のステークホルダーにも理解できるようにします
  • Mermaid 図：すべての図で適切な C4 Mermaid 記法を使用します

使用例

/c4-architecture:c4-architecture

これにより、以下が行われます。

  1. すべてのサブディレクトリをボトムアップで確認します
  2. 各ディレクトリに c4-code-*.md を作成します
  3. コンポーネントに統合します
  4. API ドキュメントとともにコンテナーに対応付けます
  5. ペルソナとジャーニーを含むシステムコンテキストを作成します

すべてのドキュメントの出力先：C4-Documentation/

コメント

Markdown 対応