c4-codebase-architecture

C4 モデルによるコードベース文書化スキル

目的

このスキルは、エージェントがコードベースを調査し、C4 スタイルの有用なアーキテクチャ文書を作成できるよう支援します。リポジトリから得られる証拠と、コードの調査だけではシステム境界、責務、実行時のトポロジー、ビジネス上の意図を特定できない場合に行う、的を絞った追加質問を組み合わせます。

このスキルは、厳格な規則に従うのではなく、実用性を重視します。目標は、すべてのリポジトリに完璧な4つの図を無理に当てはめることではなく、適切な詳細度で、可能な限り明確なアーキテクチャの全体像を示すことです。

---

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

ユーザーが次のことを希望する場合に、このスキルを使用してください。

• 既存のコードベースのアーキテクチャを理解する
• リポジトリの C4 文書を作成する
• システムコンテキスト、コンテナー、またはコンポーネントのビューを生成する
• 新しいエンジニア向けにアーキテクチャ文書を用意する
• コードやインフラストラクチャの定義からシステム構造をリバースエンジニアリングする
• 意図されたアーキテクチャと実装済みのアーキテクチャを比較する

リポジトリに次のうち少なくとも一部が含まれている場合、このスキルは特に効果を発揮します。

• ソースコード
• Infrastructure as Code
• デプロイ記述子
• README またはドキュメント
• API 仕様
• CI/CD 構成
• テストスイート

---

このスキルで作成するもの

コードベースの情報に応じて、このスキルでは次の一部またはすべてを作成することを目指します。

1. システムコンテキスト

   • 調査対象のシステム
   • 人間のユーザーまたはペルソナ
   • 外部システム、API、プロバイダー、依存関係
   • 主要な関係

2. コンテナービュー

   • 主なデプロイ可能または実行可能な単位
   • データベース、キュー、フロントエンド、API、ワーカー、サーバーレス関数、データストア
   • それらの間のプロトコルとやり取り

3. コンポーネントビュー

   • 選択したコンテナー内の主な内部コンポーネント
   • それらの責務と関係

4. 補足説明

   • コード調査から導いた前提
   • 未解決の曖昧な点
   • ユーザーへの質問
   • 注目すべきアーキテクチャ上のリスクや不整合

5. 任意の図のソース

   • Mermaid、PlantUML、Structurizr DSL、またはプレーンテキストによる図の説明

明示的に依頼されない限り、完全なコードレベルの図を生成する必要はありません。理解を大きく助ける場合に限り、クラス、モジュール、パッケージに言及してもかまいません。

---

既定の運用原則

1. まず証拠を確認する

可能な限り、リポジトリで確認できる証拠に基づいてアーキテクチャに関する主張を行います。次の情報を優先してください。

• エントリーポイント
• ルーティング定義
• パッケージマニフェスト
• デプロイ記述子
• インフラストラクチャコード
• 環境変数の使用状況
• API クライアントと SDK の使用状況
• 統合テスト
• キュー／トピックの使用状況
• 永続化処理のコード

推測を事実として示さないでください。

2. 事実と推論を分ける

コードからアーキテクチャを推論する場合は、それが推論であることを明確に示します。

例：

• 確認できた事実：リポジトリには React アプリ、Express API、RDS インスタンス用の Terraform が含まれています。
• 推論：このシステムでは、ブラウザー上のフロントエンドが PostgreSQL を基盤とするバックエンド API を呼び出していると考えられます。

3. 重要度の高い質問だけをする

コードの調査だけでは不十分な場合、簡潔で効果の高い質問をまとめて行います。コードから確認できる可能性が高い詳細を、ユーザーに問いただすことは避けてください。

4. システム境界を尊重する

リポジトリ全体がシステム全体を表すとは限りません。文書化する範囲が次のどれにあたるかを明確にしてください。

• このリポジトリのみ
• より大きなプラットフォームに属する単一のサービス
• 複数のシステムを含むモノレポ
• より広範なアーキテクチャの一部のみを実装したもの

5. 有用な詳細度を既定とする

通常、最も有用な成果物は次のとおりです。

• システムコンテキスト図
• コンテナー図
• 主要なコンテナーのコンポーネント図を1つまたは2つ

単純なサービスにコンポーネントの分解を無理に適用しないでください。

---

リポジトリ分析ワークフロー

