cqrs

CQRS — クイックリファレンス

CQRS（Command Query Responsibility Segregation）は、書き込み操作と読み取り操作を別々のモデルに分離します。デフォルトで採用するものではありません。複雑さに見合う価値がある場合に有効化する最適化です。

使用する場面

適している	適していない
不変条件に関する豊富なルールを持つ複雑なビジネスドメイン	シンプルな CRUD、ドメインが単純
読み取り／書き込み比率 > 10×	小規模プロジェクト、経験の浅いチーム
監査／コンプライアンス（Event Sourcing と自然に組み合わせられる）	即時整合性が必要
多様な読み取りモデル（モバイル、分析、バックオフィスなど）	安定した単一のデータモデル
読み取りと書き込みで異なるスケーリング（レプリカ、キャッシュ、検索）	負荷が低い、小規模なモノリス

黄金律： まずは従来型のアーキテクチャから始めます。適しているケースが少なくとも2つ同時に当てはまる場合に、CQRS へ移行します。

30秒でわかるアーキテクチャ

[ User ]
   ↓
[ Command ]──────────▶ [ Write Model (Domain) ]
                              ↓ persist + emit
                       [ Event(s) ]
                              ↓
[ Query ] ◀───── [ Read Model (denormalised) ] ◀── projections

• Command side：正規化されたモデルで、ビジネス上の不変条件を重視します。書き込みを行い、検証に必要な情報だけを読み取ります。
• Query side：非正規化されたモデルで、読み取り性能を重視します。ビジネスロジックは持ちません。
• プロジェクション：イベントを読み取りモデルに変換します。結果整合性があります。

中心となるトレードオフ

メリット	コスト
読み取りと書き込みを個別にスケーリング	結果整合性（一般的なレイテンシは約50～500 ms）
各ニーズに合わせた読み取りモデル	保守するコードが増える（モデルが2つ）
Event Sourcing を簡単に組み込める	デバッグが複雑になる（イベントフロー）
自然な監査証跡	後からの移行は非常にコストがかかる

関連パターン（併用されることが多い）

• Event Sourcing：イベントの連続を真実の源として保存し、書き込みモデルをリプレイで再構築します。
• Saga / Process Manager：イベントを介して分散トランザクションをオーケストレーションします。
• Outbox Pattern：イベントの発行と DB 書き込みの原子性を保証します。
• Materialized Views：クエリを高速化するため、専用テーブルにプロジェクションを永続化します。

重大なアンチパターン

• ❌ 明確なユースケースのない CQRS → 過剰設計、認知負荷の二重化。
• ❌ ビジネスルールを実行する読み取りモデル → プロジェクションのたびに不変条件のバグが発生します。
• ❌ 同期プロジェクション → スケーラビリティのメリットが失われます。
• ❌ スナップショットのない Event Sourcing → 起動時に数百万件のイベントをリプレイすることになります。
• ❌ 完全なデータを返すコマンド → クエリを装ったものです。

詳しく知る

Symfony / Laravel / .NET の実装、Event Sourcing（Prooph、EventStoreDB）、Saga パターン、Outbox、具体例、CRUD から CQRS への段階的な移行、フェーズごとのチェックリストについては、@.claude/skills/cqrs/REFERENCE.md を参照してください。