code-to-catalog

コードをカタログに変換

ガイド付きの、根拠に基づくヒアリングを通じて、コードベースを EventCatalog のドキュメントに変換します。次の 2 つの状況に対応します。

1. カタログがまだない場合 — 未知または未文書化のコードベースを一から文書化します。
2. 既存のカタログがある場合 — カタログを現在のコードと照合し、新しいリソースの追加、差異の確認、古くなった項目の提示を行います。

このスキル自体はカタログファイルを作成しません。合意したアーキテクチャモデルを記録した計画ファイル（.catalog-plan.md）を作成し、実際のドキュメント生成は catalog-documentation-creator スキルに引き継ぎます。

このスキルの仕組み

このスキルは 6 つのフェーズで進みます。後のフェーズは前のフェーズに依存するため、順番に進めてください。

1. 場所の特定と棚卸し — コードディレクトリと既存のカタログを探します
2. 調査スキャン — コードを読み、仮説を立てます
3. 既存カタログとの照合 — 調査結果を new / update / unchanged / investigate に分類します
4. 段階的なヒアリング — 構造上の判断事項だけをユーザーに尋ねます
5. 計画ファイルの作成 — .catalog-plan.md を作成し、承認を得ます
6. 引き継ぎ — カタログを今すぐ生成するか、計画だけで終了するかを尋ねます

会話のスタイル（全体を通じて適用）

• 一度に質問は 1 つだけです。 質問をまとめて尋ねないでください。ユーザーが回答してから次に進みます。
• 必ず推奨回答を提示します。 各質問では、根拠（ファイルパスと行番号）とともに、正しいと思われる内容を示します。ユーザーはそれを確認、訂正、または変更できます。
• コードを根拠として示します。 調査結果を提示するときは、確認したファイルを示します。例：src/orders/events.ts:42。ユーザーがあなたを信頼するだけでなく、自分で確認できるようにします。
• 不確実性について正直に伝えます。 コードから何かがイベントかコマンドか判断できない場合は、その旨を伝えます。黙って推測しないでください。
• 矛盾を示し、勝手に決めません。 カタログとコードに食い違いがある場合は、ユーザーに判断を委ねます。確認なしに上書きしないでください。
• ユーザーの時間を尊重します。 ヒアリングは意図的に段階化されており、構造上の判断事項に限定されます。リソースごとの項目（概要、オーナー、スキーマ）について細かく尋ねないでください。
• カタログからリソースを削除しません。 カタログ内にあるもののコードから見つからないリソースには investigate のフラグを付け、自動で削除することはありません。

フェーズ 1：場所の特定と棚卸し

コードベースを探す

ユーザーに「分析するコードディレクトリはどれですか？」と尋ねます。

ディレクトリが存在し、コードプロジェクトと思われることを確認します（package.json、pom.xml、go.mod、Cargo.toml、pyproject.toml、ソースディレクトリなどがあること）。ディレクトリが曖昧な場合（例：モノレポ）は、リポジトリ全体を対象とするのか、特定のサブディレクトリを対象とするのか確認します。

カタログを探す

ユーザーに「すでに EventCatalog プロジェクトをお持ちですか？ それとも新規に始めますか？」と尋ねます。

すでにプロジェクトがある場合：

• パスを尋ねます。eventcatalog.config.js または標準ディレクトリ（services/、agents/、events/、commands/、queries/、domains/、systems/、channels/、containers/、flows/）を確認し、EventCatalog プロジェクトであることを検証します。
• 既存項目の一覧を作成します。EventCatalog MCP サーバーに接続されている場合は、getResources、getResource、findResourcesByOwner を使用します。それ以外の場合は、ファイルシステムを直接読み取り、各 index.md / index.mdx のフロントマターを解析します。
• 各リソースについて、id、name、version、type、summary、および（サービスとエージェントについては）sends / receives の関係を記録します。
• カタログの規約を記録します。入れ子構造（domains/X/systems/S/services/Y/events/Z）かフラット構造か、PascalCase か kebab-case の ID か、既存のオーナー、使用中のスキーマ形式などです。

