はじめに

前回の【モダンWeb開発シリーズ第2回】では、React + TypeScript + Go + PostgreSQLを利用したフルスタック開発環境をDocker ComposeとVS Code Dev Containersで構築しました。
今回はコードを書く前に、何を作るのかを設計します。
ショッピングサイトでは、

商品
 ↓
ユーザー
 ↓
カート
 ↓
注文
 ↓
在庫

のように複数の機能が関係します。
さらに、

画面
 ↓
REST API
 ↓
Backend
 ↓
Database

の整合性も必要です。
そこで本シリーズでは、設計と実装でAIの役割を分けます。

ChatGPT Work
    ↓
要件定義・設計
    ↓
設計書
    ↓
テストケース仕様書
    ↓
人間によるレビュー
    ↓
設計・テスト仕様確定
    ↓
Codex
    ↓
実装

設計ではChatGPT Workを利用します。
Workは、複数ステップにわたる作業を進め、ドキュメントなどの成果物を完成させる用途に向いています。
一方、次回以降に利用するCodexは、コードの作成・デバッグ・テスト・コマンド実行・リポジトリ上での作業など、ソフトウェア開発に特化しています。第2回でCodex CLIをappコンテナへ導入しているため、後続回ではDevelopment Container内でCodexを起動し、Go、Node.js、npmなどと同じ開発環境からRepositoryを操作します。
そのため本シリーズでは、

Work
└─ 複数の情報を整理して
   設計成果物一式を作る
Codex
└─ 設計書とRepositoryを確認して
   実装・検証・修正する

という役割分担にします。
重要なのは、Workが作成した設計をそのまま実装へ進めないことです。

Work
 ↓
設計書
 ↓
人間レビュー
 ↓
修正
 ↓
設計確定

という工程を入れ、確定した設計書を次回以降Codexへ引き継ぎます。

この記事で分かること

本記事では、次の内容を確認します。

ChatGPT Projectの役割と使い方
Project instructionsの設定方法
Workへ設計を依頼する方法
要件定義・ユースケース・画面設計の考え方
ER図・データベース・REST APIの設計方法
未確定仕様を open-questions.md で管理する方法
設計書のレビュー方法
設計書から test-cases.md を作成する方法
テストケースを使って設計の曖昧さを実装前に検出する方法
確定した設計書とテストケース仕様書をCodexへ引き継ぐ流れ

前提条件

本記事では、第1回・第2回までの作業が完了していることを前提とします。
プロジェクトは次の場所にあるものとします。

C:\work\shopping-site

第2回終了時点では、概ね次の構成です。

shopping-site
│
├─ .codex
│
├─ .devcontainer
│   └─ devcontainer.json
│
├─ frontend
│   ├─ src
│   └─ package.json
│
├─ backend
│   ├─ go.mod
│   └─ main.go
│
├─ compose.yml
└─ README.md

また、第2回で devcontainer.json の postCreateCommand からCodex CLIをappコンテナへインストールし、Development Container内で codex を実行してサインインできる状態にしています。なお、docker compose ps などDocker Desktop自体を操作するコマンドはWindows側のPowerShellで実行し、Development Container内ではGo、npm、Codexなどの開発作業を行います。

今回の成果物はソースコードではなく設計書とテストケース仕様書です。

なぜ設計にChatGPT Workを使うのか

設計は、単一のファイルを作る作業ではありません。
例えば「商品をカートへ追加する」という機能だけでも、

要件
「商品をカートへ追加できる」
        ↓
画面
「カートに追加」ボタン
        ↓
API
POST /api/cart/items
        ↓
Backend
Cart Service
        ↓
Database
carts
cart_items
products

のように複数の設計へ影響します。
設計では、

要件
├─ ユースケース
├─ 画面
├─ データ
├─ API
├─ セキュリティ
└─ 非機能要件

を横断して考える必要があります。
OpenAIの公式ヘルプでは、Workは長めの複数ステップの作業や完成した成果物を扱うエージェントとして説明されています。
一方、Codexはコード作成、デバッグ、テスト、コマンド実行、変更レビュー、リポジトリ作業などソフトウェア開発向けです。
本シリーズでは、この性質の違いを利用して、

設計
 ↓
Work
実装
 ↓
Codex

と役割を分けます。
これは「Workは設計しかできない」「Codexは設計できない」という意味ではありません。
今回のショッピングサイト開発で、設計成果物をまとめる工程と、Repository上で実装する工程を明確に分離するための方針です。
本シリーズでは、Work → Codex と表現しますが、Workが自動的にCodexを起動して実装を依頼する構成ではありません。
具体的には、

Work
 ↓
設計書を作成
 ↓
人間がレビュー
 ↓
設計書をshopping-siteへ配置
 ↓
Development Containerを開く
 ↓
appコンテナ内でCodexを起動
 ↓
Codexが設計書を読む

という流れです。
この設計書がWorkとCodexの引き継ぎ資料になります。

ChatGPT Projectとは

今回の設計では、ChatGPT Projectを利用します。

ChatGPT Projectは、特定のテーマや仕事に関するチャット・ファイル・指示をまとめて、継続して作業するための場所です。

通常のチャットでは、それぞれのチャットで作業を進めます。一方、ショッピングサイトのように要件定義、画面設計、データベース設計、API設計など複数の作業を継続して行う場合は、関連する情報を一つのProjectにまとめておくと管理しやすくなります。

今回のイメージは次のとおりです。

ChatGPT Project
「Shopping Site」
│
├─ Project instructions
│    └─ このProjectで継続して適用する指示
│
├─ Sources / ファイル
│    └─ 設計に利用する資料
│
└─ チャット
     ├─ 要件定義
     ├─ 画面設計
     ├─ DB設計
     └─ REST API設計

本記事では、ショッピングサイトの設計に関する情報をまとめる場所として、Shopping Site というProjectを作成します。

ChatGPT Projectを作成する

それでは、実際にChatGPT Projectを作成します。

ChatGPTのサイドバーにある「プロジェクト」の右側の 「＋」ボタン をクリックします。

プロジェクト名に次の名前を入力します。

Shopping Site

入力したら、「プロジェクトを作成する」ボタンをクリックします。
これで、ショッピングサイト開発用のProjectが作成されます。

今回のシリーズでは、このProjectにショッピングサイトの設計方針や参考資料をまとめます。その後、Projectを開いてWorkを開始し、Projectのコンテキストを利用しながら要件定義、データベース設計、REST API設計などを進めます。

ChatGPT Project
「Shopping Site」
│
├─ Project instructions
├─ Sources / ファイル
└─ 関連するチャット
        ↓
Projectのコンテキスト
        ↓
Work
        ↓
要件定義・設計
        ↓
設計書

OpenAIのWorkに関する公式ヘルプでは、ProjectからWorkを開始し、そのProjectのコンテキストを利用できると案内されています。一方、Projectの公式ヘルプには、Project-only memoryを利用しているProjectではWorkを利用できないという制限も記載されています。

そのため本記事では、通常のProjectからWorkを開始してProjectのコンテキストを利用する構成を前提とします。Project-only memoryを利用している場合は、この構成をそのまま利用できない点に注意してください。

次に、このProjectで設計するときに継続して適用する方針をProject instructionsへ設定します。

Project instructionsとは

Project instructionsは、ChatGPT Project内で継続して適用したい指示を設定するための機能です。今回のショッピングサイトでは、技術スタック、設計方針、セキュリティ方針、設計成果物、レビュー方針など、設計作業全体で共通して守りたい内容を記述します。

