🔬 詳細設計に特化したAIプロンプト術【コピペOK】

はじめに

「基本設計は終わったのに、詳細設計で手が止まる…」
「クラス設計・メソッド設計まで落とし込む粒度が分からない…」
「詳細設計書を書いてもレビューで『実装者が迷う』と言われる…」
「設計書を書いた人しか実装できない属人化が起きている…」

詳細設計は**「基本設計の方針を、コードに直訳できるレベルまで具体化する」**フェーズです。
ここが甘いと、実装フェーズで毎日「これって仕様ですか？」が飛び交います。

このプロンプト集は、クラス設計・メソッド設計・アルゴリズム設計・SQL設計・画面詳細設計・テスト設計まで、実装者が迷わない詳細設計書を高速に作るために設計しました。

---

🗺️ 詳細設計の全体フロー

[クラス・モジュール設計]
→ 処理をクラス・関数に分割し、責務を定義する
      ↓
[メソッド・関数設計]
→ 各メソッドの入出力・処理ロジックを定義する
      ↓
[アルゴリズム・処理ロジック設計]
→ 複雑な処理の手順・条件分岐を定義する
      ↓
[SQL・クエリ設計]
→ DB操作の具体的なSQL・インデックス設計を定義する
      ↓
[画面詳細設計]
→ 画面の動的挙動・表示ロジックを定義する
      ↓
[テスト設計]
→ 単体テスト・統合テストの設計を行う
      ↓
[詳細設計レビュー]
→ 実装可能レベルかを確認し合意する

---

フェーズ1：クラス・モジュール設計

✅ プロンプト①：機能をクラス・モジュールに分割する

以下の機能設計をもとに、クラス・モジュール構成を設計してください。

【機能設計（基本設計書の該当部分）】
（貼り付け）

【アーキテクチャ方針】
（例：レイヤードアーキテクチャ、DI使用、Pythonで実装）

【出力内容】

■ クラス一覧
| クラス名 | 所属レイヤー | 責務（1文で） | 依存するクラス |
|--------|-----------|-----------|------------|

■ 各クラスの詳細設計
---
クラス名：UserRegistrationService
所属レイヤー：Application層
責務：ユーザー登録のユースケースを orchestrate する
依存：UserRepository, PasswordHasher, EmailNotifier

フィールド（インスタンス変数）：
| 変数名 | 型 | 説明 | 初期化タイミング |
|------|-----|-----|--------------|

メソッド一覧：
| メソッド名 | 公開/非公開 | 引数 | 戻り値 | 処理概要 |
|---------|---------|-----|------|--------|
| register | public | RegisterInput | RegisterResult | ユーザー登録処理 |
| validate | private | RegisterInput | ValidationResult | 入力検証 |
---