カタログがない場合：

• 問題ありません。足場の作成は引き継ぎ時に catalog-documentation-creator を通じて行われることを記録します（このスキルは npx @eventcatalog/create-eventcatalog@latest <name> --empty を実行します）。
• フェーズ 3（照合）は何も行いません。検出された項目はすべて new になります。

フェーズ 2：検出スキャン

コードベースを読み、仮説を立てます。調査結果はまだユーザーに見せないでください。フェーズ 4 で、根拠を添えて質問として提示します。

言語／フレームワークごとの詳細な検出ヒューリスティック（Node.js、Python、Go、Java、.NET）については、references/discovery.md を参照してください。コードベースでガイダンスが必要なスタックが使われている場合は、今すぐこのファイルを読んでください。

以下を検出します。

プロジェクト構成

• モノレポか単一サービスか（ワークスペース設定を確認します。例：pnpm-workspace.yaml、workspaces を含む package.json、nx.json、turbo.json、lerna.json、独自のマニフェストを持つ複数のトップレベルサービスディレクトリ）。
• サービスまたはエージェントごとの言語とフレームワーク。
• ビルド／デプロイ単位（Dockerfile、Helm チャート、serverless.yml、cdk スタック、k8s マニフェスト）。

サービス境界

サービスとは、独立してデプロイおよび管理できる単位です。判断材料：

• 独自のマニフェストを持つ独立したパッケージ
• 独立した Dockerfile／デプロイ設定
• 独自のエントリーポイント（main.ts、main.go、app.py など）
• ネットワーク境界（HTTP、メッセージバス）を介して他のサービスから利用される

判断に迷う場合は、候補として記録し、フェーズ 4 でユーザーに詳しく確認してください。

システム（候補）

システムは、1 つのプロダクトまたはプラットフォームを構成するサービス、エージェント、データストアをまとめたものです（ドメイン内で L1 図に示されるものです）。判断材料：

• 複数のサービスをまとめてデプロイするリポジトリ、モノレポのアプリグループ、Helm アンブレラチャート／CDK アプリ
• 複数のサービスで使われるプロダクト名（billing-api、billing-worker、billing-db → Billing システム）
• サービス群だけで共有されるデータストア

通常、単一サービスのコードベースにシステムは必要ありません。候補を記録し、トピック 1 で確認してください。

外部システム

コードから呼び出されるサードパーティ API と SaaS（Stripe、Twilio、Salesforce、SendGrid — SDK のインポート、ベース URL、API キーの環境変数など）。これらは、内部システムが関連付けられる外部システム（scope: external を持つ systems）になります。ユーザーが希望する場合は、代わりにサードパーティを externalSystem: true を持つサービスとして扱うこともできます。メッセージやコンテナとしてモデル化しないでください。

エージェント境界

エージェントとは、推論、ツールの呼び出し、意思決定の自動化を行う、AI／LLM を活用したランタイムまたはワーカーです。判断材料：

• 明示的な名前：LLM／ツールのオーケストレーションを行う *Agent、*Assistant、*Copilot、*Worker
• LLM SDK の使用：OpenAI、Anthropic、Gemini、Vercel AI SDK、LangChain、LlamaIndex、Mastra、CrewAI、AutoGen
• ツールレジストリまたは呼び出し可能なツール：MCP クライアント／サーバー、tools、function_call、tool_choice、executeTool
• エージェントフレームワーク：Agent、createAgent、runAgent、LLM を使うグラフ／ワークフローのノード
• エージェントが使用するメモリ／状態ストア：ベクトル DB、Redis、Postgres、Supabase、Pinecone、Qdrant、Chroma

LLM を一度呼び出すだけの一般的なサービスを、エージェントに分類しないでください。永続的なアシスタント／ワーカーの境界、ツールセット、モデルポリシー、メモリ、または自律的なワークフローをコードが管理している場合に、エージェントとして扱ってください。

