flow-wizard

Flow Documentation Wizard

EventCatalog でビジネスフローをドキュメント化するための、対話形式のスキルです。既存のカタログリソースを相互参照しながら、ステップごと、セクションごとにユーザーを案内します。

手順

Step 1: ユーザーのカタログを見つける

まず最初に、既存のリソースを相互参照できるよう、ユーザーの EventCatalog プロジェクトを見つける必要があります。

次のように尋ねます。「参照できる EventCatalog プロジェクトはありますか？ある場合は、どこにありますか？」

• パスが提示された場合は、eventcatalog.config.js または既知のディレクトリ（services/、agents/、events/、domains/、systems/、flows/）を確認し、EventCatalog プロジェクトであることを検証します。
• EventCatalog MCP サーバーが接続されている場合は、getResources を使ってカタログに何があるかを確認します。
• ない場合も問題ありません。リソースへの参照は付けずに、プレーンテキストの説明として各ステップをドキュメント化します。有用なフローは作成でき、後からリソースへのリンクを追加できることを伝えます。

見つかったら、カタログをスキャンして既存リソースの一覧を作成します。

• 既存のサービス、エージェント、イベント、コマンド、クエリ、ドメイン、システム、チャネル、コンテナー（データストア）、データプロダクト、フローを読み込みます。
• ID、名前、バージョンを記録します。ユーザーがフローを説明する際に、一致する候補を提案するために使用します。

Step 2: ドキュメント化するフローを尋ねる

次のように尋ねます。「どのフローをドキュメント化しますか？記録したいエンドツーエンドのプロセスを説明してください。」

ユーザー自身の言葉でフローを説明してもらいます。例：

• 「ユーザーが登録し、ウェルカムメールを受け取り、CRM に追加される」
• 「注文が行われ、支払いが処理され、在庫が確保され、注文が発送される」
• 「顧客がサポートチケットを送信し、トリアージされ、エージェントに割り当てられて、解決される」
• 「サポートエージェントが注文イベントを受け取り、注文のコンテキストを確認して、サポートケースを更新する」

説明をもとに、フローをセクション（大まかな段階）に分解します。これらのセクションをユーザーに提示し、確認してもらいます。

回答例：

ご説明から、だいたい次のようなセクションが考えられます。

1. ユーザー登録 — ユーザーが登録する
2. ウェルカムコミュニケーション — ウェルカムメールが送信される
3. CRM 連携 — ユーザーが CRM に追加される

これでよさそうですか？各セクションを詳しく確認していきます。セクションの追加、削除、並べ替えも自由に行えます。

先に進む前に、確認を待ちます。

Step 3: 各セクションを順に確認する

各セクションを一度に1つずつ進めます。各セクションで、何が起きるのかをユーザーに説明してもらいます。会話はユーザー主導とし、こちらはそれに沿って進めます。

各セクションでは、次のように尋ねます。

「まずは［セクション名］から始めましょう。ここでは何が起きますか？何が、または誰がきっかけとなり、その結果どうなりますか？」

ユーザーが何が起きるかを説明する際には、次のことを行います。

A. ステップの種類を特定する

説明から、このセクションにどの種類のステップが含まれるかを判断します。各ステップは次のいずれか1つです（正確な形式については references/flows.md を参照してください）。

• Actor — 人または役割が何かを行います（例：「ユーザーがサインアップをクリックする」、「管理者が承認する」）
• Service — アーキテクチャ内のサービスが何かを処理します（例：「認証サービスが登録を処理する」）
• Agent — AI エージェントが推論したり、ツールを呼び出したり、プロセスの一部を自動化したりします（例：「返金エージェントがケースを確認する」）
• Message — イベント、コマンド、またはクエリがやり取りされます（例：「UserRegistered イベントが発行される」）
• Channel — メッセージがどこを通るかを示します。重要な場合に使用します（例：「注文用の Kafka トピックに送信される」）
• System — システム全体が関与します。内部システムでも外部システムでもかまいません（例：「請求プラットフォームが処理する」）
• Container — データストアからデータを読み取る、または書き込みます（例：「注文データベースに保存する」）
• Data product — 分析用のデータプロダクトが作成または利用されます
• Sub-flow — プロセスが別の文書化されたフローに引き継がれます（例：「その後、返金フローが開始する」）
• External System — カタログに含まれていないサードパーティーシステムです（例：「支払いに Stripe を呼び出す」、「Twilio が SMS を送信する」）
• Custom — 図にする価値のあるその他のものです（手動レビュー、UI、スケジュール済みジョブなど）
• Plain step — 何も指し示さない、タイトル付きのボックスです（例：「キャンセルが拒否される」）

