c4-to-eventcatalog

C4 から EventCatalog へ

概要

アーキテクチャの意図を損なわずに、C4 モデルを EventCatalog のリソースにマッピングします。まずレビュー可能な .c4-eventcatalog-plan.md を作成し、その後、ユーザーの承認を得てから catalog-documentation-creator を使い、実際のカタログファイルを生成または更新します。

参照資料を読み込む

C4 モデルをマッピングする前に、必ず references/c4-mapping.md を読んでください。

ファイルを生成する際は、関連する ../catalog-documentation-creator/references/ のファイルを読んでください。

• domains.md、systems.md、services.md、agents.md
• events.md、commands.md、queries.md
• channels.md、containers.md、flows.md
• NodeGraph、Mermaid、Wiki リンク、スキーマ、MDX コンポーネントについては components.md
• 単独の図として残す価値のあるビューがモデルに含まれている場合は diagrams.md

ワークフロー

以下のフェーズを順番に進めてください。

1. 入力を特定する

C4 のソースが提供されていない場合は、提示を求めてください。Structurizr DSL/JSON、LikeC4（.c4）、C4-PlantUML、Mermaid C4、Markdown のアーキテクチャドキュメント、画像の図を受け付けます。画像のみからの抽出よりも、ソーステキストのほうが信頼性が高いことを伝えてください。

ソースが LikeC4 の場合、.c4 ファイルがカタログ内にあり、likec4 パッケージがインストールされていれば、EventCatalog は <LikeC4View viewId="..." /> を使ってビューを直接レンダリングすることもできます。生成されたリソースと併せて、マッピングしたリソースの本文に関連ビューを埋め込むことを提案してください。

EventCatalog プロジェクトがあるかどうかを尋ねてください。ある場合は、パスを尋ね、eventcatalog.config.js または既知のリソースディレクトリを確認してください。ない場合は、引き継ぎ時に catalog-documentation-creator を通じて雛形を作成することを伝えてください。

2. 既存のカタログを調査する

カタログがある場合は、変更を提案する前に調査してください。

• フラット構造かドメイン別の階層構造かを確認します。
• 既存のリソース ID、名前、バージョン、オーナー、関係を記録します。
• 命名スタイル、スキーマ形式、オーナーの慣例、バッジ、ドメインの使用状況を記録します。
• C4 モデルに存在しない既存のカタログリソースは、削除候補ではなく investigate として扱います。

3. C4 モデルを解析する

以下を抽出します。

• 人および外部システム
• ソフトウェアシステム
• アプリ、サービス、エージェント、データベース、キュー、ブラウザー／モバイルクライアントを含むコンテナー
• 所有権、デプロイ、データ、またはメッセージの境界をまたぐ場合に限り、コンポーネント
• 関係、プロトコル、テクノロジー、タグ、説明、ビュー
• フローにすべき動的ビューやシナリオの説明
• メッセージ名、トピック、キュー、API、コマンド、クエリ、イベント、スキーマ参照

根拠を保持してください。ソースファイルの場合は、可能な限りファイルパスと行番号を示してください。図の場合は、図／ビューの名前と要素 ID を示してください。

4. マッピングして調整する

references/c4-mapping.md を使い、各 C4 要素を domain、system（内部または scope: external）、システムの actor、システムの relationship、service、agent、event、command、query、channel、container、flow、resource 本文内の document、または needs user decision のいずれかにマッピングします。

既存のカタログについては、マッピングした各項目に new、update、unchanged、investigate のいずれかのステータスを付与します。

5. 構造に関する質問だけをする

質問は一度に一つにしてください。各質問には以下を含めます。

• 推奨する回答
• その回答に至った根拠
• EventCatalog リソースの生成への影響

構造に影響する判断についてのみ質問してください。具体的には、ドメインの境界、どのソフトウェアシステムが内部か外部か、デプロイ可能なサービスの境界、エージェントの分類、関係がイベント／コマンド／クエリ／API 呼び出しのどれにあたるか、インフラストラクチャノードがチャネルかデータコンテナーか、既存のリソースを更新するかどうかです。文章、要約、装飾的なメタデータについて、ユーザーに細かく尋ねないでください。

6. 計画を作成する

カタログのディレクトリが存在する場合はその中に、存在しない場合は指定された C4 ソースの隣、または現在の作業ディレクトリに .c4-eventcatalog-plan.md を作成します。references/c4-mapping.md のテンプレートを含めます。テンプレートには、ソース、決定事項、リソースのマッピング、関係、作成・更新するファイル、未解決の質問を記載します。

カタログファイルを生成する前に、ユーザーに計画の承認を求めます。

7. カタログファイルを生成する

承認後、catalog-documentation-creator を使用してファイルを作成または更新します。承認済みの計画に含まれるリソースに関連する EventCatalog のリファレンスファイルだけを読み込みます。対象カタログの既存の構成に従い、既存リソースを上書きする場合は、ユーザーのコンテンツを必ず保持するか、内容を調整してください。

品質ルール

• 特に理由がない限り、C4 のボックスごとに EventCatalog リソースを作成しないでください。責務、デプロイ、所有権、メッセージフロー、EventCatalog での有用性に基づいてマッピングします。
• 空のドメインを作成しないでください。ドメインには、少なくとも 1 つのシステム、サブドメイン、サービス、またはエージェントが含まれている必要があります。
• C4 のすべてのコンポーネントを EventCatalog リソースとしてモデル化しないでください。ほとんどのコンポーネントは、親サービスの本文、Mermaid 図、またはフローに含めます。
• 推測したメッセージタイプより、明示された C4 の関係ラベルを優先します。関係ラベルが曖昧な場合は、needs user decision と記載します。
• ID はカタログ内で一貫性を保ちます。新しいカタログを作成する場合、ユーザーから指定がなければ、ビジネスリソースの ID には PascalCase を優先します。
• 既存のカタログ内容を保持します。削除せず、追加、更新、または差異の指摘を行います。
• 関連する EventCatalog のリファレンスで推奨されている場合は、引き継ぎスキルを通じて、生成するリソースに <NodeGraph /> を含めます。