祈る前に、仕様を「明確」に書く
梅田 脩平 · 21 min read目次
AIガチャの当たり率を、少しでも上げるために
AIを使った開発は、かなり身近になりました。
PRDの下書きを作る。実装方針を整理する。UIのたたき台を作る。コードを生成する。こうした作業の初速は、AIによって確実に上がっています。
しかし、AIが常に100点の正解を出してくれるわけではありません。品質の高い、良いコードが出てくることもあれば、見当違いなコードが出てくることもある。今のAIコーディングは、言ってみればガチャのような側面があります。
何を作るかを明確に伝えられていないと、AIは“それっぽいが今回には合わないもの”（＝ハズレ）を作ってしまいます。
AIは便利です。ただし、チームの暗黙知や、プロダクト固有の前提、今の開発体制までは勝手に理解してくれません。
だからこそ、AIへ依頼する前に、まず仕様を明確に書く必要があります。
この記事では、AIをうまく使うための小技ではなく、AI時代における仕様の解像度について書きます。
AIで開発の初速は上がった
AIを使うと、開発の初速はたしかに上がります。
たとえば、以下のような作業はかなり速くなりました。
- PRDの下書きを作る
- 実装方針を整理する
- UIのたたき台を作る
- コードを生成する
- 仕様の抜け漏れを洗い出す
- テスト観点を出す
これまで時間がかかっていた最初のたたき台を作る作業は、AIによってかなり楽になりました。
特に、まだ形になっていないアイデアを文章化したり、実装の方向性をいくつか出してもらったりする場面では、AIはとても強力です。
しかし、初速の向上が、開発全体の高速化につながるとは限りません。むしろ、曖昧な仕様のままAIに依頼すると、あとから手戻りも増えてしまいます。
曖昧な仕様を渡すと、曖昧な実装が返ってくる
AIに曖昧な仕様を渡すと、AIはその曖昧さを補完してくれます。一見すると、これは便利です。
たとえば「商品一覧画面を作って」と伝えるだけでも、AIはそれっぽいUIやコードを出してくれます。検索欄、フィルター、ソート、テーブル、ページネーションなど、一般的な一覧画面にありそうな要素を組み合わせてくれるでしょう。
ただ、その補完が今回のプロダクトにとって正しい補完であるとは限りません。
曖昧な仕様を渡すと、だいたい次のような流れになります。
曖昧な仕様 ↓AIが“それっぽく”補完する ↓想定と違う実装ができる ↓手戻り・バグ・改修が増える最初の出力は速いが、その後に「いや、そうじゃない」「このケースでは困る」「この状態は許容したくない」「こういうケース漏れてない？」といった確認・修正が増える。
結果として、こうした時間が積み上がっていきます。初速は上がっているのに、トータルの開発時間はあまり短くなっていない。そんなことが起きてしまうのです。
これはAIの性能の問題というより、AIに渡している仕様の解像度の問題です。
チームの暗黙知は、AIには伝わらない
プロダクト開発では、仕様書に明示されていない前提がたくさんあります。たとえば、次のようなものです。
- お客様が実際にどう使うのか
- どこまでがMustで、どこからがNice to haveなのか
- 過去の議論で何をやらないと決めたのか
- 現在の開発体制でどこまで作り込めるのか
- 品質を優先するために、あえてシンプルにしている箇所はどこか
- プロダクト戦略上、今は何を捨てているのか
これらは、チーム内ではなんとなく共有されている前提知識みたいなものですが、AIはその暗黙知を知りません。
たとえば我々のプロダクトの例で言えば、「直近のメインターゲットが卸会社の営業担当者であること」「営業先での検索シーンに絞って開発したいこと」。また、「開発リソースが限られているため、MVPではとにかくシンプルで最低限の実装に寄せたいこと」などが挙げられます。 こうした細かい前提は、ドキュメントに書かれていなければAIには伝わりません。
AIは一般的な答えを返せます。しかし、このプロダクトにおける答えは、こちらが伝えない限り返ってきません。
例：商品一覧画面の「ビュー保存」
具体例として、商品一覧画面を考えます。
商品一覧では、Excelのようにソートやフィルターをかけたり、表示カラムを出し分けたりできます。画面だけを見ると、一見シンプルな機能に見えます。
PRDの下書きとしては、たとえばこのくらいはすぐに書けます。
- 商品一覧を用意する- ユーザーが設定した表示項目を表示できる- 表示項目や表示順を切り替えられる- キーワード検索ができる- フィルター・ソートで絞り込み・並び順を変更できる- よく使う設定は「ビュー」として保存し、あとから呼び出せるこれでも、AIはそれっぽいものを作ってくれます。ただし、本当に必要なのはここまででしょうか。
たとえば「よく使う設定をビューとして保存する」という一文だけでも、実際には多くの論点があります。
「ビュー保存」だけでも、決めるべきことは多い
「ビューを保存できるようにする」と聞くと、単純な機能に見えます。しかし、実装するには少なくとも次のようなことを決める必要があります。
- 何を保存するのか 表示カラムだけを残すのか、順番も含めるのか、フィルターやソート条件まで含めるのか。「ビュー」という言葉だけで保存対象を1つに決めるのは難しい。
- いつ保存するのか フィルター変更時の自動保存か、「保存」ボタンでの明示保存か。自動は便利な反面、意図しない上書きを招きやすい。明示保存は一手間増えるものの、ユーザーの意図が明確に残る。
- 表示設定と検索条件を一緒に保存するのか たとえば「表示設定」を変えたいだけなのに、たまたま残っていたフィルター条件まで保存されてしまうと、ユーザーの意図と結果がズレる。
- 保存後に何を正とするのか SPAとしてフロントエンドで差分更新するのか、URLの
view_idを更新してリロードするのか。滑らかさと状態整合性のどちらを優先するかで実装方針が変わる。 - 初期ビューをどう扱うのか 常に1件以上を持たせるのか、それとも0件の状態を許容するのか。常に1件あると親切な一方で、削除可否や権限の分岐が増え、MVPとしては複雑になりがちだ。
- 権限をどうするのか 作成や編集ができるのは誰か。チーム共有と個人保有のどちらを取るのか。プロダクトの使われ方によって判断が変わる。
AIが返しがちな一般解と、今回の判断
AIに「ビュー保存機能を作って」と依頼すると、一般的にはリッチな機能を提案してくれることが多いです。
- 今見えている状態（フィルターやソート含む）を丸ごと自動保存する
- 保存後はSPAらしく差分更新する
- 初期ビューは常に1件持たせる
- 共有や権限管理も考慮する
これらは、一般論としては間違っていません。しかし、今回のプロダクトでは、必ずしもそれが最適とは限りませんでした。
「検索条件」と「表示設定」は切り離す
一般的には、ビューには今見えている状態をすべて含めたくなります。
今回は保存操作を2種類に分けました。 1つ目は「現在の条件を保存」で、この操作ではフィルター・ソートを含めた条件を保存します。 2つ目は「表示設定の保存」で、こちらは「ビュー名・表示カラム・カラム順」のみを保存対象とします。 いずれも自動保存はせず、ユーザーの明示操作時のみ保存します。
理由は、営業やCSが問い合わせごとに異なる条件で商品を探すためです。試しに触ったフィルター条件までビュー定義に勝手に反映されてしまうと、現場での利用に耐えづらくなります。
そのため、「表示設定の保存」では未保存のフィルター・ソートは書き込まない仕様にしています。「表示設定の保存」と「検索条件の保存」は、ユーザーにとって意味が違う操作だからです。
再描画は「滑らかさ」より「状態の確実さ」を優先
保存後の画面更新については、SPAの差分更新ではなく、view_id でURLを更新してページリロードする方針にしました。
一般的には、差分更新のほうが体験として滑らかです。しかし今回は、滑らかさよりも状態整合性を優先しました。カラムの削除や並び替えのあと、古いソート条件やフィルター条件、インデックス参照が残ってしまうケースを避けたかったためです。MVPにおいて、そうした不整合は致命的になり得ます。
そのため、保存後はDBを正本として再取得し、画面を組み立て直す方針に寄せました。
初期ビューはあえて持たせず、分岐を減らす
初期ビューについては、常に1件持たせるのではなく、0件の状態を許容しました。ビューがない場合は新規作成導線を出すだけで、最後のビューを削除することも許容します。
これは、開発リソースが限られるMVPとして、分岐を減らすための判断です。必ず存在する特別なビューを作ると、削除可否や編集可否、遷移先などの分岐が増えます。今回はそうした複雑さを避け、シンプルな設計を優先しました。
仕様には「状態・操作・結果・制約」を書く
この例から分かるのは、仕様に書くべきなのは機能名だけではないということです。
「ビュー保存機能を作る」だけでは足りません。AIに正しく実装してもらうには、少なくとも以下のような観点を明確にする必要があります。
状態: どの状態を保持するのか 何を正とするのか 0件や未設定を許容するのか
操作: どの操作で保存するのか 自動保存なのか、明示保存なのか 操作の責務をどう分けるのか
結果: 保存後に画面はどう変わるのか URLは変わるのか 再読み込みするのか どのデータをもとに再描画するのか
制約: MVPでは何をやらないのか 権限はどこまで扱うのか どの不整合を避けたいのか 開発リソース上、どこまで作り込めるのかこれらを書いてはじめて、AIは今回のプロダクトに合った実装へ近づきます。
AIに任せるほど、人間の判断が重要になる
AIは、一般的な選択肢を出すのが得意です。「こういう機能なら、普通はこう作る」「このUIなら、一般的にはこういう状態管理にする」「この仕様なら、こういうAPI設計がありえる」。こうした案を出す力はとても強いです。
しかし、プロダクト開発で必要なのは、一般解をそのまま採用することではありません。
今回のお客様は誰なのか。どの業務シーンで使うのか。今のフェーズでは何を優先するのか。どの複雑さを避けるべきなのか。どの不便さは許容できるのか。
これらを踏まえて、今回の答えを決める必要があります。その判断は、AIではなく人間がするものです。
AIはチームの暗黙知を持っていません。プロダクトの戦略も、顧客の文脈も、開発体制の制約も知りません。だからこそ、AIへ依頼する前に、人間が仕様の解像度を上げる必要があります。
まとめ：AIガチャの当たり率は、仕様の解像度で上げられる
AIを使うと、開発の初速は確実に上がります。しかし、仕様が曖昧なままだと、AIは“それっぽいが今回には合わない”ものを返してしまいます。
AIガチャの当たり率を上げるために必要なのは、プロンプトの小技だけではありません。それ以上に大事なのは、仕様の解像度を上げることです。
表層的な機能名だけでなく、状態・操作・結果・制約といったシステム的な振る舞い。そして、顧客の実際の使い方や、MVPとしてのスコープ、今回のプロダクトならではの判断理由。
それらを言語化してはじめて、AIは単なる一般解ではなく、今回のプロダクトに合った実装を返しやすくなります。
ガチャを回して結果に祈るのをやめて、仕様を明確に書く。
当たり前に見えるこの前提こそが、AI時代の開発ではこれまで以上に効いてくる。日々AIを使いながら、そんなふうに感じています。
AIをガンガン使い倒したい。リチェルカでは、そんな仲間を募集中です。プロダクトの解像度を磨き、AIとともに最短距離でお客様へ価値を届ける。そんな働き方が気になった方は、ぜひお気軽にご連絡ください。