ChatGPT Project
「Shopping Site」
        ↓
Project instructions
        ↓
設計時に継続して考慮する方針
        ↓
Work
        ↓
設計作業

Project instructionsを設定しておくことで、Workで要件定義、画面設計、データベース設計、REST API設計などを進める際に、共通の設計方針を前提として作業できます。

Project instructionsへ設計方針を設定する

Projectの設定を開き、プロジェクトの指示へ今回の設計方針を記述します。
例えば次のようにします。

プロジェクト設定をクリックすると設定画像が表示されます。
各項目は以下を指定します。

プロジェクト名 → Shopping Site のままでOK
指示 → 設計方針を入力
メモリ → 今回はデフォルトのままでOK
ライブラリへのアクセス → 今回は有効のままでOK

設計方針

このプロジェクトでは、
React + TypeScript + Go + PostgreSQLを使用して
学習用ショッピングサイトを設計・開発します。

設計では以下の方針を守ってください。

・FrontendとBackendの責務を分離する
・FrontendとBackendはREST APIで連携する
・機能要件だけでなく非機能要件も定義する
・認証、認可、パスワード管理などのセキュリティ要件を定義する
・注文処理ではトランザクションと在庫整合性を考慮する
・データベースのテーブル間の関係を明確にする
・設計上の重要な判断理由を記載する
・設計書間で矛盾がないか確認する
・重要な仕様が不足している場合は勝手に確定しない

設計成果物は以下とします。

docs/
├─ requirements.md
├─ use-cases.md
├─ screen-design.md
├─ database-design.md
├─ api-design.md
├─ open-questions.md
└─ test-cases.md

人間による判断が必要な未確定事項は、
open-questions.mdへ整理してください。

各確認事項には、
ID、確認事項、確認理由、影響する設計書、状態を記載してください。

状態は、
「未確認」「回答済み」「設計反映済み」
のいずれかとしてください。

設定画面

設定が完了したら保存ボタンクリックします。

Project instructionsには、個別機能の実装方法を細かく指定するのではなく、設計作業全体で継続して適用したい原則を記述します。

今回のポイントは、セキュリティや非機能要件をCodexによる実装段階まで先送りしないことです。Workでは「何を満たす必要があるか」を設計し、Codexでは確定した設計を基に「コードでどのように実現するか」を具体化します。

Project instructions
        ↓
設計全体で守る原則
        ↓
Work
        ↓
機能要件
非機能要件
セキュリティ要件
DB設計
REST API設計
        ↓
設計書
        ↓
★ 人間レビュー
        ↓
Codex
        ↓
具体的な実装

例えば、「パスワードを安全に保存する」「他ユーザーの注文を閲覧できないようにする」といった内容は設計段階で要件として整理します。一方、Goでどのライブラリや処理を使って実現するかは、後のCodexによる実装段階で具体化します。

Work
「何を保証するか」
        ↓
Codex
「コードでどう実現するか」

このように役割を分けることで、Project instructionsが実装仕様書のように細かくなりすぎることを防ぎながら、重要なセキュリティ要件や非機能要件を設計段階から扱えます。

今回設計するショッピングサイト

今回のシリーズでは、学習用ショッピングサイトとして次の機能を対象にします。

ショッピングサイト
│
├─ 商品
│   ├─ 商品一覧
│   ├─ 商品詳細
│   └─ 商品検索
│
├─ ユーザー
│   ├─ ユーザー登録
│   └─ ログイン
│
├─ カート
│   ├─ 商品追加
│   ├─ カート表示
│   ├─ 数量変更
│   └─ 商品削除
│
├─ 注文
│   ├─ 注文内容確認
│   └─ 注文確定
│
└─ 注文履歴
    ├─ 一覧
    └─ 詳細

第6回では、この設計を基に実装していきます。
そのため今回は、コードではなく、

何を作るか
どの画面が必要か
どのデータが必要か
どのAPIが必要か

を決めます。

Workへ設計を依頼する

Project instructionsの設定が完了したら、Shopping Site Projectを開いた状態で、画面上部を 「Chat」から「Work」へ切り替えます。

Projectの「指示」を設定
        ↓
Shopping Site Projectを開く
        ↓
画面上部の「Work」を選択
        ↓
設計依頼を入力
        ↓
Workを実行

Workへ切り替えることで、Shopping Site Projectのコンテキストを利用しながら設計作業を進めます。

今回は、以下の依頼文をWorkの入力欄へ貼り付けて実行します。

このプロジェクトの指示と資料を確認してください。
React + TypeScript + Go + PostgreSQLで構築する
学習用ショッピングサイトについて、
要件定義からREST API設計までを行ってください。
要件定義では、機能要件だけでなく、
今回の学習用ショッピングサイトに必要な非機能要件と
セキュリティ要件も整理してください。

対象機能は以下です。
・商品一覧
・商品詳細
・商品検索
・ユーザー登録
・ログイン
・カートへの商品追加
・カート表示
・数量変更
・カートからの商品削除
・注文内容確認
・注文確定
・注文履歴一覧
・注文履歴詳細
以下の設計成果物を作成してください。

1. requirements.md
2. use-cases.md
3. screen-design.md
4. database-design.md
5. api-design.md
6. open-questions.md

設計書同士で矛盾がないようにしてください。
特に以下を確認してください。
・FrontendとBackendの責務
・認証と認可
・パスワードの扱い
・注文時のトランザクション
・在庫整合性
・ユーザーと注文の関係
・注文時点の商品名と価格の保持
・REST APIのHTTP MethodとStatus Code

設計中に仕様が不足しており、人間による判断が必要な事項を発見した場合は、
勝手に仕様を確定しないでください。

確認が必要な事項は、設計書とは別に
open-questions.md
へまとめてください。

各確認事項には以下を記載してください。
・ID
・確認事項
・確認が必要な理由
・影響する設計書
・現在の状態

状態は以下のいずれかとしてください。
・未確認
・回答済み
・設計反映済み

重要な未確認事項が残っている場合は、
設計完了とはせず、その旨を報告してください。

設計書作成後、設計書間の矛盾や不足をレビューし、
確認結果も報告してください。

依頼時には、対象機能だけでなく、成果物、技術的制約、レビュー観点、不明点の扱いまで指定します。

ここからの要件定義、ユースケース、画面設計、ER図、データベース設計、REST API設計は、人間が一つずつ手作業で作成するのではなく、先ほどの依頼を受けたWorkがまとめて進める作業です。

本記事では、Workがどのような観点で設計し、どのような成果物を作るのかを理解できるように、各設計工程を順番に確認します。人間の役割は、Workが作成した内容を確認し、重要な仕様や設計判断に問題がないかをレビューすることです。

人間
│
├─ Project instructionsを設定
└─ Workへ設計を依頼
        ↓
      Work
        │
        ├─ 要件定義
        ├─ ユースケース
        ├─ 画面設計
        ├─ ER図
        ├─ データベース設計
        ├─ REST API設計
        ├─ 確認事項をopen-questions.mdへ整理
        └─ 設計書間の整合性を確認
        ↓
   設計成果物を作成
        ↓
open-questions.mdに未確認事項
        ↓
      人間
        ↓
   仕様を判断・回答
        ↓
      Work
        ↓
設計書とopen-questions.mdを更新
        ↓
   Workが再レビュー
        ↓
      人間
        ↓
     最終レビュー
        ↓
     設計確定

