catalog-documentation-creator

EventCatalog ドキュメント作成ツール

プロジェクトの規約とベストプラクティスに従って、適切にフォーマットされた EventCatalog ドキュメントファイルを生成します。

手順

ステップ 1：ユーザーのカタログを特定または作成する

ファイルを生成する前に、ユーザーに次のように尋ねます。「すでに EventCatalog プロジェクトをお持ちですか？それとも新しく作成しますか？」

すでにカタログをお持ちの場合：

• 次のように尋ねます。「EventCatalog プロジェクトはどこにありますか？」 — 次のような場所が考えられます。
  • ローカルにクローンしたリポジトリ（例：~/projects/my-catalog/）
  • マシン上のフォルダー
  • カタログがサブディレクトリにあるモノレポ
• eventcatalog.config.js ファイル、または既知のディレクトリ（systems/、services/、agents/、events/、domains/、adrs/、data-products/、entities/ など）があることを確認し、EventCatalog プロジェクトのように見えるか検証します
• 既存の構造を読み取り、ネスト型（domains/services/agents/events）またはフラット型（トップレベルの services/、agents/、events/）のどちらで構成されているかを把握します

まだカタログをお持ちでない場合：

• 作成場所を尋ねます（デフォルト：現在のディレクトリ）
• 次のコマンドを実行して、新しい空のカタログをひな形から作成します。

  npx @eventcatalog/create-eventcatalog@latest my-catalog --empty
  

  （my-catalog をユーザーの希望する名前に置き換えます）
• これにより、正しい構造を備えた、すぐに使える EventCatalog プロジェクトが作成されます
• 生成されたドキュメントファイルはすべて、この新しいカタログディレクトリ内に配置します

重要：生成するファイルはすべて、表示するだけでなく、ユーザーのカタログディレクトリに書き込む必要があります。リソースをどこにドキュメント化するかは必ず尋ね、決して決めつけないでください。

ステップ 2：ユーザーがドキュメント化したい内容を把握する

ユーザーに、ドキュメント化したい内容を尋ねます。一般的な例：

• 単一のサービスまたはエージェントと、そのメッセージ
• サービス、コンテナ、フロー、エンティティ、アクター、関連システムをまとめるシステム
• イベント、コマンド、またはクエリ
• ネストされたサービスを含むドメイン全体
• サービスやエージェントをまたぐビジネスフロー
• チャネル（Kafka トピック、RabbitMQ キューなど）
• コンテナ（データベース、キャッシュ、キュー）
• アーキテクチャ決定記録（ADR）
• 分析、レポート、ML 機能、または運用データの出力を対象とするデータプロダクト
• ドメインエンティティまたは集約
• 再利用可能な図のリソース

生成する前に、次の情報を収集します。

• リソース名と目的
• バージョン（新しいリソースの場合、デフォルトは 0.0.1）
• システムをドキュメント化する場合は、システム境界、スコープ（internal または external）、アクター、関係、含まれるリソース
• メッセージの関係（送受信する内容）
• チャネルのルーティング（メッセージが流れるチャネル）
• コンテナ（サービスが読み取りまたは書き込みを行うデータベースやキャッシュ）
• ADR のリンク（決定が適用されるリソース、および別の ADR に取って代わるか、修正するか）
• データプロダクトのリネージ（入力、出力、コントラクト、鮮度／SLA の要件）
• エンティティと関係（識別子、プロパティ、参照、集約ルート）
• 図の記法（Mermaid、PlantUML、またはその他のサポート対象のフェンス付き図形式）
• エージェントをドキュメント化する場合は、エージェントのモデル／プロバイダーとツール
• 該当する場合は、スキーマ形式（JSON Schema、Avro、Protobuf）

ユーザーがカタログではなくコードベースを指定した場合は、それを分析してサービス、エージェント、メッセージ、スキーマ、関係を抽出し、対応するカタログドキュメントを生成します。

ステップ 3：既存のカタログを確認する

カタログディレクトリにすでにリソースがある場合は、既存のファイルを読んで、次の点を確認します。

