Microservices Pattern Architect

目的と使用時期

トリガー条件:

分散トランザクションが2PC/XAなしで複数のマイクロサービスにまたがる
高スケールシナリオで読み取り/書き込み最適化が必要 (CQRS)
監査証跡、時間軸クエリ、またはイベントリプレイ要件 (Event Sourcing)
サービス間通信がフォールトトレランスとグレースフルデグラデーションを必要とする
複数のクライアント種別がプロトコル変換を伴う統一API エントリポイントを必要とする
クラウドネイティブまたはコンテナ環境での動的サービスインスタンス検出
モノリスからマイクロサービスへの移行にパターンガイダンスが必要
複雑なシナリオで複数パターンの構成が必要
既存のマイクロサービスアーキテクチャがアンチパターンまたはパフォーマンス問題を示している

向かない用途:

シングルサービスアプリケーションまたは真のモノリス (より単純なパターンを使用)
補償ロジック許容度なしの ACID トランザクション要件
補償ロジックなしの強い一貫性要件 (パターンは結果整合性に焦点)
明確なサービス境界のないグリーンフィールドプロジェクト (まずドメインを定義)
インフラストラクチャ関連のみ (cloud-native-deployment-orchestrator を使用)

事前チェック

時刻の正規化:

NIST/time.gov セマンティクス (America/New_York、ISO-8601) を使用して NOW_ET を計算: 2025-10-25T21:30:36-04:00
すべての引用アクセス日付に NOW_ET を使用

入力検証:

scenario は分散トランザクション、データ整合性、フォールトトレランス、API コンポジション、サービス検出、またはそれらの組み合わせのいずれかである必要があります
architecture_context は以下を説明する必要があります: 既存サービス、通信パターン、データストア
deployment_tier は T1 または T2 である必要があります
指定された場合、framework_preference は spring-boot、nodejs、.net、go、または python である必要があります
提供された場合、scalability_requirements は少なくとも1つの SLO メトリクスを含む必要があります

ソース鮮度:

Microservices.io Patterns (2025-10-25T21:30:36-04:00 アクセス): https://microservices.io/patterns/index.html - Chris Richardson のパターンカタログ、2025年更新
Martin Fowler Microservices Guide (2025-10-25T21:30:36-04:00 アクセス): https://martinfowler.com/microservices/ - 基本原則とパターン
Microsoft Azure Microservices Patterns (2025-10-25T21:30:36-04:00 アクセス): https://learn.microsoft.com/en-us/azure/architecture/microservices/design/patterns - 2025年9月更新
Saga Pattern Reference (2025-10-25T21:30:36-04:00 アクセス): https://microservices.io/patterns/data/saga.html - choreography と orchestration ガイダンス
Event Sourcing Pattern (2025-10-25T21:30:36-04:00 アクセス): https://microservices.io/patterns/data/event-sourcing.html - イベントストア設計原則
Circuit Breaker Pattern (2025-10-25T21:30:36-04:00 アクセス): https://microservices.io/patterns/reliability/circuit-breaker.html - フォールトトレランスメカニズム

中止条件:

architecture_context が不足しているか不明瞭な場合、データフロー付きサービスインベントリを要求します
シナリオが補償許容度なしで強力な ACID 保証を必要とする場合、モノリスまたは分散データベースを推奨します
明確なサービス境界が存在しない場合、まず architecture-decision-framework スキルを呼び出します

手順

T1: パターン推奨事項 (≤2k トークン)

ステップ 1: シナリオ分析

scenario をパースして主な関心事を特定: トランザクション、整合性、復元力、ルーティング、または検出
シナリオをパターンファミリーにマップ:
- 分散トランザクション → Saga (choreography または orchestration)
- データ整合性 + スケール → CQRS (オプションで Event Sourcing)
- 監査/リプレイ/時間軸 → Event Sourcing (CQRS 付き)
- フォールトトレランス → Circuit Breaker (Bulkhead と Timeout 付き)
- API 統合 → API Gateway (BFF バリアント付き)
- サービス検出 → Service Discovery (クライアント側またはサーバー側)

ステップ 2: クイックパターン選択

Saga: マルチサービストランザクションで補償アクションが許容可能な場合
- Choreography を選択: 疎結合、イベント駆動アーキテクチャを優先
- Orchestration を選択: 集中管理、複雑なワークフロー、デバッグが容易
CQRS: 読み取り/書き込みワークロードが大幅に異なる場合 (>10 倍のスケール差)
- Event Sourcing を追加: 監査証跡または時間軸クエリが必要
Circuit Breaker: 信頼性の低い依存関係へのサービス呼び出し (外部 API、レガシーサービス)
- 設定: 障害閾値 (例: 10 秒間に 50% エラー)、タイムアウト (例: 2 秒)、ハーフオープンリトライ
API Gateway: 複数のクライアント種別 (Web、モバイル、IoT) または横断的関心事 (認証、レート制限)
- BFF バリアントを使用: クライアント固有の最適化が必要
Service Discovery: 動的サービスインスタンス (Kubernetes、AWS ECS、サービスメッシュ)
- クライアント側 (Ribbon、Eureka クライアント) vs サーバー側 (Consul、Kubernetes DNS)

