# 設計ドキュメントテンプレート

---
**目的**: 実装者が異なる場合でも一貫した実装を保証するために、十分な詳細を提供し、解釈のズレを防ぐ。

**アプローチ**:
- 実装の判断に直接影響する必須セクションを含める
- 実装エラーの防止に重要でない限り、オプションセクションは省略
- 機能の複雑さに応じた詳細レベル
- 長い文章よりも図表やテーブルを使用

**警告**: 1000行に近づくと機能の複雑さが過度であり、設計の簡素化が必要な可能性がある。
---

セクションの順序は、明確さが向上する場合に変更可能（例：要件トレーサビリティを前方に配置、データモデルをアーキテクチャの近くに移動）。各セクション内では **概要 → スコープ → 決定事項 → 影響/リスク** の流れを維持し、レビュアーが一貫してスキャンできるようにする。

## 概要
2-3段落以内
**目的**: この機能は[対象ユーザー]に[具体的な価値]を提供する。
**ユーザー**: [対象ユーザーグループ]が[特定のワークフロー]でこれを利用する。
**影響**（該当する場合）: 現在の[システム状態]を[具体的な変更]によって変更する。

**成果物（推奨）**: 設計の一次ソースとして、可能な限り以下3つを作成/更新し、設計と矛盾させない。\n> - `.cursor/<feature>/artifacts/feature-list.md`\n> - `.cursor/<feature>/artifacts/data-model.md`\n> - `.cursor/<feature>/artifacts/table-definition.md`\n> テンプレートは `.cursor/templates/artifacts/` を参照。（初期作成ロジックは `.cursor/rules/artifacts-generation.md`）。

### ゴール
- 主要目標1
- 主要目標2
- 成功基準

### 非ゴール
- 明示的に除外する機能
- 現在のスコープ外の将来の検討事項
- 延期する連携ポイント

## アーキテクチャ

> 詳細な調査ノートは`research.md`を参照（背景情報のみ）。レビュアーのために設計ドキュメントを自己完結型に保ち、すべての決定事項と契約をここに記載する。
> 重要な決定事項はテキストで記述し、図で構造の詳細を伝える—同じ情報を文章で繰り返さない。

### 既存アーキテクチャ分析（該当する場合）
既存システムを変更する場合：
- 現在のアーキテクチャパターンと制約
- 尊重すべき既存のドメイン境界
- 維持すべき連携ポイント
- 対処または回避する技術的負債

### アーキテクチャパターン＆境界マップ
**推奨**: 選択したアーキテクチャパターンとシステム境界を示すMermaid図を含める（複雑な機能では必須、単純な追加ではオプション）

**アーキテクチャ統合**:
- 選択パターン: [名前と簡潔な理由]
- ドメイン/機能境界: [競合を避けるための責任分離方法]
- 維持する既存パターン: [主要パターンのリスト]
- 新コンポーネントの理由: [各コンポーネントが必要な理由]
- ステアリング準拠: [維持する原則]

### 技術スタック

| レイヤー | 選択 / バージョン | 機能での役割 | 備考 |
|---------|-----------------|-------------|------|
| フロントエンド / CLI | | | |
| バックエンド / サービス | | | |
| データ / ストレージ | | | |
| メッセージング / イベント | | | |
| インフラ / ランタイム | | | |

> 理由は簡潔に。より深い内容（トレードオフ、ベンチマーク）が必要な場合は、短い要約と参照セクションおよび`research.md`の調査ノートへのポインタを追加。

## システムフロー

非自明なフローを説明するために必要な図のみを提供。純粋なMermaid構文を使用。一般的なパターン：
- シーケンス（複数パーティのインタラクション）
- プロセス/状態（分岐ロジックまたはライフサイクル）
- データ/イベントフロー（パイプライン、非同期メッセージング）

単純なCRUD変更ではこのセクション全体をスキップ。
> フローレベルの決定（例：ゲート条件、リトライ）は図の後に簡潔に記述し、各ステップを繰り返さない。

## 要件トレーサビリティ

要件が複数のドメインにまたがる複雑な機能やコンプライアンス重視の機能に使用。単純な1:1マッピングはコンポーネント概要テーブルに依存可能。

