---
name: detail-design
description: |
  `02.design-doc.md`（req-estimate の出力）と `03.db-design.md` を受け取り、実装者が迷わずコードを書き始められる詳細設計書（`04.detail-design.md`）を生成するスキル。
  シーケンス図・API仕様・エラーハンドリング・環境変数一覧を含む。
---

## Trigger Conditions
次のような状況で必ず使うこと:
- 「詳細設計作って」「シーケンス図書いて」「API仕様をまとめて」
- 「実装者に渡す設計書が欲しい」「コーディング前の設計書を作りたい」
- 「エラーハンドリングの方針を決めたい」「環境変数を整理したい」
- 02.design-doc.md を渡されて「もっと詳しく」と言われたとき

---

## Steps

### Step 1: 入力を読み込み設計要素を抽出する

以下の優先順でファイルを読み込む：
1. `02.design-doc.md`（アーキテクチャ設計）
2. `03.db-design.md`（テーブル設計）
3. 元の要件定義書 / readme.md

以下を抽出する：
```
- コンポーネント一覧（ECS / Lambda / SQS / API Gateway 等）
- 主要な処理フロー（ユーザー操作 → システム応答の流れ）
- 外部サービス連携（Claude API / Slack / 決済 等）
- 非同期処理・キューの利用箇所
- 認証・認可の仕組み
- エラーが発生しうる箇所
```

### Step 2: 主要フローのシーケンス図を作成する

**対象フロー**（最大5フロー）：
- システムの中心となるメインフロー（必須）
- 認証フロー（認証がある場合）
- エラー・リトライフロー（非同期処理がある場合）
- 管理者操作フロー（管理画面がある場合）

Mermaid の `sequenceDiagram` 記法を使用する：

```mermaid
sequenceDiagram
    actor User
    participant Frontend
    participant API
    participant DB

    User->>Frontend: 操作
    Frontend->>API: POST /api/resource
    API->>DB: INSERT
    DB-->>API: OK
    API-->>Frontend: 201 Created
    Frontend-->>User: 完了表示
```

**シーケンス図の作成ルール**：
- 参加者（participant）は左から右に処理の流れ順に並べる
- 外部サービスは `participant` の末尾にまとめる
- 非同期処理は `activate` / `deactivate` で表現
- エラー分岐は `alt` / `else` で記載
- DBへの直接アクセスはリポジトリ層を介して表現する

### Step 3: API エンドポイント仕様を定義する

各エンドポイントについて以下を定義する。

**フォーマット**：
```
### POST /api/{resource}

**概要**: {このエンドポイントの役割}
**認証**: {不要 / Bearer Token / API Key}

**リクエスト**:
| フィールド | 型 | 必須 | 説明 |
|-----------|---|------|------|
| field_name | string | ✅ | 説明 |

**レスポンス（200 OK）**:
| フィールド | 型 | 説明 |
|-----------|---|------|
| field_name | string | 説明 |

**エラーレスポンス**:
| ステータス | エラーコード | 発生条件 |
|-----------|------------|---------|
| 400 | VALIDATION_ERROR | バリデーション失敗 |
| 401 | UNAUTHORIZED | 認証トークン不正 |
| 500 | INTERNAL_ERROR | サーバーエラー |
```

**エンドポイント一覧テーブル**（冒頭にまとめる）：
```
| メソッド | パス | 概要 | 認証 |
|---------|-----|------|------|
| GET    | /api/... | ... | 必要 |
| POST   | /api/... | ... | 必要 |
```

### Step 4: エラーハンドリング方針を定義する

以下のカテゴリごとに方針を記載する：

**① バリデーションエラー（4xx）**
- 入力値チェックはどこで行うか（フロントエンド / APIゲートウェイ / アプリ層）
- エラーレスポンスの統一フォーマット

**② 外部サービスエラー**
- タイムアウト値（秒）とリトライ回数
- リトライ対象 / 非対象の判断基準（冪等性があるかどうか）
- サーキットブレーカーの要否

**③ 非同期処理のエラー（SQS / EventBridge）**
- リトライ上限・DLQ への移動条件
- DLQ 監視・アラートの方針
- 手動リカバリー手順

**④ 予期しないエラー（500系）**
- ログ出力レベルと構造（JSON ログフォーマット）
- CloudWatch アラートの閾値
- ユーザーへの見せ方（技術情報を含めない）

### Step 5: 環境変数・設定値一覧を作成する

実装時に必要な環境変数を網羅する：

