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

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

[Extended thinking: このワークフローは、C4 モデル (Context、Container、Component、Code) に従う完全な C4 アーキテクチャ ドキュメンテーション プロセスを実装しています。ボトムアップ アプローチを使用し、最も深いコード ディレクトリから開始して上向きに進み、すべてのコード要素がドキュメント化された後に、より高いレベルの抽象化に合成されることを確認します。ワークフローは 4 つの専門化された C4 エージェント (Code、Component、Container、Context) を調整して、技術者と非技術者の両方の関係者に役立つ完全なアーキテクチャ ドキュメント セットを作成します。]

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

• C4 アーキテクチャ ドキュメント ワークフロー タスクまたはワークフローに取り組んでいる場合
• C4 アーキテクチャ ドキュメント ワークフローのガイダンス、ベストプラクティス、またはチェックリストが必要な場合

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

• タスクが C4 アーキテクチャ ドキュメント ワークフローと無関係な場合
• このスコープ外の異なるドメインまたはツールが必要な場合

指示

• 目標、制約、および必要な入力を明確にします。
• 関連するベストプラクティスを適用し、結果を検証します。
• 実行可能なステップと検証を提供します。
• 詳細な例が必要な場合は、resources/implementation-playbook.md を開きます。

概要

このワークフローは、公式 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-<directory-name>.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. 概要セクション:
     • 名前: [コンポーネント名 - 説明的で意味のある]
     • 説明: [コンポーネントの目的の短い説明]
     • タイプ: [Application、Service、Library など]
     • テクノロジー: [使用される主要なテクノロジー]
  2. 目的セクション:
     • このコンポーネントが何を行うかの詳細な説明
     • 解決される問題
     • システム内でのその役割
  3. ソフトウェア機能セクション:
     • このコンポーネントが提供するすべてのソフトウェア機能をリストアップ
     • 各機能の簡潔な説明
  4. コード要素セクション:
     • このコンポーネントに含まれるすべての c4-code-*.md ファイルをリストアップ
     • 各ファイルへのリンクと簡潔な説明
  5. インターフェース セクション:
     • すべてのコンポーネント インターフェースをドキュメント化:
       • インターフェース名
       • プロトコル (REST、GraphQL、gRPC、Events など)
       • 説明
       • 操作 (関数シグネチャ、エンドポイントなど)
  6. 依存関係セクション:
     • 使用されるコンポーネント (このコンポーネントが依存する他のコンポーネント)
     • 外部システム (データベース、API、サービス)
  7. コンポーネント ダイアグラム:
     • このコンポーネントとその関係を示す Mermaid ダイアグラム

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

• 予期される出力: 各コンポーネントの c4-component-<name>.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 ファイルをレビューします
• デプロイメント/インフラストラクチャ定義を検索:
  • Dockerfiles
  • Kubernetes マニフェスト (deployments、services など)
  • Docker Compose ファイル
  • Terraform/CloudFormation 設定
  • クラウド サービス定義 (AWS Lambda、Azure Functions など)
  • CI/CD パイプライン定義

3.2 コンポーネントをコンテナにマップ

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

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

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

  見つかったデプロイメント定義: [デプロイメント設定ファイルのリスト: Dockerfiles、K8s マニフェストなど]

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

  1. コンテナ セクション (各コンテナについて):
     • 名前: [コンテナ名]
     • 説明: [コンテナの目的とデプロイメントの短い説明]
     • タイプ: [Web Application、API、Database、Message Queue など]
     • テクノロジー: [主要なテクノロジー: Node.js、Python、PostgreSQL など]
     • デプロイメント: [Docker、Kubernetes、Cloud Service など]
  2. 目的セクション (各コンテナについて):
     • このコンテナが何を行うかの詳細な説明
     • デプロイ方法
     • システム内でのその役割
  3. コンポーネント セクション (各コンテナについて):
     • このコンテナにデプロイされるすべてのコンポーネントをリストアップ
     • コンポーネント ドキュメントへのリンク
  4. インターフェース セクション (各コンテナについて):
     • すべてのコンテナ API とインターフェースをドキュメント化:
       • API/インターフェース名
       • プロトコル (REST、GraphQL、gRPC、Events など)
       • 説明
       • OpenAPI/Swagger/API Spec ファイルへのリンク
       • エンドポイント/操作のリスト
  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. システム概要セクション:
     • 短い説明: [システムが何を行うかの 1 文での説明]
     • 詳細な説明: [システムの目的、機能、解決される問題の詳細な説明]
  2. ペルソナ セクション:
     • 各ペルソナについて (人間ユーザーとプログラム的「ユーザー」):
       • ペルソナ名
       • タイプ (Human User / Programmatic User / External System)
       • 説明 (彼らが誰であるか、何が必要か)
       • 目標 (彼らが何を達成したいか)
       • 使用される主要機能
  3. システム機能セクション:
     • 各高レベル機能について:
       • 機能名
       • 説明 (この機能が何を行うか)
       • ユーザー (このペルソナがこの機能を使用する)
       • ユーザー ジャーニー マップへのリンク
  4. ユーザー ジャーニー セクション:
     • 各主要機能とペルソナについて:
       • ジャーニー名: [機能名] - [ペルソナ名] ジャーニー
       • ステップバイステップ ジャーニー:
         2. ...
       • すべてのシステム タッチポイントを含める
     • プログラム的ユーザー (外部システム、API) について:
       • ステップバイステップ プロセスを含む統合ジャーニー
  5. 外部システムと依存関係セクション:
     • 各外部システムについて:
       • システム名
       • タイプ (Database、API、Service、Message Queue など)
       • 説明 (それが何を提供するか)
       • 統合タイプ (API、Events、File Transfer など)
       • 目的 (システムがこれに依存する理由)
  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              # コード レベル ドキュメント (ディレクトリごと 1 つ)
├── c4-component-*.md          # コンポーネント レベル ドキュメント (コンポーネントごと 1 つ)
├── c4-component.md            # マスター コンポーネント インデックス
├── c4-container.md            # コンテナ レベル ドキュメント
├── c4-context.md              # コンテキスト レベル ドキュメント
└── apis/                      # API 仕様
    ├── [container]-api.yaml   # 各コンテナの OpenAPI 仕様
    └── ...

調整に関する注記

• ボトムアップ処理: 最も深いものから最も浅いものへディレクトリを処理
• 段階的な合成: 各レベルは前のレベルのドキュメントに基づいて構築される
• 完全なカバレッジ: 合成を開始する前に、すべてのディレクトリにコード レベルのドキュメントが必要
• リンクの一貫性: すべてのドキュメント ファイルは互いに適切にリンクする
• API ドキュメント: コンテナ API は OpenAPI/Swagger 仕様を持つ必要がある
• 関係者に優しい: コンテキスト ドキュメントは非技術関係者が理解できるようにする
• Mermaid ダイアグラム: すべてのダイアグラムに対して適切な C4 Mermaid 記法を使用

使用例

/c4-architecture:c4-architecture

これにより:

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

すべてのドキュメントは次の場所に書き込まれます: C4-Documentation/

制限事項

• 上記で説明されているスコープに明確に一致するタスクである場合にのみ、このスキルを使用します。
• 出力を環境固有の検証、テスト、または専門家レビューの代替と見なさないでください。
• 必要な入力、権限、安全性の境界、または成功基準が不足している場合は、停止して明確にするよう依頼します。