したがって、以下の各章は追加の作業を人間が個別に実行する手順ではなく、Workが作成する設計内容を人間が確認するための解説として読み進めてください。

Workが要件定義を作成する

最初の成果物は、

requirements.md

です。
ここでは「どのように実装するか」よりも、まずシステムが何を実現するかを整理します。
例えば、

システム目的
対象ユーザー
機能要件
├─ 商品
├─ ユーザー
├─ カート
├─ 注文
└─ 注文履歴
非機能要件
├─ セキュリティ
├─ 性能
├─ 可用性
├─ 保守性
└─ ログ・監視
制約事項
対象外

という構成が考えられます。
機能要件では、例えば、

ユーザーは商品一覧を閲覧できる
ユーザーは商品名で商品を検索できる
ユーザーは商品詳細を閲覧できる
ユーザーはアカウントを登録できる
登録ユーザーはログインできる
ログインユーザーは商品をカートへ追加できる
ログインユーザーはカート内の商品数量を変更できる
ログインユーザーは注文を確定できる
ログインユーザーは自分の注文履歴を閲覧できる

などを整理します。

機能要件だけでなく、今回のシステムで必要な非機能要件もWorkに整理させます。学習用ショッピングサイトなので、企業システムのようにすべてを詳細に定義するのではなく、今回の実装で必要な範囲を明確にします。

例えば、次のような観点です。

セキュリティ
・パスワードを平文保存しない
・認証と認可を分離する
・他ユーザーの注文を閲覧できない
・SQLインジェクション対策を行う

性能
・学習用途で支障のない応答性能を目標とする

可用性
・今回は冗長化や高可用性構成を対象外とする

保守性
・Frontend / Backend / Databaseの責務を分離する

ログ・監視
・Backendでエラーを記録できる構成とする
・パスワードなどの機密情報をログへ出力しない

ここでも、根拠のない数値や重要な仕様をWorkに勝手に決めさせないことが重要です。例えば「APIは3秒以内に応答する」「可用性99.9%」などの具体的な目標値が必要にもかかわらず指定されていない場合は、必要に応じて open-questions.md の確認事項として扱います。

Work
 ↓
非機能要件を整理
 ↓
判断できる内容
 → requirements.md
 ↓
人間の判断が必要な内容
 → open-questions.md

ここで後から必要になりそうな機能を何でも追加するのではなく、今回のシリーズで実装する範囲を決めることが重要です。Workが作成した requirements.md に対象外の機能が追加されていないかは、人間が確認します。

Workがユースケースを整理する

次に、

use-cases.md

を作成します。
要件だけでは、ユーザーがどの順番でシステムを利用するのか分かりにくいためです。
例えば購入までの流れは、

ユーザー
  ↓
商品一覧
  ↓
商品検索
  ↓
商品詳細
  ↓
カートへ追加
  ↓
カート確認
  ↓
注文内容確認
  ↓
注文確定
  ↓
注文履歴

となります。
ユーザー登録・ログインは、

未登録ユーザー
    ↓
ユーザー登録
    ↓
ログイン
    ↓
認証済みユーザー

と整理できます。
ユースケースでは、

誰が
何をきっかけに
何を行い
どの状態になるか

を確認します。

Workが画面設計を作成する

次に、

screen-design.md

を作成します。
今回必要な画面は、例えば次のようになります。

画面	主な役割
商品一覧	商品表示・検索
商品詳細	商品情報表示・カート追加
ユーザー登録	アカウント作成
ログイン	認証
カート	商品・数量・合計金額確認
注文確認	注文前の最終確認
注文完了	注文結果表示
注文履歴	過去の注文一覧
注文履歴詳細	注文内容の詳細表示

画面遷移も整理します。

商品一覧
  ↓
商品詳細
  ↓
カート
  ↓
注文確認
  ↓
注文完了
  ↓
注文履歴

また、

未ログイン
   ↓
ログイン
   ↓
元の操作へ戻る

など、認証が必要な画面についても考えます。
この段階ではCSSの細かいデザインよりも、

必要な画面
必要な入力
必要な表示項目
画面遷移

を決めることを優先します。

WorkがER図を作成する

画面とユースケースが整理できたら、必要なデータを考えます。
今回の基本テーブルは、

users
products
carts
cart_items
orders
order_items

とします。
関係を簡略化すると、

users
  │
  ├──── carts
  │       │
  │       └──── cart_items
  │                 │
  │                 └──── products
  │
  └──── orders
          │
          └──── order_items
                    │
                    └──── products

となります。
例えば、

users
1
│
│
N
orders

なので、1人のユーザーは複数の注文を持てます。
同様に、

orders
1
│
│
N
order_items

となります。
ER図を作る目的は、図を作ること自体ではありません。

要件
 ↓
必要なデータ
 ↓
Entity
 ↓
Relationship

を確認することです。

Workがデータベース設計を作成する

ER図を基に、

database-design.md

へテーブル設計をまとめます。
例えば users では、

users
id
email
password_hash
created_at
updated_at

などが必要になります。
products では、

products
id
name
description
price
stock
created_at
updated_at

などを考えます。
cart_items では、

cart_items
id
cart_id
product_id
quantity
created_at
updated_at

などが必要です。
注文では注意点があります。
商品価格が後から変更された場合でも、過去の注文金額が変わってはいけません。
そのため order_items には、注文時点の情報を保持する設計を検討します。
例えば、

order_items
id
order_id
product_id
product_name
unit_price
quantity
subtotal

です。
つまり、

products.price
現在の商品価格
order_items.unit_price
注文時点の商品価格

を分けます。
このような判断理由も設計書へ残しておくと、後でCodexが実装するときに判断しやすくなります。

Workが注文と在庫の整合性を設計する

ショッピングサイトでは、注文処理が特に重要です。
単純に、

注文INSERT
 ↓
在庫UPDATE

とするだけでは、途中で失敗した場合に不整合が発生する可能性があります。
そのため設計段階で、

Transaction開始
    ↓
在庫確認
    ↓
注文作成
    ↓
注文明細作成
    ↓
在庫更新
    ↓
カート整理
    ↓
Commit

という処理を検討します。
途中で失敗した場合は、

Rollback

します。
第6回でCodexに実装を依頼するときに、ここが曖昧だと実装方法も曖昧になります。
だからこそ、コードを書く前の設計で決めておくことが重要です。

WorkがREST APIを設計する

次に、

api-design.md

を作成します。
FrontendとBackendはREST APIで連携します。
例えば商品関連は、

Method	Path	用途
GET	`/api/products`	商品一覧・検索
GET	`/api/products/{id}`	商品詳細

ユーザー関連は、

Method	Path	用途
POST	`/api/users`	ユーザー登録
POST	`/api/login`	ログイン

カート関連は、

Method	Path	用途
GET	`/api/cart`	カート取得
POST	`/api/cart/items`	商品追加
PATCH	`/api/cart/items/{id}`	数量変更
DELETE	`/api/cart/items/{id}`	商品削除

注文関連は、

Method	Path	用途
POST	`/api/orders`	注文確定
GET	`/api/orders`	注文履歴一覧
GET	`/api/orders/{id}`	注文履歴詳細

実際の設計書ではPathだけでなく、

HTTP Method
Path
Authentication
Request
Response
Status Code
Validation
Error Response

まで定義します。

WorkがAPIと画面の対応を確認する

APIだけを独立して設計すると、画面で必要なデータが不足することがあります。
そこで、