各要件ID（例：`2.1`）を実現する設計要素にマッピング。

| 要件 | 概要 | コンポーネント | インターフェース | フロー |
|------|------|--------------|----------------|--------|
| 1.1 | | | | |
| 1.2 | | | | |

> 単一のコンポーネントが横断的な関心事なしに単一の要件を満たす場合のみ、このセクションを省略。

## コンポーネントとインターフェース

コンポーネント別の詳細に入る前のクイックリファレンス。

- 概要はテーブルまたはコンパクトなリスト形式。テーブル例：
  | コンポーネント | ドメイン/レイヤー | 意図 | 要件カバレッジ | 主要な依存関係 (P0/P1) | 契約 |
  |-|-|-|-|-|-|
  | ExampleComponent | UI | XYZを表示 | 1, 2 | GameProvider (P0), MapPanel (P1) | Service, State |
- 新しい境界を導入するコンポーネント（例：ロジックフック、外部連携、永続化）のみが完全な詳細ブロックを必要とする。単純なプレゼンテーションコンポーネントは概要行と短い実装ノートで十分。

ドメインまたはアーキテクチャレイヤーごとに詳細ブロックをグループ化。各詳細コンポーネントについて、要件IDを`2.1, 2.3`としてリスト（「要件」は省略）。複数のUIコンポーネントが同じ契約を共有する場合、コードブロックを重複させずに基本インターフェース/props定義を参照。

### [ドメイン / レイヤー]

#### [コンポーネント名]

| フィールド | 詳細 |
|----------|------|
| 意図 | 責任の1行説明 |
| 要件 | 2.1, 2.3 |
| オーナー / レビュアー | （オプション） |

**責任と制約**
- 主な責任
- ドメイン境界とトランザクションスコープ
- データ所有権 / 不変条件

**依存関係**
- インバウンド: コンポーネント/サービス名 — 目的 (重要度)
- アウトバウンド: コンポーネント/サービス名 — 目的 (重要度)
- 外部: サービス/ライブラリ — 目的 (重要度)

外部依存関係の調査結果をここに要約。より深い調査（APIシグネチャ、レート制限、移行ノート）は`research.md`に記載。

**契約**: Service [ ] / API [ ] / Event [ ] / Batch [ ] / State [ ]  ← 該当するもののみチェック。

##### サービスインターフェース
- 提供するメソッドと責任を自然言語で記述
- 事前条件 / 事後条件 / 不変条件を箇条書きで明記
- 型定義はコードで実装時に定義（Prisma等のORMを使用する場合は自動生成される型を活用）

##### API契約
| メソッド | エンドポイント | リクエスト | レスポンス | エラー |
|---------|--------------|-----------|----------|--------|
| POST | /api/resource | CreateRequest | Resource | 400, 409, 500 |

##### イベント契約
- 発行イベント:
- 購読イベント:
- 順序 / 配信保証:

##### バッチ / ジョブ契約
- トリガー:
- 入力 / 検証:
- 出力 / 宛先:
- 冪等性 & 復旧:

##### 状態管理
- 状態モデル:
- 永続化 & 一貫性:
- 並行性戦略:

**実装ノート**
- 統合:
- 検証:
- リスク:

## データモデル

この機能で変更されるデータ環境の部分に焦点を当てる。

**注記**: データモデルは `data-model.md` / `table-definition.md` と整合している必要がある。設計内では決定事項と契約を要約し、詳細は成果物側を一次ソースとして参照してよい（ただし矛盾は許容しない）。

### ドメインモデル
- 集約とトランザクション境界
- エンティティ、値オブジェクト、ドメインイベント
- ビジネスルール & 不変条件
- 複雑な関係のオプションMermaid図

### 論理データモデル

**構造定義**:
- エンティティ関係とカーディナリティ
- 属性とその型
- 自然キーと識別子
- 参照整合性ルール

**一貫性 & 整合性**:
- トランザクション境界
- カスケードルール
- 時間的側面（バージョニング、監査）

### 物理データモデル
**含める場合**: 実装で特定のストレージ設計決定が必要な場合

**リレーショナルデータベースの場合**:
- データ型を含むテーブル定義
- 主キー/外部キーと制約
- インデックスとパフォーマンス最適化
- スケールのためのパーティショニング戦略