• 命名規則（PascalCase の ID か、kebab-case か）
• フォルダー構成（ドメインごとに階層化されているか、フラットか）
• すでに定義されているオーナー／チーム
• 使用されているバッジのスタイルやパターン
• 使用されているスキーマ形式（JSON Schema、Avro など）

新しいドキュメントは、既存の規約に合わせてください。

ユーザーが EventCatalog MCP サーバーに接続している場合：

1. getResources を使用して、カタログにすでに何があるか確認します
2. getResource を使用して、既存のエントリーで使われている規約（命名パターン、オーナーの形式、バッジのスタイル）を確認します
3. findResourcesByOwner を使用して、一貫性のあるオーナーを提案します
4. getSchemaForResource を使用して、既存のスキーマ形式に合わせます

これにより、新しいドキュメントがカタログ内の既存の内容と一貫したものになります。

ステップ 4：ドキュメントを生成する

リソース固有のリファレンスに従ってファイルを生成します。リソースの種類に応じたリファレンスファイルを参照してください。

• references/services.md — 送受信、チャネルルーティング、コンテナを含むサービス
• references/systems.md — スコープ、サービス、コンテナ、フロー、エンティティ、アクター、システム間の関係を含むシステム
• references/agents.md — モデルのメタデータ、ツール、送受信、コンテナ、フローを含むエージェント
• references/events.md — スキーマ、ペイロードの例、プロデューサー／コンシューマーのコードを含むイベント
• references/commands.md — REST 操作とスキーマを含むコマンド
• references/queries.md — REST 操作とレスポンススキーマを含むクエリ
• references/domains.md — サブドメイン、サービス、ビジネスコンテキストを含むドメイン
• references/flows.md — ステップ、分岐、外部システムを含むビジネスフロー
• references/channels.md — ルーティング、プロトコル、パラメーターを含むチャネル
• references/containers.md — データ分類を含むコンテナ（データベース、キャッシュ、キュー）
• references/adrs.md — ステータス、日付、意思決定者、適用対象、関係を含むアーキテクチャ決定記録
• references/data-products.md — 入力、出力、データコントラクト、リネージ、SLA を含むデータプロダクト
• references/entities.md — 識別子、プロパティ、関係、集約ルートを含む DDD／ドメインエンティティ
• references/diagrams.md — 再利用可能な図リソース（Mermaid、PlantUML、アーキテクチャ図）
• references/ubiquitous-language.md — ドメインごとのユビキタス言語用語（DDD 用語集／辞書）
• references/teams-and-users.md — チームとユーザー（所有者）
• references/components.md — コンポーネント（NodeGraph、Schema、Mermaid、Tabs など）およびリソース参照（[[type|Name]] 形式の Wiki リンク）
• references/supporting-collections.md — 変更履歴、リソースドキュメント、カスタムドキュメント、スキーマ、Studio デザイン

すべてのリソースファイルには、必ず以下を含めてください。

• --- 区切りで囲んだ有効な YAML フロントマター
• 既存のカタログ規約に沿った id フィールド
• 人が読み取れる表示名としての name
• セマンティックバージョン文字列としての version
• 簡潔な 1～2 文の説明としての summary
• 少なくとも 1 つのチームまたはユーザーを指定した owners（summary または所有者のないリソースは、EventCatalog リンターでデフォルトでエラーになります）

重要：リファレンスファイルに記載されているフロントマターフィールドのみを使用してください。不明なトップレベルキーがあるとビルドに失敗します（Unknown property "tags". Custom properties must start with "x-"）。カスタムメタデータは x- で始まるキーに格納してください（例：x-tier: gold）。また、<CustomProperties /> または <CustomProperty name="x-tier" /> を使って本文に表示してください。

重要：バージョン管理されるリソース（システム、サービス、エージェント、イベント、コマンド、クエリ、ドメイン、フロー、チャネル、コンテナ、ADR、データプロダクト、エンティティ、図）では、必ず index.mdx をファイル名に使用してください。チームとユーザーには {id}.mdx ファイルを直接使用します。変更履歴には changelog.mdx または changelog.md を使用します。ユビキタス言語には ubiquitous-language.mdx を使用します。リソースの旧バージョンは、リソース内の versioned/{version}/index.mdx フォルダーにアーカイブしてください（例：events/OrderCreated/versioned/0.0.1/index.mdx）。最新バージョンはリソースのルートに置きます。ネスト構造のパターンに従い、正しいフォルダーパスにファイルを配置してください。

