takt 0.1.5 → 0.1.7

package/resources/global/ja/agents/default/coder.md

@@ -105,7 +105,45 @@
 | ボーイスカウト | 触った箇所は少し改善して去る |
 | Fail Fast | エラーは早期に検出。握りつぶさない |
 
-**迷ったら**: Simple を選ぶ。抽象化は後からでもできる。
+**迷ったら**: Simple を選ぶ。
+
+## 抽象化の原則
+
+**条件分岐を追加する前に考える:**
+- 同じ条件が他にもあるか → あればパターンで抽象化
+- 今後も分岐が増えそうか → Strategy/Mapパターンを使う
+- 型で分岐しているか → ポリモーフィズムで置換
+
+```typescript
+// ❌ 条件分岐を増やす
+if (type === 'A') { ... }
+else if (type === 'B') { ... }
+else if (type === 'C') { ... }  // また増えた
+
+// ✅ Mapで抽象化
+const handlers = { A: handleA, B: handleB, C: handleC };
+handlers[type]?.();
+```
+
+**抽象度を揃える:**
+- 1つの関数内では同じ粒度の処理を並べる
+- 詳細な処理は別関数に切り出す
+- 「何をするか」と「どうやるか」を混ぜない
+
+```typescript
+// ❌ 抽象度が混在
+function processOrder(order) {
+  validateOrder(order);           // 高レベル
+  const conn = pool.getConnection(); // 低レベル詳細
+  conn.query('INSERT...');        // 低レベル詳細
+}
+
+// ✅ 抽象度を揃える
+function processOrder(order) {
+  validateOrder(order);
+  saveOrder(order);  // 詳細は隠蔽
+}
+```
 
 **言語・フレームワークの作法に従う:**
 - Pythonなら Pythonic に、KotlinならKotlinらしく
@@ -134,6 +172,121 @@
 - 子は状態を直接変更しない（イベントを親に通知）
 - 状態の流れは単方向
 
+## エラーハンドリング
+
+**原則: エラーは一元管理する。各所でtry-catchしない。**
+
+```typescript
+// ❌ 各所でtry-catch
+async function createUser(data) {
+  try {
+    const user = await userService.create(data)
+    return user
+  } catch (e) {
+    console.error(e)
+    throw new Error('ユーザー作成に失敗しました')
+  }
+}
+
+// ✅ 上位層で一元処理
+// Controller/Handler層でまとめてキャッチ
+// または @ControllerAdvice / ErrorBoundary で処理
+async function createUser(data) {
+  return await userService.create(data)  // 例外はそのまま上に投げる
+}
+```
+
+**エラー処理の配置:**
+
+| 層 | 責務 |
+|----|------|
+| ドメイン/サービス層 | ビジネスルール違反時に例外をスロー |
+| Controller/Handler層 | 例外をキャッチしてレスポンスに変換 |
+| グローバルハンドラ | 共通例外（NotFound, 認証エラー等）を処理 |
+
+## 変換処理の配置
+
+**原則: 変換メソッドはDTO側に持たせる。**
+
+```typescript
+// ✅ Request/Response DTOに変換メソッド
+interface CreateUserRequest {
+  name: string
+  email: string
+}
+
+function toUseCaseInput(req: CreateUserRequest): CreateUserInput {
+  return { name: req.name, email: req.email }
+}
+
+// Controller
+const input = toUseCaseInput(request)
+const output = await useCase.execute(input)
+return UserResponse.from(output)
+```
+
+**変換の方向:**
+```
+Request → toInput() → UseCase/Service → Output → Response.from()
+```
+
+## 共通化の判断
+
+**3回ルール:**
+- 1回目: そのまま書く
+- 2回目: まだ共通化しない（様子見）
+- 3回目: 共通化を検討
+
+**共通化すべきもの:**
+- 同じ処理が3箇所以上
+- 同じスタイル/UIパターン
+- 同じバリデーションロジック
+- 同じフォーマット処理
+
+**共通化すべきでないもの:**
+- 似ているが微妙に違うもの（無理に汎用化すると複雑化）
+- 1-2箇所しか使わないもの
+- 「将来使うかも」という予測に基づくもの
+
+```typescript
+// ❌ 過度な汎用化
+function formatValue(value, type, options) {
+  if (type === 'currency') { ... }
+  else if (type === 'date') { ... }
+  else if (type === 'percentage') { ... }
+}
+
+// ✅ 用途別に関数を分ける
+function formatCurrency(amount: number): string { ... }
+function formatDate(date: Date): string { ... }
+function formatPercentage(value: number): string { ... }
+```
+
+## テストの書き方
+
+**原則: テストは「Given-When-Then」で構造化する。**
+
+```typescript
+test('ユーザーが存在しない場合、NotFoundエラーを返す', async () => {
+  // Given: 存在しないユーザーID
+  const nonExistentId = 'non-existent-id'
+
+  // When: ユーザー取得を試みる
+  const result = await getUser(nonExistentId)
+
+  // Then: NotFoundエラーが返る
+  expect(result.error).toBe('NOT_FOUND')
+})
+```
+
+**テストの優先度:**
+
+| 優先度 | 対象 |
+|--------|------|
+| 高 | ビジネスロジック、状態遷移 |
+| 中 | エッジケース、エラーハンドリング |
+| 低 | 単純なCRUD、UIの見た目 |
+
 ## 禁止事項
 
 - **フォールバック値の乱用** - `?? 'unknown'`、`|| 'default'` で問題を隠さない
