【プロンプト不要】Spec Kitがもたらす仕様駆動AIコーディング

Project summary:
地域の無料ワークショップや体験イベントの参加枠を、スマホから簡単に予約できるミニアプリ。参加者は日時と会場を選んで申し込み、主催側はダッシュボードで申込状況とキャンセル待ちを管理する。目的は「申し込みの分かりやすさ」と「当日運営の負担軽減」。

Users:

Participant (参加者)

Organizer (主催スタッフ)

Admin (運営責任者)

User journeys:

Participant: 告知ページのリンクからLPへ → 会場と日時を選択 → 利用規約と注意事項に同意 → 名前とメールを入力 → 予約確定 → 開催前にリマインド通知を受信。

Organizer: ダッシュボードにログイン → 開催ごとの申込率と欠員を確認 → キャンセル発生時に繰り上げ処理をワンクリックで実行。

Admin: 期間・会場別の参加率、キャンセル率、No-showを週次で把握。

Success criteria:

予約完了までの平均所要時間が1分未満。

No-show率が前回開催比で20%低下。

主催側の当日までの手動作業が50%削減。

Acceptance criteria:

二重予約は不可。定員到達の枠は選択不可。

キャンセル待ちは先着順で自動繰り上げ通知。

取得する個人情報は最小限 (名前またはニックネーム、メール) とし、閲覧は権限で制御。

予約確定メールと前日リマインドメールを自動送信。

Constraints and assumptions:

モバイルファースト、アクセシビリティはWCAG 2.1 AAを目標。

複数会場・複数日対応。タイムゾーンや言語は設定で切り替え可能。

日本語UIを既定としつつ、英語表示への切替余地を残す。

Out of scope:

決済機能は含めない (無料イベント前提)。

健康情報やその他の機微情報は扱わない。

全体像

本プロジェクトは、参加者がスマホからイベント枠を予約し、主催側が申込状況とキャンセル待ちを可視化できる小規模な Web アプリケーションである。参加者は告知ページからランディングページに遷移し、会場と日時を選択して同意事項にチェックし、氏名またはニックネームとメールアドレスを入力して申し込む。主催側はダッシュボードで開催別の申込率と欠員、キャンセル待ちを確認し、ワンクリックで繰り上げを実行する。体験の中心は「迷わず予約できること」と「前日までの連絡が確実に届くこと」である。

アーキテクチャとディレクトリ構成

構成はシンプルな Web フロントエンドと軽量 API で構成する。フロントは SPA もしくは SSR に対応できるフレームワークを用い、API は REST で提供する。データストアはリレーショナルデータベースを採用し、枠の在庫管理と一意制約で二重予約を防止する。静的アセットは CDN 配信とし、メール配信は外部サービスを利用する。目安のディレクトリ構成は以下の通りである。

/app            (画面、ルーティング)
/components     (共通 UI)
/lib            (API クライアント、ユーティリティ)
/api            (サーバ API またはエッジ関数)
/db             (スキーマ、マイグレーション)
/tests          (E2E と API テスト)
/docs           (仕様、計画、タスク)

データモデル

主要エンティティは Event、Venue、Slot、Reservation、Waitlist、User の6つである。Event は開催単位、Venue は会場情報、Slot は日時枠、Reservation は予約レコード、Waitlist はキャンセル待ち、User は参加者と運営のアカウントを持つ。Reservation は Slot と User の複合一意制約で二重予約を防ぐ。Slot は capacity と remaining を持ち、トランザクション内で残数を減算する。個人情報は最小限とし、メールアドレスはインデックス化して検索を容易にする。

API 設計

API は公開系と運営系に分ける。公開系ではイベント一覧、会場と枠の検索、予約作成、キャンセルを提供する。運営系では開催別の申込率、欠員、キャンセル待ちの一覧、繰り上げ操作、エクスポートを提供する。予約作成時は枠の残数を楽観的ロックまたは行ロックで保護し、重複を一意制約で退ける。キャンセル時は Waitlist の先頭を自動繰り上げ候補として抽出し、通知を送る。エラー応答は参加者に対しては簡潔な文言、サーバ側ログには識別子付きで詳細を書く。