```
| 変数名 | 説明 | 設定箇所 | 例（ダミー） |
|--------|------|---------|------------|
| DATABASE_URL | Aurora 接続文字列 | Secrets Manager | postgresql://user:pass@host/db |
| CLAUDE_API_KEY | Claude API キー | Secrets Manager | sk-ant-... |
| SQS_QUEUE_URL | メッセージキューURL | ECS 環境変数 | https://sqs.ap-northeast-1... |
```

**設定箇所の分類**：
- `Secrets Manager`: 認証情報・APIキー等のシークレット
- `ECS 環境変数`: アプリケーション設定（URLなど）
- `SSM Parameter Store`: 環境ごとに変わる設定値（feature flag等）
- `コード内定数`: 変更不要な固定値

### Step 6: コンポーネント間インターフェースを定義する

複数のコンポーネント（Lambda / ECS / SQS）が連携する場合、データの受け渡し形式を定義する：

**SQS メッセージスキーマ**（非同期処理がある場合）：
```json
{
  "version": "1.0",
  "type": "{メッセージ種別}",
  "payload": {
    // フィールド定義
  },
  "metadata": {
    "account_id": "uuid",
    "timestamp": "ISO8601"
  }
}
```

**Lambda イベントスキーマ**（Lambda が別サービスから呼ばれる場合）も同様に定義する。

### Step 7: テスト仕様を定義する

**単体テスト（Unit Test）対象と方針を定義する**:

| テスト対象 | テストフレームワーク | カバレッジ目標 | テスト手法 |
|-----------|-----------------|------------|---------|
| バックエンド API ロジック | pytest | 80%+ | モック（unittest.mock / pytest-mock）で外部依存を分離 |
| LLM 分類・ビジネスルール | pytest | 90%+ | 境界値・分類ラベルごとの期待出力をパラメタライズ |
| フロントエンド コンポーネント | React Testing Library | 主要 UI | ユーザー操作シミュレーション |
| DB リポジトリ層 | pytest + testcontainers | 主要CRUD | テスト用 DB（Docker）または SQLite インメモリ |

**結合テスト（Integration Test）対象と方針を定義する**:

| テスト対象 | テスト環境 | 実施タイミング |
|-----------|----------|------------|
| API エンドポイント（DB込み） | Docker Compose（アプリ + DB） | CI で PR ごとに自動実行 |
| 外部サービス連携 | サンドボックス / テスト用アカウント | フェーズ0 PoC・定期実行 |
| SQS → Lambda / ECS 非同期フロー | LocalStack または実 AWS テスト環境 | フェーズ1 受け入れ前 |

**E2E / システムテスト対象と方針を定義する**:

| テスト対象フロー | ツール | 自動化有無 | 合格基準 |
|--------------|-------|----------|--------|
| メインハッピーパス | Playwright または pytest E2E | 自動（CI/CD ステージング） | エラーなく完了、レスポンスタイム要件を満たす |
| エラー・リトライフロー | pytest | 自動 | DLQ への移動・アラート発報を確認 |
| パフォーマンス（簡易） | k6 / Locust | 手動（リリース前） | 目標スループット・レイテンシを達成 |

**テスト環境構築方針**:
- CI（GitHub Actions）に単体テスト・結合テストを組み込む。PR マージ前に必ず通過
- ローカル開発用に `docker-compose.test.yml` でテスト用 DB / LocalStack を起動できる構成にする
- テストデータは `fixtures/` または `factory_boy` で管理し、テスト間の独立性を保つ

### Step 7.5: データ移行・インポート/エクスポート仕様を確認する（該当する場合）

既存システム（iOS アプリ等）からのデータ移行や JSON インポート/エクスポートが要件に含まれる場合:

**JSONキー名の確認**:
- 実際のサンプルファイル（エクスポートデータ等）を必ず参照し、キー名を**そのまま**使用する
- 自分でキー名を推測・命名しない（`translation` を `meaning` と間違える等の不一致が起きやすい）
- 代表的なキー名の例（iOSアプリ系）:
  ```json
  {
    "words": [{
      "id": "uuid",
      "word": "rarity",
      "meaning": "珍しさ・希少性",
      "phonetic": "ˈrɛrɪti",
      "sentences": [{
        "id": "uuid",
        "english": "This is a rare opportunity.",
        "japanese": "これは珍しい機会だ。",
        "category": "一般的な使い方"
      }]
    }]
  }
  ```
  → DBカラムとのマッピング例: `meaning` → `words.translation`、`english` → `sentences.sentence`、`japanese` → `sentences.translation`