1つのセクションから複数のステップが生じる場合があります（例：ユーザーの操作がコマンドをトリガーし、そのコマンドがサービスによって処理され、サービスがイベントを発行する）。1つのステップが同時に2つの種類になることはありません。「サービスがイベントを発行する」は2つのステップです。

B. カタログとの相互参照

ユーザーが説明する各ステップについて、EventCatalog（利用可能な場合）を検索し、一致するリソースを探します。

1. サービス — ユーザーが言及したサービスはカタログにありますか？名前、ID、または類似語で検索します。
2. エージェント — ユーザーが言及した AI エージェント、アシスタント、コパイロット、自律型ワーカーはカタログにありますか？
3. イベント／コマンド／クエリ — ユーザーが説明したメッセージは、すでに文書化されているものと一致しますか？完全一致と類似するものを探します（例：ユーザーが「order created event」と言った場合、OrderCreated、OrderPlaced などを検索します）。
4. チャネル — このメッセージの流れに関連するチャネルはありますか？
5. システム — 文書化されたシステム（scope: external を持つ Stripe などの外部システムを含む）ですか？該当する場合は、externalSystem よりも system ステップを優先します。
6. コンテナー／データプロダクト — ユーザーが言及したデータストアまたはデータプロダクトは文書化されていますか？
7. ドメイン — このステップは文書化されたドメインに属していますか？

一致するものが見つかった場合は、ユーザーに伝えます。

カタログに一致すると思われる、[ResourceName] という**[リソースの種類]**（バージョン [version]）が見つかりました。このステップで参照しますか？

ユーザーが「はい」と答えた場合は、フローステップでリソースの実際の id と version を使用します。

候補が複数見つかった場合は、それらを提示してユーザーに選んでもらいます。

説明された内容に一致しそうなリソースがいくつか見つかりました。

• OrderCreated（イベント、v1.0.0）—「新しい注文が発生したときに送信されます」
• OrderPlaced（イベント、v0.0.1）—「チェックアウトの完了時に公開されます」

どちらが適切ですか？それとも、これは新しいものですか？

一致するものが見つからない場合でも問題ありません。ただし、存在しないリソースを指し示してはいけません。存在しないものを指す service、agent、message、channel、system、container、dataProduct、flow はリンターで失敗します（デフォルトではエラーの refs/resource-exists）。どちらを希望するか、ユーザーに尋ねます。

• 先にリソースを作成する — catalog-documentation-creator スキルを使って文書化してから、そのステップで参照します。実際に存在するサービス、エージェント、メッセージに適しています。
• ポインターを使わずに説明する — タイトル付きの通常のステップ（id + title + summary）、またはアイコン付きの custom ステップを使用します。まだ文書化したくないものに適しています。
• 人物／役割の場合は、actor を使用します。
• カタログにないサードパーティ製ツール／API の場合は、externalSystem を使用します。

ユーザーには次のように伝えます。「これはカタログに見つかりませんでした。ひとまず［作成する／通常のステップとして説明する］ことにします。後でリソース全体を文書化して、このステップから参照できます。」

C. 次に進む前に各セクションを確認する

セクションの処理後、そのセクションについて把握した内容を要約し、次に進む前にユーザーに確認を求めます。

例：

Payment Processing について、次のように把握しました。

1. ProcessPayment コマンドを送信（既存の ProcessPayment コマンド v0.0.1 と一致）
2. PaymentService が支払いを処理（既存の PaymentService v1.2.0 と一致）
3. FraudReviewAgent が不正利用の兆候を確認（既存の FraudReviewAgent v0.0.1 と一致）
4. カードへの請求のために Stripe（外部システム）を呼び出す
5. PaymentProcessed イベントを送信（まだカタログにありません。先に作成しますか、それともひとまず通常のステップとして説明しますか？）

この内容で合っていますか？追加や変更はありますか？

ステップ 4：分岐と例外ケースを扱う

各セクションを確認しながら、次の点に注意してください。

• 分岐するパス — 「支払いが成功したら続行し、失敗したらユーザーに通知します」

  • 確認する質問：「ここに判断ポイントがあるようです。考えられるパスを教えてください」
  • 各分岐にラベルを付け、これらを next_steps（複数形）として記録します

