Architecture design

アーキテクチャ設計

目的

機能要件・非機能要件を入力として、システムの骨格となるアーキテクチャスタイル・技術スタック・データモデル・API方針を決定し、基本設計書とADRとして残す。設計の意思決定とその根拠を記録し、後続の詳細設計・実装フェーズで迷わないようにする。

使うタイミング

• 要件定義が完了し、「どう作るか」を決める基本設計フェーズに入ったとき
• 既存システムの刷新・再設計でアーキテクチャを見直すとき
• 技術選定で複数候補があり、トレードオフを整理して決断したいとき
• 重要な設計判断をADRとして記録・共有したいとき

進め方

1. 非機能要件の読み取り

   • [[non-functional-requirements]] の成果物を入力とする
   • スケール要件(DAU, TPS, データ量)、可用性(SLA)、レイテンシ目標、セキュリティ要件、運用体制を確認
   • 非機能要件がアーキテクチャを決める。機能要件だけで設計しない

2. アーキテクチャスタイルの選定

   • デフォルト: モジュラーモノリス（境界を持ちつつ単一デプロイ）
   • マイクロサービスは [[microservices]] の採用基準を満たす場合のみ選択
   • サーバーレスはイベント駆動・スパイク負荷・運用コスト最小化が必要な場合に検討
   • 選定理由を必ずADRに記録する

   スタイル	向いているケース	注意点
   モノリス	プロトタイプ、小規模チーム	スケールの限界
   モジュラーモノリス	多くのWebサービス（デフォルト）	モジュール境界の規律が必要
   マイクロサービス	独立デプロイが必須、チーム規模大	分散システムの複雑性
   サーバーレス	非同期処理、バースト対応	ベンダーロックイン、コールドスタート

3. 技術選定

   • 選定基準（優先順）:
     1. チームの習熟度（学習コストを甘く見ない）
     2. エコシステムの成熟度・採用実績（枯れた技術を優先）
     3. 運用負荷（マネージドサービスを積極活用）
     4. ロックインリスク（移行コストを見積もる）
   • 「枯れた技術を選ぶ」原則: 新技術はコア機能に使わず、周辺から試す
   • 例外: チーム全体が習熟しており、代替不能なメリットがある場合

4. システム構成図の作成（Mermaid）

   • クライアント・ゲートウェイ・サービス・データストア・外部連携の関係を図示
   • 詳細は後続ステップで詰める。最初はC4モデルのコンテキスト図レベルで十分

5. データモデル設計

   • エンティティ抽出 → エンティティ間の関連定義 → 正規化（第3正規形を目安）
   • ER図をMermaidで描く
   • 読み取り性能が要件にある場合は非正規化・キャッシュ戦略もこの段階で検討

6. API設計方針の決定

   • REST: リソース指向、広い互換性、デフォルト選択
   • GraphQL: 複雑なデータ取得、フロントエンド主導の場合
   • gRPC: 内部サービス間通信、高スループット、型安全性重視
   • バージョニング方針（URLパス /v1/ vs ヘッダー）とエラーレスポンス規約を合意

7. ADRの作成

   • 重要な決定（アーキテクチャスタイル・主要技術・API方針）ごとに1枚作成
   • 決定理由・却下した選択肢・想定される影響を必ず記録

8. 基本設計書の取りまとめ

   • 成果物テンプレートに沿って構成し、レビューに提出

成果物テンプレート

# 基本設計書

## 1. 設計概要
- プロジェクト名:
- 対象フェーズ:
- 作成日 / 更新日:
- 作成者:

## 2. アーキテクチャ概要
### 2.1 採用スタイル
（モノリス / モジュラーモノリス / マイクロサービス / サーバーレス）
選定理由:

### 2.2 システム構成図
```mermaid
graph TD
  Client --> Gateway
  Gateway --> AppService
  AppService --> DB[(Database)]
  AppService --> Cache[(Cache)]

2.3 技術スタック

レイヤー	採用技術	選定理由
フロントエンド
バックエンド
データストア
インフラ / CI/CD

3. データモデル

3.1 主要エンティティ

（エンティティ一覧と責務）

3.2 ER図

erDiagram
  USER ||--o{ ORDER : places
  ORDER ||--|{ LINE_ITEM : contains

4. API設計方針

• プロトコル: REST / GraphQL / gRPC
• バージョニング:
• エラーレスポンス規約:
• 認証方式:

5. ADR一覧

ID	タイトル	ステータス	決定日
ADR-001		Accepted

6. 未解決事項

項目	担当	期限

```markdown
# ADR-NNN: タイトル

**ステータス**: Proposed / Accepted / Deprecated / Superseded by ADR-XXX
**決定日**: YYYY-MM-DD
**決定者**:

## コンテキスト
（背景・制約・この決定が必要になった理由）

## 決定
（何を決めたか、1〜2文で明確に）

## 選択肢と比較
| 選択肢 | メリット | デメリット |
|---|---|---|
| A（採用） | | |
| B | | |
| C | | |

## 影響
- ポジティブ:
- ネガティブ / リスク:
- フォローアップ:

チェックリスト

• 非機能要件（スケール・可用性・レイテンシ・セキュリティ）を確認した
• アーキテクチャスタイルの選定理由をADRに記録した
• 技術選定でチームの習熟度を評価した
• システム構成図（Mermaid）を作成した
• ER図（Mermaid）を作成した
• API設計方針（プロトコル・バージョニング・エラー規約）を合意した
• 重要な決定ごとにADRを作成した
• 未解決事項をリストアップした
• 基本設計書をレビューに提出した

アンチパターン

• 流行で技術を選ぶ: 「今ホットだから」はNG。採用実績・運用コスト・チーム習熟度で判断する
• 最初からマイクロサービス: 分散システムの複雑性を過小評価しがち。モジュラーモノリスから始めて必要になったら分割する
• ADRを書かない: 決定理由が失われ、数ヶ月後に「なぜこうなったか誰もわからない」状態になる
• 非機能要件を無視した設計: 機能要件だけで設計すると、後からスケール・可用性対応で大規模リファクタが発生する
• 過度な抽象化: 将来の拡張性を見越しすぎて、現在の要件に対してオーバーエンジニアリングになる
• データモデルを後回し: API設計が固まってからデータモデルを詰めると大幅な手戻りが発生する

モデル委譲ガイド

共通原則は [[orchestration]] を参照。

作業	担当モデル	理由
アーキテクチャスタイルの最終選定	司令塔	トレードオフ評価と最終判断が必要
技術選定の最終決定	司令塔	チーム・ビジネス制約を踏まえた判断
基本設計書ドラフト作成	Opus	設計ドキュメント全体の構成と記述
ADRドラフト作成	Opus	選択肢比較と影響分析の記述
設計レビュー（穴出し）	Opus	設計の整合性・抜け漏れ指摘
技術比較表・調査	Sonnet	複数技術の調査と表形式での整理
Mermaid図作成	Sonnet	構成図・ER図の描画
既存システムの構成調査	Haiku	コードベース・設定ファイルの読み取り

関連スキル

• [[orchestration]] - マルチエージェント協調の共通原則
• [[requirements-definition]] - 入力となる要件定義
• [[non-functional-requirements]] - アーキテクチャを決める非機能要件
• [[detailed-design]] - 基本設計を受けた詳細設計
• [[microservices]] - マイクロサービス採用基準と設計パターン
• [[screen-design]] - UIレイヤーの設計
• [[implementation]] - 設計を受けた実装フェーズ
• [[estimation]] - 技術選定を踏まえた工数見積もり
• [[task-breakdown]] - 基本設計を元にしたタスク分解
• [[mvp-development]] - 最小構成での設計アプローチ