画面
 ↓
必要データ
 ↓
API
 ↓
Database

を確認します。
例えば商品一覧画面なら、

商品一覧画面
│
├─ 商品名
├─ 価格
└─ 在庫状態
        ↓
GET /api/products
        ↓
products

となります。
注文履歴詳細なら、

注文履歴詳細
│
├─ 注文番号
├─ 注文日時
├─ 商品名
├─ 注文時価格
├─ 数量
└─ 合計
        ↓
GET /api/orders/{id}
        ↓
orders
order_items

です。
このように設計書同士をつなげて確認します。

Workが認証と認可を分けて設計する

今回の設計では、認証と認可を区別します。

認証
Authentication
「誰なのか」
認可
Authorization
「その人が操作してよいのか」

例えば、

ログイン成功
 ↓
認証済み

だけでは、

GET /api/orders/{id}

で他人の注文を閲覧してよいことにはなりません。
注文履歴では、

ログインユーザー
 ↓
注文ID指定
 ↓
その注文のuser_idを確認
 ↓
本人の注文なら返す

という認可が必要です。
このような要件もWorkが設計段階で整理します。人間は、認証できることだけでなく、他のユーザーの注文を参照できない設計になっているかを確認します。

セキュリティ要件と実装を分けて考える

セキュリティについても、WorkとCodexの役割を分けます。

設計段階のWorkでは、具体的なコードを書くのではなく、システムとして何を保証する必要があるかを整理します。Codexでは、その確定した要件を満たす具体的な実装を行います。

内容	Workで設計	Codexで具体化
パスワードを安全に保存する	要件として定義	ハッシュ処理を実装
認証と認可を分離する	APIごとの認証・認可要件を定義	Middlewareなどを実装
SQLインジェクションを防ぐ	セキュリティ要件として定義	パラメータ化クエリなどを実装
注文をTransactionで処理する	処理単位と失敗時の扱いを設計	GoでTransaction処理を実装
在庫整合性を維持する	在庫確認・更新ルールを設計	SQLや排他制御などを実装

つまり、

Work
「何を保証するか」
        ↓
設計書
        ↓
人間レビュー
        ↓
Codex
「どう実装するか」

という分担です。

セキュリティをすべてCodexへ任せるのではなく、認証・認可、パスワード管理、データアクセス制御などの重要な要件は設計段階で明確にしておきます。そのうえで、具体的なライブラリ、関数、Middleware、SQLなどの実装方法をCodex側で決めていきます。

Workが確認事項をopen-questions.mdへ整理する

設計を進めると、最初の依頼だけでは決められない仕様が出てくることがあります。例えば、使用通貨、決済方法、送料、消費税の扱いなどです。

これらはWorkが勝手に決めるのではなく、open-questions.md に確認事項として整理させます。

open-questions.md

Q001 使用通貨
・確認事項：使用通貨が未指定
・確認が必要な理由：商品価格や注文金額の表現に影響する
・影響する設計書：requirements.md / database-design.md / api-design.md
・状態：未確認

Q002 決済方法
・確認事項：決済方法が未指定
・確認が必要な理由：注文フロー、画面、DB、APIに影響する
・影響する設計書：requirements.md / use-cases.md / screen-design.md / database-design.md / api-design.md
・状態：未確認

open-questions.md は、設計書とは別に人間の判断が必要な未確定事項を管理するためのファイルです。

Work
 ↓
設計中に不足仕様を発見
 ↓
open-questions.md
 ↓
★ 人間が仕様を判断
 ↓
Workへ回答
 ↓
影響する設計書を修正
 ↓
open-questions.mdを更新
 ↓
再レビュー

例えば人間が次のように仕様を決定したとします。

Q001 使用通貨
→ 日本円（JPY）のみ

Q002 決済方法
→ 今回は実際の決済機能を実装しない

その場合は、Workへ次のように依頼します。

open-questions.md の確認事項について回答します。

Q001 使用通貨
→ 日本円（JPY）のみとします。

Q002 決済方法
→ 今回は実際の決済機能を実装しません。
注文確定までを対象とします。

この回答を基に、影響する設計書を修正してください。

修正後、
・requirements.md
・use-cases.md
・screen-design.md
・database-design.md
・api-design.md
の整合性を再確認してください。

open-questions.md の該当項目についても、
設計書への反映が完了したものは
「設計反映済み」へ変更してください。

未確認事項が残っている場合は一覧で報告してください。

この工程により、Workが不足仕様を発見し、人間が判断し、Workが設計書へ反映するという役割分担が明確になります。重要な未確認事項を残したまま設計確定には進みません。

確認事項を一次開発と二次開発に振り分ける

実際にWorkへ設計を依頼すると、open-questions.md には想定していた使用通貨や決済方法だけでなく、多くの確認事項が出てくる場合があります。

例えば今回Workが作成した open-questions.md では、実際の商品販売・決済・配送を行うか、配送先住所を管理するか、支払方法をどうするか、キャンセル・返品を扱うか、認証方式をどうするか、性能やバックアップをどこまで求めるか、といった項目が確認事項として挙げられました。

このような確認事項が返ってきた場合の対処に関してですが、今回の目的は、React + TypeScript + Go + PostgreSQLを使ったショッピングサイト開発の基本的な流れを学ぶことです。そのため、最初から実際のECサイトと同等の決済、配送、返品、高可用性などまで含めると、学習対象が大きくなりすぎます。

そこで本シリーズでは、確認事項を次の2つに分けます。

open-questions.md
        ↓
★ 人間が確認
        ↓
┌──────────────────────┬──────────────────┐
│ 一次開発で決める事項 　│ 二次開発へ回す事項 │
└──────────────────────┴──────────────────┘
        ↓                    ↓
基本機能に必要          発展的な機能・運用要件
        ↓                    ↓
今回の設計へ反映        今回は対象外として明記

一次開発では、商品閲覧、ユーザー登録・ログイン、カート、注文確定、注文履歴という基本フローを成立させるために必要な仕様を決めます。一方、実サービスを想定した発展的な機能は二次開発へ回します。

例えば次のように整理できます。

分類	今回の扱い
商品閲覧・検索	一次開発
ユーザー登録・ログイン	一次開発
カート	一次開発
注文確定・注文履歴	一次開発
日本円での商品価格表示	一次開発
実際のオンライン決済	二次開発
配送先住所・配送処理	二次開発
送料計算	二次開発
割引・クーポン	二次開発
キャンセル・返品	二次開発
パスワード再設定・メール確認・退会	二次開発
ゲストカート	二次開発
管理者機能（商品管理・在庫管理・注文管理・ユーザー管理）	二次開発
本番向け高可用性・バックアップ設計	二次開発
本格的なモバイル・アクセシビリティ対応	二次開発

ただし、二次開発へ回す機能であっても、今回の一次開発に影響する最低限の方針は決めておきます。例えば「実際の決済は実装しない」「配送は扱わない」「注文確定時に在庫を確認して減算する」などです。

管理者機能についても、一次開発では実装対象外とします。一次開発では購入者側の基本フローを成立させ、二次開発で管理者という新しいRoleを追加することで、認証だけでなく認可をより具体的に扱います。

一次開発
購入者側の基本機能
        ↓
商品閲覧
ユーザー登録・ログイン
カート
注文
注文履歴

        ↓

二次開発
管理者機能
        ↓
Role / Authorization
管理者ダッシュボード
商品管理
在庫管理
注文管理
ユーザー管理