メッセージ（イベント、コマンド、クエリ）

候補は次の場所から見つかります。

• 命名パターン — *Created、*Placed、*Updated、*Deleted（イベントの可能性が高い）；Place*、Create*、Cancel*、Process*（コマンドの可能性が高い）；Get*、Find*、List*（クエリの可能性が高い）。
• メッセージバスのクライアント — Kafka（kafkajs、confluent-kafka、sarama）、RabbitMQ（amqplib、pika）、NATS、AWS SNS/SQS/EventBridge、GCP PubSub、Azure Service Bus。
• スキーマファイル — JSON Schema（.schema.json）、Avro（.avsc）、Protobuf（.proto）。これらはメッセージコントラクトを示す強いシグナルです。
• DTO / 型定義 — 特にペイロードのような形式（フラットでデータのみを含み、ドメインイベントにちなんだ名前）のもの。

証拠に基づいて、各候補をイベント、コマンド、またはクエリに分類します。

• イベント：過去形で、トピック／エクスチェンジに発行され、複数のコンシューマーが存在する可能性があり、直接の応答は想定されません。
• コマンド：命令形で、特定のハンドラーに送信され、処理されることを想定します。
• クエリ：読み取り専用で、応答を想定します。

証拠が曖昧な場合（よくあることです）は、不確実とマークし、フェーズ 4 で詳しく確認してください。何も言わずに選択してはいけません。

チャネル

名前付きインフラストラクチャを介してメッセージが流れる箇所はすべて対象です。

• Kafka トピック（producer.send({ topic: '...' }) に渡される文字列リテラル）
• RabbitMQ のキュー／エクスチェンジ
• SNS トピック、SQS キュー（キューは常にチャネルであり、コンテナではありません）
• クエリサービスの HTTP エンドポイント（GET /users/:id）

ドメイン（候補）

強いシグナル：

• 最上位フォルダーによるグループ化（src/orders/、src/payments/、src/shipping/）
• README やモジュールドキュメントにある境界づけられたコンテキストの手がかり
• パッケージの名前空間（com.company.orders.*）
• 所有権ファイル（CODEOWNERS、.codeowners）

確信度が低いドメインは推測しないでください。不明な場合は、「単一ドメイン = コードベース全体」を提案し、フェーズ 4 でユーザーに分割してもらいます。

コンテナ（データストア）

設定、環境変数、またはクライアントのインスタンス化で参照されるデータベース、キャッシュ、ストアです。それぞれに container_type が必要です。値は database、cache、objectStore、searchIndex、dataWarehouse、dataLake、externalSaaS、other のいずれかで、エンジンは technology に指定します。

• Postgres / MySQL / SQLite / Mongo / DynamoDB / Cassandra → database
• Redis / Memcached → cache
• S3 バケット、GCS バケット → objectStore
• Elasticsearch / OpenSearch → searchIndex；Snowflake / BigQuery / Redshift → dataWarehouse

キューとトピックはコンテナではなく、チャネルです。

フェーズ 2 の出力

内部ドラフトマップ：

domains:
  - name: <candidate>
    confidence: high|medium|low
    systems: [...]
    services: [...]
    agents: [...]
systems:
  - name: <candidate>
    scope: internal|external
    services: [...]
    containers: [...]
    relationships: [<other system>: <label>]
services:
  - name: <candidate>
    path: <dir>
    sends: [...]
    receives: [...]
    channels: [...]
    containers: [...]
agents:
  - name: <candidate>
    path: <dir>
    model: <provider/name/version if found>
    tools: [...]
    sends: [...]
    receives: [...]
    channels: [...]
    containers: [...]
    flows: [...]
messages:
  - name: <candidate>
    classification: event|command|query|uncertain
    evidence: <file:line>
    producer: <service or agent>
    consumer: <service, agent, or unknown>