• ループ — 「外部呼び出しが失敗した場合、サービスは再試行します」

  • 前のステップを next_step で参照するステップとして記録します

• エラー／失敗のパス — 「検証に失敗した場合、エラーを返します」

  • 終端ステップにするか、通知／エラー処理のステップに分岐させます

• 並列パス — 「支払いを処理する間に、在庫も確保します」

  • 共通のステップから next_steps を使って別々の分岐として記録します

分岐を検出した場合は、ユーザーにパスを明確に確認します。

「ここで分岐があるようです。[ステップ] の後に、次のことが起こる可能性があります。

1. [成功パス] → [次のセクション] に進む
2. [失敗パス] → [発生すること]

この理解で合っていますか？ほかにも結果はありますか？」

ステップ 5：フローの概要を作成する

すべてのセクションを確認したら、ファイルを生成する前に、フロー全体の概要を提示します。

フロー全体はこちらです：[フロー名]

1. [ステップ 1 の概要] → [ステップ 2]
2. [ステップ 2 の概要] → [ステップ 3]
3. [ステップ 3 の概要] → [ステップ 4a] または [ステップ 4b] に分岐 ...

カタログ内で一致したリソース： [一致したリソースの一覧] 新しいリソース（まだカタログにありません）： [一致しなかった項目の一覧]

フローファイルを生成してもよろしいですか？

ステップ 6：フローファイルを生成する

ユーザーの確認後、references/flows.md の形式に従って、フローの index.mdx ファイルを生成します。

生成時のルール：

1. ユーザーのカタログディレクトリを使用します。保存先が不明な場合は、カタログの構成に応じて flows/{FlowName}/index.mdx、domains/{Domain}/flows/{FlowName}/index.mdx、またはシステム配下の systems/{System}/flows/{FlowName}/index.mdx のどこに保存するかを尋ねます。フローがドメインまたはシステムに属する場合は、そのドメインまたはシステムの flows フロントマターにも追加します。フォルダーに置くだけでは、ドメインやシステムとの関連付けにはなりません。

2. 一致したリソース（カタログ内で見つかったもの）には、カタログの正確な id と version を使用します。title は省略可能です。省略するとリソース名が既定値になるため、別のラベルのほうが適切な場合にのみ設定します。

   - id: "payment_processing"
     service:
       id: "PaymentService"
       version: "1.2.0"
   

   エージェントのステップには agent フィールドを使用します。

   - id: "fraud_review"
     agent:
       id: "FraudReviewAgent"
       version: "0.0.1"
   

   チャネル、システム、コンテナー、データプロダクト、サブフローのステップには、channel、system、container、dataProduct、flow の下で同じ { id, version } 形式を使用します。

3. まだ作成しないことをユーザーが選択した一致しないリソースには、通常のステップ（ポインターなし）または custom ステップを記述します。

   - id: "send_welcome_email"
     title: "Send Welcome Email"
     summary: "WelcomeEmailRequested is sent (not documented yet)"
   

4. アクターには、ロール名またはペルソナ名を使用します。

   - id: "user_initiates_signup"
     title: "User Signs Up"
     actor:
       name: "Customer"
   

5. 外部システムには、判明している場合、名前、概要、URL を記載します。

   - id: "stripe_charges_card"
     title: "Stripe Payment"
     externalSystem:
       name: "Stripe"
       summary: "Third-party payment processor"
       url: "https://stripe.com"
   

6. すべてのステップを、適切に next_step または next_steps で接続します。

7. 終端ステップ（フローの終わり、または分岐の終わり）には、next_step を設定しません。

8. 本文は <NodeGraph /> にします。

   ステップに type フィールドを追加しないでください（無視されます）。カスタムのステップメタデータは x- キーに記述してください。未定義のキーがあるとビルドに失敗します。

9. 新しいフローの version は 0.0.1 に設定します。

10. エンドツーエンドのビジネスプロセスを説明する、内容のある summary を記述します。

ステップ 7：検証して書き込む

ファイルを書き込む前に、次のことを確認します。

1. フロー内のすべてのステップ ID が一意であること
2. すべての next_step / next_steps の参照先が有効なステップ ID であり、各ステップに両方が指定されていないこと
3. すべてのポインターが、カタログ内のリソース ID（バージョンが設定されている場合はそのバージョンも）と一致すること
4. どのステップも 2 つの項目を指しておらず、不明なキーがないこと（カスタムキーは x- で始まる必要があります）
5. YAML フロントマターが有効であること
6. <NodeGraph /> が本文に含まれていること

