event-modeling

イベントモデリング

価値： コミュニケーション — イベントモデリングは、コードを書く前に、隠れたドメイン知識を明らかにし、人間とエージェントの間に共通理解を築く、構造化された対話です。

目的

Martin Dilger の「Understanding Eventsourcing」の方法論に沿って、エージェントがイベントモデリングセッションを進行できるようにします。後続のすべての実装を支える、完全なイベントモデル（アクター、イベント、コマンド、読み取りモデル、自動化、スライス）を作成します。モデルは docs/event_model/ に保存されます。

プラクティス

2 段階のプロセス：発見してから設計する

幅広いドメインの理解を得る前に、詳細なワークフロー設計に進んではいけません。フェーズ 1 で全体像を把握し、フェーズ 2 で各領域を詳しく調べます。

フェーズ 1 — ドメインの発見。 ビジネスが何を行うか、アクターは誰か、主なプロセスは何か、どの外部システムと連携するか、どのワークフローをモデル化するかを特定します。これらの質問をユーザーに尋ね、回答を推測してはいけません。出力：docs/event_model/domain/overview.md。

フェーズ 2 — ワークフローの設計。 各ワークフローについて、9 ステップのプロセスに従います。完全な方法論については、必ず references/nine-steps.md に従ってください。ワークフローは一度に 1 つずつ設計します。次のワークフローを始める前に、9 ステップすべてを完了してください。出力：docs/event_model/workflows/<name>/overview.md と slices/ 内の個別のスライスファイル。

最優先の指針：情報を失わないこと

現在の状態だけでなく、何が起きたか（イベント）を保存します。イベントは、ビジネス用語で記述された不変の過去の事実です。読み取りモデルのすべてのフィールドは、イベントまでたどれる必要があります。フィールドのソースとなるイベントがない場合、モデルに何かが欠けています。

イベント設計ルール

1. イベントにはビジネス用語を使い、過去形で名前を付けます。PlaceOrder や CreateOrderDTO ではなく、OrderPlaced とします。
2. イベントは不変の事実です。変更したり削除したりしてはいけません。
3. 関連するデータを含めます。何が起きたか、いつ起きたか、誰または何が原因かを記録します。
4. 適切な粒度を見極めます。広すぎる DataUpdated でも、狭すぎる FieldXChanged でもいけません。
5. コマンドは、ユーザー入力とイベントストリームに依存し、読み取りモデルには依存しません。読み取りモデルはビューと自動化にのみ使用します。
6. イベントにはドメイン上の事実（どのマシンでも真である事実）を記録します。実行時コンテキスト（ファイルパス、ホスト名、PID、作業ディレクトリ）はイベントデータに含めません。

4 つのパターン

イベントソーシングを採用するすべてのシステムで、これらのパターンを使用します。各パターンは 1 つの垂直スライスに対応します。

1. 状態変更： コマンド -> イベント。状態を変更する唯一の方法です。1 回の操作で、コマンドが複数のイベントを生成する場合があります。
2. 状態ビュー： イベント -> 読み取りモデル。システムがクエリに応答する方法です。ドメインが並行する複数のインスタンスをサポートする場合、読み取りモデルのフィールドには単一の値ではなく、コレクション型を使用します。
   コマンドは、ユーザーが提供するデータとイベントストリームから入力を導出します。読み取りモデルから導出してはいけません。図に ReadModel → Command のエッジを含めてはいけません。コマンドが、何かがすでに起きたか（冪等性など）を確認する必要がある場合は、読み取りモデルではなくイベントストリームを確認します。
   読み取りモデルは、ドメイン上で意味のあるプロジェクションを表します。コマンドの実行コンテキストに暗黙的に含まれるインフラストラクチャの前提条件（「ディレクトリは存在するか？」「サービスは実行中か？」など）について、独自の読み取りモデルを用意する必要はありません。
3. 自動化： イベント -> 読み取りモデル（TODO リスト） -> プロセス -> コマンド -> イベント。イベントを契機に開始するバックグラウンド作業です。4 つの要素すべてが必要です。トリガーとなるイベント、参照する読み取りモデル、条件付きのプロセスロジック、結果として実行されるコマンドです。読み取りモデルも条件付きロジックもない場合、それは自動化ではなく、複数のイベントを生成するコマンドです。明確な終了条件が必要です。
4. 変換： 外部データ -> 内部イベント。ワークフロー固有の外部連携のための腐敗防止層です。すべてのワークフローで共有される汎用インフラストラクチャ（イベントの永続化、メッセージ転送など）は変換ではありません。イベントモデルの外部に置く、横断的なインフラストラクチャです。

スライスパターンごとに必要なレイヤー

各スライスパターンには、最小限必要なアーキテクチャレイヤーがあります。必要なレイヤーがすべて実装され、相互に接続されるまで、スライスは完成していません。

