ヒアリングからAPI案まで -- メモを構造化し、ユーザーストーリーとAPI設計を効率的に導出する
要件定義はヒアリングから始まり、要件整理、ユーザーストーリー化、機能一覧、API設計、レビューへと進む。従来は各工程が手作業で、特にメモの整理とストーリー化に時間がかかっていた。AIはこの「変換作業」を高速化する。
| 工程 | 従来の作業 | AI補助の内容 | 時間削減 |
|---|---|---|---|
| ヒアリング | 手書きメモ、議事録作成 | 音声文字起こし、要点自動抽出 | 60-70% |
| 要件整理 | メモをExcelに手入力、分類 | カテゴリ自動分類、重複検出、優先度提案 | 50-60% |
| ユーザーストーリー作成 | 要件を1つずつストーリー形式に変換 | テンプレートへの自動変換、Acceptance Criteria生成 | 60-70% |
| 機能一覧 | ストーリーから機能を手動で洗い出し | ストーリーの分解、CRUD操作の自動列挙 | 40-50% |
| API設計 | 機能一覧からエンドポイントを手設計 | エンドポイント候補の自動生成、OpenAPI Spec出力 | 40-50% |
| レビュー | 手動で要件の漏れ・矛盾をチェック | AIによる網羅性チェック、矛盾検出、非機能要件の補完提案 | 30-40% |
同じ規模のプロジェクト（画面数15、API数30程度のWebアプリ）で要件定義にかかる工数を比較する。AIは「人間の判断が要る工程」を代替するのではなく、「変換・整理の手作業」を圧縮する。
時間削減の数値はAIの出力品質に依存する。プロンプトの設計とドメイン知識の注入が不十分だと、修正工数が膨らんで効果が薄れる。「AIに丸投げ」ではなく「AIの出力を叩き台にして人間が仕上げる」が正しいスタンス。
ヒアリングで集まるメモは断片的で、同じ話題が複数箇所に散らばっていることが多い。AIはこの混沌としたメモをカテゴリに分類し、構造化された要件リストに変換する。
| カテゴリ | 要件 | 優先度 | フェーズ |
|---|---|---|---|
| 商品管理 | 商品の名前・カテゴリによる検索機能 | High | Phase 1 |
| 商品管理 | 商品画像の複数登録 | Medium | Phase 1 |
| 商品管理 | 管理画面からの在庫更新 | High | Phase 1 |
| 注文管理 | 注文確認メールの自動送信 | High | Phase 1 |
| 注文管理 | 注文履歴の閲覧 | Medium | Phase 1 |
| 決済 | クレジットカード決済対応 | High | Phase 1 |
| 決済 | コンビニ払い対応 | Medium | Phase 1 |
| ユーザー | ゲスト購入（会員登録不要での購入） | High | Phase 1 |
| 管理・分析 | 月次売上レポート | Medium | Phase 1 |
| ロイヤルティ | ポイント制度 | Low | Phase 2 |
| 非機能要件 | モバイルレスポンシブ対応 | High | Phase 1 |
AIは「ポイント制度は次のフェーズ」という発言からPhase 2に分類し、「スマホでも使えないと困る」を非機能要件として抽出している。人間のメモでは明示されない暗黙の分類を推論で補う。ただし、推論が間違っている可能性があるため、出力は必ず人間が確認する。
構造化された要件リストをユーザーストーリー形式に変換する。「As a ～ / I want to ～ / So that ～」のテンプレートに当てはめ、Acceptance Criteria（受け入れ条件）もセットで生成する。
US-001: 商品検索
As a 購入者
I want to 商品名やカテゴリで商品を検索したい
So that 大量の商品の中から目的の商品を素早く見つけられる
Acceptance Criteria:
- 商品名の部分一致検索ができる
- カテゴリによるフィルタリングができる
- 検索結果が0件の場合、適切なメッセージを表示する
- 検索結果が20件以上の場合、ページネーションを表示する
- 検索はレスポンス2秒以内で完了する
US-002: ゲスト購入
As a 初めてサイトを訪れた利用者
I want to 会員登録せずに商品を購入したい
So that 面倒な登録手続きなしにすぐ買い物ができる
Acceptance Criteria:
- メールアドレスと配送先情報の入力だけで注文が完了する
- ゲスト購入後に会員登録への導線を表示する
- ゲスト購入でも注文確認メールが届く
- ゲスト購入の注文履歴は注文番号とメールで確認できる
AIは元の要件に書かれていない情報も推論で補完している。「ページネーション」「レスポンス2秒以内」「会員登録への導線」は元のメモにはなかった内容。こうした補完は便利だが、プロジェクトの方針と異なる可能性があるため確認が必須。
生成したユーザーストーリーをユーザー行動の時系列に沿って並べ、エピック単位でグループ化する。横軸がユーザー行動の流れ、縦軸が優先度。上の行がMVP、下の行が後回しの機能。
| フェーズ | 商品閲覧 | カートと注文 | 決済 | 注文後 |
|---|---|---|---|---|
| Epic | 商品の発見 | 購入プロセス | 支払い | アフターサービス |
| MVP (Phase 1) |
商品検索MVP カテゴリ一覧MVP 商品詳細表示MVP |
カート追加MVP ゲスト購入MVP 数量変更MVP |
クレジットカードMVP コンビニ払いMVP |
注文確認メールMVP 注文履歴MVP |
| 拡張 (Phase 1.5) |
画像複数表示拡張 お気に入り拡張 |
クーポン適用拡張 | 電子マネー拡張 | 売上レポート拡張 在庫管理拡張 |
| 将来 (Phase 2) |
レコメンド将来 | 定期購入将来 | 後払い将来 | ポイント制度将来 レビュー機能将来 |
AIにストーリーマッピングを依頼すると、ユーザー行動の流れに沿った配置とMVP/拡張の振り分けを提案してくれる。ただし、ビジネス判断が必要な優先順位（「コンビニ払いはMVPか拡張か」など）は人間が最終決定する。
ユーザーストーリーと機能一覧が揃ったら、API設計に進む。AIは要件からエンドポイント候補を自動生成し、リクエスト/レスポンスの型定義、さらにはOpenAPI Specまで出力できる。
| HTTPメソッド | エンドポイント | 機能 | 認証 |
|---|---|---|---|
| GET | /api/v1/products | 商品一覧取得（検索・フィルタ対応） | 不要 |
| GET | /api/v1/products/{id} | 商品詳細取得 | 不要 |
| POST | /api/v1/cart/items | カートに商品追加 | 任意（ゲスト可） |
| PATCH | /api/v1/cart/items/{id} | カート内商品の数量変更 | 任意（ゲスト可） |
| DELETE | /api/v1/cart/items/{id} | カートから商品を削除 | 任意（ゲスト可） |
| POST | /api/v1/orders | 注文作成 | 任意（ゲスト可） |
| GET | /api/v1/orders/{id} | 注文詳細取得 | 必須 |
| GET | /api/v1/orders | 注文履歴一覧取得 | 必須 |
| POST | /api/v1/payments | 決済処理実行 | 必須 |
| POST | /api/v1/admin/products | 商品登録（管理者） | 管理者のみ |
| PATCH | /api/v1/admin/products/{id}/stock | 在庫更新（管理者） | 管理者のみ |
AIにAPI設計を任せる前に、RESTの基本原則を押さえておく。AIの出力がこの原則に沿っているかを確認する目として使う。
| メソッド | 用途 | 冪等性 | リクエストボディ | 例 |
|---|---|---|---|---|
| GET | リソースの取得 | あり | なし | GET /products -- 商品一覧取得 |
| POST | リソースの作成 | なし | あり | POST /products -- 商品新規作成 |
| PUT | リソースの全体更新 | あり | あり | PUT /products/123 -- 商品全項目更新 |
| PATCH | リソースの部分更新 | 条件付き | あり | PATCH /products/123 -- 商品一部更新 |
| DELETE | リソースの削除 | あり | 通常なし | DELETE /products/123 -- 商品削除 |
| コード | 名称 | 使用場面 |
|---|---|---|
| 200 | OK | GET, PUT, PATCH, DELETEの成功 |
| 201 | Created | POSTによるリソース作成成功。Locationヘッダで新リソースのURLを返す |
| 204 | No Content | DELETE成功時にボディを返さない場合 |
| 400 | Bad Request | リクエストの構文エラー、バリデーション失敗 |
| 401 | Unauthorized | 認証が必要だが認証情報がない、または無効 |
| 403 | Forbidden | 認証済みだが権限がない |
| 404 | Not Found | 指定されたリソースが存在しない |
| 409 | Conflict | リソースの状態と矛盾する操作（在庫切れの商品を注文など） |
| 422 | Unprocessable Entity | 構文は正しいがビジネスルール違反 |
| 500 | Internal Server Error | サーバー側の予期しないエラー |
AIが生成した要件定義やAPI設計を鵜呑みにしてはいけない。以下のチェックリストで出力を検証し、漏れや矛盾を人間が補完する。
| カテゴリ | 確認項目 | AIが見落としやすい例 |
|---|---|---|
| 性能 | レスポンスタイム、スループット、同時接続数 | セール時のアクセス集中（通常の10倍を想定する等） |
| セキュリティ | 認証方式、データ暗号化、CSRF対策 | PCI DSS準拠（クレジットカード決済を扱う場合） |
| 可用性 | SLO目標、障害時のフォールバック | メンテナンスウィンドウの設定、決済処理中の二重注文防止 |
| 運用 | ログ設計、監視項目、バックアップ方針 | 個人情報のマスキング、ログの保持期間 |
| 法規制 | 個人情報保護法、特定商取引法 | 退会時のデータ削除義務、特商法に基づく表示 |
ここまでの内容を1つのシナリオで通しで見る。ECサイトの注文機能を題材に、ヒアリングメモからAPI設計までの変換プロセスを実演する。
| ID | カテゴリ | 要件 | 優先度 |
|---|---|---|---|
| R-001 | 注文 | カートの商品をまとめて注文できる | High |
| R-002 | 注文 | 注文時に配送先住所を入力する | High |
| R-003 | 注文 | 前回の配送先住所を自動入力（会員ユーザーのみ） | Medium |
| R-004 | 通知 | 注文確定時に確認メール送信 | High |
| R-005 | 在庫 | 在庫なし商品の注文をブロック | High |
| R-006 | 注文 | 発送前の注文キャンセル機能 | Medium |
| R-007 | 管理 | 全注文の一覧表示（管理者向け） | High |
| R-008 | 管理 | 配送ステータスの更新（準備中/発送済み/配達完了） | High |
US-006: 注文キャンセル
As a 注文した購入者
I want to 発送前であれば注文をキャンセルしたい
So that 誤って注文した場合や不要になった場合に対処できる
Acceptance Criteria:
- 配送ステータスが「準備中」の注文のみキャンセル可能
- キャンセル実行後、在庫数が元に戻る
- キャンセル完了メールが送信される
- 決済済みの場合、返金処理が自動で開始される
| メソッド | エンドポイント | 対応要件 | 備考 |
|---|---|---|---|
| POST | /api/v1/orders | R-001, R-002, R-005 | 在庫チェック後に注文作成。在庫不足なら409を返す |
| GET | /api/v1/users/{id}/addresses | R-003 | 会員の配送先住所一覧。最後に使った住所をdefaultフラグで識別 |
| PATCH | /api/v1/orders/{id}/cancel | R-006 | ステータスが「準備中」でなければ422を返す。在庫を戻す処理を含む |
| GET | /api/v1/admin/orders | R-007 | 管理者専用。ページネーション、ステータスフィルタ対応 |
| PATCH | /api/v1/admin/orders/{id}/status | R-008 | 配送ステータス更新。ステータス遷移のバリデーションあり |
このシナリオでは8つのヒアリングメモから8つの要件を抽出し、それを元にユーザーストーリーとAPIエンドポイントを導出した。AI出力のたびに人間が確認・修正するフローが一連の品質を担保する。全体を通すと、手動で1日かかる作業が半日で完了する。