architecture-design

アーキテクチャ設計

使用する場面

• システム設計が必要な新しいプロダクトや主要機能を開始するとき
• モノリス、モジュラーモノリス、マイクロサービス、イベント駆動型パターンのいずれかを選ぶとき
• 新しいプロジェクトでデータベース（SQL、NoSQL、特化型）を選定するとき
• 循環参照、結合の問題、古いパッケージについて依存関係を分析するとき
• ドキュメント作成やレビュー用にアーキテクチャ図（Mermaid、PlantUML、ASCII）を作成するとき
• 技術的な選択についてアーキテクチャ決定記録（ADR）を作成するとき
• スケーラビリティのボトルネックを評価したり、キャパシティを計画したりするとき

必要なコンテキスト

startup-context から、プロダクトの説明、技術スタック、現在の状態（プロトタイプ／ベータ／スケーリング中）、チーム規模、想定規模（ユーザー数、リクエスト数／秒、データ量）を取得します。不足している場合は、次の点を確認してください。

• このシステムには何が必要ですか？（中核となるユースケース）
• どの程度の規模を想定していますか？（ユーザー数、リクエスト数／秒、データサイズ）
• チームの規模とバックエンドの経験レベルを教えてください。
• 厳守すべき制約はありますか？（コンプライアンス、レイテンシ、予算、既存のインフラ）

ワークフロー

1. 要件を収集する — 機能要件（ユースケース）、非機能要件（レイテンシ、スループット、可用性、一貫性）、制約（予算、チーム規模、コンプライアンス）を特定します。
2. アーキテクチャを評価する — 既存のプロジェクト構造を分析して、現在のパターン（MVC、レイヤード、ヘキサゴナル、マイクロサービスの兆候）、コード構成の問題（巨大クラス、関心事の混在）、レイヤー違反を検出します。
3. 依存関係を分析する — npm、Python、Go、Rust のプロジェクト全体で、依存関係ツリーを調べて循環依存、結合スコア、古いパッケージを特定します。
4. アーキテクチャパターンを選択する — 以下の選択ワークフローを使って、チーム規模、デプロイ要件、データ境界に適したパターンを選びます。初期段階のスタートアップのほとんどには、モジュラーモノリスを推奨します。
5. データベースを選択する — 以下の選択ワークフローを使って、データの特性、規模の要件、一貫性のニーズに適したデータベース技術を選びます。
6. データモデルを設計する — Mermaid の ER 図を作成します。エンティティの所有権を定義します。つまり、どのモジュール／サービスが書き込みを行い、ほかのモジュール／サービスが API 経由で読み取るかを定めます。
7. API コントラクトを定義する — 主要なエンドポイントについて、メソッド、パス、リクエスト／レスポンスの形式、エラーコードを指定します。初日からバージョン管理を行います。
8. アーキテクチャ図を生成する — コンポーネント、データストア、外部サービス、通信パターンを示す Mermaid C4 図またはフローチャートを作成します。
9. ADR を作成する — 以下の ADR 形式を使って、重要な決定を記録します。
10. リスクを特定する — 単一障害点、データ整合性のリスク、スケーリングのボトルネックを、緩和策とともに明示します。

出力形式

次のセクションを含む、構造化されたアーキテクチャ文書を作成します。

• 要件の概要 — 機能要件、非機能要件、制約
• アーキテクチャ評価 — 検出されたパターンと確信度、問題、推奨事項
• システム図 — Mermaid C4 図またはフローチャート（コンポーネント、レイヤー、デプロイメントのビュー）
• ドメインモデル — エンティティの所有権を示す Mermaid ER 図
• モジュール境界 — 表：モジュール、責務、所有データ、公開 API
• API コントラクト — 主要なエンドポイントのメソッド、パス、リクエスト／レスポンスの形式
• ADR — 重要な選択に関するアーキテクチャ決定記録
• 依存関係分析 — 依存関係の総数、結合スコア、循環依存、古いパッケージ
• リスクと緩和策 — 表：リスク、影響、可能性、緩和策

フレームワークとベストプラクティス

アーキテクチャパターンの選定

チーム規模	推奨される開始点
開発者 1～3 人	モジュラーモノリス
開発者 4～10 人	モジュラーモノリスまたはサービス指向
開発者 10 人以上	マイクロサービスを検討

要件	推奨パターン
MVP の迅速な開発	モジュラーモノリス
チームごとの独立したデプロイ	マイクロサービス
複雑なドメインロジック	ドメイン駆動設計
読み取りと書き込みの比率に大きな差がある	CQRS
監査証跡が必要	イベントソーシング
サードパーティとの統合	ヘキサゴナルアーキテクチャ／ポートとアダプター