• 状態ビュー：インフラストラクチャ（ストアからイベント／データを読み取る）＋ドメイン（プロジェクション／クエリのロジック）＋プレゼンテーション（レンダリングする、または呼び出し元に結果を返す）＋アプリケーションの配線（レイヤーをエンドツーエンドで接続する）
• 状態変更：プレゼンテーション（ユーザー入力または外部リクエストを受け付ける）＋ドメイン（コマンドの検証とビジネスルール）＋インフラストラクチャ（結果のイベント／データを永続化する）＋アプリケーションの配線（レイヤーをエンドツーエンドで接続する）
• 自動化：インフラストラクチャ（トリガー条件を検出する ― タイマー、外部イベント、しきい値）＋ドメイン（ポリシー／意思決定のロジック）＋インフラストラクチャ（結果のアクションを実行する ― メッセージの送信、データの書き込み、サービスの呼び出し）＋アプリケーションの配線（トリガー、ポリシー、アクションを接続する）
• 変換：インフラストラクチャ（外部システムから受け取る）＋ドメイン（マッピング／変換のロジック）＋インフラストラクチャ（ターゲットシステムに渡す）＋アプリケーションの配線（インバウンドアダプター、マッパー、アウトバウンドアダプターを接続する）

スライスを分解する際は、受け入れ条件とタスクの内訳で、必要なレイヤーすべてがカバーされていることを確認してください。プレゼンテーションやインフラストラクチャなしにドメインロジックだけを実装するスライスは未完成です。これは垂直スライスではなく、コンポーネントです。

GWT シナリオ

ワークフローの設計後、各スライスについて Given/When/Then シナリオを作成します。 これらは実装の受け入れ条件になります。

コマンドのシナリオ： Given = 状態を確立する先行イベント。When = 具体的なデータを伴うコマンド。Then = 生成されたイベント、またはエラー（両方が発生することはありません）。

ビューのシナリオ： Given = 現在のプロジェクション状態。When = 新しいイベントが 1 つ発生する。Then = 結果のプロジェクション状態。ビューはイベントを拒否できません。

重要な違い： GWT シナリオでテストするのはビジネスルール（状態に依存するポリシー）であり、データ検証（型システムで扱う形式／構造のチェック）ではありません。型システムによって無効な状態を表現できないようにできる場合、それは GWT シナリオではありません。

シナリオの形式と例については、必ず references/gwt-template.md を使用してください。

アプリケーション境界の受け入れシナリオ

すべての垂直スライスには、アプリケーション境界で定義された GWT シナリオを少なくとも 1 つ含める必要があります。

• Given：システムが既知の状態にある（先行イベント、シードデータ、設定）
• When：ユーザー（または外部の呼び出し元）が、アプリケーションの外部インターフェースを通じて操作する ― 具体的なインターフェースはプロジェクトによって異なります（HTTP エンドポイント、CLI コマンド、メッセージキューコンシューマー、UI アクションなど）
• Then：同じ境界で結果を観測できる ― レスポンス、出力、レンダリングされた状態の変化、発行されたイベントなど

ユニットテストで内部関数を呼び出すだけで満たせる GWT シナリオは、ユニットレベルの仕様であり、スライスの受け入れ基準ではありません。スライスの受け入れ基準では、外部入力から観測可能な出力までの経路をテストする必要があります。

受け入れテスト戦略

アプリケーション境界をプログラムでテストできる場合（HTTP エンドポイント、CLI 出力の解析、ヘッドレスブラウザーの自動化、メッセージキューのアサーション、API コントラクトテストなど）は、外部入力から観測可能な出力まで、GWT シナリオ全体を実行する自動受け入れテストを作成してください。これらのテストは迅速なフィードバックをもたらし、スライスの動作を記した生きたドキュメントとして役立ちます。

自動化された境界テストが実行できない場合（複雑な GUI 操作、ハードウェアに依存する動作、視覚的／美的な検証）は、人が手動で確認すべき内容を文書化してください。具体的な手順と、期待される観測可能な結果を記載します。この手動確認チェックリストは、スライスの完了の定義の一部になります。

スライスの独立性

イベントスキーマを共有するスライスは独立しています。イベントスキーマが共有契約です。コマンドスライスでは生成されたイベントを検証し、ビュー スライスでは合成イベントフィクスチャを使ってテストします。どちらも、もう一方が先に実装されている必要はありません。スライス間に人為的な依存関係を作らないでください。

モデルの検証

GWT シナリオを作成した後、モデルの完全性を検証します。

1. すべての読み取りモデルのフィールドがイベントにひも付いている
2. すべてのイベントに、トリガーとなるコマンド、自動化、または変換がある
3. すべてのコマンドに、文書化された拒否条件（ビジネスルール）がある
4. すべての自動化に終了条件がある
5. GWT の Given／When／Then 句が、未定義の要素を参照していない