ステップ 3: クイック推奨事項出力

パターン名と1行の正当化
プライマリトレードオフ (例: "Saga: 分散スケーラビリティのための結果整合性")
実装の複雑性推定 (低、中、高)
resources/ フォルダのパターンテンプレートへのリンク

T1 トークン予算: ≤2k トークン

T2: 拡張実装ガイダンス (≤6k トークン)

T1 を含む、さらに:

ステップ 4: パターン詳細分析

Saga パターン向け:

各ステップ用の補償トランザクションを設計 (べき等、再試行可能)
Choreography: イベント種別 (OrderCreated、PaymentProcessed、ShipmentScheduled) を伴うイベントスキーマ設計
- メッセージブローカー (Kafka、RabbitMQ、AWS EventBridge) をイベントバス用に使用
- 各サービスがイベントをサブスクライブし、新しいイベントをパブリッシュ
- 例: Order Service → OrderCreated イベント → Payment Service → PaymentProcessed イベント
Orchestration: 中央コーディネーター (ステートマシン) が saga ワークフローを管理
- オーケストレーターサービス (Temporal、Camunda、AWS Step Functions) を使用
- Saga 状態を維持し、コマンド/クエリ経由でサービスを呼び出し
- 集中ログとステート可視性でデバッグが容易
失敗処理: タイムアウト、指数バックオフ付きリトライ、補償トリガー
監視: 分散トレーシング (OpenTelemetry) で saga 相関 ID を追跡

CQRS パターン向け:

コマンドモデル: ドメイン検証とビジネスロジック付き書き込み操作
- コマンド: CreateOrder、UpdateInventory (命令型、意図を明らかに)
- コマンドハンドラー: 検証、ビジネスルール適用、状態永続化、イベントパブリッシュ
クエリモデル: 読み取り最適化プロジェクション (非正規化、マテリアライズドビュー)
- クエリ: GetOrderDetails、SearchProducts (宣言型、データ取得)
- クエリハンドラー: プロジェクションストア (Redis、Elasticsearch、読み取りレプリカ) から読み取り
同期化: イベント経由の結果整合性 (Event Sourcing または CDC)
- コマンド側がドメインイベントをパブリッシュ → クエリ側がコンシュームしプロジェクションを更新
- 許容可能な遅延ウィンドウ (例: ほとんどの場合 <1 秒)
データストア: 書き込みストア (PostgreSQL、DynamoDB) vs 読み取りストア (Redis、MongoDB、Elasticsearch)

Event Sourcing 向け:

イベントストア設計: 不変イベントの追記専用ログ (EventStoreDB、Kafka、DynamoDB Streams)
- イベントスキーマ: { eventId、aggregateId、eventType、timestamp、payload、metadata }
- バージョニング: イベント種別のセマンティックバージョニング、古いバージョン向けアップキャスティング
イベントリプレイ: 開始からのイベントリプレイまたはスナップショットで現在の状態を再構築
- スナップショット: 完全リプレイ回避用の定期的状態スナップショット (例: 100 イベント毎)
CQRS 統合: イベントが読み取りモデル (プロジェクション) に供給
- プロジェクション再構築: イベントをリプレイして新規プロジェクション作成または破損プロジェクション修正
イベントスキーマエボリューション: イベントバージョニングと変換機を使用して後方互換性を維持

Circuit Breaker 向け:

状態: Closed (正常)、Open (失敗中、要求を拒否)、Half-Open (復旧テスト中)
- Closed → Open: 閾値 (例: 10 秒間に 5 回の失敗) を超過
- Open → Half-Open: タイムアウト期間後 (例: 30 秒)
- Half-Open → Closed: テスト要求成功
- Half-Open → Open: テスト要求時の失敗
フォールバック戦略: キャッシュ応答、デフォルト値、グレースフルデグラデーション、エラーメッセージ
ライブラリ: Resilience4j (Java)、Polly (.NET)、Hystrix (非推奨、Resilience4j 使用)、opossum (Node.js)
監視: 回路状態変更、障害率、フォールバック呼び出し

API Gateway 向け:

責務: ルーティング、コンポジション、プロトコル変換 (REST→gRPC)、認証、レート制限
パターン:
- Gateway Routing: バックエンドサービスへの単純なリクエスト転送
- Gateway Aggregation: 複数バックエンド呼び出しを単一応答に結合 (N+1 回避)
- Gateway Offloading: 横断的関心事 (SSL 終了、認証、ログ、CORS)
BFF (Backend for Frontend): クライアント種別毎の個別ゲートウェイ (Web、モバイル、IoT)
- Web BFF: ネストされたオブジェクト付きリッチデータ
- モバイル BFF: 最小限ペイロード、ページネーション応答
実装: Kong、AWS API Gateway、Azure API Management、Spring Cloud Gateway、Envoy

Service Discovery 向け:

クライアント側: サービス呼び出しがディスカバリークライアント (Eureka、Consul クライアント) でインスタンスリスト取得、その後ロードバランス
- 長所: ネットワークホップ排除、高速化
- 短所: クライアント複雑性、言語毎の SDK
サーバー側: サービス呼び出しがロードバランサー/DNS に実施、レジストリをクエリしルーティング
- 長所: クライアント単純性、言語非依存
- 短所: 追加ネットワークホップ、単一障害点 (HA で軽減)
実装: Kubernetes DNS (サーバー側)、Consul、Eureka (Netflix OSS)、etcd、Zookeeper
ヘルスチェック: ハートビート、HTTP/gRPC ヘルスエンドポイント、コンテナライブネスプローブ

ステップ 5: 実装テンプレート生成

framework_preference (指定された場合) 向けコードスキャフォルディングを提供
Spring Boot 例: @Saga アノテーション、CQRS/ES 向け Axon Framework
Node.js 例: CQRS モジュール付き NestJS、イベント駆動マイクロサービス
.NET 例: CQRS 向け MediatR、Saga オーケストレーション向け MassTransit
Go 例: マイクロサービス向け go-kit、イベントストリーミング向け NATS
Python 例: イベント駆動パターン付き FastAPI、非同期タスク向け Celery

ステップ 6: アンチパターンと落とし穴

Saga: 補償ロジック不足、べき等でない操作、無制限リトライ
CQRS: シンプル CRUD への過度な使用、結果整合性 UX 影響の軽視
Event Sourcing: スナップショット不足 (リプレイ遅い)、イベントスキーマバージョニング不良
Circuit Breaker: タイムアウト短すぎ/長すぎ、フォールバック不足、ハーフオープンテスト軽視
API Gateway: モノリシックゲートウェイ (ボトルネック化)、バックエンドへの密結合
Service Discovery: 古いレジストレーション (不十分なヘルスチェック)、シャットダウン時の登録解除不足

ステップ 7: オブザーバビリティと監視戦略

分散トレーシング: サービス境界を超える相関 ID (OpenTelemetry、Jaeger、Zipkin)
メトリクス: パターン固有メトリクス
- Saga: saga 期間、補償率、ステップ毎の失敗率
- CQRS: コマンドレイテンシ、クエリレイテンシ、プロジェクション遅延
- Event Sourcing: イベントストア書き込みスループット、リプレイ期間
- Circuit Breaker: 回路状態、障害率、フォールバック呼び出し率
- API Gateway: リクエスト率、レイテンシパーセンタイル (p50、p95、p99)、エラー率
- Service Discovery: インスタンス数、登録/登録解除率、ヘルスチェック失敗
ログ: コンテキスト付き構造化ログ (サービス、相関 ID、パターン名)
アラート: パターン固有アラート (例: 5 分以上の回路オープン、10 秒超えのプロジェクション遅延)

ステップ 8: デプロイメントパターンとの統合

cloud-native-deployment-orchestrator を参照 (Kubernetes マニフェスト)
横断的関心事向けサイドカーパターン (Envoy プロキシ、Istio経由 Circuit Breaker)
サービスメッシュ統合: Istio/Linkerd (トラフィック管理、オブザーバビリティ、復元力)

T2 トークン予算: ≤6k トークン (T1 との累積)

判断ルール

パターン選択デシジョンツリー:

分散トランザクションが必要な場合:
- 結果整合性を許容可能? → Saga (疎結合なら choreography、複雑ワークフローなら orchestration)
- 強い一貫性が必要? → 中止; モノリスまたは 2PC 付き分散データベースを推奨
読み取り/書き込みスケール不一致 (>10 倍) がある場合:
- 監査証跡または時間軸クエリが必要? → CQRS + Event Sourcing
- 単に読み取り最適化が必要? → CQRS のみ (CDC またはポーリング付き)
外部依存関係のフォールトトレランスが必要な場合:
- 予測不能な障害、グレースフルデグラデーション必要? → Circuit Breaker + Bulkhead + Timeout
複数クライアント種別またはサービス横断的関心事がある場合:
- クライアント固有の最適化? → API Gateway + BFF バリアント
- ルーティング/認証/レート制限のみ? → API Gateway (シンプルルーティング)
クラウド/コンテナの動的サービスインスタンスがある場合:
- 言語非依存の検出が必要? → Service Discovery (サーバー側: Kubernetes DNS、Consul)
- クライアントライブラリを埋め込み可能? → Service Discovery (クライアント側: Eureka、Ribbon)