channels: [...]
containers:
  - name: <candidate>
    container_type: database|cache|objectStore|...
    technology: <postgres, redis, ...>

このマップは内部に保持してください。フェーズ 3 とフェーズ 4 の進行に使用します。

フェーズ 3：既存のカタログとの照合

既存のカタログがない場合は、このフェーズをスキップしてください。検出されたものはすべて new です。

ドラフトマップの各項目について、カタログのインベントリから一致するリソースを探します（一致判定は ID、次に名前、次に名前と種類によるあいまい一致の順に行います）。ステータスを割り当てます。

ステータス	意味
unchanged	リソースがカタログに存在し、コード内の内容と一致しています。ユーザーへの確認は不要です。
update	リソースはカタログに存在しますが、コードとの間に乖離があります。新しいメッセージの送信、フィールド名の変更、スキーマの変更、送受信関係の追加などが該当します。
new	コード内で見つかりましたが、カタログには存在しません。新しいリソースの候補です。
investigate	カタログには存在しますが、コード内では見つかりません。古くなっている、削除された、または別のリポジトリにある可能性があります。削除は決してせず、提示するだけにしてください。

update 項目については、具体的に何が変わったかを記録します。

• カタログ内の OrderService は [OrderPlaced] を送信し、コードでは OrderCancelled も送信しています → 乖離：新しい送信。
• PaymentService のスキーマフィールド名が amount_cents → amountCents に変更されています → 乖離：スキーマの変更。
• カタログ内の OrderSupportAgent にはツールがありませんが、コードでは orderLookup と zendeskNotes の MCP ツールが定義されています → 乖離：新しいツール。

この分類に基づいてフェーズ 4 を進めます。確認するのは update、曖昧な new、および investigate 項目のみです。unchanged リソースについては何も伝えません。

フェーズ 4：段階的な確認

構造上の判断だけを詳しく確認します。 リソースごとの詳細（概要テキスト、オーナー名、スキーマフィールド、バッジのスタイル）は対象外です。これらは catalog-documentation-creator が処理します。

推奨回答テンプレートを含む質問集全体については、references/grilling.md を参照してください。今すぐ読んでください。

以下の順序でトピックを進めます。依存関係は下位に向かっているため、後のトピックに進む前に、先行するトピックを解決してください。

トピック 1：ドメインと境界

サービスの配置はドメインによって決まるため、まずドメインのグループ分けについて質問します。

• 明確なドメイン候補を検出した場合：各候補と、推奨するシステム、サービス、エージェントを提示し、ユーザーに確認を求めます。
• 検出できなかった場合：「コードベース全体を単一のドメインにする」案を提示し、分割するかどうかを尋ねます。
• 曖昧なサービスやエージェントについては（「OrderSupportAgent は Orders に属しますか、それとも独自の Support ドメインに属しますか？」など）、詳しく確認します。
• 次に、各ドメイン内のシステムのグループ分けを確認します（「billing-api、billing-worker、billing-db は一緒にデプロイされます。Billing システムとしてまとめますか？」）。また、どのサードパーティを外部システムにするかも確認します。

トピック 2：サービスの境界

• 各サービス候補を確認します。根拠（パス、エントリーポイント、Dockerfile）を提示します。
• 曖昧なケース（「このモジュールは独立したサービスにも、別のサービスの一部にもなり得ます」など）は、推奨回答とともに詳しく確認します。
• モノレポの例外的なケースにも対応します。共有 lib/ パッケージはサービスでしょうか？（おそらく違います。これはインフラストラクチャです。）

トピック 3：エージェントの境界

• 各エージェント候補を確認します。根拠（LLM SDK の使用、モデル設定、ツールレジストリ、MCP ツール、メモリストア、エントリーポイント）を提示します。
• 曖昧なケース（「このサービスは LLM を 1 回呼び出します。LLM 統合を備えたサービスにするべきですか、それとも独立したエージェントにするべきですか？」など）は、推奨回答とともに詳しく確認します。
• モデル／プロバイダー名とツール名は根拠として記録しますが、すべてのプロンプトや低レベルのツールパラメーターについて逐一確認するのは避けます。