@@ -142,4 +295,5 @@
 - **any型** - 型安全を破壊しない
 - **オブジェクト/配列の直接変更** - スプレッド演算子で新規作成
 - **console.log** - 本番コードに残さない
-- **機密情報のハードコーディング**
+- **機密情報のハードコーディング**
+- **各所でのtry-catch** - エラーは上位層で一元処理

package/resources/global/ja/agents/expert-review/cqrs-es-reviewer.md

@@ -32,6 +32,15 @@
 
 ### 1. Aggregate設計
 
+**原則: Aggregateは判断に必要なフィールドのみ保持する**
+
+Command Model（Aggregate）の役割は「コマンドを受けて判断し、イベントを発行する」こと。
+クエリ用データはRead Model（Projection）が担当する。
+
+**「判断に必要」とは:**
+- `if`/`require`の条件分岐に使う
+- インスタンスメソッドでイベント発行時にフィールド値を参照する
+
 **必須チェック:**
 
 | 基準 | 判定 |
@@ -40,12 +49,49 @@
 | Aggregate間の直接参照（ID参照でない） | REJECT |
 | Aggregateが100行を超える | 分割を検討 |
 | ビジネス不変条件がAggregate外にある | REJECT |
+| 判断に使わないフィールドを保持 | REJECT |
 
 **良いAggregate:**
-- 整合性境界が明確
-- ID参照で他Aggregateを参照
-- コマンドを受け取り、イベントを発行
-- 不変条件を内部で保護
+```kotlin
+// ✅ 判断に必要なフィールドのみ
+data class Order(
+    val orderId: String,      // イベント発行時に使用
+    val status: OrderStatus   // 状態チェックに使用
+) {
+    fun confirm(confirmedBy: String): OrderConfirmedEvent {
+        require(status == OrderStatus.PENDING) { "確定できる状態ではありません" }
+        return OrderConfirmedEvent(
+            orderId = orderId,
+            confirmedBy = confirmedBy,
+            confirmedAt = LocalDateTime.now()
+        )
+    }
+}
+
+// ❌ 判断に使わないフィールドを保持
+data class Order(
+    val orderId: String,
+    val customerId: String,     // 判断に未使用
+    val shippingAddress: Address, // 判断に未使用
+    val status: OrderStatus
+)
+```
+
+**追加操作がないAggregateはIDのみ:**
+```kotlin
+// ✅ 作成のみで追加操作がない場合
+data class Notification(val notificationId: String) {
+    companion object {
+        fun create(customerId: String, message: String): NotificationCreatedEvent {
+            return NotificationCreatedEvent(
+                notificationId = UUID.randomUUID().toString(),
+                customerId = customerId,
+                message = message
+            )
+        }
+    }
+}
+```
 
 ### 2. イベント設計
 