ファイルをユーザーのカタログディレクトリに書き込みます。カタログに lint スクリプトがある場合（create-eventcatalog で作成されたカタログでは eventcatalog-linter が実行されます）、npm run lint を実行し、報告された問題を修正します。

書き込み後、ユーザーに次のことを伝えます。

• ファイルの保存場所
• カタログ内で一致したリソース
• 新しいリソース、または一致しなかったリソース — 後で catalog-documentation-creator スキルを使ってドキュメント化できることを提案します。特に新しいエージェントがある場合は、その旨を伝えます
• 開発サーバーを起動すれば EventCatalog でフローのビジュアライゼーションを表示でき、フローページからドメイン、システム、チーム別にグループ化できること（または <Flow id="..." lanes="team" /> を使ってチーム別にグループ化して開けること）

会話のガイドライン

• ユーザーが主導します。 質問して案内しますが、何が起きるかはユーザー自身の言葉で説明してもらいます。ステップを推測したり、作り上げたりしないでください。
• 一度に 1 つのセクションを扱います。 先へ急がず、次に進む前に各セクションを確認します。
• 一致する項目があれば役立つ提案をします。 カタログ内で一致するリソースを見つけたら、積極的に提案します。ただし、決定は必ずユーザーに委ねます。
• 見つからない場合は正直に伝えます。 カタログ内に一致するものがなければ、そのことを明確に伝え、内容を説明する形で記述します。
• 会話らしさを保ちます。 これは入力フォームではなく、ガイド付きのやり取りです。自然に応答します。
• 指示ではなく提案をします。 ユーザーの説明がステップタイプにぴったり当てはまらない場合は、適切だと思うタイプを提案し、それでよいか尋ねます。
• 複雑さにうまく対応します。 フローが複雑になった場合（分岐やループが多い場合など）は、定期的に要約して整理を助けます。

カタログの検索

一致するリソースを探すときは、次の方法を使います。

1. ID の完全一致 — 言及された名前をそのまま検索します（例：「OrdersService」→ OrdersService を検索）
2. あいまい一致 — 表記のバリエーションを検索します（例：「orders service」→ OrdersService、OrderService、orders-service を試す）
3. 意味的な一致 — ユーザーが「支払いを処理するもの」と言った場合、名前や概要に「payment」が含まれるサービスを検索します
4. タイプ別の検索 — イベントだとわかっている場合は、イベントに絞って検索します
5. エージェント関連の用語 — ユーザーが「assistant」、「copilot」、「worker」、「reviewer」、「agent」と言った場合は、外部システムとして扱う前に agents/ を検索します

EventCatalog MCP サーバーが利用可能な場合：

• getResources を使ってすべてのリソースを一覧表示します
• getResource を使って特定のリソースの詳細を取得します
• findResourcesByOwner を使ってチームごとにリソースを調べます

ファイルシステムを直接読み取る場合：

• services/、agents/、events/、commands/、queries/、domains/、systems/、flows/、channels/、containers/、data-products/ ディレクトリを確認します（これらはドメインやシステムの下にネストされている場合もあります）
• index.mdx ファイルを読み、id、name、version、summary フィールドを確認します

品質チェックリスト

フローファイルを提出する前に、次の項目を確認してください。

1. すべてのステップに一意の id がある
2. すべてのステップに明確なラベルがある — title を指定するか、わかりやすいリソース名のポインターを指定します（title はデフォルトでその名前になります）
3. すべてのステップが要素を1つだけ持っている（actor、service、agent、message、channel、system、container、dataProduct、flow、custom、externalSystem のいずれか）。また、type フィールドがない
4. すべての next_step と next_steps の参照が、フロー内の有効なステップ ID を指している
5. 孤立したステップがない（分岐を除き、すべてのステップが最初のステップから到達可能である）
6. すべてのポインターがカタログ内のリソースに一致している（プレースホルダーは使用しないでください。refs/resource-exists でエラーになります）
7. フローに明確な開始点（最初のステップ）と、少なくとも1つの終端ステップ（next_step がないステップ）がある
8. YAML フロントマターが --- 区切りで有効である
9. ファイル名が index.mdx である
10. 本文に <NodeGraph /> がある
11. version が有効な semver 文字列である
12. summary がビジネスプロセスの意味を具体的に説明している