event-driven-architect

イベント駆動型アーキテクト

永続性のあるイベント、明示的な契約、運用上安全なコンシューマーを中心に、非同期システムを設計します。

対象範囲： イベント駆動型アプリケーションのアーキテクチャと信頼性パターン。同期 API 設計（api-designer）やバッチ ETL パイプライン設計（data-pipeline-architect）は対象外です。

基本用語

用語	定義
イベント	発生した事象を記録した不変のレコード
コマンド	事実ではなく、アクションの実行を求めるリクエスト
トピック	関連するイベントを運ぶ、名前付きのストリームまたはチャネル
パーティションキー	イベントの一部について順序を維持するために使う値
コンシューマーグループ	同じトピックを処理する、独立したワーカーの集合
冪等性キー	処理の繰り返しを安全にするために使う、変わらない識別子
デッドレターキュー	通常の再試行回数を超えたメッセージを保管する領域
アウトボックス	データベースの変更をもとにイベントを公開するトランザクションパターン
サガ	イベントと補償処理を通じて調整される、複数ステップのワークフロー
契約バージョン	イベントスキーマの進化における互換性を示す指標

振り分け

$ARGUMENTS	モード
design <domain or workflow>	イベント駆動型アーキテクチャを設計する
review <architecture or code path>	既存のイベントフローを監査する
contract <event>	イベント契約を定義または進化させる
reliability <flow>	再試行、順序付け、復旧を設計する
migration <change>	イベントフローの導入または置き換えを計画する
キュー、ブローカー、非同期ワークフローに関する自然言語	最も近いモードを自動検出する
空	例を含むモードメニューを表示する

モードメニュー

#	モード	例
1	設計	design order fulfillment across payments, inventory, and shipping
2	レビュー	review event flow for user-created -> email sync
3	契約	contract invoice.paid
4	信頼性	reliability retry strategy for webhook ingestion
5	移行	migration move monolith side effects to events

使用する場面

• サービス間または境界づけられたコンテキスト間の非同期ワークフローを設計するとき
• イベント契約、パーティションキー、コンシューマーの責務を選定するとき
• アウトボックス、再試行、リプレイ、デッドレター処理を導入するとき
• イベントシステムの耐障害性や、過度な結合の有無をレビューするとき
• 同期的な副作用から永続性のあるイベントへの移行を計画するとき

分類ロジック

分類ゲート

1. タスクが同期 API 設計、リクエスト／レスポンス契約、または CRUD エンドポイントの構成である場合は、api-designer を使用してください。
2. タスクがバッチ ETL、データウェアハウスへのデータ移動、または分析を目的とした変換である場合は、data-pipeline-architect を使用してください。
3. タスクがブローカーのインストール、ベンダー固有の設定、またはプラットフォーム運用である場合は、該当するプラットフォームまたは devops のスキルを使用してください。
4. ワークフローが曖昧な場合は、まずシステムの中心が永続性のある事実、非同期の調整、リプレイに安全なコンシューマーのどれにあるかを分類してください。答えが「はい」の場合に限り、このスキルを使用してください。

段階的な情報開示

• SKILL.md は、振り分け、オペレーターの手順、譲れない制約に重点を置いてください。
• すべてを一度に読み込まず、指示に従って参照ファイルを読んでください。
• 何かをイベント、コマンド、同期呼び出しのどれにすべきかが主な論点となる場合は、references/event-vs-command.md を読み込んでください。
• タスクに再試行、リプレイ、順序付け、ポイズンメッセージ、デッドレター処理が含まれる場合は、references/failure-modes.md を読み込んでください。
• 振り分け、オーケストレーション、補償ワークフローのどれを選ぶか検討する場合は、references/saga-comparison.md を読み込んでください。
• アーキテクチャ、契約、信頼性、移行の出力を整形する場合は、references/output-templates.md を読み込んでください。

指示

モード：設計

1. イベントにすべきビジネス上の事実を特定します。過去形で名前を付けます。
2. 事実とコマンド、クエリを区別します。
3. 事実とコマンドの境界が不明確な場合は、references/event-vs-command.md を読みます。
4. 各イベントのプロデューサー、トピック、パーティションキー、コンシューマー、コントラクトを定義します。
5. 順序の要件と、順序が重要でない箇所を明確にします。
6. ワークフローが複数のサービスや補償アクションにまたがる場合は、references/saga-comparison.md を読みます。
7. 必要に応じて references/output-templates.md を使い、障害処理、リプレイ、可観測性を備えたアーキテクチャを作成します。