不足が見つかった場合は、ユーザーに確認し、不足している要素を作成してから再検証します。不足を残したまま先に進まないでください。

ファシリテーションの姿勢

あなたは書記ではなく、ファシリテーターです。踏み込んだ質問をしてください。前提に異議を唱えてください。イベント、コマンド、回答のたびに「その後、何が起こりますか？」と問い続けてください。専門用語ではなく、ビジネスの言葉を使ってください。イベントモデリング中は、データベース、API、フレームワーク、実装について話し合わないでください。例外は、必須のサードパーティ連携を名前と目的とともに記録する場合だけです。

実施すること：

• すべてのステップを順番どおりに進める。プロセスを通じて理解が深まります
• 「その後、何が起こりますか？」と粘り強く問い続ける
• すべての例とシナリオで、具体的で現実的なデータを使う
• 一度に1つのワークフローを設計する
• 先に進む前に、情報がすべてそろっていることを確認する
• 読み取りモデルのフィールドについて、「これが同時に複数存在することはありますか？」と尋ねる
• 自動化として扱う前に、4つの構成要素がすべてそろっていることを確認する

行わないこと：

• 十分に分かっていると思っても、ステップを飛ばさない
• モデリング中にアーキテクチャや実装に関する決定をしない
• データ検証の GWT シナリオを書かない（型システムを使う）
• 複数のワークフローを同時に設計しない
• モデルに不足があるまま先に進まない

強制に関する注記

• スタンドアロンモード：助言的です。エージェントは慣例として9ステップの方法論に従います。
• パイプラインモード：ゲートとして機能します。不完全なモデル（GWT シナリオの不足、自動化の未定義）があると、スライスの分解はブロックされます。

厳守事項：

• モデルに不足があるまま先に進まない：[RP]

制約

• 「MUST follow nine-steps.md」：9つのステップに従うとは、各ステップに固有の活動を実行し、固有の成果物を作成することです。リファレンスを読んで「精神に従った」と主張することではありません。各ステップで定められた成果物を作成してください。
• 「Do not design multiple workflows simultaneously」：これには、ワークフロー1のステップが完了していないうちに、ワークフロー2の「ディスカバリー」を始めることも含まれます。ディスカバリーも設計です。将来のワークフローについて情報を集めているなら、それを設計していることになります。
• ファシリテーションと書記の違い：ファシリテーションとは、ドメインの専門家がまだ言語化していないことを発見できるような質問をすることです。自分が望む回答へ誘導するような質問をすることではありません。判断基準は、専門家の回答に本当に驚く可能性があるかどうかです。そうでなければ、ファシリテーションではなく誘導です。

検証

イベントモデリング作業を完了したら、次の項目を検証します。

• ドメインの概要が docs/event_model/domain/overview.md にあり、アクター、ワークフロー、外部連携、および推奨される開始ワークフローが記載されている
• 設計した各ワークフローに docs/event_model/workflows/<name>/overview.md があり、9 つのステップがすべて完了している
• すべてのイベントが過去形で、ビジネス用語で記述された不変の事実である
• すべての読み取りモデルのフィールドがソースイベントまでたどれる
• すべてのイベントにトリガー（コマンド、自動化、またはトランスレーション）がある
• 自動化に 4 つの構成要素（イベント、読み取りモデル、条件ロジック、コマンド）がすべて含まれている
• ドメインで複数のインスタンスの同時存在が可能な場合、読み取りモデルのフィールドにコレクション型が使われている
• 横断的なインフラストラクチャがトランスレーションスライスとしてモデリングされていない
• 各スライスの GWT シナリオが、具体的なデータとともに docs/event_model/workflows/<name>/slices/*.md に（インラインで）記載されている
• GWT のエラーシナリオがデータ検証ではなく、ビジネスルールのみをテストしている
• イベントスキーマを共有するスライスが独立してテスト可能であり、人為的な依存関係の連鎖がない
• 検証後、モデルに未解決の問題が残っていない

いずれかの基準を満たしていない場合は、続行する前に該当するプラクティスを見直してください。

依存関係

このスキルは単独で動作します。ワークフローを強化するため、次のスキルと連携します。

• domain-modeling： イベントからドメイン型（Email、Money、OrderStatus）が明らかになり、ドメインモデリングスキルで詳細化します
• tdd： 各垂直スライスが 1 つの TDD サイクルに対応します
• architecture-decisions： イベントモデルがアーキテクチャに役立ちます。イベントモデリング中に ADR を作成しないでください
• task-management： ワークフローはエピックに、スライスはタスクに対応します

依存関係が見つかりませんか？次のコマンドでインストールしてください。

npx skills add jwilger/agent-skills --skill domain-modeling