例えば一次開発では、ログインユーザーが自分の注文だけを参照できるようにします。二次開発では、一般ユーザーと管理者で操作可能な範囲を分けます。

一般ユーザー
    ↓
自分の情報・自分の注文だけ

管理者
    ↓
商品管理
在庫管理
注文管理
ユーザー管理

これにより、二次開発ではAuthentication（認証）に加えて、Authorization（認可）とRoleによるアクセス制御を発展的な学習テーマとして扱うことができます。

Authentication
「ログインしているか」
        ↓
Authorization
「その操作をする権限があるか」
        ↓
Role
user / admin

管理者向けのAPIについては、一般ユーザー向けAPIと責務を分け、例えば /api/admin/... のような管理者用APIを設計することも二次開発で検討します。

未確認
 ↓
今回の基本機能に必要か？
 ↓
YES ─→ 一次開発として仕様を決定
 ↓
NO
 ↓
二次開発へ回す
 ↓
requirements.mdの対象外・将来拡張として明記
 ↓
open-questions.mdにも判断結果を反映

今回の学習用ショッピングサイトでは、Workへ例えば次のように回答します。

open-questions.md の確認事項を確認しました。

今回は学習用ショッピングサイトの一次開発として、
商品閲覧、ユーザー登録・ログイン、カート、注文確定、
注文履歴までの基本フローを実装対象とします。

以下の方針で設計を更新してください。

・実際の商品販売、外部決済、配送は行わない
・通貨は日本円（JPY）のみとする
・商品価格は税込価格として扱い、今回のシステムでは税計算を行わない
・送料、割引、クーポンは扱わない
・キャンセル、返品、発送状態管理は二次開発とする
・配送先住所、会員住所管理は二次開発とする
・パスワード再設定、メール確認、退会は二次開発とする
・ゲストカートは二次開発とする
・管理者機能は二次開発とする
・管理者機能では、一般ユーザーと管理者を区別するRole / Authorizationを導入する
・商品管理（商品一覧・登録・編集・販売状態変更）は二次開発とし、一次開発では初期データを使用する
・在庫管理（在庫確認・在庫数変更）は二次開発とする
・注文管理（全ユーザーの注文一覧・注文詳細）は二次開発とする
・ユーザー管理（ユーザー一覧・ユーザー詳細）は二次開発とする
・管理者向けダッシュボードは二次開発とする
・本番運用を前提とした高可用性、バックアップ、詳細な性能目標は二次開発とする
・本格的なモバイル対応、アクセシビリティ要件は二次開発とする

一次開発の基本フローを成立させるために必要な確認事項については、
今回の設計として整理してください。

二次開発へ回す項目は削除せず、
requirements.md の「対象外・将来拡張」に記載してください。

open-questions.md についても、
今回方針を決定した項目は回答済みとして整理し、
設計書への反映後は「設計反映済み」へ更新してください。

まだ一次開発を進めるために人間の判断が必要な重要事項が残っている場合は、
その項目だけを改めて提示してください。

最後に、requirements.md、use-cases.md、screen-design.md、
database-design.md、api-design.md の整合性を再確認してください。

ここで重要なのは、二次開発へ回すことも一つの設計判断だということです。単に確認事項を無視するのではなく、「今回は対象外」と明示して設計書へ残します。

Workが確認事項を提示
        ↓
★ 人間がスコープを判断
        ↓
一次開発 / 二次開発に分類
        ↓
Workが設計書へ反映
        ↓
open-questions.mdを更新
        ↓
一次開発に必要な未確認事項だけ再提示
        ↓
★ 人間が確認
        ↓
設計確定

これにより、学習用として実装範囲を広げすぎず、将来の二次開発で追加できる機能も設計上残しておくことができます。

Workに設計レビューを依頼する

ここまでの設計工程によって、Workが5つの設計書と確認事項を管理する open-questions.md を作成します。

Work
 ↓
requirements.md
use-cases.md
screen-design.md
database-design.md
api-design.md
open-questions.md
 ↓
Workによる横断レビュー
 ↓
人間によるレビュー

5つの設計書を作成し、重要な確認事項への回答を反映したら、続けてWorkへ横断レビューを依頼します。
例えば次のようにします。

作成した以下の設計書を横断してレビューしてください。

- requirements.md
- use-cases.md
- screen-design.md
- database-design.md
- api-design.md
- open-questions.md

まだ実装は行わないでください。
以下を確認してください。

1. 要件に対応する画面が存在するか
2. 画面で必要なAPIが存在するか
3. APIで必要なデータをDBから取得できるか
4. テーブル間の関係に矛盾がないか
5. 認証と認可が不足していないか
6. 注文処理のトランザクションが考慮されているか
7. 在庫整合性が考慮されているか
8. 注文時点の商品名・価格を保持できるか
9. HTTP MethodとStatus Codeが適切か
10. 設計書間で用語が統一されているか
11. open-questions.md に重要な未確認事項が残っていないか
12. 回答済みの確認事項が影響する設計書へ反映されているか
13. 二次開発へ回した項目が今回の対象外・将来拡張として明記されているか
14. 一次開発に必要な重要な未確認事項が残っていないか

問題がある場合は、
対象の設計書、問題点、修正案を整理してください。
設計書にない重要仕様を勝手に確定せず、
判断が必要なものは確認事項として分けてください。

ここでは、設計書を個別に見るだけでなく、

requirements
      ↓
use-cases
      ↓
screen-design
      ↓
api-design
      ↓
database-design

のつながりを確認します。

レビューで問題が見つかった場合は設計書を修正する

Workによる横断レビューでは、確認事項への回答を反映した後でも、設計書間の不整合や実装時に解釈が分かれる箇所が見つかることがあります。

今回のレビューでは、例えば次のような指摘が出ました。

・冪等性キーを確認する処理順序
・ログアウト操作と画面遷移
・CSRFトークンの取得と送信フロー
・「注文番号」と「注文ID」の用語
・冪等再送時のHTTP Status Code
・409レスポンスの形式
・request_hashの対象と正規化方法
・注文金額の算出・検証方法

このような指摘が出た場合、レビュー結果をそのまま残してCodexへ進むのではなく、設計確定前にWorkへ修正を依頼します。
ただし、すべての指摘を同じように扱うわけではありません。次の3種類に分けて判断します。

種類	例	対応
設計上の不整合・不足	冪等性処理の順序、ログアウト画面、CSRFフロー	Workへ修正を依頼する
人間の判断が必要な仕様	注文番号の扱い、再送時の応答方針など	人間が方針を決めてWorkへ回答する
今回の学習範囲を超える機能	実決済、配送、返品、本番向け高可用性など	二次開発へ回す

今回のレビューで指摘された冪等性、ログアウト、CSRFなどは、一次開発で実装する注文処理や認証処理に直接関係します。そのため二次開発へ回さず、一次開発の設計として修正します。

Workによる横断レビュー
        ↓
問題あり
        ↓
┌─────────────────────┐
│ 設計上の不整合       │ → Workが修正
│ 人間の判断が必要     │ → 人間が方針を決定
│ 今回不要な発展機能   │ → 二次開発
└─────────────────────┘
        ↓
Workが設計書を修正
        ↓
Workが再レビュー
        ↓
★ 人間が最終確認
        ↓
設計確定

今回のレビュー結果に対しては、Workへ例えば次のように修正を依頼します。

設計レビュー結果を確認しました。