非機能要件

モバイルファーストとし、主要操作の P95 応答時間は 300ms 未満を目標とする。可用性はイベント期間中のスパイクに耐えられる構成を想定し、読み取りはキャッシュで緩和する。アクセシビリティは WCAG 2.1 AA を目標とし、フォーム要素のラベル、コントラスト、キーボード操作を担保する。多言語対応は日本語を既定とし、英語切替の余地を残す。

セキュリティとプライバシー

取得する個人情報は氏名またはニックネームとメールアドレスの最小限にとどめる。通信はすべて TLS とし、保存時は必要に応じてメールハッシュを併用する。運営ダッシュボードは認証とロールで保護し、参加者の個票は権限のあるユーザーのみが閲覧できる。ログには個人情報を直接出力しない。削除リクエストに対応できるよう、連絡先と手順を明示する。

リスクと対応

同時申し込みの競合、メールの到達率、キャンセル待ちの自動繰り上げに伴う重複通知が主なリスクである。競合は一意制約とトランザクションで対処する。到達率は配信サービスのレピュテーションとバックオフ再送で改善する。重複通知は状態遷移を厳格化し、繰り上げ確定時に Waitlist を即時更新する。

スコープ外

決済機能と有料チケットの扱いは対象外とする。健康情報やその他の機微情報は扱わない。対面受付の運用フローは本アプリの外で定義する。

代替案と比較

単一リポジトリにフロントと API を同居させる案と、API を外部に分離する案の2通りがある。前者は開発体験とデプロイが簡素で初期に適するが、負荷分散の自由度が低い。後者はスケールしやすく権限境界も明確だが、運用が増える。初期は単一で始め、需要に応じて API 分離に移行する。

共通の完了条件 (Definition of Done)

受け入れ条件が満たされ、主要なエッジケースがテストされていること。

ログとメトリクスの出力が最小限でも確認できること。

ドキュメントに手順または API 契約が追記されていること。

1. スキーマとマイグレーション

目的と範囲: Event、Venue、Slot、Reservation、Waitlist、User のテーブルを作成する。重複予約防止の一意制約と外部キー整合性を設定する。削除は基本的にソフトデリートとする。

成果物: スキーマ定義、初回マイグレーションファイル、簡単なシードデータ。

受け入れ条件: マイグレーションの適用とロールバックが成功し、シード後に Slot の残数が初期化される。

エッジケース: 予約レコードの孤児化、Venue 削除時の整合性。

観測性: マイグレーション実行ログ。

依存関係と規模: 依存なし、M。

2. 枠一覧 API

目的と範囲: 公開側で Event と Venue を絞り込み、予約可能な Slot の一覧を返す。

成果物: GET /api/slots エンドポイントと簡易キャッシュ。

受け入れ条件: 指定イベントの空き枠のみが返る。満枠は除外される。

エッジケース: 日付範囲外や存在しないイベント指定。

観測性: リクエスト数、ヒット率。

依存関係と規模: タスク1、S。

3. 予約作成 API

目的と範囲: 参加者が枠を予約する。二重予約を禁止する。

成果物: POST /api/reservations。入力は slotId、nameOrNickname、email。

受け入れ条件: 同一 email が同一 slotId を重複予約できない。一意制約違反は 409 を返す。成功時に確認メールを送信する。

エッジケース: 同時送信の競合、メール不達。

観測性: 成功率、409 発生回数、メール送信結果。

依存関係と規模: タスク1、通知はタスク7、M。

4. キャンセル API

目的と範囲: 参加者が予約をキャンセルする。繰り上げ候補の抽出を行う。

成果物: POST /api/reservations/{id}/cancel。

受け入れ条件: 予約がキャンセル状態に遷移し、枠の残数が増える。Waitlist の先頭が繰り上げ候補としてフラグされる。