**ドキュメントストアの場合**:
- コレクション構造
- 埋め込み vs 参照の決定
- シャーディングキー設計
- インデックス定義

**イベントストアの場合**:
- イベントスキーマ定義
- ストリーム集約戦略
- スナップショットポリシー
- プロジェクション定義

**Key-Value/ワイドカラムストアの場合**:
- キー設計パターン
- カラムファミリーまたは値構造
- TTLとコンパクション戦略

### データ契約 & 連携

**APIデータ転送**
- リクエスト/レスポンススキーマ
- バリデーションルール
- シリアライゼーション形式（JSON、Protobufなど）

**イベントスキーマ**
- 発行イベント構造
- スキーマバージョニング戦略
- 後方/前方互換性ルール

**クロスサービスデータ管理**
- 分散トランザクションパターン（Saga、2PC）
- データ同期戦略
- 結果整合性の処理

この機能に関連しないサブセクションはスキップ。

## エラーハンドリング

### エラー戦略
各エラータイプの具体的なエラーハンドリングパターンと復旧メカニズム。

### エラーカテゴリとレスポンス
**ユーザーエラー** (4xx): 無効な入力 → フィールドレベル検証; 未認証 → 認証ガイダンス; 未検出 → ナビゲーションヘルプ
**システムエラー** (5xx): インフラ障害 → グレースフルデグラデーション; タイムアウト → サーキットブレーカー; 枯渇 → レート制限
**ビジネスロジックエラー** (422): ルール違反 → 条件説明; 状態競合 → 遷移ガイダンス

**プロセスフロー可視化**（複雑なビジネスロジックが存在する場合）:
複雑なビジネスワークフローを伴うエラーシナリオのみMermaidフローチャートを含める。

### モニタリング
エラー追跡、ロギング、ヘルスモニタリングの実装。

## テスト戦略

### デフォルトセクション（ドメインに合わせて名前/セクションを調整）
- ユニットテスト: コア機能/モジュールから3〜5項目（例：認証メソッド、サブスクリプションロジック）
- 統合テスト: 3〜5のクロスコンポーネントフロー（例：Webhookハンドリング、通知）
- E2E/UIテスト（該当する場合）: 3〜5の重要なユーザーパス（例：フォーム、ダッシュボード）
- パフォーマンス/負荷テスト（該当する場合）: 3〜4項目（例：並行性、大量操作）

## オプションセクション（関連する場合に含める）

### セキュリティ考慮事項
_認証、機密データ、外部連携、またはユーザー権限を扱う機能に使用。この機能に固有の決定のみを記載。ベースラインコントロールはステアリングドキュメントに委ねる。_
- 脅威モデリング、セキュリティコントロール、コンプライアンス要件
- 認証・認可パターン
- データ保護とプライバシーの考慮事項

### パフォーマンス & スケーラビリティ
_パフォーマンス目標、高負荷、またはスケーリングの懸念がある場合に使用。機能固有の目標やトレードオフのみを記録し、一般的なプラクティスはステアリングドキュメントに依存。_
- 目標メトリクスと測定戦略
- スケーリングアプローチ（水平/垂直）
- キャッシュ戦略と最適化技術

### 移行戦略
スキーマ/データ移動が必要な場合、移行フェーズを示すMermaidフローチャートを含める。
- フェーズ分割、ロールバックトリガー、検証チェックポイント

## 参考資料（オプション）
- メイン本文に情報を残すと可読性が損なわれる場合のみこのセクションを作成（例：非常に長いTypeScript定義、ベンダーオプションマトリックス、網羅的なスキーマテーブル）。意思決定のコンテキストはメインセクションに残し、設計を自己完結型に保つ。
- 大きなスニペットをインラインで含めず、メインテキストから参考資料へのリンクを張る。
- 背景調査ノートと比較は引き続き`research.md`に記載するが、その結論はメイン設計に要約する必要がある。

---

## 変更履歴

| 日付 | バージョン | 変更者 | 変更内容 |
| ---- | ---------- | ------ | -------- |
| {{DATE}} | v1.0 | {{AUTHOR}} | 初版作成 |