フェーズ 1：スコープを定める

まず、リポジトリが何を表しているように見えるかを確認します。

次の項目を確認します。

• リポジトリ名
• README の概要
• ワークスペースまたはモノレポの構成
• トップレベルのフォルダー
• パッケージマニフェスト
• ビルドファイル
• インフラストラクチャのフォルダー
• デプロイ用のフォルダー
• ドキュメント用のフォルダー

次の点を明らかにします。

• これはどのようなシステムまたはサブシステムですか？
• 完全なプロダクト、サービス、ライブラリ、インフラストラクチャのいずれですか？
• スコープに含まれるものと、含まれないものは何ですか？

スコープが曖昧な場合は、ユーザーに質問します。

フェーズ 2：実行時の構成要素を特定する

主な実行可能単位またはデプロイ可能単位を見つけます。

次の項目を確認します。

• Web フロントエンド
• バックエンドサービス
• CLI ツール
• サーバーレス関数
• ワーカーまたはスケジュール実行ジョブ
• データベース
• キャッシュ
• キューとストリーム
• 検索エンジン
• ストレージバケット
• サードパーティの SaaS 依存関係

重要な注意点：C4 における「コンテナー」は、デプロイまたは実行可能な単位を意味し、Docker コンテナーに限定されません。

フェーズ 3：相互作用を特定する

実行時の構成要素間の相互作用を整理します。

次の項目を確認します。

• HTTP クライアントとサーバー
• SDK の呼び出し
• メッセージの発行または受信
• データベースアクセスレイヤー
• 認証ミドルウェア
• イベントハンドラー
• cron またはスケジューラーの設定
• ファイルまたはオブジェクトストレージへのアクセス

次の点を把握します。

• データの流れる方向
• 確認できる場合は、トランスポートまたはプロトコル
• 同期処理か非同期処理か
• 信頼境界

フェーズ 4：アクターと外部システムを推定する

コードから外部システムが分かることは多いものの、エンドユーザーやビジネス上のアクターまでは分からない場合があります。

次の項目を確認します。

• 認証プロバイダー
• 決済システム
• メールプロバイダー
• クラウドサービス
• パートナー API
• ID 管理システム
• オブザーバビリティシステム

アクターは、次の情報から慎重に推定します。

• UI のラベル
• ルート名
• ドメイン固有の用語
• ロールチェック
• ドキュメント

ユーザーのペルソナが明確でない場合は、ユーザーに質問します。

フェーズ 5：重要なコンテナーをコンポーネントに分解する

重要度が高い、または複雑なコンテナーについて、主要な内部コンポーネントを特定します。

次の項目を確認します。

• モジュール
• パッケージ
• 機能別フォルダー
• コントローラー
• サービス
• リポジトリー
• アダプター
• ドメインレイヤー
• ハンドラー
• ミドルウェア

適切なコンポーネント分解では、ファイルをひとつずつ列挙するのではなく、通常は責務に焦点を当てます。

フォルダー名を並べただけのコンポーネント図は作成しないでください。

フェーズ 6：ドキュメントを作成する

最終出力に次の内容を含めます。

• 明示したスコープ
• 前提条件
• C4 ビュー
• 必要に応じた確認事項
• 要求された場合は図のソース

---

このスキルがユーザーに尋ねる質問

正確性を実質的に高める場合にのみ質問します。3～7 個の質問をまとめて尋ねることを優先します。

スコープについて

• このリポジトリはシステム全体ですか、それとも大規模なプラットフォーム内のひとつのサービスですか？
• ドキュメントの対象はリポジトリ内のものだけですか、それとも依存する周辺システムも含めますか？
• 新しいエンジニア、ステークホルダー、運用チームなど、図の対象読者に希望はありますか？

アクターとペルソナについて

• このシステムの主なユーザーまたは運用担当者は誰ですか？
• 顧客、管理者、サポート担当者、パートナーなど、異なるペルソナやロールはありますか？
• システムコンテキストビューに含めるべき社内運用チームはありますか？

デプロイ／実行時のトポロジーについて

• リポジトリ内のデプロイ可能単位は、本番環境における実際の実行時コンテナーでもありますか？
• マネージドデータベース、外部キュー、共有ゲートウェイなど、コードには含まれていない重要な外部要素はありますか？
• これはモノリス、マイクロサービス、サーバーレス関数、またはそれらを組み合わせた構成のいずれとしてデプロイされていますか？