トピック 4：メッセージの分類

これは最も誤りが起きやすい判断です。念入りに確認してください。

検出時に uncertain とマークされたメッセージごとに、次のように確認します。

src/orders/handlers.ts:18 に OrderReceived が見つかりました。キューから消費され、返信経路もないため、イベントとして分類するのがよさそうです。よろしいですか？

確信度の高い分類のメッセージについては、まとめて簡単に確認できるよう提示します。

過去形の命名と pub/sub パターンに基づき、以下をイベントとして特定しました：OrderPlaced、OrderCancelled、PaymentProcessed。再分類したいものはありますか？

トピック 5：差分の調整（既存のカタログがある場合のみ）

update 項目ごとに、次のように確認します。

カタログには、PaymentService が [PaymentProcessed] を送信すると記載されています。コードでは src/payments/refund.ts:24 で PaymentRefunded も出力しています。サービスの送信メッセージに PaymentRefunded を追加しますか？追加するのがよさそうです。

investigate 項目ごとに、次のように確認します。

カタログには LegacyPaymentConfirmed（イベント、v0.0.3）がありますが、コード内では見つかりませんでした。別のリポジトリにあるか、削除されている可能性があります。計画では investigate としてフラグを付けます。後でユーザーが判断できます。それでよろしいですか？

削除を提案してはいけません。該当項目を提示するだけにしてください。

詳細に確認しない項目

• 各リソースの概要テキスト
• オーナー／チームの割り当て（CODEOWNERS から検出され、曖昧な場合を除く）
• エージェントのプロンプトの文言や低レベルのツールパラメーター
• スキーマのフィールドレベルの詳細
• バッジ、視覚的なカスタマイズ
• フロー図（これは flow-wizard の担当です）

これらは適切なデフォルト値とともに catalog-documentation-creator に引き継がれます。

質問疲れに注意

確認に時間がかかっている場合（たとえば質問が約 15 件を超える場合）：

• 進捗を要約します：「ここまでに合意した内容はこちらです。ドメインは X、Y、サービスは A、B、C、分類済みメッセージは 12 件です。」
• 計画ファイルの作成時点で一時中断することを提案します：「ここで止めて計画を書き、詳細は後から再開できます。」

フェーズ 5：計画ファイルを作成する

計画を .catalog-plan.md に書き込みます。デフォルトの場所はコードディレクトリのルートです。別の場所にしたいかどうか、ユーザーに尋ねてください。

次の正確な構成を使用します。

# Catalog Plan

**Generated:** YYYY-MM-DD
**Codebase:** /absolute/path/to/repo
**Existing catalog:** /absolute/path/to/catalog (or "none — will be created")

## Summary
<1–2 paragraph narrative of what was found and the agreed architectural model>

## Domains
- **Orders** (status: new)
  - Systems: OrderManagement
  - Agents: OrderSupportAgent
  - Rationale: both deal with the order lifecycle; confirmed with user

- **Payments** (status: unchanged)
  - Services: PaymentService

## Systems
- **OrderManagement** (internal, status: new)
  - Domain: Orders
  - Services: OrderService, ShippingService
  - Containers: orders-db
  - Relationships: Stripe ("charges cards via")

- **Stripe** (external, status: new) — called from /services/orders/payments.ts

## Services
### OrderService (status: new)
- Domain: Orders
- System: OrderManagement
- Path in code: /services/orders
- Receives: PlaceOrder (command)
- Sends: OrderPlaced (event), OrderCancelled (event)
- Channels: orders.commands, orders.events
- Containers: orders-db (database, postgres)

### PaymentService (status: update)
- Domain: Payments
- Path in code: /services/payments
- Drift: code emits new PaymentRefunded event not in catalog
- Sends (after update): PaymentProcessed, PaymentRefunded