構成ルール:

Saga + Event Sourcing: Event Store からのイベントが Saga choreography を供給
CQRS + Event Sourcing: イベントがコマンドモデルと読み取りプロジェクション両方を更新
API Gateway + Circuit Breaker: ゲートウェイがバックエンド呼び出し用 circuit breaker を実装
Service Discovery + API Gateway: ゲートウェイが動的にバックエンドサービスインスタンスを検出

中止/停止条件:

architecture_context にサービス境界がない → architecture-decision-framework を呼び出し
リアルタイム一貫性が補償なしで必要 → 代替案 (モノリス、分散 DB) を推奨
シナリオが不明瞭すぎる → 特定サービスとデータフロー付き明確化を要求
framework_preference なし、T2 要求 → ポリグロット疑似コード提供

出力契約

必須フィールド (すべてのティア):

{
  "pattern_recommendation": {
    "primary_pattern": "Saga | CQRS | Event Sourcing | Circuit Breaker | API Gateway | Service Discovery",
    "variant": "choreography | orchestration | BFF | client-side | server-side (オプション)",
    "justification": "このパターンがシナリオに適合する理由 (1-2 文)",
    "trade_offs": {
      "pros": ["利点リスト"],
      "cons": ["短所と制約リスト"]
    },
    "complexity": "low | medium | high"
  },
  "implementation_template": {
    "language": "spring-boot | nodejs | .net | go | python | polyglot (文字列)",
    "code_scaffolding": "resources/ テンプレートへのファイルパスまたはインラインコードスニペット",
    "dependencies": ["必須ライブラリ/フレームワークリスト"]
  },
  "anti_patterns": [
    {
      "name": "アンチパターン名",
      "description": "回避するもの",
      "mitigation": "回避方法"
    }
  ],
  "integration_guidance": {
    "steps": ["実装ステップの順序付きリスト"],
    "decision_points": ["実装中に実施すべき主要判断"]
  }
}

追加フィールド (T2 のみ):

{
  "event_schemas": [
    {
      "event_type": "EventName",
      "version": "1.0.0",
      "schema": { "JSON スキーマまたはペイロード例" },
      "versioning_strategy": "semantic | append-only | upcasting"
    }
  ],
  "monitoring_strategy": {
    "metrics": ["追跡するパターン固有メトリクス"],
    "traces": "分散トレーシング要件",
    "alerts": ["推奨アラート条件"]
  },
  "deployment_integration": {
    "kubernetes_resources": "ConfigMap、Service、Deployment アノテーション",
    "service_mesh_config": "Istio VirtualService、DestinationRule (該当する場合)"
  }
}

例

例: 注文処理向け Saga パターン

# 入力
scenario: distributed transaction
architecture_context:
  services:
    - OrderService: 注文を管理
    - PaymentService: 支払いを処理
    - InventoryService: 在庫を予約
    - ShipmentService: 配送をスケジュール
  communication: REST APIs
deployment_tier: T1

# 出力
pattern_recommendation:
  primary_pattern: Saga
  variant: choreography
  justification: "イベント駆動 choreography により、疎結合サービスが補償トランザクション付き注文履行を調整できます。"
  trade_offs:
    pros:
      - "サービスが疎結合"
      - "単一障害点なし"
      - "イベント駆動アーキテクチャに自然な適合"
    cons:
      - "分散フロー デバッグが困難"
      - "結果整合性は UX 考慮が必要"
  complexity: medium

クオリティゲート

トークン予算 (強制):

T1: ≤2k トークン (パターン推奨、クイックテンプレートリンク)
T2: ≤6k トークン (詳細分析、実装テンプレート、監視戦略)
T3: このスキル向けに未実装 (パターンアーキテクチャガイダンスに十分な T2)

セキュリティ:

テンプレートに秘密情報や認証情報なし
すべてのコード例でプレースホルダー値使用 (例: your-api-key、localhost)
外部ツール参照にバージョン制約含む (例: Resilience4j 2.x)

監査可能性:

すべてのパターン推奨がソースを引用 (microservices.io、Martin Fowler、

ライセンス: Apache-2.0(寛容ライセンスのため全文を引用しています) · 原本リポジトリ

SKILL.md 本文