システム境界について

• コンテキスト図では、何をシステム境界の外側と見なすべきですか？
• 共有プラットフォームサービスは別チームが所有しているため、外部システムとして表示するのが適切ですか？

曖昧な依存関係について

• この外部依存関係は、図に明示するほど中心的なものですか？
• S3、Redis、EventBridge などのインフラストラクチャサービスは、システム内のコンテナーとして表示すべきですか、それとも外部のマネージドサービスとして表示すべきですか？

コンポーネントについて

• コンポーネント図では、どのコンテナーに焦点を当てますか？
• ドメイン指向の内訳、技術レイヤーごとの内訳、またはコードに最も近い構造のどれを希望しますか？

出力形式について

• Mermaid、PlantUML、Structurizr DSL、またはテキストのみのドキュメントのどれを希望しますか？
• 簡潔なドキュメントと、説明を加えたオンボーディングにも役立つドキュメントのどちらがよいですか？

---

よくあるコードベースの形状に関するヒューリスティック

モノリス

リポジトリにメインアプリケーションが1つとデータベースが含まれている場合、出力として考えられるものは次のとおりです。

• コンテキスト：ユーザー、システム、外部連携
• コンテナー：Web アプリまたは API、データベース、場合によってはバックグラウンドワーカー
• コンポーネント：コントローラー、サービス、リポジトリ、連携機能

フロントエンドとバックエンドを含むモノレポ

リポジトリに複数のアプリまたはパッケージが含まれている場合：

• 独立してデプロイ可能なものを特定する
• ライブラリとコンテナーを分ける
• アーキテクチャの説明に役立つ場合に限り、共有ライブラリを示す

サーバーレスシステム

サーバーレスアーキテクチャの場合：

• 適切であれば、関数を意味のある実行時コンテナーにまとめる
• ユーザーがその粒度を明示的に求めていない限り、すべての関数を図にするのは避ける
• 関連する API Gateway、キュー、バケット、イベントバス、データストアを示す
• 複数の関数で実装されている場合でも、「API」、「非同期ワーカー」、「スケジュール処理」をコンテナーとして検討する

マイクロサービス

マイクロサービスのリポジトリの場合：

• 独立してデプロイ可能な各サービスをコンテナーとして示す
• サービス間の通信経路を特定する
• ライブラリやパッケージをサービスと混同しないよう注意する

ライブラリまたは SDK

リポジトリの主体がライブラリである場合、C4 ドキュメント一式は適切でないことがあります。その場合は：

• リポジトリ自体は完全な実行時システムではないことを説明する
• ユーザーがコンテキストを提供している場合は、より大きなシステムにおける役割を記録する
• 必要に応じて、ライブラリ自体のコンテキスト図とコンポーネント図を簡易版として作成する

---

出力テンプレート

デフォルトでは、次の構成を使用してください。

1. スコープ

ドキュメントの対象と、重要なスコープの境界を明記します。

例：

このドキュメントでは、現在のリポジトリから読み取れるアーキテクチャを扱います。バックエンドサービスとそのデプロイ設定を表しているようですが、エンドユーザー向けプラットフォーム全体は対象外です。

2. コードベースからの観察事項

リポジトリで確認できた、特に確かな手がかりを要約します。

例：

• apps/web にある React フロントエンド
• apps/api にある Node.js API
• PostgreSQL 依存関係とマイグレーションスクリプト
• VPC、ECS、RDS、SQS 用の Terraform モジュール
• キューメッセージを処理するバックグラウンドワーカー

3. 前提と推論

直接確認できた事実ではなく、推論に基づく項目を列挙します。

4. システムコンテキスト

簡潔に説明し、希望があれば図の定義も提示します。

5. コンテナービュー

簡潔に説明し、希望があれば図の定義も提示します。

6. コンポーネントビュー

重要なコンテナーを1つ以上取り上げます。

7. 未解決の質問

ドキュメントの改善に役立つ、未解決の曖昧な点を列挙します。

8. 次に検討すべき改善点

次に確認または記録すべき事項を提案します。

---

図の作成に関するガイダンス

全般的なガイダンス

すべての図で、次の点を満たしてください。