## Agents
### OrderSupportAgent (status: new)
- Domain: Orders
- Path in code: /agents/order-support
- Model: OpenAI / gpt-4.1-mini
- Tools: order-lookup (mcp), support-case-notes (mcp)
- Receives: OrderConfirmed, OrderCancelled
- Reads from: orders-db
- Flows: PlaceOrderFlow

### FraudReviewAgent (status: update)
- Domain: Payments
- Path in code: /agents/fraud-review
- Drift: code added fraud-case-queue MCP tool not in catalog
- Receives (after update): PaymentInitiated, RiskScoreCalculated, FraudDetected

## Messages
- **OrderPlaced** (event, status: new) — emitted by OrderService via orders.events
- **OrderCancelled** (event, status: new) — emitted by OrderService via orders.events
- **PlaceOrder** (command, status: new) — handled by OrderService
- **PaymentRefunded** (event, status: new) — emitted by PaymentService
- **LegacyPaymentConfirmed** (event, status: investigate) — in catalog, not found in code

## Channels
- orders.events (Kafka topic, status: new)
- orders.commands (Kafka topic, status: new)

## Containers
- orders-db (database, technology: postgres, status: new) — used by OrderService

## Open decisions / rationale
- Classified `CancelOrder` as a command (user confirmed — it expects a handler)
- Kept Shipping as a sub-area of Orders rather than splitting (user preference)
- Flagged `LegacyPaymentConfirmed` for manual review — may live in a different repo

## Next step
Run `catalog-documentation-creator` with this plan to generate resources marked `new` or `update`.

ステータス値（次の値をそのまま使用します）：new、update、unchanged、investigate。

書き込み後、計画をユーザーに提示し、明示的な承認を求めます：「こちらが計画です。合意した内容と一致していますか？進める前に、追加、変更、削除する点はありますか？」

ユーザーが承認するまで、編集を繰り返します。

フェーズ 6：引き継ぎ

計画が承認されたら、次のように尋ねます。

「今すぐカタログを生成しますか、それとも計画のみで終了しますか？」

今すぐ生成する場合：

• catalog-documentation-creator スキルを呼び出し、計画ファイルのパスを渡します。
• new または update のステータスが付いたリソースのみを作成／更新するよう指示します。unchanged はスキップします。investigate 項目は自動で処理せず、一覧にしてユーザーに報告します。
• ユーザーに既存のカタログがない場合、catalog-documentation-creator が先にカタログのひな形を作成します。

ここで終了する場合：

• 計画ファイルの場所を確認します。
• 再開方法をユーザーに伝えます：「準備ができたら、catalog-documentation-creator を実行し、この計画ファイルを指定してください。new と update のリソースが生成されます。」

引き継ぎ後

次の内容をユーザーに伝えます。

• 計画の保存場所。
• （生成した場合）作成／更新したリソース。
• 手動で確認が必要な investigate 項目。
• カタログ全体のビジネスフローを文書化する場合は、次に flow-wizard を実行できること。

品質チェックリスト

完了前に、次の点を確認します。

1. 計画ファイルが合意したパスに存在する。
2. すべてのドメイン、システム、サービス、エージェント、メッセージ、チャネル、コンテナに、new／update／unchanged／investigate のいずれかのステータスが付いている。
3. update の項目ごとに、具体的にどのような差異が生じたかが記載されている。
4. すべての investigate 項目にフラグが付いており、削除されていない。
5. メッセージの分類（イベント／コマンド／クエリ）がユーザーによって確認されているか、根拠を示して明確に推奨されている。
6. すべてのサービスとエージェントについて、サービスからドメイン（またはシステム）へのマッピングと、エージェントからドメインへのマッピングが明示されている。
7. リソースごとに細かく質問していない（概要、担当者、スキーマについては catalog-documentation-creator の担当です）。
8. 引き継ぐ場合、catalog-documentation-creator に計画のパスと、unchanged をスキップする指示が渡されている。