■ クラス関連図（Mermaid記法）
```mermaid
classDiagram
  class UserRegistrationService {
    -user_repository: UserRepository
    -password_hasher: PasswordHasher
    +register(input: RegisterInput) RegisterResult
    -validate(input: RegisterInput) ValidationResult
  }
  UserRegistrationService --> UserRepository
  UserRegistrationService --> PasswordHasher

■ 設計の判断メモ

• なぜこの分割にしたか
• 迷った箇所と採用しなかった案

---

### ✅ プロンプト②：SOLID原則に照らして設計を見直す

以下のクラス設計について、SOLID原則の観点でレビューしてください。

【クラス設計（コード or 設計書）】
（貼り付け）

【出力内容】
各原則について「○ 準拠 / △ 要改善 / × 違反」と具体的な理由を述べてください：

■ S：単一責任の原則（SRP）

• 評価：
• 理由：
• 改善案（問題がある場合）：

■ O：開放閉鎖の原則（OCP）

• 評価：
• 理由：
• 改善案：

■ L：リスコフの置換原則（LSP）

• 評価：
• 理由：
• 改善案：

■ I：インターフェース分離の原則（ISP）

• 評価：
• 理由：
• 改善案：

■ D：依存性逆転の原則（DIP）

• 評価：
• 理由：
• 改善案：

■ 総合評価と優先度の高い改善アクション（Top3）

「この設計でどういう変更が来たときに困るか」を具体的なシナリオで示してください。

---

### ✅ プロンプト③：デザインパターンの適用を検討する

以下の設計課題に対して、適用できるデザインパターンを提案してください。

【設計課題・現状の設計】
（貼り付け）

【技術スタック】
（例：Python 3.11）

【出力内容】
各候補パターンについて：

■ 推奨パターン名

• 解決できる問題：
• この設計への適用方法：
• 実装例（コード or 擬似コード）：
• メリット：
• デメリット・注意点：
• 適用のタイミング（今すぐ / 将来の拡張時でよい）：

■ 適用しないほうがよいパターンと理由
（過剰設計になるリスクがあるものも明示）

■ 最終推奨と判断根拠
「このチーム・この規模ではどこまでやるか」の現実的な落とし所も示してください。

---

## フェーズ2：メソッド・関数設計

### ✅ プロンプト④：メソッドの詳細仕様を設計する

以下のメソッドについて、詳細仕様を設計してください。

【メソッド概要】

• クラス名：
• メソッド名：
• 目的（1文で）：
• 呼び出し元：

【出力内容】

■ メソッド仕様書

シグネチャ：

def method_name(param1: Type, param2: Type) -> ReturnType:

引数定義：

引数名	型	必須/任意	説明	バリデーション	不正値の扱い

戻り値：

型	説明	正常時	異常時

例外・エラー：

例外クラス名	発生条件	メッセージ

処理ロジック（擬似コード）：

1. 引数バリデーション
2. 〇〇を取得する
3. 条件によって処理を分岐
   - 条件A の場合：〇〇する
   - 条件B の場合：△△する
4. 結果を返す

副作用（DBへの書き込み・外部APIコール・ファイル操作など）：
テスト時の注意点（モック対象など）：

■ 使用例（呼び出し側コード）

# 正常系
result = service.method_name(valid_param1, valid_param2)

# 異常系
try:
    result = service.method_name(invalid_param, ...)
except SpecificException as e:
    ...

---

### ✅ プロンプト⑤：複数メソッドの責務分割を設計する

以下の「1つの関数に処理が集中している」コードを、
責務を分割したメソッド設計に再設計してください。

【現状のコード or 処理概要】
（貼り付け）

【問題点（分かっていれば）】
（例：1メソッドが200行ある、テストが書けない、変更のたびにバグが出る）

【出力内容】

■ 分割方針と根拠
（何を基準に分割するか：処理の抽象度 / 副作用の有無 / 再利用性など）

■ 分割後のメソッド一覧

メソッド名	責務	引数	戻り値	副作用	テスト容易性

■ 分割後の処理フロー
（各メソッドがどの順番で呼ばれるか、コード例で示す）

■ 分割前後の比較

• テスタビリティの変化
• 変更の影響範囲の変化
• 可読性の変化

■ 分割しすぎに注意が必要な箇所と理由

---

## フェーズ3：アルゴリズム・処理ロジック設計

### ✅ プロンプト⑥：複雑な処理ロジックを設計する

以下の処理要件をもとに、アルゴリズム・処理ロジックを設計してください。

【処理要件】
（例：複数条件に基づいてユーザーランクを算出する）

【入力データの形式・サンプル】
（具体的なデータ例を貼り付け）

【期待する出力】
（期待する結果のサンプル）

【出力内容】

■ アルゴリズムの選定と理由
（複数案がある場合は比較して選定）

■ 処理ロジック詳細（フローチャート / 擬似コード）

FUNCTION calculate_rank(user_data):
  IF user_data.purchase_amount >= 100000 THEN
    SET rank = "GOLD"
  ELSE IF user_data.purchase_amount >= 30000 THEN
    SET rank = "SILVER"
  ELSE
    SET rank = "BRONZE"
  END IF

  IF user_data.is_premium == True THEN
    SET rank = upgrade(rank)
  END IF

  RETURN rank

■ 条件分岐の真理値表

条件A	条件B	条件C	結果

■ 境界値・エッジケースの設計

ケース名	入力	期待結果	対処方法

■ 計算量の分析（時間計算量・空間計算量）
■ パフォーマンス最適化の余地（あれば）

---

### ✅ プロンプト⑦：状態遷移を設計する

以下のエンティティの状態遷移を詳細設計してください。

【エンティティ名と状態の概要】
（例：注文エンティティ。未払い → 支払い済み → 配送中 → 完了 / キャンセル）

【出力内容】

■ 状態一覧

状態ID	状態名	説明	初期状態か	終了状態か

■ 状態遷移図（Mermaid記法）

■ 遷移条件の詳細定義

遷移元	遷移先	トリガー	遷移条件（ガード）	遷移時の処理（アクション）	権限

■ 不正遷移の扱い

• 許可されていない遷移を試みた場合の挙動
• エラーメッセージとHTTPステータス

■ 状態ごとの操作制限マトリクス

操作	未払い	支払い済み	配送中	完了	キャンセル
編集	○	×	×	×	×
キャンセル	○	○	×	×	×

---

## フェーズ4：SQL・クエリ設計

### ✅ プロンプト⑧：複雑なSQLを設計する

以下の処理要件をもとに、SQLを設計してください。

【処理要件】
（例：過去30日間の商品カテゴリ別売上ランキングTop10を取得する）

【テーブル定義】
（関連するテーブルの構造を貼り付け）

【出力内容】

■ SQL（コメント付き・可読性重視）

-- 過去30日間のカテゴリ別売上ランキングTop10
SELECT
  c.category_name,
  COUNT(DISTINCT o.order_id) AS order_count,
  SUM(oi.quantity * oi.unit_price) AS total_sales,
  RANK() OVER (ORDER BY SUM(oi.quantity * oi.unit_price) DESC) AS sales_rank
FROM
  orders o
  INNER JOIN order_items oi ON o.order_id = oi.order_id
  INNER JOIN products p ON oi.product_id = p.product_id
  INNER JOIN categories c ON p.category_id = c.category_id
WHERE
  o.ordered_at >= CURRENT_DATE - INTERVAL '30 days'
  AND o.status != 'cancelled'
GROUP BY
  c.category_id, c.category_name
ORDER BY
  sales_rank
LIMIT 10;

■ SQL解説

• JOINの設計理由（なぜINNER JOINか、LEFT JOINではないか）
• WHERE条件の設計意図
• 集計・ウィンドウ関数の使い方の説明

■ パフォーマンス考慮

• このSQLが遅くなる条件
• 推奨インデックス（テーブル・カラム・インデックス種別）
• EXPLAIN結果で確認すべきポイント

■ エッジケース

• データが0件の場合の挙動
• NULLが含まれる場合の挙動
• 大量データ時の対策

---

### ✅ プロンプト⑨：インデックス設計をする

以下のテーブル設計・クエリパターンをもとに、インデックス設計を行ってください。

【テーブル定義】
（貼り付け）

【想定するクエリパターン（実行頻度順に）】

1. （よく実行するクエリ1）
2. （よく実行するクエリ2）
3. （よく実行するクエリ3）

【データ量・増加傾向】
（例：現在100万件、月10万件ペースで増加）

【出力内容】

■ 推奨インデックス一覧

テーブル名	インデックス名	カラム	種別	作成理由	対応クエリ

■ 各インデックスのDDL

CREATE INDEX idx_orders_user_status
  ON orders (user_id, status)
  WHERE status != 'completed';

■ インデックスのトレードオフ

• 検索パフォーマンスの改善見込み
• 書き込みパフォーマンスへの影響
• ストレージ使用量の増加見込み

■ 不要なインデックスの検出
（既存インデックスがある場合、削除候補と理由）

■ インデックスの有効性を確認するためのEXPLAINの読み方

---

### ✅ プロンプト⑩：マイグレーション設計をする

以下のDB変更をもとに、マイグレーション設計を行ってください。

【変更内容】
（例：usersテーブルにphoneカラムを追加、既存データへのデフォルト値設定が必要）

【現在のテーブル定義】
（DDLを貼り付け）

【本番データの状況】
（例：レコード数50万件、24時間無停止運用が必要）

【出力内容】

■ マイグレーション手順（ダウンタイムなしの場合）
ステップ1：（安全な変更）
ステップ2：（アプリケーション側の対応）
ステップ3：（最終的なDB変更）

■ マイグレーションSQL（Up）

-- UP: カラム追加（NULLABLEで追加し、後からNOT NULL化する2段階方式）
ALTER TABLE users ADD COLUMN phone VARCHAR(20) NULL;

■ ロールバックSQL（Down）

-- DOWN: カラム削除
ALTER TABLE users DROP COLUMN phone;

■ マイグレーション実行時のリスクと対策

リスク	発生条件	対策
ロック取得によるタイムアウト
大量データの一括更新による負荷

■ 実行前チェックリスト
■ 実行後の確認事項

---

## フェーズ5：画面詳細設計

### ✅ プロンプト⑪：画面の動的挙動・表示ロジックを設計する

以下の画面について、動的挙動・表示ロジックを詳細設計してください。

【画面名・基本設計での定義】
（貼り付け）

【出力内容】

■ 初期表示ロジック

• 画面表示時にAPIから取得するデータ一覧
• 取得データのマッピング（APIレスポンス → 画面要素）
• 初期値・デフォルト値の設定ロジック
• ローディング状態の表示制御

■ イベント別の処理設計

イベント	トリガー	処理内容	UIの変化	API呼び出し
フォーム入力変更	onChange	バリデーション実行	エラー表示更新	なし
検索ボタン押下	onClick	API呼び出し	ローディング表示	GET /api/search

■ 条件による表示制御ロジック

条件	表示する要素	非表示にする要素	備考
管理者ロールの場合	削除ボタン
データ0件の場合	空表示メッセージ	テーブル本体

■ フォームのリアルタイムバリデーション設計

• バリデーション実行タイミング（onBlur / onChange / onSubmit）
• エラーメッセージの表示場所・スタイル
• 複数フィールド間の相関バリデーション

■ 非同期処理の状態管理
（Loading / Success / Error / Empty の4状態の表示設計）

---

### ✅ プロンプト⑫：テーブル・リスト表示の詳細設計をする

以下の一覧画面のテーブル・リスト表示を詳細設計してください。

【一覧画面の要件】
（貼り付け）

【出力内容】

■ テーブルカラム定義

カラム名（表示）	バインドするデータ項目	データ型	表示フォーマット	ソート可否	幅

■ ソート設計

• デフォルトソート条件
• ソート変更時のAPI呼び出し仕様
• 複数カラムソートの可否と仕様

■ 検索・フィルタ設計

フィルタ項目	UI部品	検索方式（完全一致 / 前方一致 / 範囲）	APIパラメータ名

■ ページネーション設計

• 方式（ページ番号型 / 無限スクロール / Load More）
• 1ページの表示件数（デフォルト / 変更可否）
• APIのページネーションパラメータ仕様

■ 行操作の設計

操作名	表示条件	操作後の画面動作

■ 大量データ時のパフォーマンス考慮

---

## フェーズ6：テスト設計

### ✅ プロンプト⑬：単体テストの設計をする

以下のクラス・メソッドに対して、単体テスト設計を行ってください。

【対象クラス・メソッド（コード or 設計書）】
（貼り付け）

【テストフレームワーク】
（例：Python / pytest）

【出力内容】

■ テスト戦略

• テスト対象の責務と、テストで確認すべきこと
• モック対象（外部依存 / DBアクセス / 外部API）
• テストデータの方針

■ テストケース一覧

テストID	テスト名	種別	入力条件	期待結果	モック設定
TC-001	正常登録	正常系	有効な入力値	ユーザーが作成されRegistered返却	DBへの保存を確認
TC-002	メールアドレス重複	異常系	既存メール	DuplicateEmailError発生	DB検索でTrue返却

■ テストコード（主要ケース）

import pytest
from unittest.mock import Mock, patch

class TestUserRegistrationService:

    def setup_method(self):
        self.user_repository = Mock()
        self.password_hasher = Mock()
        self.service = UserRegistrationService(
            user_repository=self.user_repository,
            password_hasher=self.password_hasher
        )

    def test_register_success(self):
        """正常系：有効な入力でユーザー登録が成功する"""
        # Arrange
        self.user_repository.exists_by_email.return_value = False
        self.password_hasher.hash.return_value = "hashed_password"

        # Act
        result = self.service.register(
            RegisterInput(email="[e-mail]", password="Pass1234!")
        )

        # Assert
        assert result.is_success
        self.user_repository.save.assert_called_once()

    def test_register_duplicate_email_raises_error(self):
        """異常系：重複メールアドレスでDuplicateEmailErrorが発生する"""
        # Arrange
        self.user_repository.exists_by_email.return_value = True

        # Act & Assert
        with pytest.raises(DuplicateEmailError):
            self.service.register(
                RegisterInput(email="[e-mail]", password="Pass1234!")
            )

■ テストカバレッジ方針

• 必須カバレッジ目標（%）
• カバレッジが不要な箇所と理由

---

### ✅ プロンプト⑭：テストデータ設計をする

以下のテスト対象機能に対して、テストデータを設計してください。

【テスト対象機能・ロジック】
（貼り付け）

【DBスキーマ（関連テーブル）】
（貼り付け）

【出力内容】

■ テストデータ設計方針

• フィクスチャの粒度（テストクラス単位 / テストメソッド単位）
• テストDB / モックの使い分け方針
• テストデータのクリーンアップ方針

■ テストデータ一覧

データID	用途	テーブル	データ内容	使用するテストケース

■ テストフィクスチャ（コード）

import pytest

@pytest.fixture
def normal_user(db_session):
    """通常ユーザー（テスト基本データ）"""
    user = User(
        id=1,
        email="[e-mail]",
        name="テストユーザー",
        role="user",
        is_active=True
    )
    db_session.add(user)
    db_session.commit()
    return user

@pytest.fixture
def admin_user(db_session):
    """管理者ユーザー"""
    user = User(
        id=2,
        email="[e-mail]",
        name="管理者",
        role="admin",
        is_active=True
    )
    db_session.add(user)
    db_session.commit()
    return user

■ 境界値・エッジケース用テストデータの設計
（最大文字数・ゼロ件・最大件数・NULL値・特殊文字など）

---

## フェーズ7：詳細設計レビュー

### ✅ プロンプト⑮：詳細設計の品質チェックをする

以下の詳細設計書を読み、実装フェーズに進んでよいかチェックしてください。

【詳細設計書（または該当部分）】
（貼り付け）

【チェック観点】

□ 実装可能性チェック

• コードに直訳できるレベルまで具体化されているか
• 実装者が判断を迷う箇所がないか
• 「あとで考える」「TBD」が残っていないか

□ 処理ロジックの完全性

• 正常系・異常系・境界値がすべて設計されているか
• 例外・エラーの処理が定義されているか
• NULL・空・0件の場合の挙動が定義されているか

□ 整合性チェック

• 基本設計との矛盾がないか
• クラス間・メソッド間のインターフェースが一致しているか
• DB設計とロジック設計が整合しているか

□ テスタビリティチェック

• 単体テストが書きやすい設計になっているか
• 外部依存が適切に分離されているか
• テストケースを列挙できるレベルまで仕様が明確か

□ 性能・セキュリティチェック

• N+1クエリ等のパフォーマンス問題が設計に含まれていないか
• 入力値の検証が適切に設計されているか
• SQLインジェクション・XSSの対策が設計に含まれているか

【出力形式】
問題点ごとに「深刻度（High/Medium/Low）・該当箇所・問題内容・修正案」をセットで。
「このまま実装に進んでよいか」の最終判定と、進める場合の条件を述べてください。

---

## 🎁 詳細設計プロンプト強化ワード

| 状況 | 追加ワード |
|------|----------|
| 実装者が迷わないようにしたい | 「コードに直訳できるレベルまで具体化して」 |
| テストを書きやすくしたい | 「テスタビリティを考慮した設計で。副作用を明示して」 |
| 将来の変更に備えたい | 「変更が生じた場合の影響範囲が最小になる設計で」 |
| パフォーマンスを考慮したい | 「計算量・DBアクセス回数・N+1の観点も含めて」 |
| セキュリティを考慮したい | 「OWASP Top10の観点で脆弱性リスクも確認して」 |

---

## 詳細設計の3つの罠と対策

### 罠1：「分かっている前提」で書いてしまう
設計者本人は分かっているが、他の実装者が読んでも分からない設計書。
**対策：** プロンプト⑮の品質チェックを、**設計書を書いていない人がレビューするつもりで**実施する。

### 罠2：テスト設計を後回しにする
「実装してからテストを考える」罠。テストが書けない設計は設計ミスのサイン。
**対策：** プロンプト⑬の単体テスト設計を、コード実装の**前に**行う（TDDの思想）。

### 罠3：エッジケースを楽観視する
NULL・空・0件・最大値・権限違いのケースを「まあ大丈夫だろう」で済ませる罠。
**対策：** プロンプト⑥の条件分岐設計で**真理値表を必ず作成**し、全パターンを網羅する。

---

## おわりに

詳細設計は「設計書を書く」のではなく、**「実装者への手紙を書く」**行為です。
未来の自分・チームメンバーが迷わず・手戻りなく実装できる状態を作ることがゴールです。

AIで初版を高速に作り、浮いた時間をエッジケースの洗い出しとレビューに使いましょう～