# Exercise 3：画面詳細仕様書を作る（50 min）

## ゴール

要求整理シートを元に、Codex にコードを書かせる前段の「画面詳細仕様書」を作る。ChatGPT で初稿を出し、自分で精度を上げる。

## 終了条件

- `output/screen_spec.md` に画面が 1 つ以上、以下が埋まっている
  - 画面の役割
  - 表示する情報（項目名・データ型）
  - ユーザーが行える操作
  - 遷移先（CSV ダッシュボードでは「同一画面で完結」）
  - 制約
- Codex に渡したらコードが生成できる粒度になっている

## やること

1. `docs/screen_spec_template.md` を `output/screen_spec.md` にコピーする
2. ChatGPT に以下を送る

```
要件整理シートをもとに、画面詳細仕様書を 1 枚作ってください。

【要件整理シート】
[output/requirements.md の中身を貼る]

【出力形式】
- 画面タイトル
- 画面の役割（1〜2 行）
- 表示する情報（項目名 / データ型 / 補足の 3 列で表形式）
- ユーザーが行える操作（箇条書き）
- 遷移先
- 制約

これは AI に HTML プロトタイプを書かせるための設計書として使います。
曖昧表現を避け、データ型を必ず明示してください。
```

3. 出力を `output/screen_spec.md` に貼り付け、テンプレートの該当箇所を埋める
4. **データ型** が「string」「number」「日付」など具体名で書かれているかを確認。曖昧な「テキスト」「数字」になっていたら書き直す
5. 「ベンダーに見せても会話が成立する精度か」を自問して、足りなければ追記

## 補足：仕様書の粒度がコード品質を決める

AI のコード生成で「思った通りに出ない」最大の原因は、AI 側ではなく **仕様側にあります**。曖昧な仕様には曖昧なコードが返ります。

特にデータ型は要注意。「数字」と書くと AI は文字列として扱うかもしれませんし、桁区切りカンマ入りの整数として扱うかもしれません。「number（整数、3 桁区切りカンマあり、負数なし）」のように、AI が解釈で迷わない粒度にすると、出戻りが減ります。

実務でも、ベンダーに発注する時の仕様書はこのくらい細かく書く必要があります。AI と仕事するスキルは、そのままベンダーと仕事するスキルです。

## つまずいたら

- 「データ型が決まらない」 → サンプル CSV (`samples/sales-by-region.csv`) を開いてカラムを直接見る
- 「操作が抜けていそう」 → 「ユーザーがこの画面でやりたい動詞」を 5 個書き出して照らし合わせる。例：「アップロードする・絞り込む・並べ替える・拡大する・PDF 化する」
- 「画面が 2 つ目以上必要か分からない」 → CSV 可視化ダッシュボードは 1 画面完結を推奨。詳細表示や設定画面が欲しいと感じても、本研修では 1 画面で吸収する設計にする
- 「制約に書くことがない」 → 「何を意図的に作らないか」を 3 つ書く。「ユーザー認証は実装しない」「印刷ボタンは実装しない」など、明示の **しない宣言** が後段で効く

## Tips（実務で効かせるコツ）

- データ型は「JSON Schema 風に書く」と AI が即座に解釈できる。例：「price: integer, 0 以上, 桁区切りカンマあり」
- 操作は **動詞で始める**。「アップロード機能」ではなく「CSV をアップロードする」と書く。動詞があると、AI は対応するイベントハンドラを生成しやすい
- 制約に「やらないこと」を明示すると、AI が暴走して認証画面を作るような余計な親切が消える

## 注意

- 仕様書の最初に「これは AI にコード生成させる前段の設計書です」と書く。AI はこの 1 行で書き方を変えてくる
- 「素敵な」「モダンな」「直感的な」のような感想語を書かない。AI は具体物に変換できない

## 参考リンク

- [Prompt engineering best practices — OpenAI Help Center（出力形式の重要性）](https://help.openai.com/en/articles/10032626-prompt-engineering-best-practices-for-chatgpt)
- [Codex Prompting Guide — OpenAI Cookbook（コード生成向け仕様の書き方）](https://developers.openai.com/cookbook/examples/gpt-5/codex_prompting_guide)

## 観察ポイント

仕様書の粒度が荒いと、Codex の出力もブレます。データ型・操作・制約の 3 点を仕様書側で確定させると、AI のコード生成の出戻りが激減します。