mcpField
C
c4-architecture-c4-architecture

c4-architecture-c4-architecture

github.com/sickn33開発48.7k332 回インストール今日更新
リポジトリ

c4-architecture-c4-architecture について

c4-architecture-c4-architecture は、既存リポジトリから C4 アーキテクチャ文書を作成するエージェントスキルです。ソースの棚卸しからコンポーネント、コンテナ、コンテキストの各ビューへ進み、根拠や対象読者、安全な文書化を重視します。

主な機能

  1. 01ソースディレクトリのボトムアップ調査
  2. 02コードとコンポーネントの文書化
  3. 03コンポーネントとコンテナの対応付け
  4. 04C4 コンテキスト文書の作成
  5. 05ソースの根拠と文書範囲の維持

活用シーン

  1. 01既存リポジトリのアーキテクチャ文書化
  2. 02コード調査結果からコンポーネントを整理
  3. 03コンポーネントとデプロイ定義の関連付け
  4. 04対象読者に適した C4 ビューの準備

インストール

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

$npx skills add https://github.com/sickn33/agentic-awesome-skills --skill c4-architecture-c4-architecture

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

詳細

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

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

ボトムアップでソースを棚卸しし、C4 ビューの根拠とします。そのうえで、対象読者に役立つレベルだけを選択します。専門エージェントは任意の実行支援であり、同梱ツールでも、ソースがレビューされたことの証明でもありません。

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

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

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

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

手順

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

概要

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

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

注：C4 モデルによると、図の 4 つのレベルすべてを使用する必要はありません。ほとんどのソフトウェア開発チームには、システムコンテキスト図とコンテナー図があれば十分です。まず役立つレベルを選択してください。コードレベルの図は任意であり、すべてのディレクトリを網羅する機能カタログではありません。詳細な図を省略する場合も、ソースの棚卸しは維持してください。

ユーザーが指定した場所を使用し、指定がない場合は、リポジトリのルートに新しい C4-Documentation/ ディレクトリを提案してください。

書き始める前に、リポジトリ／HEAD、対象読者、システム境界、実際に調査したファイルを記録してください。機密情報や内部インフラの詳細を保護し、既存のドキュメント規約に従ってください。C4 のコンテナーはアプリケーションまたはデータストアであり、Docker コンテナーやデプロイのレプリカ 1 つと同義ではありません。コンポーネントは 1 つのコンテナーに属します。コードディレクトリだけでは、コンポーネント境界を定められません。

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

1.1 すべてのサブディレクトリを特定する
  • コードベース検索を使用して、リポジトリ内のすべてのサブディレクトリを特定します
  • ボトムアップで処理できるよう、ディレクトリを深さ順（最も深いものから）に並べ替えます
  • 一般的な非コードディレクトリ（node_modules、.git、build、dist など）を除外します
  • 処理対象のディレクトリ一覧を作成します
1.2 各ディレクトリを処理する（ボトムアップ）