今回は学習用ショッピングサイトの一次開発として、
商品閲覧、ユーザー登録・ログイン、カート、注文確定、
注文履歴までを実装対象とします。

レビューで指摘された内容について、
一次開発に必要な設計上の不整合を修正してください。

【1. 冪等性キー】

注文確定APIでは、認証後、カートの状態を確認する前に、
ユーザーIDと冪等性キーから成功済み注文を検索してください。

同じ冪等性キーかつ同じリクエスト内容の場合は、
既存の注文を返してください。

同じ冪等性キーで異なるリクエスト内容の場合は、
409 Conflictとしてください。

並行して同一キーのリクエストが実行され、
DBの一意制約に抵触した場合も、
既存注文を取得して返す設計としてください。

use-cases.md
 database-design.md
 api-design.md

へ反映してください。

【2. ログアウト】

screen-design.mdへログアウト操作を追加してください。

ログイン後の共通ナビゲーションからログアウトできるようにし、

POST /api/auth/logout

を呼び出します。

成功後は未認証状態へ切り替え、
ログイン画面または商品一覧画面へ遷移する設計としてください。

【3. CSRF】

ログイン後に、

GET /api/auth/csrf

でCSRFトークンを取得する流れを追加してください。

取得したトークンはブラウザーのメモリ上で保持し、
状態変更APIでは、

X-CSRF-Token

ヘッダーへ設定してください。

ログアウトAPIにもCSRFトークンを送信してください。

screen-design.md
use-cases.md
api-design.md

の整合性を確認してください。

【4. 注文番号】

今回は独自の注文番号を追加せず、
既存のUUIDを「注文ID」として画面へ表示してください。

screen-design.md
database-design.md
api-design.md

で用語を「注文ID」に統一してください。

【5. 冪等再送時のHTTP Status】

同じ冪等性キー・同じリクエストによる再送で
既存注文を返す場合のHTTP Status Codeを
API設計上で明確にしてください。

既存のAPI設計との整合性を確認したうえで、
採用したStatus Codeとその理由をapi-design.mdへ記載してください。

【6. その他のレビュー指摘】

以下についても、今回の一次開発に必要な範囲で設計を明確化してください。

・409レスポンスのreason codeと最新候補データ
・request_hashの対象項目と正規化ルール
・subtotal_jpyとtotal_amount_jpyのBackendでの算出・検証方法

新しい機能を追加する必要がある場合や、
人間による仕様判断が必要な場合は、
勝手に決定せずopen-questions.mdへ追加してください。

今回の一次開発に不要な発展的機能については、
二次開発の対象として整理してください。

【7. open-questions.md】

上記修正後、open-questions.mdを更新してください。

一次開発に必要な重要事項について、

・未確認
・回答済み
・設計反映済み

を再確認してください。

「一次開発を進めるために重要な未決事項はない」
という記載は、今回の修正と再レビューが完了した場合のみ記載してください。

【8. 最終レビュー】

修正後、

requirements.md
use-cases.md
screen-design.md
database-design.md
api-design.md
open-questions.md

の6文書を再レビューしてください。

特に、

・認証
・認可
・CSRF
・ログアウト
・注文Transaction
・在庫整合性
・冪等性
・HTTP Status Code
・画面とAPIの対応
・DBとAPIの対応

に矛盾がないか確認してください。

最後に、

「一次開発を開始できる状態か」

を確認し、残っている問題がある場合は一覧で提示してください。

ここで重要なのは、レビューで問題が見つかったこと自体を失敗と考えないことです。Workに設計書を作らせた後、横断レビューによって不整合を見つけ、修正と再レビューを繰り返すことで設計の精度を上げます。

Workが設計
 ↓
人間がスコープ・確認事項を判断
 ↓
Workが設計書へ反映
 ↓
Workが横断レビュー
 ↓
指摘事項を分類
 ↓
Workが修正
 ↓
Workが再レビュー
 ↓
★ 人間が最終確認
 ↓
一次開発に重要な未決事項なし
 ↓
設計確定

「一次開発を開始できる状態」と確認できるまでは、Codexによる実装へ進みません。

再レビューで新しい未確認事項が見つかった場合

設計書を修正して再レビューすると、最初の確認では見つからなかった未確認事項が新たに見つかることがあります。

今回の再レビューでは、注文・在庫・認証などの設計を修正した後、次の確認事項が新たに見つかりました。

Q-27 登録パスワードの入力要件

・最小文字数
・最大文字数
・文字種の条件
・入力条件を満たさない場合の扱い

ユーザー登録は一次開発の対象です。そのため、登録パスワードの入力要件は二次開発へ回すのではなく、一次開発を始める前に確定する仕様として扱います。

ここで重要なのは、「設計段階で決めること」と「実装段階で決めること」を分けることです。

内容	決める段階
パスワードの最小・最大文字数	Workでの設計段階
文字種の条件	Workでの設計段階
条件違反時のHTTP Status	Workでの設計段階
画面で必要な入力検証	Workでの設計段階
Goでどのように検証するか	Codexでの実装段階
具体的な関数・ライブラリ	Codexでの実装段階
パスワードハッシュ処理の具体的なコード	Codexでの実装段階

つまり、

Work
「何を満たす必要があるか」
        ↓
★ 人間が仕様を確定
        ↓
設計書
        ↓
Codex
「コードでどう実現するか」

という分担です。

今回の学習用ショッピングサイトでは、Q-27を次のように確定することにします。

・パスワードは8文字以上72文字以下
・文字種の組み合わせは必須としない
・前後の空白は自動的に削除しない
・条件を満たさない場合は400 Bad Request
・パスワードは平文保存しない

一方、メール確認、パスワード再設定、多要素認証、パスキー、アカウントロックなど、今回の基本的なユーザー登録・ログインに必須ではない発展的な機能は二次開発へ回します。

Q-27を確定したら、Workへ次のように依頼します。

Q-27 登録パスワードの入力要件について回答します。

一次開発では、登録パスワードを以下の仕様とします。

・パスワードは8文字以上72文字以下
・文字種の組み合わせは必須としない
・前後の空白は自動的に削除しない
・条件を満たさない場合は400 Bad Request
・パスワードは平文保存しない

この回答をQ-27へ反映してください。

また、影響する以下の設計書を更新してください。

・requirements.md
・screen-design.md
・api-design.md

open-questions.md のQ-27についても、
設計書への反映が完了したら
「設計反映済み」へ変更してください。

その後、以下の6文書を最終横断レビューしてください。

・requirements.md
・use-cases.md
・screen-design.md
・database-design.md
・api-design.md
・open-questions.md

特に、

・ユーザー登録画面の入力条件
・ユーザー登録APIのValidation
・400 Bad Requestとなる条件
・パスワードの保存方針
・設計書間のパスワード要件の整合性

を確認してください。

新たに一次開発を進めるための重要な未確認事項がなければ、
「一次開発を開始できる状態」と判定してください。

新たな重要な未確認事項を発見した場合は、
勝手に仕様を確定せずopen-questions.mdへ追加してください。

このように、再レビューで未確認事項が追加されても、それ自体を問題と考える必要はありません。重要なのは、一次開発に必要な事項であれば人間が仕様を決め、Workへ設計書への反映と再レビューを依頼することです。

Workが設計書を作成
        ↓
人間が確認事項を判断
        ↓
Workが設計書へ反映
        ↓
Workが横断レビュー
        ↓
問題を修正
        ↓
Workが再レビュー
        ↓