エッジケース: 期限を過ぎたキャンセル、存在しない予約 ID。

観測性: キャンセル率、時刻分布。

依存関係と規模: タスク1、M。

5. キャンセル待ち登録 API

目的と範囲: 満枠時に参加者を Waitlist に登録する。

成果物: POST /api/waitlist。

受け入れ条件: 既に予約済みの email は Waitlist へ登録不可。重複登録は 409 を返す。

エッジケース: 同時登録の競合。

観測性: 登録数、繰り上げ成功率。

依存関係と規模: タスク1、S。

6. 繰り上げ確定 API

目的と範囲: キャンセルにより空いた枠へ Waitlist 先頭を繰り上げて確定する。

成果物: POST /api/waitlist/{id}/promote。

受け入れ条件: Waitlist レコードが予約に変換され、残数が適切に減る。通知が送信される。

エッジケース: 競合で残数が尽きた場合の再試行。

観測性: 繰り上げ成功率。

依存関係と規模: タスク3・5、M。

7. 通知送信 (メール)

目的と範囲: 予約確定、前日リマインド、繰り上げ確定のメールを送る。

成果物: メール送信サービス連携、テンプレート、失敗時のバックオフ。

受け入れ条件: 3 種類の通知が環境変数設定で切り替え可能。バウンス時にログが残る。

エッジケース: 不達、スパム判定。

観測性: 到達率、バウンス率。

依存関係と規模: タスク3・6、M。

8. 予約フロー UI

目的と範囲: LP → 枠選択 → 同意 → 入力 → 確定の画面を実装する。

成果物: モバイルファーストのフォーム、入力検証、完了画面。

受け入れ条件: 主要読み上げとキーボード操作に対応し、エラー時のガイダンスが明確。

エッジケース: 回線遅延、戻る操作。

観測性: 離脱ポイント。

依存関係と規模: タスク2・3・7、M。

9. ダッシュボード UI

目的と範囲: 開催別の申込率、欠員、キャンセル待ちの可視化と繰り上げ操作。

成果物: 集計カード、テーブル、繰り上げボタン。

受け入れ条件: 指標の定義が画面上に明示され、状態が即時に反映される。

エッジケース: データの遅延、同時操作。

観測性: 操作履歴、主要 KPI。

依存関係と規模: タスク2・4・5・6、L。

10. ics 出力

目的と範囲: 参加者が予約をカレンダーに追加できる ics を提供する。

成果物: GET /api/reservations/{id}/ics。

受け入れ条件: 主要カレンダーアプリで登録可能。

エッジケース: タイムゾーン。

観測性: ダウンロード数。

依存関係と規模: タスク3、S。

11. E2E テスト

目的と範囲: 予約→確認→キャンセル→繰り上げの主要導線を自動化する。

成果物: ブラウザベースのテストと最小限のシナリオデータ。

受け入れ条件: CI で緑が維持される。

エッジケース: 二重予約の同時送信。

観測性: 成功率、所要時間。

依存関係と規模: タスク2〜9、M。

参考 JSON 例

予約作成のサンプルリクエストとレスポンスの例を示す。

POST /api/reservations
{
  "slotId": "slot_20251012_1400",
  "nameOrNickname": "Taro",
  "email": "taro@example.com"
}

201 Created
{
  "reservationId": "resv_abcdef123",
  "slotId": "slot_20251012_1400",
  "status": "confirmed"
}


重複時は以下を返す。

409 Conflict
{
  "error": "duplicate_reservation",
  "message": "同じ枠は重複予約できません。"
}

付録: CONSTITUTION.md 雛形
Non-negotiables:
- 個人情報は名前またはニックネームとメールのみを扱う。機微情報は扱わない。
- 運営画面は認証とロールで保護し、原則として最小権限で運用する。
- エラー時のメッセージは参加者に分かりやすく、詳細はサーバ側ログに集約する。
- 主要導線の E2E テストは必須とし、CI で常に実行する。
- 二重予約は DB の一意制約とトランザクションで防止する。