モード：レビュー

1. イベントカタログ、コードパス、またはアーキテクチャ図を読みます。
2. 隠れた同期結合、欠落した冪等性、弱いコントラクトの所有権、未定義のリプレイ動作がないか確認します。
3. イベントストリームがリクエスト・レスポンスのセマンティクスに誤用されている箇所を指摘します。
4. レビューが順序、リプレイ、再試行、コンシューマーの安全性に関わる場合は、references/failure-modes.md を読みます。
5. 重要度の高い順に指摘事項を提示します。

モード：コントラクト

1. 必須フィールド、プロデューサー、所有権、順序に関する期待、バージョニング戦略を定義します。
2. どのフィールドが識別子、ビジネス上の事実、メタデータなのかを明記します。
3. 追加による進化を優先し、コンシューマー向けに非推奨化の期間を文書化します。
4. 提案されたコントラクトが依然としてコマンドまたはクエリに見える場合は、references/event-vs-command.md を読みます。

モード：信頼性

1. references/failure-modes.md を読みます。
2. 再試行ポリシー、バックオフ、ポイズンメッセージの処理、デッドレターへのルーティングを設計します。
3. コンシューマーとハンドラーの冪等性戦略を指定します。
4. リプレイの安全性と運用担当者向けの制御を定義します。

モード：移行

1. 現在の同期的な副作用、またはレガシーなイベントフローをマッピングします。
2. 明示的なチェックポイントを設け、新しいイベント経路を導入します。
3. 移行のチェックポイントと切り替え方法については、references/output-templates.md を読みます。
4. 新しい経路の安定性が実証されるまで古い経路を維持し、ロールバックを簡単にします。

出力要件

• すべての設計で、プロデューサー、トピック、パーティションキー、コンシューマー、障害対応戦略を明示する必要があります。
• すべてのコントラクトで、所有権とバージョニングのルールを明記する必要があります。
• すべての信頼性計画に、冪等性とデッドレター処理を含める必要があります。

参照ファイル一覧

ファイル	読むタイミング
references/event-vs-command.md	イベントを発行するか、コマンドを送るか、同期呼び出しを維持するかが主な設計上の問いである場合
references/failure-modes.md	タスクが再試行、順序、リプレイ、ポイズンメッセージ、デッドレターキュー、またはコンシューマーの復旧に関わる場合
references/saga-comparison.md	サービス間でコレオグラフィー、オーケストレーション、補償サガの構造を選択する場合
references/output-templates.md	アーキテクチャ、コントラクト、信頼性、レビュー、または移行の出力を整形する場合

重要なルール

1. ビジネスイベントはコマンドではなく、過去形の事実としてモデル化します。
2. 再試行やリプレイが発生しうる場合、コンシューマーは冪等でなければなりません。
3. トランザクションを伴うデータベース変更からイベントを発行する場合は、アウトボックスパターンを使用します。
4. 即時整合性が必要な低レイテンシのリクエスト・レスポンス要件に、イベントバスを使用してはいけません。
5. 可能な限り、イベントコントラクトは追加によって進化させます。

スケーリング戦略

• 小規模：設計の範囲を絞ります。拡張する前に、最小限のイベントセット、1つの所有権境界、1つの信頼性戦略を定義します。
• 中規模：明確なコントラクトの所有権、パーティション戦略、リプレイルールを追加し、複数サービスにまたがるワークフローやバッチとイベントが混在するワークフローでは、サガの選択を明確にします。イベントという用語の陰に同期依存関係を隠さないでください。
• 大規模：境界づけられたコンテキストごとに、複数ドメインにまたがるプログラムと移行の順序を決めます。まず実証済みのイベント経路を1つ導入し、リプレイ、デッドレター処理、可観測性が運用担当者にとって安全になってから、コンシューマーの対象範囲と下流の自動化を拡張します。

対象範囲

対象： イベントコントラクト、トピック、サーガ、再試行、リプレイ、アウトボックス、コンシューマー設計。

対象外： 同期 REST または GraphQL API の設計、バッチ分析パイプライン、ブローカーのインストールに関する詳細。