新しい未確認事項を発見
        ↓
今回の一次開発に必要か？
        ↓
YES
        ↓
★ 人間が仕様を決定
        ↓
Workが設計書へ反映
        ↓
open-questions.mdを更新
        ↓
Workが最終横断レビュー
        ↓
重要な未確認事項なし
        ↓
「一次開発を開始できる状態」
        ↓
★ 人間が最終確認
        ↓
設計確定
        ↓
Codexへ引き継ぐ

逆に、新しく見つかった事項が今回の一次開発に必要でなければ、前述したように二次開発へ回し、requirements.md の対象外・将来拡張として残します。

この工程を繰り返し、一次開発に必要な重要な未確認事項がなくなった時点を設計確定の条件とします。

Workがテストケース仕様書を作成する

ここまでで、一次開発に必要な重要な未確認事項を解消し、6文書の整合性を確認しました。

本シリーズでは、ここで設計を終了してすぐCodexへ実装を依頼するのではなく、実装前にWorkでテストケース仕様書まで作成します。

requirements.md
use-cases.md
screen-design.md
database-design.md
api-design.md
open-questions.md
        ↓
      Work
        ↓
設計内容をテスト条件へ変換
        ↓
   test-cases.md

テストケースを実装前に作成する目的は、単にテスト項目を早く用意することではありません。

設計書に書かれた仕様を、

前提条件
入力・操作
期待結果
HTTP Status Code
DBへの副作用
認証・認可
競合時の動作

まで具体化すると、設計書だけを読んでいる段階では気付きにくかった曖昧さが見つかることがあります。

例えば注文確定では、

・空カートの場合はどうなるか
・注文確認後に数量が変更された場合はどうなるか
・注文確認後に商品が削除された場合はどうなるか
・最後の商品が削除され、カートが空になった場合はどうなるか
・価格や在庫が変更された場合はどうなるか
・同じ冪等性キーで再送された場合はどうなるか
・同じ冪等性キーで異なる内容が送信された場合はどうなるか
・同時に注文確定された場合はどうなるか

といった条件をテストケースへ落とし込む必要があります。

このとき期待結果を一意に書けない箇所があれば、実装前に設計をもう一度確認する必要があると判断できます。

設計書
  ↓
test-cases.mdへ具体化
  ↓
期待結果を書けないケースを発見
  ↓
設計の曖昧さを確認
  ↓
必要なら設計書を修正
  ↓
再レビュー
  ↓
設計＋テストケース確定

これにより、実装後に仕様差異が見つかってWorkへ何度も差し戻す回数を減らします。

test-cases.mdを作成する

6文書の設計内容が一次開発として固まったら、Workへ次のように依頼します。

この確定設計を横断して確認し、
一次開発のテストケース仕様書を作成してください。

参照対象:
- docs/requirements.md
- docs/use-cases.md
- docs/screen-design.md
- docs/database-design.md
- docs/api-design.md
- docs/open-questions.md

出力先:
- docs/test-cases.md

テストケースには少なくとも次の情報を含めてください。
- テストケースID
- 対象機能
- テスト種別
- 前提条件
- 入力・操作
- 期待結果
- 期待するHTTP Status Code（該当する場合）
- 自動テスト／手動確認の区分
- 根拠となる設計書

次の観点からテストケースを抽出してください。
- 正常系
- 異常系
- 境界値
- Validation
- 認証・認可
- CSRF
- DB制約
- 必要な業務状態の競合
- Transaction / Rollback
- 在庫整合性
- 冪等性
- 並行実行

重要:
- docs/に存在しない仕様を推測して追加しないでください。
- 期待結果を設計書から一意に判断できない場合は、勝手に補完しないでください。
- 設計書間で矛盾する場合は、そのテストケースを確定扱いにせず、差異として報告してください。
- 一次開発の対象機能をすべて確認してからテストケースを作成してください。
- 特定の画面やAPIだけに対象を限定しないでください。

ここで重要なのは、test-cases.md を実装済みコードから逆算して作らないことです。

設計書
 ↓
test-cases.md
 ↓
Codexによる実装

という順序にすることで、テストケースが実装が正しいかを判断する基準になります。

テストケースから設計を再レビューする

test-cases.md が作成されたら、Workにはテストケースと6文書をもう一度横断して確認させます。

作成したtest-cases.mdと以下の設計書を横断して確認してください。

- requirements.md
- use-cases.md
- screen-design.md
- database-design.md
- api-design.md
- open-questions.md
- test-cases.md

まだ実装は行わないでください。

以下を確認してください。

1. 一次開発の全機能にテストケースが存在するか
2. 正常系だけでなく異常系・境界値が含まれているか
3. Validationの条件と期待するHTTP Status Codeが設計書と一致するか
4. 認証・認可・CSRFのケースが不足していないか
5. 注文TransactionとRollbackを確認できるか
6. 在庫整合性を確認できるか
7. 冪等性を確認できるか
8. 並行実行・競合時の期待結果が設計書から判断できるか
9. DB制約を確認できるか
10. 画面で必要な手動確認が整理されているか
11. 各テストケースの根拠となる設計書が明確か
12. 設計書とtest-cases.mdの期待結果に矛盾がないか

期待結果を設計書から一意に判断できない箇所がある場合は、
勝手に仕様を補完せず、対象テストケースID、関連する設計書、
何が未確定なのかを整理してください。

新しい機能を追加せず、一次開発の確定仕様の範囲でレビューしてください。

このレビューで設計上の曖昧さが見つかった場合は、Codexへ進む前にここで解消します。

第3回では、実装前に判断できる仕様をできるだけ docs/ に集約し、以降はCodexが同じ docs/ を基準として実装・テスト・修正を進められる状態を作ります。

人間の判断が必要なのは、例えば次のような場合です。

・新しい機能を追加する必要がある
・API契約そのものを変更する
・DB Schemaを大きく変更する
・認証方式を変更する
・業務ルールに複数の妥当な選択肢がある
・一次開発のスコープが変わる

一方、確定済みの設計に対する実装上の不足、テスト不足、コードと test-cases.md の軽微な不整合は、次回以降Codex側でRepository全体を確認しながら修正します。

第3回：Work
設計
 ↓
テストケース設計
 ↓
設計の曖昧さを解消
 ↓
docs/を確定

        ↓ ここからCodex

第4回以降：Codex
開発ルール
 ↓
実装
 ↓
テスト実装・実行
 ↓
FAIL
 ↓
Fix
 ↓
再テスト

この境界を明確にすることで、Workは上流の設計とテスト仕様、CodexはRepository上の実装・検証・修正という役割分担にできます。

AIのレビューだけで確定しない

Workによるレビュー、指摘事項に対する設計修正、test-cases.md の作成と再レビューが完了しても、まだ設計確定ではありません。最後に人間が設計書、open-questions.md、test-cases.md を確認します。

特に、重要な確認事項が「未確認」のまま残っていないこと、回答した内容が各設計書へ反映されていることを確認します。

Work
 ↓
設計書
 ↓
Workによるレビュー
 ↓
問題があれば設計書を修正
 ↓
Workによる再レビュー
 ↓
open-questions.mdを確認
 ↓
★ 人間が最終レビュー
 ↓
設計確定

特に確認したいのは、

