はじめに
社内 SaaS に「アプリ内アンケート機能」を追加しました。質問を作るのはビジネス側の責任者、箱を作るのは開発側という分担です。
要件のすり合わせ開始から、実装完了（PR 3本マージ）までは 2 日でした。
速かった理由は、AI の実装力ではありません。要件定義の順序を変えたことです。文章で要件を固めてからモックを作るのではなく、モックを先に作って画面で要件を決めました。
この記事では、実際にやった 5 ステップと、その過程で「認識ズレが実装前に 3 回見つかった」話を書きます。
想定読者はこんな人です。
- 少人数チームで、ビジネス側（PdM・事業責任者）と仕様をすり合わせながら開発しているエンジニア
- Claude Code などの AI コーディングツールは使っているが、要件定義のやり方は変えていない人
前提
- チーム: 開発は少人数。要件の決裁者は非エンジニアのビジネス側責任者
- 作ったもの: アプリ内で条件に合ったユーザーにアンケートを出し、回答を集めて CSV で見られる機能
- 使ったツール: Claude Code（要件定義はモデルの力量差が出やすいので、そのとき使える最上位モデルを推奨）
従来のやり方の何が問題か
これまでの流れはこうでした。
文章で要件定義 → レビュー → 実装 → 「思ってたのと違う」
問題は、文章の合意は誤解を隠すことです。同じ文章を読んでも、読んだ人はそれぞれ別の画面を頭に描きます。それでも「OK」と言えてしまいます。ズレが見つかるのは、動くものができた後です。
ではなぜ今までモックを先に作らなかったのか。答えは単純で、モックを作るのが高くついたからです。デザインを起こして、画面を組んで、と数日かかるなら、先に文章で絞り込むのが合理的でした。
AI でこの前提が崩れました。実物のデザインに寄せたモックが数十分で作れます。安くなったものを先に作り、高いもの（意思決定）をそれに乗せる。順序が逆転します。
全体像: 5 ステップ
順に説明します。
Step 1: 先に決めるのは「あとから変えると作り直しになること」だけ
最初に私は「モックの前に要件をしっかり決めた方がいいか？」と迷いました。結論は No です。
先に決めるのは、データの持ち方が変わる分岐だけに絞ります。今回は 2 つでした。
- 回答形式は何種類必要か（単一選択だけか、自由記述やスケールもあるか）
- 非エンジニアが質問を編集できる管理画面を作るか
この 2 つは、あとから変えるとテーブル設計からやり直しになります。逆に、文言・配色・レイアウト・表示位置は、あとからいくらでも変えられます。モックを見ながら決めた方が速いので、先に決めません。
聞き方にもコツがあります。番号付きで、yes / no で答えられる形にして 1〜2 個だけ聞きます。「どんなアンケートにしたいですか？」のような自由記述の質問は、返事が遅くなるうえに曖昧な答えが返ってきます。
Step 2: モックを最初に作る。ただし「本物そっくり」で
2 つの答えが返ってきたら、文章化はせず、いきなりモックを作ります。
理由はシンプルで、人間は文章より視覚の方が理解が速いからです。文章の仕様を頭の中で画面に変換する作業は、書く側にも読む側にも負荷がかかります。最初から画面を見せれば、その変換が要りません。だから最初のすり合わせは、文章ではなくモックの画面を一緒に見ながらやります。「この画面でこう出ます」「ここを押すとこうなります」と画面で話す方が、圧倒的にイメージが湧きやすいからです。
作るときのポイントは 3 つです。
1. 実物のデザイントークンで作る
AI にプロダクトの CSS 変数（デザイントークン）と既存画面のコードを読ませて、実物と同じ色・部品でモックを作らせます。実物に近いほど、指摘の精度が上がります。ハリボテ感のあるワイヤーフレームだと「まあイメージだから」と流されてしまい、細部の違和感を拾えません。
2. 全画面を 1 ページに縦に並べる
ユーザーに見える画面と管理画面を 1 枚の HTML に縦に並べ、上から読めば仕様が通しで分かる構成にします。末尾に「決まったこと」「決めたいこと」のセクションを置き、決めたいことには「誰が決めるか」を添えます。
3. 更新は同じ URL に重ねる
指摘を反映するたびに新しいファイルを作るのではなく、同じ URL を上書きします。「最新の合意はここを見れば分かる」という状態を保つためです。
実際に起きたこと: 画面は誤解を暴く
モックを見せた瞬間、こんな指摘が来ました。
「あれ、ここの選択UIって何に使うものですか？これは無くてもいい気がします」
会話では素通りしていた設定 UI が、画面になった瞬間に不要だと発覚しました。さらに続けて、
「ここは同じ質問を、利用の節目ごとに 4 回出すイメージです」
こちらが「4 種類の質問を作る」と誤解していた基本仕様が、「同じ質問セットを利用の節目ごとに 4 回出して変化を見る」だったことも、モックがきっかけで判明しました。文章の合意は誤解を隠し、画面は誤解を暴きます。
Step 3: 要件書は「確認事項」を分けて書く
モックで大枠が決まってから、はじめて文章化します。順序が大事です。文章は「決めるための道具」ではなく「決まったことを固定する道具」として使います。
書き方で効いたのは 3 つです。
1. 機能は「〜できる」の箇条書きで書き、「今回つくらないもの」を必ず設ける
スコープ外を明記しないと、読み手（実装者と AI）が勝手に補完します。
2. 決まっていないことは本文に混ぜず、末尾の「確認事項」に分ける
並び順は「決まらないと着手できない順」です。各項目に選択肢とトレードオフを 1〜2 行で添えると、決裁者が即答できます。そして回答が揃ったら、本文に溶かし込んで確認事項セクションごと消します。残しておくと「まだ決まっていない機能」に見えてしまうからです。
3. 実装の手がかりをコードで裏取りして書く
「案件数のカウントは、既存のクレジット消費と同じトリガーに乗せる」のように、既存のどの仕組みを使うかをカラム名まで特定して書きます。AI に実装させるときも、人が引き継ぐときも、そのまま着手できます。
読んでもらう順序: 文章は最後の最後
ここがこの記事でいちばん伝えたいところです。要件書ができても、いきなり文章を読ませてはいけません。順序はこうです。
- 確認事項は、文章を渡さず口頭（またはチャット）で 1 問ずつ質問する。 穴だらけの文章を読ませると、認知負荷が高いうえに指摘するところが多すぎて、読む側が疲れます。疲れた読み手はレビューの精度が落ちます
- 回答を本文に溶かし込んで、文章を完成させる
- 完成した文章を、最終チェックとして時間をかけて読んでもらう。 この工程は省けません。「時間をかけて読む」という行為そのものが頭を使わせる作業なので、口頭では流れてしまったミスや齟齬にここで気づけます
つまり、口頭は「決めるため」、文章は「最終チェックのため」と役割を分けます。
1 つ注意点があります。要件書は 10 分前後で読み切れる分量にします。 読むのに 20〜30 分以上かかる要件書は、読み手の集中力が持たず最終チェックとして機能しません。そして、それだけ長くなるということは、そもそもタスク自体を分割した方がいいサインです。
実際に起きたこと: 文章化は 2 回目のフィルター
完成した要件書をビジネス側に最終チェックとして読んでもらったところ、こう返ってきました。
「表示タイミングは固定ではなく、自由に設定できるようにしたいです」
モックの段階で合意したはずの「表示タイミングは固定値」が、文章で読み直すと違ったわけです。会話 → 画面 → 文章と 3 つの形式を通すたびに、別の種類の誤解が濾し取られていきました。実装前に見つかったので、手戻りはゼロです。
Step 4: DB 設計は「動き」でレビューしてもらう
ここからは開発チーム内の話です。ビジネス側とのすり合わせは Step 3 で終わっていて、スキーマはビジネス側には見せません。
AI が出したスキーマ案を ER 図にしてチーム内でレビューしようとしたとき、正直に言うとこうなりました。
「DB を視覚的に見ただけじゃ、妥当かどうか判断ができない」
うちのチームは経験の浅いメンバーが中心で、ER 図を渡されても妥当性までは判断できません。考えてみれば当然で、**ER 図は構造しか見せません。妥当かどうかの判断に必要なのは動きです。**そこで AI に「3 つの見方」で説明資料を作らせました。
| 見方 | 内容 | 何が分かるか |
|---|---|---|
| いつ行が増えるか | 架空のユーザーの操作を時系列で追い、増える行を diff 風に見せる | テーブルの役割 |
| 画面のどこから来るか | 画面の項目とカラムの対応表 | 設計漏れ・不要カラム |
| 変えたら何が壊れるか | 削除・修正・二重送信などのシナリオで過去データを追う | 制約とスナップショットの妥当性 |
ポイントは「何も起きないステップ」も入れることです。たとえば「翌日また同じ画面を開いた → 何も増えない」という 1 枚があると、重複防止の仕様をそこで確認できます。
この資料で、DB を読み慣れていない人がスキーマレビューをできるようになりました。レビューの最後に置いた「5 つの質問」（このテーブルは誰が何をしたときに行が増えますか？など）は、資料を作らない場面でもそのまま使えます。
Step 5: 実装して、ずれたら要件書を直す
ここまで来れば実装は速いです。Issue は依存関係で 3 本に分割し（データモデルと管理画面 → ユーザー側表示 → 回答一覧と CSV）、1 Issue = 1 PR で進めました。
実装中の判断で、仕様は必ず少しずれます。今回も「CSV の列見出しは現在の質問文にする（回答の中身は回答時点のスナップショット）」といった判断が実装中に入りました。ずれたら要件書側を実装に合わせて更新します。
要件書を「作るための文書」で終わらせず「機能の説明書」として生かし続けると、あとから仕様を聞かれるたびにコードを読み直さなくて済みます。更新履歴にコメントを付けておけば、ページの履歴がそのまま意思決定の記録になります。
考察: なぜ AI 時代は「画面が先」になるのか
整理すると、こういう構造だと思っています。
| Before | After | |
|---|---|---|
| モックの製造コスト | 数日 | 数十分 |
| ボトルネック | 作ること | 決めること |
| 決める道具 | 文章 | 画面（＋文章で固定） |
モックが高かった時代は、文章で絞り込んでから作るのが合理的でした。モックがほぼタダになった今は、先に作って画面で決める方が合理的です。人は文章の行間は読み飛ばせますが、画面の違和感は一目で指摘できます。
注意点も書いておきます。
- モックの見た目に引きずられて、データ設計の議論が飛びやすい。 だから Step 1 で「作り直しになる分岐」だけは先に決め、Step 4 で DB 設計のレビューを別途やります
- モックがきれいすぎると「もうできてる」と誤解されることがあります。「見た目だけで中身はありません」と一言添えると安全です
おまけ: この型を AI への指示書にした
最後に、この一連の流れを Claude Code のスキル（AI に読ませる手順書）として保存しました。要件書のフォーマット、確認事項の運用、DB 説明資料の構成と見本画像まで同梱してあるので、次の機能では「〇〇機能を作りたい」と言うだけで同じ型で進みます。
AI 時代は、コードだけでなくうまくいったプロセスも資産化できます。1 回うまくいったやり方を、チームの誰が使っても再現できる形で残せるのは、地味に大きい変化だと思います。
まとめ
- 先に決めるのは「あとから変えると作り直しになること」だけ。yes / no で 1〜2 個
- モックを最初に作る。人間は視覚の方が速いので、すり合わせは画面を見ながら
- 確認事項は口頭で聞き、回答を溶かして完成させた文章を最終チェックとして時間をかけて読んでもらう
- 要件書は 10 分で読める分量に。超えるならタスク分割のサイン
- DB 設計は構造ではなく「動き」でレビューしてもらう（開発チーム内）
- 実装で仕様がずれたら、要件書を実装に合わせて更新する
最初の一歩としては、次の機能追加で「要件書を書く前にモックを 1 枚作る」だけでも試してみてください。指摘の量と質が変わるはずです。
参考
- First Round Review: How Superhuman Built an Engine to Find Product Market Fit — アンケート機能の元ネタになった PMF サーベイの手法
- 伊藤淳一『技術記事を書く技術』 — 本記事の書き方の参考
株式会社シンシア
株式会社xincereでは、実務未経験のエンジニアの方や学生エンジニアインターンを採用し一緒に働いています。
※ シンシアにおける働き方の様子はこちら
シンシアでは、年間100人程度の実務未経験の方が応募し技術面接を受けます。
興味のある方は、ぜひ上のリンクから覗いてみてください。