「こういうアプリを作りたい」だけでは、実装に入れません。かといって仕様書を先に全部書くのも重い。いきなり「仕様書を書いて」と渡すと、それらしいものが返ってきますが、そこに書かれているのは自分が作りたいものではありませんでした。足りない情報が埋められるからです。私はAIに質問させることから始めるやり方に落ち着きました。一人でアプリとサイトを作りながら、曖昧な思いつきを開発できる形へ変える手順と、未定を消させない書き方、できた仕様書の置き場所までまとめます。
いきなり書かせると、それらしい嘘が返ってくる
最初にやって失敗したのが、「ランニングアプリの仕様書を書いて」と渡すことでした。画面構成も機能一覧も、きれいな形で返ってきます。ただ、そこに書かれているのは私が作りたいものではありませんでした。
当たり前で、こちらが渡した情報が少なすぎます。足りない部分は埋めるしかないので、一般的なランニングアプリの姿が入ります。しかも、もっともらしく書かれているぶん、読んでいると「そんな気がして」きます。
厄介なのはここからです。その仕様を前提に実装へ進むと、違和感に気づくのは動くものが出てきたあとになります。戻る距離が長い。
しかも、出てきた画面がきれいだと、こちらが折れます。「まあこれでもいいか」と思ってしまう。作りたかったものと、作れてしまったものが入れ替わる瞬間が、たしかにありました。
この失敗を避ける方法は一つで、書かせる前に聞かせることでした。順番を入れ替えるだけです。
手順：仕様書ではなく、先に質問を出させる
01 整えずに思いつきをそのまま渡す
整える必要はありません。「走る距離を決めたら、その距離で一周して戻ってこられるコースを出したい」くらいで十分です。きれいに書こうとすると、この段階で手が止まります。
02 仕様書ではなく、質問を出させる
「これを実装できる形にするために、足りない情報を質問してください。推測で埋めないでください」と渡します。ここが肝で、埋めるなと明示しない限り埋められます。返ってくる質問の多さで、自分の中でどれだけ決まっていなかったかが分かります。
03 答えられるものだけ答えて返す
全部に答える必要はありません。決まっていないものは「決まっていない」と返します。これも情報です。仕様書に「未定」と書かれていれば、実装前に必ず目に入ります。
04 未定を含んだ状態で書かせる
答えた内容と「未定」を反映した形で書かせます。空欄のある仕様書は不格好ですが、空欄が見えていることのほうが大事です。
05 仕様を確認の手順まで落とす
最後に「この仕様どおりかを確かめる手順を書いて」と続けます。ここまでやると、仕様書がそのまま受け入れの基準になります。
質問が浅いときは、渡す材料と頼み方を変える
質問が浅いときは、こちらの情報が足りません。似たアプリの画面、既存のコード、使いたい外部サービスの名前。渡せるものを足すと、質問の粒度が上がります。
私の場合、既存のコードを読ませるのが一番効きました。書き方の作法が伝わるので、既存と揃った仕様が出てきます。ゼロから説明するより速い。
もう一つ有効だったのは、似ているが違うものを渡すことです。「このアプリに近いが、ここだけ違う」と言えると、違いの部分に質問が集中します。ゼロから聞かれるより、こちらも答えやすい。
何を書けばよいかという中身の話はアプリの仕様書は何を書けばいい？個人開発で使う九つの項目にまとめています。この記事は、それをどう埋めるかの話です。
同じ「質問してください」でも、付け方で返りが変わります。私がよく足すのは次の3つです。
一つ目は答えの選択肢も一緒に出させること。「質問と、考えられる選択肢を添えてください」と頼むと、こちらは選ぶだけで済みます。ゼロから言葉にするより速い。
二つ目は決めないと先に進めない順に並べさせること。質問が20個返ってくると、それだけで止まります。実装をブロックする順に並んでいれば、上から3つ答えて着手できます。
三つ目はその質問がなぜ要るのかを書かせること。理由の弱い質問は、答えなくてよい質問です。ここで質問の数がだいぶ減りました。
逆に、質問が多すぎるのも困ります。20個返ってくると、それを読むだけで止まります。優先順に並べさせるのはそのためで、上から3つ答えれば着手できる状態にしておくと、そこで一度手が動きます。残りは実装しながら決まることもあります。
弱い頼み方
足りないことを質問してください。
強い頼み方
実装できる形にするために足りない情報を質問してください。推測で埋めないでください。各質問には、考えられる選択肢と、その質問がなぜ必要かを添えてください。決めないと着手できない順に並べてください。
「決まっていない」を消させない。未定は未定と書く
一番気をつけているのがここです。未定の項目は、放っておくと次の往復で消えます。書き直しを頼んだときに、それらしい値で埋まって戻ってくる。
対策は単純で、未定のまま残すことを明示的に指示します。「未定の項目は未定のまま残し、勝手に決めないでください」と毎回添えます。
決めるのは私の仕事です。材料を集めさせることと、決めさせることは別で、ここを混ぜると自分が何を選んだのか分からなくなります。任せる範囲の線引きはAIに任せてよい作業・任せない作業をどう決める？三つの基準に書きました。
未定を残すもう一つの効用は、優先順位が見えることです。空欄が10個あって、そのうち3つが無いと実装に入れないなら、次に決めるのはその3つです。全部を一度に決めようとして止まるより、ずっと進みます。
実装から仕様を起こす場合と、書いたあとの置き場所
順番が逆になる場面もあります。作ってしまったものを、あとから文書にする場合です。
私はアプリの法務文面を、実装から1項目ずつ起こしました。認証の仕組み、保存しているデータ、課金の扱いを読ませて、実際の挙動として何が言えるかを並べる。そのうえで、文面に書いてあるのに実装に無いもの、実装にあるのに文面に無いものを洗い出します。
このとき見つかったのが、分析ログに位置情報は入れていないつもりが、地図の部品が既定で送っていたという食い違いでした。自分の書いた行だけを見ていると出てきません。実装を読ませて書かせる形にしたから見つかりました。
仕様を頭の外へ出す考え方そのものはひとりで3つのアプリを作る。仕様を「頭の中」に置かないためにやっていることにまとめています。
書かせた仕様は、会話の中に置いたままにしません。ファイルにしてリポジトリへ入れます。次に作業を頼むとき、同じ説明を繰り返さずに済むからです。
置くときの決まりを2つ持っています。同じ内容を2か所に書かないことと、確認済みかどうかを分けて書くことです。後者は特に効きました。コードを読んで分かったことと、外部のサービスに問い合わせないと確定しないことは、同じ文書の中でも別に扱います。
実際、あるアプリの公開前チェックでは「コードだけでは確定できない」と明記した項目を残しました。委託先の処理国や保存期間のように、実装を読んでも決まらないものです。あとから読んだときに、確かめた項目と確かめていない項目が混ざらずに済みます。
この区別を省くと、数か月後の自分が全部を「確認済み」として読みます。そこから先の判断がまとめてずれるので、書式として分けておく価値がありました。
置き場所を決めておくと、次の依頼が短くなります。「仕様書のここを見て、この部分を実装して」で通るからです。会話の中に仕様が散らばっていると、毎回そこから説明し直すことになります。ファイルにするのは整理のためではなく、次の依頼を短くするためでした。
- 決まったことは仕様書へ。会話に残さない。
- 未定は未定と書く。空欄を埋めない。
- 確認済みと未確認を、同じ文書の中で分ける。
- 同じ内容を2か所に持たない。出どころを指す。
よくある疑問と、この方法が向かないケース
AIに仕様書を丸ごと書かせてはいけませんか？
書かせること自体は問題ありませんが、渡した情報が少ないと足りない部分が埋められます。埋められた部分はもっともらしく書かれるので、読んでいるうちに自分が決めたことのように思えてきます。先に質問を出させると、この埋まりが起きません。
質問が20個も返ってきて答えきれません。
決めないと着手できない順に並べさせてください。上から3つ答えれば実装に入れます。加えて「その質問がなぜ必要かを添えて」と頼むと、理由の弱い質問が減ります。全部に答える必要はありません。
未定の項目があるまま実装に入れますか？
入れます。⚠️ 未定が見えていることのほうが大事です。空欄が10個あって、そのうち3つが無いと着手できないなら、次に決めるのはその3つだと分かります。全部を一度に決めようとするより進みます。
未定と書いたのに、いつの間にか埋まっています。
書き直しを頼んだ往復で消えます。「未定の項目は未定のまま残し、勝手に決めないでください」を毎回添える必要があります。一度言えば覚えている、という前提で進めると埋まります。
仕様書はどこまで細かく書けばいいですか？
目安は説明をもう一度することになりそうかです。一度で終わる作業なら会話のまま、二度目がありそうならファイルにします。数行の直しに仕様書は要りません。
まだ作るものが決まっていない段階でも使えますか？
向きません。形にすると、それを守ろうとしてしまうからです。迷っている段階なら、仕様ではなく選択肢を並べさせるほうが向いています。「この方針で作ると、あとから変えにくくなる部分はどこか」と聞くと材料が出ます。
何を作るかがまだ揺れている段階では、仕様書に落とすのが早すぎます。形にすると、それを守ろうとしてしまうからです。
形にするのは、捨てる覚悟が決まってからがちょうどよかった。まだ迷っているなら、仕様ではなく選択肢を並べさせるほうが向いています。「この方針で作った場合に、あとから変えにくくなる部分はどこか」と聞くと、決める材料が出てきます。
逆に、作るものが決まっていて実装だけが残っているなら、この手順は強く効きます。質問に答えるだけで、渡せる形になります。
規模も関係します。数行の直しに仕様書は要りません。目安にしているのは、説明をもう一度することになりそうかどうかです。一度で終わる作業なら会話のまま、二度目がありそうならファイルにします。