要件の抜け
画面遷移
テーブルの関係
APIの一貫性
認証・認可
非機能要件
セキュリティ要件
注文処理
在庫更新
Transaction
重要な仕様をAIが独自判断していないか
open-questions.mdに重要な未確認事項が残っていないか
test-cases.mdが一次開発の全機能を対象としているか
テストケースの期待結果と設計書が一致しているか
回答した仕様が設計書へ反映されているか
二次開発へ回した機能が対象外として明記されているか
一次開発に必要な未確認事項が残っていないか

です。
例えば、

users
products
orders
order_items

しかなければ、

カートはどこへ保存するのか？

という問題に気付けます。
また、

order_items
product_id
quantity

だけなら、

商品価格が変更されたら
過去の注文金額はどうなるのか？

という問題があります。
AIが設計したから正しいと考えるのではなく、AIが作成した設計成果物を人間がレビューして確定することを本シリーズの基本方針とします。

設計書をdocsへ整理する

人間によるレビューが完了したら、確定した設計書をプロジェクトへ配置します。
最終的に次の構成にします。

C:\work\shopping-site
│
├─ docs
│   ├─ requirements.md
│   ├─ use-cases.md
│   ├─ screen-design.md
│   ├─ database-design.md
│   ├─ api-design.md
│   ├─ open-questions.md
│   └─ test-cases.md
│
├─ .devcontainer
│   └─ devcontainer.json
│
├─ frontend
│   ├─ src
│   └─ package.json
│
├─ backend
│   ├─ go.mod
│   └─ main.go
│
├─ compose.yml
└─ README.md

この docs/ が、次回以降のCodexにとって重要な入力になります。

設計書がWorkとCodexの境界になる

今回の構成をもう一度整理します。

ChatGPT Work
      ↓
要件定義・設計
      ↓
設計書
      ↓
テストケース仕様書
      ↓
人間レビュー
      ↓
設計・テスト仕様確定
      ↓
docs/
      ↓
Codex

WorkとCodexが直接会話する必要はありません。
確定した設計書とテストケース仕様書を共通の成果物として受け渡すことで、役割を分離します。
この方法には、

設計
 ↓
レビュー
 ↓
確定
 ↓
実装

という工程が明確になるメリットがあります。

今回の完成構成

第3回終了時点では、次の状態になります。

ChatGPT Project
│
├─ Project instructions
│    └─ 設計方針
│
└─ Work
     └─ 設計作業
          ↓
       設計書一式
          ↓
       test-cases.md
          ↓
       人間レビュー
          ↓
       設計・テスト仕様確定

ローカルプロジェクトでは、

C:\work\shopping-site
│
├─ docs
│   ├─ requirements.md
│   ├─ use-cases.md
│   ├─ screen-design.md
│   ├─ database-design.md
│   ├─ api-design.md
│   ├─ open-questions.md
│   └─ test-cases.md
│
├─ frontend
├─ backend
├─ .devcontainer
├─ compose.yml
└─ README.md

となります。
ここまでで、

開発環境
+
設計書
+
テストケース仕様書

がそろいました。

まとめ

今回はChatGPT Workを利用して、ショッピングサイトを実装する前の設計工程を整理しました。
ポイントは次のとおりです。

第1・2回で開発環境を作り、第3回から設計へ進む
Workは複数ステップの設計業務と成果物作成に利用する
Codexは次回以降、Repository上でのソフトウェア開発に利用する
WorkとCodexを自動的に直接連携させる構成ではない
ChatGPT Projectに設計作業のコンテキストをまとめる
Project instructionsへ設計時に継続して適用する方針を書く
要件定義では機能要件だけでなく、必要な非機能要件とセキュリティ要件も整理する
Project instructionsには実装詳細ではなく、設計全体で守る原則を書く
要件定義、ユースケース、画面、DB、APIを別々ではなく関連付けて設計する
注文ではTransactionと在庫整合性を設計段階から考慮する
認証と認可を分けて考える
Workでは「何を保証するか」を設計し、Codexでは「どう実装するか」を具体化する
不足している仕様は open-questions.md へ整理し、Workが勝手に確定しない
open-questions.md の確認事項は人間が判断し、Workへ設計書への反映を依頼する
確認事項は一次開発と二次開発に振り分け、学習用サイトでは実装範囲を広げすぎない
二次開発へ回した項目も削除せず、対象外・将来拡張として設計書へ残す
Workの横断レビューで問題が見つかった場合は、設計上の不整合、人間の判断が必要な仕様、二次開発へ回す項目に分類する
一次開発に必要な設計上の問題はWorkへ修正を依頼し、再レビューする
Workによる再レビューで新しい未確認事項が見つかった場合も、一次開発に必要な仕様は人間が判断して設計へ反映する
一次開発に不要な発展事項は二次開発へ回し、対象外・将来拡張として残す
一次開発に必要な重要な未確認事項がなくなるまで、修正と再レビューを繰り返す
設計確定前にWorkで test-cases.md を作成し、一次開発の仕様をテスト条件まで具体化する
テストケースを使って、実装前に設計の曖昧さや期待結果の不一致を検出する
Workによる再レビュー後に人間が最終レビューする
確定した設計書と test-cases.md を docs/ へ配置する
第4回以降は docs/ を基準としてCodexに実装・テスト・Fixを任せ、Workへの細かな差し戻しを減らす
docs/ の設計書とテストケース仕様書をWorkからCodexへの引き継ぎ資料とする

第3回終了時点で、Workが作成した設計書と open-questions.md をレビューし、指摘事項の修正と再レビューを行います。さらに test-cases.md を作成して、一次開発の仕様を正常系・異常系・境界値・認証・CSRF・DB制約・競合・Transaction・冪等性までテスト条件へ落とし込みます。
テストケースから設計を再確認し、重要な未確認事項や設計上の不整合が解消された状態を人間が最終確認したうえで、Codexへ引き継ぎます。

本連載について

回	タイトル	対応範囲	主な内容
第1回	Docker × VS Code Dev ContainersでGo開発環境を構築する	🐳 Go開発環境	Docker Desktop・VS Code・Dev Containersを使ったGo開発環境の構築
第2回	React + TypeScript + Go + PostgreSQLのフルスタック開発環境を構築する	🛠️ フルスタック開発環境	Docker Desktop・Dev Containers・React・TypeScript・Go・PostgreSQL・Node.js・Vite
第3回	ChatGPT Workでショッピングサイトを設計してみる	📐 システム設計	Project instructions・要件定義・ユースケース・画面設計・ER図・DB設計・REST API設計・テストケース仕様書
第4回	Codex × AGENTS.md × Skillsで実装準備を整える	🤖 AI開発ルール	AGENTS.md・プロジェクトルール・階層化・Skills・実装準備
第5回	Codexで設計書からショッピングサイトを実装する	🛒 ショッピングサイト実装	設計書・AGENTS.md・Skillsを活用した段階的なAI開発・実装・検証
第6回	Codexで実装したショッピングサイトをテスト・動作確認する	🧪 テスト・動作確認	test-cases.md・ユニットテスト・結合テスト・API・ブラウザ・DBによる動作確認
発展編①	Codexのエージェントハーネスでテスト・デバッグ・再テストを自律化する	🤖 エージェントハーネス	AGENTS.md・確定仕様・テストケース・停止条件を利用したテスト・デバッグ・修正・再テスト・Regression Testの自律化
発展編②	Playwrightでブラウザテストを自動化する	🎭 E2Eテスト自動化	Playwright・E2Eテスト・ブラウザ操作・Auto-waiting・Trace Viewer・Seleniumとの違い・Codexとの連携

参考リンク