domains/{DomainName}/systems/{SystemName}/index.mdx
domains/{DomainName}/systems/{SystemName}/services/{ServiceName}/index.mdx
domains/{DomainName}/systems/{SystemName}/containers/{ContainerName}/index.mdx
domains/{DomainName}/services/{ServiceName}/events/{EventName}/index.mdx
domains/{DomainName}/agents/{AgentName}/index.mdx
domains/{DomainName}/data-products/{DataProductName}/index.mdx
domains/{DomainName}/entities/{EntityName}/index.mdx
domains/{DomainName}/diagrams/{DiagramName}/index.mdx

または、カタログがそのパターンを使用している場合は、フラット構造にしてください。

systems/{SystemName}/index.mdx
services/{ServiceName}/index.mdx
agents/{AgentName}/index.mdx
events/{EventName}/index.mdx
adrs/{adr-id}/index.mdx
data-products/{DataProductName}/index.mdx
entities/{EntityName}/index.mdx
diagrams/{DiagramName}/index.mdx

schemas コレクションのエントリーを直接生成しないでください。イベント、コマンド、またはクエリから schemaPath または schemas を使ってスキーマファイルを生成または参照してください。EventCatalog は、これらの参照から schemas コレクションを作成します。ユーザーが EventCatalog Studio の .ecstudio コンテンツを明示的に提供した場合を除き、designs を手動で作成しないでください。

ステップ 5：出力を検証する

ファイルをユーザーに提示する前に、次の点を確認してください。

• YAML フロントマターの両側に --- の区切りがある
• すべてのフロントマターキーが該当するリソースタイプ向けに定義されているか、x- が先頭に付いている
• すべての id フィールドに一貫性がある（スペースがなく、フォルダー名と一致している）
• すべての version フィールドが有効な semver 文字列である（例：0.0.1）
• sends／receives 内のすべてのメッセージ参照に id が含まれ、version は任意である
• システムの services、containers、flows、entities、relationships、およびドメインの systems の各参照に id が含まれ、version は任意である
• システムの scope が internal または external であり、アクターの direction が inbound または outbound である
• チャネルのルーティングで、sends／receives の to／from フィールドが正しく使われている
• schemaPath で参照されているスキーマファイルが実在するか、生成される
• アーキテクチャを可視化するために <NodeGraph /> コンポーネントが含まれている
• オーナー ID がカタログ内の実在するチーム／ユーザーを参照している

よくあるパターン

メッセージを処理するサービスのドキュメント化

ユーザーが「OrderCreated イベントを受信し、PaymentProcessed イベントを送信する決済サービスをドキュメント化して」と言った場合：

1. receives と sends の配列を含むサービスの index.mdx を生成します
2. メッセージがチャネルを経由する場合は、sends／receives に to／from フィールドを追加します
3. カタログに存在しない場合は、各イベントの index.mdx を生成します
4. メッセージフローを示すために、サービス本文に <NodeGraph /> を含めます
5. サービスが重要なドメインオブジェクトを所有する場合は、関連するエンティティを生成します
6. 各メッセージのサンプルペイロードのセクションを追加します
7. ファイルを正しい階層フォルダー構造に配置します

システムのドキュメント化

ユーザーが機能、サブシステム、製品機能、または外部システムについて説明した場合：