• 明確なタイトルを付ける
• スコープを定義する
• 説明的なボックスラベルを使う
• 関係には短い動詞またはフレーズでラベルを付ける
• 重要な技術情報は必要な場合に限り含める
• 視覚的に煩雑にならないようにする

ラベルの例

次のようなラベルを推奨します。

• Web Application\nReact SPA used by customers
• Orders API\nNode.js service handling checkout and order retrieval
• PostgreSQL\nStores users, orders, and payment state

次のような曖昧なラベルよりも適しています。

• Frontend
• Backend
• DB

関係の例

次のようなラベルを推奨します。

• Submits order via HTTPS
• Reads product catalog
• Publishes job messages
• Verifies identity token

ラベルのない矢印は避けてください。

インフラストラクチャとマネージドサービスの扱い方

このスキルでは、クラウドリソースを C4 図に含めるかどうかを、状況に応じて判断する必要があります。

コンテナレベルで表示する候補

アーキテクチャに実質的な影響を与える場合は、次の要素を表示します。

• 主要なデータベース
• メッセージキュー
• イベントバス
• 中核的なワークフロー要素として使用するオブジェクトストレージ
• キャッシュ
• 検索エンジン
• ID プロバイダー
• 主要な外部 API

関連性がない限り、通常は詳細すぎるもの

設計の中心でない限り、これらは実装の詳細にすぎない場合が多いです。

• サブネット
• セキュリティグループ
• IAM ロール
• オートスケーリングポリシー
• ロググループ
• CI ランナー

境界の判断

判断に迷った場合は、次の点を考慮します。

• チームがアプリケーションアーキテクチャの一部として所有し、検討するものであれば、システム境界内に含めるのが適切な場合があります
• 別のチームやベンダーが提供するプラットフォーム依存関係であれば、外部システムとして示すほうが適切な場合があります

---

スキルに求められる品質水準

良い成果物は、次の条件を満たします。

• コードベースを忠実に反映している
• 不確実性を明示している
• 人にとって役立つ
• 図が箱と矢印だらけになっていない
• 重要なランタイム構造に焦点を当てている

望ましくない成果物には、次のような問題があります。

• パッケージとデプロイ可能な単位を混同する
• 根拠のないアクターを作り出す
• 些細な詳細を過剰に記載する
• ラベルのない矢印が多数ある図を作成する
• 事実と推測の境界を曖昧にする

---

やり取りのパターン例

最初の応答例

リポジトリを調べたところ、フロントエンドアプリ、API サービス、ワーカー、そして PostgreSQL データベースと SQS キューのインフラストラクチャコードが確認できました。これらをもとに、System Context と Container の初稿を作成できます。

最終版を作成する前に、コードだけでは明確に判断できない点をいくつか確認する必要があります。

1. このリポジトリはシステム全体ですか、それともより大きなプラットフォームの一部ですか？
2. コンテキスト図に表示すべき主なユーザーロールは何ですか？
3. SQS や S3 などのマネージド AWS サービスはシステム境界内に表示しますか、それとも外部のサポートサービスとして表示しますか？
4. Component レベルで詳しく示すコンテナはどれですか？

追加のやり取りにおける動作例

ユーザーがすべての質問に回答しなくても、最善の範囲で初稿を作成し、前提を明確に記載して続行します。

---

推奨される標準成果物

ユーザーから別の指示がない限り、このスキルでは次の成果物を返すようにします。

• 簡潔な System Context ビューを 1 つ
• 簡潔な Container ビューを 1 つ
• 最も中核的なコンテナの Component ビューを 1 つ
• 前提と未解決の質問を説明する短い概要を 1 つ

システムが大規模な場合は、すべてを 1 回の応答に詰め込むのではなく、段階的な文書化を提案します。

---

任意の出力形式

求められた場合、このスキルでは次の形式で図を出力できます。

• Mermaid
• C4 拡張を使用した PlantUML
• Structurizr DSL
• 構造化されたセクションを含むプレーンな Markdown

ユーザーに希望がない場合は、Markdown の概要と Mermaid を既定とします。

---

エージェントへの最終指示

コードベースを注意深く調べ、アーキテクチャを慎重に推測し、コードからは判断できない点を解決するために的を絞った質問をしてください。不確実性について正直であり、正確で読みやすい C4 ドキュメントを作成してください。