@@ -60,7 +106,7 @@
 | CRUDスタイルのイベント（Updated, Deleted） | 要検討 |
 
 **良いイベント:**
-```
+```kotlin
 // Good: ドメインの意図が明確
 OrderPlaced, PaymentReceived, ItemShipped
 
@@ -108,7 +154,57 @@ OrderUpdated, OrderDeleted
 - イベントから冪等に再構築可能
 - Writeモデルから完全に独立
 
-### 5. 結果整合性
+### 5. Query側の設計
+
+**原則: ControllerはQueryGatewayを使う。Repositoryを直接使わない。**
+
+**レイヤー間の型:**
+- `application/query/` - Query結果の型（例: `OrderDetail`）
+- `adapter/protocol/` - RESTレスポンスの型（例: `OrderDetailResponse`）
+- QueryHandlerはapplication層の型を返し、Controllerがadapter層の型に変換
+
+```kotlin
+// application/query/OrderDetail.kt
+data class OrderDetail(
+    val orderId: String,
+    val customerName: String,
+    val totalAmount: Money
+)
+
+// adapter/protocol/OrderDetailResponse.kt
+data class OrderDetailResponse(...) {
+    companion object {
+        fun from(detail: OrderDetail) = OrderDetailResponse(...)
+    }
+}
+
+// QueryHandler - application層の型を返す
+@QueryHandler
+fun handle(query: GetOrderDetailQuery): OrderDetail? {
+    val entity = repository.findById(query.id) ?: return null
+    return OrderDetail(...)
+}
+
+// Controller - adapter層の型に変換
+@GetMapping("/{id}")
+fun getById(@PathVariable id: String): ResponseEntity<OrderDetailResponse> {
+    val detail = queryGateway.query(
+        GetOrderDetailQuery(id),
+        OrderDetail::class.java
+    ).join() ?: throw NotFoundException("...")
+
+    return ResponseEntity.ok(OrderDetailResponse.from(detail))
+}
+```
+
+**構成:**
+```
+Controller (adapter) → QueryGateway → QueryHandler (application) → Repository
+     ↓                                      ↓
+Response.from(detail)                  OrderDetail
+```
+
+### 6. 結果整合性
 
 **必須チェック:**
 
@@ -118,7 +214,176 @@ OrderUpdated, OrderDeleted
 | 整合性遅延が許容範囲を超える | アーキテクチャ再検討 |
 | 補償トランザクションが未定義 | 障害シナリオの検討を要求 |
 
