Detailed design

詳細設計

目的

実装者(人間でもエージェントでも)が設計書を読んで「迷わず実装できる粒度」まで仕様を落とすこと。 すべてを事前に決めるのではなく、手戻りが高くつく部分だけを先に決めるのが原則。 エージェントに実装を委譲する場合はインターフェースとエラー仕様が特に重要となる。

使うタイミング

• [[architecture-design]] が確定し、個別モジュール・機能の実装に入る直前
• APIや関数シグネチャを複数人・複数エージェントが参照する並列開発の前
• 既存コードへの大きな改修で、影響範囲の境界を明確化したいとき
• [[task-breakdown]] でタスクを切り出す前の精度向上目的

進め方

1. スコープ確認: 対象機能・モジュールを1〜3個に絞る。広すぎる場合は分割して個別に設計する
2. モジュール分割と責務定義: 1モジュール1責務を原則とし、依存方向(上位→下位のみ)を図示する
3. インターフェース定義: 関数・APIのシグネチャ、入出力の型、例外・エラーコードを先に決める。実装は後
4. シーケンス設計: 主要フローと代替フローをMermaid sequenceDiagramで描く。分岐は3パターン以内に絞る
5. データ構造・DB定義: カラム・型・制約・インデックスを確定。スキーママイグレーションの影響も確認
6. エラーハンドリング方針: 想定エラーを列挙し、リトライ可否・フォールバック・ユーザー向けメッセージとログの分離を決める
7. 境界値・エッジケース列挙: テスト設計([[testing]])への入力になるため、ここで洗い出しておく
8. 命名・パターン確認: 既存コードの命名規約・ディレクトリ構成・エラー処理パターンに準拠しているか確認
9. 未決事項の明示: 実装中に判明することは「未決事項」として残し、過剰に先回りしない

成果物テンプレート

# 詳細設計書: {対象機能名}

## 対象機能
- 機能概要: 
- 関連チケット/要件: 
- 作成日 / 最終更新: 

---

## モジュール構成

| モジュール | 責務 | 依存先 |
|-----------|------|--------|
| FooService | ○○のビジネスロジック | FooRepository, BarClient |
| FooRepository | DBアクセスの抽象化 | DB |

依存方向: Controller → Service → Repository（逆方向の依存は禁止）

---

## インターフェース定義

### FooService.create

```typescript
// 入力
type CreateFooInput = {
  name: string;       // 1〜50文字
  ownerId: string;    // UUID
};

// 出力
type CreateFooResult = {
  id: string;
  createdAt: Date;
};

// 例外
// - ValidationError: name が空またはオーバー
// - ConflictError: 同名がすでに存在
// - UnexpectedError: DB障害など
function create(input: CreateFooInput): Promise<CreateFooResult>

---

シーケンス図

sequenceDiagram
  participant C as Client
  participant S as FooService
  participant R as FooRepository
  participant DB as Database

  C->>S: create(input)
  S->>S: validate(input)
  alt バリデーションエラー
    S-->>C: ValidationError
  end
  S->>R: findByName(input.name)
  R->>DB: SELECT
  alt 同名存在
    S-->>C: ConflictError
  end
  S->>R: insert(foo)
  R->>DB: INSERT
  S-->>C: CreateFooResult

---

データ定義

テーブル: foos

カラム	型	制約	備考
id	UUID	PK, NOT NULL
name	VARCHAR(50)	NOT NULL
owner_id	UUID	NOT NULL, FK→users.id
created_at	TIMESTAMPTZ	NOT NULL, DEFAULT NOW()

インデックス:

• idx_foos_owner_id on (owner_id)
• idx_foos_name_owner UNIQUE on (name, owner_id)

---

エラーハンドリング一覧

エラー種別	発生条件	リトライ	ユーザーメッセージ	ログレベル
ValidationError	入力不正	不可	「名前は1〜50文字で入力してください」	WARN
ConflictError	同名重複	不可	「同名の項目がすでに存在します」	INFO
UnexpectedError	DB障害等	自動3回	「しばらく経ってから再試行してください」	ERROR

---

エッジケース・境界値

• name が空文字・スペースのみ・51文字以上
• ownerId が存在しないユーザーを指す場合
• 同時リクエストによる競合（楽観ロック or UNIQUE制約で対処）
• DB接続タイムアウト時の部分コミット

---

未決事項

#	内容	判断期限	担当
1	ページネーション方式(offset vs cursor)	実装着手時	-

## チェックリスト

- [ ] 各モジュールの責務が1文で言えるか
- [ ] インターフェースの入出力型がすべて定義されているか
- [ ] エラーの種類・リトライ可否・ログレベルが決まっているか
- [ ] シーケンス図に主要な代替フロー(エラー・空結果)が含まれているか
- [ ] DBスキーマに制約・インデックスが明記されているか
- [ ] 境界値・エッジケースが少なくとも3つ列挙されているか
- [ ] 命名規約と既存コードのパターンを確認済みか
- [ ] 未決事項が「未決事項」セクションに明示されているか

## アンチパターン

- **実装をなぞるだけの設計書**: 「○○クラスの○○メソッドを呼ぶ」と書くだけで型・エラー・境界値の記載がない
- **エラー設計の後回し**: 「エラー処理は実装時に考える」→エラー体系が一貫しない・ユーザー向けメッセージが散乱する
- **インターフェース未定のまま並列実装着手**: 型が決まる前に複数エージェントが実装を始め、後から型合わせで大量修正が発生
- **過剰設計**: 実装コードをそのまま疑似コードで書き起こした設計書。設計コストが無駄になり実装者も読まない
- **単一巨大モジュール**: 責務を分離せず1つのサービスに詰め込む。変更時の影響範囲が把握できなくなる

## モデル委譲ガイド

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

| 作業 | 担当モデル | 理由 |
|------|-----------|------|
| モジュール分割・依存方向の判断 | 司令塔 | アーキテクチャ全体を俯瞰した判断が必要 |
| インターフェース設計の最終承認 | 司令塔 | エージェント間の契約になるため |
| 複雑な処理のシーケンス設計 | Opus | 分岐・エラーフローの網羅的な推論 |
| エラーハンドリング方針の詳細化 | Opus | エッジケースの深い検討が必要 |
| 定型部分の設計書ドラフト作成 | Sonnet | テンプレート埋め・Mermaid図生成 |
| 既存コードのパターン調査 | Sonnet | コード検索・読解タスク |
| 型定義・既存インターフェースの収集 | Haiku | grep・ファイル読み込みなどの単純タスク |

## 関連スキル

- [[requirements-definition]] — 詳細設計の前提となる機能要件の確定
- [[architecture-design]] — モジュール構成の上位設計
- [[screen-design]] — UI側のインターフェース仕様（APIと合わせて確認）
- [[implementation]] — 詳細設計書を入力として実装を委譲
- [[testing]] — エッジケース一覧をテストケース設計に引き継ぐ
- [[task-breakdown]] — 詳細設計後にタスクを実装単位に分割
- [[non-functional-requirements]] — パフォーマンス・セキュリティ要件が設計に影響する場合
- [[orchestration]] — 複数エージェントへの実装委譲フロー