最も深い階層から順に、各ディレクトリについて以下を行います。

  • 権限があり、互換性のあるサブエージェントが存在する場合は、この範囲を限定した分析を委任します。そうでない場合は、直接実行します。c4-architecture::c4-code はロール名の例であり、同梱ツールではありません。

  • プロンプト： | ディレクトリ内のコードを分析します：[directory_path]

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

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

    出力を次の場所に保存します：C4-Documentation/c4-code-[directory-name].md 安定した、衝突のないパスマッピングを使用します。a/b と a-b が互いに上書きされないようにしてください。出力サブディレクトリを対応させるか、短いパスハッシュを付加し、マッピングを記録してください。

    ドキュメントに以下が含まれていることを確認してください。

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

  • 想定される出力：C4-Documentation/ 内の c4-code-.md ファイル

  • コンテキスト：このインベントリ単位が直接所有するファイルのみを対象にします。同じファイルを繰り返し対象として記載するのではなく、以前にレビューした子インベントリへのリンクを使用してください。

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

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

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

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

  • 利用可能な認可済みヘルパーを使用するか、このコンポーネントの統合を直接実行します。

  • プロンプト：| 次の 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 コンポーネントのマスターインデックスを作成する

  • 利用可能な認可済みヘルパーを使用するか、このコンポーネントの統合を直接実行します。

  • プロンプト：| システム内のすべてのコンポーネントを一覧表示するマスターコンポーネントインデックスを作成します。

    作成したすべての 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 コンポーネントをコンテナにマッピングする

  • 利用可能な認証済みヘルパーを使用するか、このコンテナの統合作業を直接行います。

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

    コンポーネントのドキュメント： [すべての 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 仕様：
      • 検証済みの HTTP API ごとに、既存の正式な仕様へのリンクを記載します。依頼があり、実際のルート／スキーマで裏付けられる場合に限り、OpenAPI 3.1 以降のドラフト文書を作成します。HTTP 以外のプロトコルには、架空の OpenAPI ではなく、適切な契約仕様を用意します。
      • 次の場所に保存します：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 コンテキストドキュメントの作成

  • 利用可能な承認済みヘルパーを使用するか、このコンテキストの統合を直接実行します。

  • プロンプト： | システムの包括的な C4 コンテキストレベルのドキュメントを作成してください。

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

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

    1. システム概要セクション：
      • 短い説明：[システムが何をするかを示す1文の説明]
      • 詳細な説明：[システムの目的、機能、解決する問題の詳細な説明]
    2. ペルソナセクション：
      • 各ペルソナ（人間のユーザーとプログラムによる「ユーザー」）について、以下を記載します。
        • ペルソナ名
        • 種別（人間のユーザー／プログラムによるユーザー／外部システム）
        • 説明（どのような人か、何を必要としているか）
        • 目標（何を達成したいか）
        • 使用する主な機能
    3. システム機能セクション：
      • 各高レベル機能について、以下を記載します。
        • 機能名
        • 説明（この機能が何をするか）
        • ユーザー（この機能を使用するペルソナ）
        • ユーザージャーニーマップへのリンク
    4. ユーザージャーニーセクション：
      • 各主要機能とペルソナについて、以下を記載します。
        • ジャーニー名：[機能名] - [ペルソナ名] ジャーニー
        • ジャーニーの手順：
          1. [手順1]：[説明]
          2. [手順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）

命名だけからユーザー、ジャーニー、スケーリング、CPU／メモリ要件を推測しないでください。根拠となるソースへのリンクを記載するか、仮定／未解決の質問として明示してください。図をコードやデプロイの担当者と照合し、リンクと ID を確認し、静的なソースの解釈と実際のランタイムトポロジーを区別してください。

成功基準

  • ✅ すべてのサブディレクトリに対応する c4-code-*.md ファイルがある
  • ✅ すべてのコードレベルのドキュメントに完全な関数シグネチャが含まれている
  • ✅ コンポーネントが明確な境界を持つよう論理的にグループ化されている
  • ✅ すべてのコンポーネントにインターフェイスのドキュメントがある
  • ✅ 関係図を含むマスターコンポーネントインデックスが作成されている
  • ✅ コンテナが実際のデプロイ単位に対応している
  • ✅ 検証済みの HTTP API は実際の仕様にリンクされているか、未完成の草案であることが明示されている。HTTP 以外のインターフェイスには適切なコントラクトが使用されている
  • ✅ コンテナ図にデプロイアーキテクチャが示されている
  • ✅ システムコンテキストにすべてのペルソナ（人間およびプログラム）が含まれている
  • ✅ すべての主要機能についてユーザージャーニーが文書化されている
  • ✅ すべての外部システムと依存関係が特定されている
  • ✅ コンテキスト図にシステム、ユーザー、外部システムが示されている
  • ✅ ドキュメントが 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 テンプレートを埋めるために、リクエスト、レスポンス、認証の詳細を創作しないでください
  • ステークホルダーに配慮：コンテキストドキュメントは、技術者以外のステークホルダーにも理解できる内容にします
  • Mermaid 図：対象のレンダラーがサポートする図の構文を使用してください。C4 Mermaid のサポート状況はバージョンによって異なります。レンダリングと関係性を検証するか、フローチャートを代替として明確に表示してください

使用例

Document this repository’s context and containers at the specified commit.
Include source links and open questions; omit detailed code views unless they add value.

これにより、次の処理が行われます。

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

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

制限事項

  • タスクが上記の範囲に明確に該当する場合に限り、このスキルを使用してください。
  • 出力を、環境固有の検証、テスト、または専門家によるレビューの代替として扱わないでください。
  • 必要な入力、権限、安全上の境界、または成功基準が不足している場合は、作業を中断して確認を求めてください。

コメント

Markdown 対応