1. システムをドメイン内（domains/{Domain}/systems/{System}/index.mdx）に配置するか、複数のドメインで共有されている、外部にある、または特定のドメインに所有されていないためカタログのルート（systems/{System}/index.mdx）に配置するかを判断します
2. 判明している場合は、scope、owners、および services、containers、flows、entities、diagrams への参照を含むシステムの index.mdx を生成します
3. 他のシステムへの一方向リンクには relationships を追加し、エッジに短い label を使用します
4. 人、役割、または外部の参加者には actors を追加します。アクターがシステムとやり取りする場合は direction: inbound、システムがアクターに働きかける場合は direction: outbound を使用します
5. アクターとシステム間の関係を示すために、<ContextDiagram /> を含めます
6. システム内のリソースを示すために、<NodeGraph /> を含めます
7. システムが所有する場合は、そのシステムフォルダーの下にネストしたリソースを生成します。例：domains/{Domain}/systems/{System}/services/{Service}/index.mdx
8. システムがドメインの下にネストされている場合は、ドメインの systems フロントマターに追加します。ドメイン内にネストされたすべてのシステムは、そのドメインの index.mdx で参照しなければなりません。

   systems:
     - id: cart-system
       version: 1.0.0
     - id: promotion-system
       version: 1.0.0
   

9. ADR がシステム境界、永続化、統合パターン、または所有権モデルに関係する場合は、appliesTo: [{ type: system, id: ... }] を指定してリンクします

エージェントのドキュメント化

ユーザーが「注文データを読み取り、Zendesk を使うサポートエージェントをドキュメント化して」と言った場合：

1. 判明している範囲で、model、tools、receives／sends、readsFrom／writesTo、flows を含むエージェントの index.mdx を生成します
2. エージェントが消費または生成するイベント／コマンド／クエリを生成するか、参照します
3. エージェントが読み取る、または書き込むデータストアのコンテナーを生成します
4. ツールがドキュメント化されている場合は、<AgentTools /> を含めます
5. アーキテクチャの可視化にエージェントが表示されるよう、<NodeGraph /> を含めます
6. エージェントがドメインに属する場合は、ドメインの agents フロントマターに追加します

ドメインの文書化

重要：ドメインには、システム、サービス、エージェントのいずれかが少なくとも1つ必要です。空のドメインは作成しないでください。ユーザーがドメインについて説明した場合は、そのドメインに属するシステム、サービス、エージェントを特定して生成してください。

ユーザーがドメイン全体を文書化したい場合：

1. このドメインに属するシステム、サービス、エージェントを特定します。ユーザーが何も指定していない場合は、「このドメインにはどのシステム、サービス、エージェントが属していますか？」と尋ねます。空のドメインは作成しないでください。
2. ドメインの index.mdx を生成し、systems フィールドにすべてのシステムを、services フィールドにドメイン直下のすべてのサービスを、agents フィールドにドメイン直下のすべてのエージェントを列挙します
3. entities、data-products、flows、diagrams のリソースがドメイン直下に属する場合は、それらのフィールドを含めます
4. ドメイン内の各システム、サービス、エージェントを生成します
5. サービスとエージェントが参照する各メッセージを生成します
6. ユーザーが説明した場合は、エンティティ、データプロダクト、図、チャネルを生成します
7. 入れ子になったフォルダー構造を使用します：domains/{Domain}/systems/{System}/、domains/{Domain}/systems/{System}/services/{Service}/events/{Event}/、domains/{Domain}/services/{Service}/events/{Event}/、domains/{Domain}/agents/{Agent}/、domains/{Domain}/entities/{Entity}/、domains/{Domain}/data-products/{DataProduct}/
8. サービス名、エージェント名、イベント名／コマンド名、エンティティ、ビジネスプロセスからドメイン固有の用語を抽出し、ドメインの ubiquitous-language.mdx ファイルを生成します。domains/{Domain}/ubiquitous-language.mdx に配置してください。形式と例については references/ubiquitous-language.md を参照してください。
9. 重要：すべてのファイルを生成した後、ドメインのフロントマターの systems フィールドにすべてのシステムが、services フィールドにドメイン直下のすべてのサービスが、agents フィールドにドメイン直下のすべてのエージェントが記載されていることを確認します。ドメイン直下に作成されたすべてのシステム、サービス、エージェントは、ドメインの index.mdx で必ず参照してください：

   systems:
     - id: CheckoutSystem
   services:
     - id: OrdersService
     - id: InventoryService
     - id: PaymentService
   agents:
     - id: OrderSupportAgent
   

   システム、サービス、エージェントがドメインフォルダー内にネストされていても、ドメインのフロントマターに記載されていない場合、そのドメインの一部として表示されません。必ず相互確認してください。

ADR の文書化