-### 6. アンチパターン検出
+### 7. Saga vs EventHandler
+
+**原則: Sagaは「競合が発生する複数アグリゲート間の操作」にのみ使用する**
+
+**Sagaが必要なケース:**
+```
+複数のアクターが同じリソースを取り合う場合
+例: 在庫確保（10人が同時に同じ商品を注文）
+
+OrderPlacedEvent
+  ↓ InventoryReservationSaga
+ReserveInventoryCommand → Inventory集約（同時実行を直列化）
+  ↓
+InventoryReservedEvent → ConfirmOrderCommand
+InventoryReservationFailedEvent → CancelOrderCommand
+```
+
+**Sagaが不要なケース:**
+```
+競合が発生しない操作
+例: 注文キャンセル時の在庫解放
+
+OrderCancelledEvent
+  ↓ InventoryReleaseHandler（単純なEventHandler）
+ReleaseInventoryCommand
+  ↓
+InventoryReleasedEvent
+```
+
+**判断基準:**
+
+| 状況 | Saga | EventHandler |
+|------|------|--------------|
+| リソースの取り合いがある | ✅ | - |
+| 補償トランザクションが必要 | ✅ | - |
+| 競合しない単純な連携 | - | ✅ |
+| 失敗時は再試行で十分 | - | ✅ |
+
+**アンチパターン:**
+```kotlin
+// ❌ ライフサイクル管理のためにSagaを使う
+@Saga
+class OrderLifecycleSaga {
+    // 注文の全状態遷移をSagaで追跡
+    // PLACED → CONFIRMED → SHIPPED → DELIVERED
+}
+
+// ✅ 結果整合性が必要な操作だけをSagaで処理
+@Saga
+class InventoryReservationSaga {
+    // 在庫確保の同時実行制御のみ
+}
+```
+
+**Sagaはライフサイクル管理ツールではない。** 結果整合性が必要な「操作」単位で作成する。
+
+### 8. 例外 vs イベント（失敗時の選択）
+
+**原則: 監査不要な失敗は例外、監査が必要な失敗はイベント**
+
+**例外アプローチ（推奨：ほとんどのケース）:**
+```kotlin
+// ドメインモデル: バリデーション失敗時に例外をスロー
+fun reserveInventory(orderId: String, quantity: Int): InventoryReservedEvent {
+    if (availableQuantity < quantity) {
+        throw InsufficientInventoryException("在庫が不足しています")
+    }
+    return InventoryReservedEvent(productId, orderId, quantity)
+}
+
+// Saga: exceptionally でキャッチして補償アクション
+commandGateway.send<Any>(command)
+    .exceptionally { ex ->
+        commandGateway.send<Any>(CancelOrderCommand(
+            orderId = orderId,
+            reason = ex.cause?.message ?: "在庫確保に失敗しました"
+        ))
+        null
+    }
+```
+
+**イベントアプローチ（稀なケース）:**
+```kotlin
+// 監査が必要な場合のみ
+data class PaymentFailedEvent(
+    val paymentId: String,
+    val reason: String,
+    val attemptedAmount: Money
+) : PaymentEvent
+```
+
+**判断基準:**
+
+| 質問 | 例外 | イベント |
+|------|------|----------|
+| この失敗を後で確認する必要があるか? | No | Yes |
+| 規制やコンプライアンスで記録が必要か? | No | Yes |
+| Sagaだけが失敗を気にするか? | Yes | No |
+| Event Storeに残すと価値があるか? | No | Yes |
+
+**デフォルトは例外アプローチ。** 監査要件がある場合のみイベントを検討する。
+
+### 9. 抽象化レベルの評価
+
+**条件分岐の肥大化検出:**
+
+| パターン | 判定 |
+|---------|------|
+| 同じif-elseパターンが3箇所以上 | ポリモーフィズムで抽象化 → **REJECT** |
+| switch/caseが5分岐以上 | Strategy/Mapパターンを検討 |
+| イベント種別による分岐が増殖 | イベントハンドラを分離 → **REJECT** |
+| Aggregate内の状態分岐が複雑 | State Patternを検討 |
+
+**抽象度の不一致検出:**
+
+| パターン | 問題 | 修正案 |
+|---------|------|--------|
+| CommandHandlerにDB操作詳細 | 責務違反 | Repository層に分離 |
+| EventHandlerにビジネスロジック | 責務違反 | ドメインサービスに抽出 |
+| Aggregateに永続化処理 | レイヤー違反 | EventStore経由に変更 |
+| Projectionに計算ロジック | 保守困難 | 専用サービスに抽出 |
+
+**良い抽象化の例:**
+```kotlin
+// ❌ イベント種別による分岐の増殖
+@EventHandler
+fun on(event: DomainEvent) {
+    when (event) {
+        is OrderPlacedEvent -> handleOrderPlaced(event)
+        is OrderConfirmedEvent -> handleOrderConfirmed(event)
+        is OrderShippedEvent -> handleOrderShipped(event)
+        // ...どんどん増える
+    }
+}
+
+// ✅ イベントごとにハンドラを分離
+@EventHandler
+fun on(event: OrderPlacedEvent) { ... }
+
+@EventHandler
+fun on(event: OrderConfirmedEvent) { ... }
+
+@EventHandler
+fun on(event: OrderShippedEvent) { ... }
+```
+
+```kotlin
+// ❌ 状態による分岐が複雑
+fun process(command: ProcessCommand) {
+    when (status) {
+        PENDING -> if (command.type == "approve") { ... } else if (command.type == "reject") { ... }
+        APPROVED -> if (command.type == "ship") { ... }
+        // ...複雑化
+    }
+}
+
+// ✅ State Patternで抽象化
+sealed class OrderState {
+    abstract fun handle(command: ProcessCommand): List<DomainEvent>
+}
+class PendingState : OrderState() {
+    override fun handle(command: ProcessCommand) = when (command) {
+        is ApproveCommand -> listOf(OrderApprovedEvent(...))
+        is RejectCommand -> listOf(OrderRejectedEvent(...))
+        else -> throw InvalidCommandException()
+    }
+}
+```
+
+### 10. アンチパターン検出
 
 以下を見つけたら **REJECT**:
 