**重複チェックの基準**:
- `id`（UUID）ベースを優先する（文字列フィールドは将来の変更・表記ゆれのリスクあり）
- UUID が存在しない場合に限り、文字列フィールドによる重複チェックを採用し、その旨を設計書に明記する

### Step 8: 04.detail-design.md を出力する

---

## Output Template

### 04.detail-design.md

```markdown
# 詳細設計書 — {システム名}

**生成日**: {日付}
**対象**: 実装担当者向け
**前提**: 02.design-doc.md / 03.db-design.md を読んでいること

---

## 1. API エンドポイント一覧

| メソッド | パス | 概要 | 認証 |
|---------|-----|------|------|
{全エンドポイントの一覧表}

---

## 2. シーケンス図

### 2-1. {メインフロー名}

```mermaid
sequenceDiagram
    {Step 2 の内容}
```

### 2-2. {認証フロー / エラーフロー 等}

...（フローごとに繰り返し）

---

## 3. API エンドポイント詳細

### {メソッド} {パス}
{Step 3 のフォーマットで全エンドポイント分}

---

## 4. エラーハンドリング方針

### 4-1. バリデーションエラー（4xx）
{Step 4 の内容}

### 4-2. 外部サービスエラー
...

### 4-3. 非同期処理のエラー
...

### 4-4. 予期しないエラー（500系）
...

---

## 5. 環境変数・設定値一覧

{Step 5 の表}

---

## 6. コンポーネント間インターフェース

{Step 6 の内容（非同期処理がある場合のみ）}

---

## 7. 実装上の注意事項

- {設計で決めたルールや落とし穴の注意書き}
- {ライブラリのバージョン指定など}

---

## 8. テスト仕様

### 8-1. 単体テスト（Unit Test）

| テスト対象 | フレームワーク | カバレッジ目標 | テスト手法 |
|-----------|-------------|------------|---------|
| {対象コンポーネント} | pytest / RTL | {XX%} | {モック / パラメタライズ / etc.} |

**主要テストケース（例）**:
- {ビジネスロジック}: `{入力条件}` → `{期待出力}`
- {境界値}: `{境界条件}` → `{期待動作}`
- {異常系}: `{エラー条件}` → `{例外 / エラーレスポンス}`

### 8-2. 結合テスト（Integration Test）

| テスト対象 | テスト環境 | 実施タイミング |
|-----------|----------|------------|
| {API エンドポイント} | Docker Compose（アプリ + DB） | CI（PR マージ前） |
| {外部サービス連携} | サンドボックス / モックサーバー | {フェーズ X 受け入れ前} |
| {非同期フロー（SQS等）} | LocalStack / 実 AWS テスト環境 | {フェーズ X 受け入れ前} |

### 8-3. E2E / システムテスト

| テスト対象フロー | ツール | 自動化 | 合格基準 |
|--------------|-------|------|--------|
| {メインフロー} | Playwright / pytest E2E | 自動（CI ステージング） | {具体的な基準} |
| {エラー・リトライフロー} | pytest | 自動 | DLQ 移動・アラート発報を確認 |
| {パフォーマンス（簡易）} | k6 / Locust | 手動（リリース前） | {スループット / レイテンシ目標} |

### 8-4. テスト環境構築

- **CI**: GitHub Actions で単体・結合テストを PR ごとに自動実行
- **ローカル環境**: `docker-compose.test.yml` でテスト用 DB / LocalStack 起動
- **テストデータ管理**: `fixtures/` または `factory_boy` でテスト間独立性を確保
- **カバレッジレポート**: `pytest-cov` で計測、PR コメントに自動投稿（目標: 全体 80%+）
```

---

## Quality Checklist

- [ ] シーケンス図にメインフローが含まれているか
- [ ] 全 API エンドポイントのリクエスト/レスポンス定義があるか
- [ ] エラーレスポンスの統一フォーマットが定義されているか
- [ ] SQS / EventBridge を使う場合、DLQ の方針が記載されているか
- [ ] 環境変数一覧に認証情報が含まれているか（Secrets Manager への誘導込み）
- [ ] タイムアウト値・リトライ回数が数値で記載されているか
- [ ] **セクション8（テスト仕様）が含まれているか**
- [ ] **単体・結合・E2E の3種類がすべて記載されているか**
- [ ] **CI への組み込み方針（GitHub Actions 等）が記載されているか**
- [ ] 実装者が読んで迷う箇所がないか（曖昧な表現を避ける）
- [ ] データインポート/エクスポートの仕様がある場合、実際のサンプルファイルのJSONキー名を確認して使用しているか
- [ ] 重複チェックはUUIDベースか（文字列フィールドによる場合はその旨と理由を明記）