ユーザーがアーキテクチャ上の決定について説明した場合：

1. adrs/{adr-id}/index.mdx を生成します
2. サポートされているステータスのいずれかを使用します：proposed、accepted、rejected、deprecated、superseded
3. YYYY-MM-DD 形式で date を含めます
4. 既存のチーム／ユーザー ID が分かっている場合は、decisionMakers と owners に設定します
5. appliesTo を使用して、影響を受けるリソース（system、service、event、domain、flow、data-product、entity など）に決定をリンクします
6. ADR 同士をリンクする場合は、supersedes、supersededBy、amends、amendedBy、または related を使用します
7. 本文を Context、Decision、Consequences で構成します

データプロダクトの文書化

ユーザーが分析、レポート、BI、ML 機能、または派生した運用データについて説明した場合：

1. data-products/{DataProductName}/index.mdx を生成するか、関連するドメイン／サブドメインの下に配置します
2. 上流のメッセージ、サービス、コンテナー、チャネル、その他のリソースを inputs に追加します
3. 生成されるメッセージ、サービス、コンテナー、チャネル、コントラクトを outputs に追加します
4. 出力にデータコントラクトがある場合は、contract.path、contract.name、contract.type を含めます
5. <NodeGraph /> と、コントラクトファイルに関連する <SchemaViewer /> を含めます
6. データリネージ、鮮度、所有権、アクセスパターン、SLA を文書化します

エンティティのドキュメント作成

ユーザーがプロパティを含むドメインモデル、集約、データオブジェクト、またはビジネス概念を説明した場合：

1. カタログの構造に応じて、entities/{EntityName}/index.mdx、domains/{Domain}/entities/{EntityName}/index.mdx、または services/{Service}/entities/{EntityName}/index.mdx を生成します
2. 該当する場合は、identifier と aggregateRoot: true を含めます
3. name、type、required、description を含む properties を追加します
4. 他のエンティティとの関係には、references、referencesIdentifier、relationType を使用します
5. プロパティテーブルを表示するために、本文に <EntityPropertiesTable /> を含めます
6. ドメイン／サービスのフロントマターで entities を使用して、エンティティにリンクします

図のドキュメント作成

ユーザーが再利用可能なアーキテクチャ図、シーケンス図、フロー図、またはモデル図を提供または要求した場合：

1. diagrams/{DiagramName}/index.mdx を生成するか、関連するドメイン／サブドメインの下に配置します
2. id、name、version、summary を含めます
3. 本文に mermaid、plantuml、またはその他のサポートされている図のブロックをフェンスで囲んで記述します
4. 関連リソースから、フロントマターの diagrams フィールドを使用して図を参照します

ビジネスフローのドキュメント作成

ユーザーが複数のステップからなるプロセスを説明した場合：

1. 個別のステップ（ユーザーの操作、サービス呼び出し、メッセージのやり取り、外部システム）を特定します
2. steps 配列を含むフローの index.mdx を生成します
3. 各ステップには id と、省略可能な title（デフォルトでは、参照先の名前が使用されます）を指定でき、リソースキーは最大1つ指定できます。リソースキーは message、service、agent、system、channel、flow、container、dataProduct、actor、custom、または externalSystem です。type は設定しないでください（無視されます）。各ステップの形式については references/flows.md を参照してください
4. 分岐には next_step または next_steps を使ってステップを接続します（1つのステップに両方を指定してはいけません）
5. ドキュメント化されているステップキーのみ使用できます。カスタムステップキーは x- で始める必要があります

チャネルルーティングのドキュメント作成

ユーザーがインフラストラクチャ内でのメッセージの流れを説明した場合：

1. チャネル間のルーティングを定義する routes を含むチャネルの index.mdx ファイルを生成します
2. サービスまたはエージェントの sends／receives を更新し、チャネルを指す to／from フィールドを設定します
3. 全体像として、次の流れを示します：サービスまたはエージェントが送信 → チャネル → 次のチャネルへルーティング → サービスまたはエージェントが受信

品質チェックリスト

• 時間をかけて、丁寧に作業してください
• 速さよりも品質を重視してください
• 検証手順を省略しないでください