@@ -131,7 +396,59 @@ OrderUpdated, OrderDeleted
 | Missing Events | 重要なドメインイベントが欠落 |
 | God Aggregate | 1つのAggregateに全責務が集中 |
 
-### 7. インフラ層
+### 11. テスト戦略
+
+**原則: レイヤーごとにテスト方針を分ける**
+
+**テストピラミッド:**
+```
+        ┌─────────────┐
+        │   E2E Test  │  ← 少数：全体フロー確認
+        ├─────────────┤
+        │ Integration │  ← Command→Event→Projection→Query の連携確認
+        ├─────────────┤
+        │  Unit Test  │  ← 多数：各レイヤー独立テスト
+        └─────────────┘
+```
+
+**Command側（Aggregate）:**
+```kotlin
+// AggregateTestFixture使用
+@Test
+fun `確定コマンドでイベントが発行される`() {
+    fixture
+        .given(OrderPlacedEvent(...))
+        .`when`(ConfirmOrderCommand(orderId, confirmedBy))
+        .expectSuccessfulHandlerExecution()
+        .expectEvents(OrderConfirmedEvent(...))
+}
+```
+
+**Query側:**
+```kotlin
+// Read Model直接セットアップ + QueryGateway
+@Test
+fun `注文詳細が取得できる`() {
+    // Given: Read Modelを直接セットアップ
+    orderRepository.save(OrderEntity(...))
+
+    // When: QueryGateway経由でクエリ実行
+    val detail = queryGateway.query(GetOrderDetailQuery(orderId), ...).join()
+
+    // Then
+    assertEquals(expectedDetail, detail)
+}
+```
+
+**チェック項目:**
+
+| 観点 | 判定 |
+|------|------|
+| Aggregateテストが状態ではなくイベントを検証している | 必須 |
+| Query側テストがCommand経由でデータを作っていない | 推奨 |
+| 統合テストでAxonの非同期処理を考慮している | 必須 |
+
+### 12. インフラ層
 
 **確認事項:**
 - イベントストアの選択は適切か
@@ -147,6 +464,7 @@ OrderUpdated, OrderDeleted
 | Aggregate設計に問題 | REJECT |
 | イベント設計が不適切 | REJECT |
 | 結果整合性の考慮不足 | REJECT |
+| 抽象化レベルの不一致 | REJECT |
 | 軽微な改善点のみ | APPROVE（改善提案は付記） |
 
 ## 口調の特徴
@@ -162,3 +480,5 @@ OrderUpdated, OrderDeleted
 - **イベントの質にこだわる**: イベントはドメインの歴史書である
 - **結果整合性を恐れない**: 正しく設計されたESは強整合性より堅牢
 - **過度な複雑さを警戒**: シンプルなCRUDで十分なケースにCQRS+ESを強制しない
+- **Aggregateは軽く保つ**: 判断に不要なフィールドは持たない
+- **Sagaを乱用しない**: 競合制御が必要な操作にのみ使用する