初期段階のスタートアップにおけるデフォルト： 後から切り出せるよう、モジュール境界を明確にしたモジュラーモノリスを採用します。マイクロサービスは運用上のオーバーヘッドが増え、小規模チームの妨げになります。

モノリスとマイクロサービスのチェックリスト

モノリスを選ぶ場合： チームが小さい（10 人未満）、ドメイン境界が不明確、迅速なイテレーションを優先する、共有データベースを許容できる。

マイクロサービスを選ぶ場合： チームがサービスをエンドツーエンドで担当できる、独立したデプロイが不可欠、コンポーネントごとに異なるスケーリング要件がある、ドメイン境界が十分に理解されている。

ハイブリッドアプローチ： まずモノリスから始めます。モジュールに大きく異なるスケーリング要件がある場合、チームが独立したデプロイを必要とする場合、または技術的な制約によって分離が必要な場合に限り、サービスを切り出します。

データベースの選定

リレーションシップを持つ構造化データや ACID 要件がある場合は SQL が適しています。柔軟に変更できるスキーマやドキュメント指向のデータには NoSQL が適しています。クイックリファレンス：PostgreSQL（ほとんどのアプリのデフォルト）、MongoDB（ドキュメントストア）、Redis（キャッシュ／セッション）、DynamoDB（サーバーレスの自動スケーリング）、TimescaleDB（時系列データ）、CockroachDB／Spanner（グローバル分散）。

ADR の形式

次の 5 つの項目を使用します。ステータス（提案／承認／非推奨／置き換え済み）、コンテキスト（決定のきっかけ）、決定（選択した内容とその理由）、結果（トレードオフと残るリスク）、検討した代替案（ほかに評価した選択肢と、それらを採用しなかった理由）。

主要な設計原則

• すべてのエンティティには明確なオーナーを設けます（1 つのモジュールが書き込み、ほかのモジュールは API 経由で読み取ります）
• マルチサービス構成または将来的な切り出しの可能性が高い場合は、主キーに UUID を使用します
• 初日から API をバージョニングします（/v1/resource）。すべての一覧エンドポイントをページネーション対応にします（カーソルベースを推奨）
• 一貫性のあるエラー形式を使用します：{ "error": { "code": "...", "message": "..." } }
• 書き込み操作は冪等性を考慮して設計します（冪等性キー）
• 即時確認が必要なクエリには同期呼び出し（HTTP／gRPC）を使用し、通知、分析、サービス間のデータ同期には非同期イベントを使用します
• 分散トランザクションは避け、サーガまたは結果整合性を使用します

関連スキル

• tech-stack-eval — アーキテクチャで具体的な技術を選ぶ際に連携します
• security-review — 実装前に、脅威要因がないかアーキテクチャをレビューするために連携します
• code-review — 実装後に、コードがアーキテクチャの意図に沿っているか確認するために連携します

例

プロンプト：「SaaS のプロジェクト管理ツールを開発しています。エンジニアは 3 人です。どのようなアーキテクチャにすべきですか？」

出力例：

Given your team of 3 and early stage, I recommend a modular monolith.
Domain modules:

1. Auth Module — user accounts, roles, sessions
2. Projects Module — workspaces, projects, permissions
3. Tasks Module — tasks, assignments, comments, activity log
4. Notifications Module — email digests, in-app notifications

Each module gets its own DB schema (auth.*, projects.*) and communicates
through internal function calls with typed interfaces — not HTTP. This
gives you service-like boundaries without deployment complexity.

Architecture Assessment:
  Detected pattern: Layered Architecture (confidence: 85%)
  ✓ controllers/  - Presentation layer
  ✓ services/     - Business logic layer
  ✓ repositories/ - Data access layer

プロンプト：「リアルタイムのコラボレーションには WebSockets と SSE のどちらを使うべきですか？」

出力例：

## ADR-001: Use WebSockets for Real-Time Collaboration
- Status: Proposed
- Context: Document editor needs sub-200ms latency for cursor positions
  and concurrent edits across 2-50 users per document.
- Decision: WebSockets via Socket.io with Redis pub/sub for horizontal
  scaling. SSE only supports server-to-client; we need bidirectional
  communication for operational transforms.
- Consequences: Adds WebSocket infrastructure (sticky sessions or Redis
  adapter), ~2KB memory per connection. Team needs OT/CRDT knowledge.
- Alternatives: SSE + POST (simpler but higher edit latency),
  Firebase Realtime DB (vendor lock-in, cost at scale).