ドキュメントをユーザーに渡す前に、各ファイルをこのチェックリストに照らして確認してください。

1. フロントマターが --- 区切りの間に有効な YAML で記述されている
2. id がフォルダー名と一致している
3. 未知のフロントマターキーがない — ドキュメント化されたフィールド、または x- を接頭辞とするカスタムフィールドのみを使用している
4. version が有効な semver 文字列である
5. summary が簡潔で意味のある内容である（汎用的な内容ではない）
6. メッセージの関係（sends／receives）に id が含まれている
7. チャネルのルーティング（to／from）が有効なチャネル ID を参照している
8. リソースにグラフの関係がある場合、本文に可視化用の <NodeGraph /> が含まれている
9. スキーマ参照が実在するファイルを指している
10. フォルダー構造がカタログの規約に従っている
11. 重複するリソースがない（既存のカタログと照合済み）
12. バージョン管理されたリソースでは index.mdx を使用している（またはカタログ内の既存の .md／.mdx の規約に従っている）。チームとユーザーでは {id}.mdx を使用し、変更履歴では changelog.mdx／changelog.md を使用している
13. すべてのドメインに少なくとも1つのシステム、サービス、またはエージェントがある — 空のドメインは作成しない
14. ドメインのフロントマターの systems、services、agents に、そのドメインに属する直接のシステム、サービス、エージェントがすべて列挙されている
15. ドメインのフロントマターの entities、data-products、flows、diagrams に、存在する場合はネストされたリソースが列挙されている
16. すべてのドメインに、サービス、エージェント、イベント、コマンド、エンティティ、データプロダクト、ビジネスプロセスから抽出した関連ドメイン用語を記載する ubiquitous-language.mdx ファイルがある
17. ADR に有効なステータス、日付、判明している場合は意思決定者、および影響を受けるリソースへの appliesTo 参照がある
18. システムの生成時に、システムの scope、関係のポインター、アクターの方向が有効である
19. 生成時に、outputs.contract.path で参照されるデータプロダクトのコントラクトファイルが存在する

トラブルシューティング

ビジュアライザーにメッセージが表示されない

生成されたイベント／コマンドがサービスまたはエージェントのノードグラフに表示されない場合：

• サービスまたはエージェントのフロントマターにある sends／receives 配列が、メッセージの正確な id を参照していることを確認してください
• メッセージに専用の index.mdx ファイルがあることを確認してください

スキーマが表示されない

<Schema /> または <SchemaViewer /> コンポーネントでエラーが表示される場合：

• フロントマターの schemaPath が、index.mdx と同じ場所にある実在のファイルを指していることを確認してください
• スキーマファイルが有効な JSON／Avro／Protobuf であることを確認してください

フォルダー構造が認識されない

EventCatalog にリソースが表示されない場合：

• ファイル名が正確に index.mdx または index.md であることを確認してください（INDEX.mdx や readme.md ではありません）
• 古いバージョンは {resource}/versioned/{version}/index.mdx に配置してください
• フォルダーが認識対象のコレクションディレクトリー（systems/、services/、agents/、events/、domains/ など）の中にあることを確認してください

システムコンテキスト図にアクターや関係が表示されない

<ContextDiagram /> に想定されるシステムコンテキストが表示されない場合：

• システムのフロントマターに relationships または actors があることを確認してください
• relationships が有効なシステム ID を指し、それぞれに label があることを確認してください（ラベルのない関係はエッジとして描画されません）
• アクターの direction が inbound または outbound であることを確認してください
• ドメインのコンテキスト図を表示する場合は、ドメインのフロントマターの systems が関連システムを参照していることを確認してください

Unknown property でビルドが失敗する

• フロントマターに、リソースのスキーマで定義されていないキーがあります。削除するか、スペルを修正するか、x- 接頭辞を付けて名前を変更してください

チャネルルーティングが表示されない

チャネル接続がビジュアライザーに表示されない場合：

• チャネルのフロントマターにある routes フィールドが有効なチャネル ID を参照していることを確認してください
• サービスまたはエージェントの sends／receives にある to／from フィールドが、有効なチャネル ID を参照していることを確認してください