仕様書は長い説明書ではなく、数週間後の自分が同じ判断をするための基準です。一人だと誰も指摘しないので、頭の中に置いたままだと食い違ったまま進みます。最低限、目的、画面、操作、データ、例外、完了条件を分けて書きます。この記事では、書く九項目、画面ごとの形、完了条件を操作で書く理由、正本を増やさない置き方、そして書かなくてよいものまで並べます。個人開発の範囲で、実際に使っている形をそのまま書いていきます。
仕様書の九項目。判断の基準になるものだけ書く
仕様書を「作るものの説明」だと思うと、長くなって読まれなくなります。目的は、迷ったときに戻る場所を作ることです。だから、判断に使う項目だけを書きます。
九項目のうち、最初の3つが判断の基準になります。目的、対象、利用シナリオ。ここが書いてあれば、機能を足すか削るかを自分で決められます。
⚠️ 「対象外」を書くのを忘れないでください。誰のためではないかを書いておくと、要望が来たときに判断できます。対象だけを書くと、境界が曖昧なままになります。
後半の6項目は、実装しながら埋まっていくことが多いです。画面一覧、データ、権限、エラー状態。最初に全部を決めようとすると、着手が遅れます。決まった順に書き足していく形で足ります。
九項目に入れていないものもあります。スケジュール、工数、体制。一人でやっている範囲では、書いても判断に使いませんでした。
⚠️ 書く順番も決めていません。書ける項目から書くほうが手が止まりません。上から順に埋めようとすると、決まっていない項目で詰まります。
- 目的と解決する課題。
- 対象ユーザーと対象外。
- 主要な利用シナリオ。
- 画面一覧と遷移。
- 各画面の操作と表示条件。
- 保存するデータと削除方法。
- 権限・通知・課金。
- エラー・空・読み込み状態。
- 完成条件と公開対象OS。
画面ごとに書く形。目的・入力・出力・例外
画面の仕様は、4つの欄で足ります。目的、入力、出力、例外。この形にしておくと、画面が増えても書き方が変わりません。
「目的」に書くのは、その画面で終える行動です。機能名ではありません。「検索画面」ではなく「コース条件を決める」と書くと、何が揃えば完成かが決まります。
例外の欄がいちばん効きます。候補が0件、通信が失敗、権限が無い。ここを書かないと、実装のときに毎回その場で決めることになります。決めた内容も残りません。
4つの欄で書くと、画面をまたいだ見落としにも気づけます。ある画面の出力が、次の画面の入力になっているか。並べて見ると、途中で切れているところが分かります。
画面が少ないうちは、1画面1ブロックで並べるだけで足ります。遷移図を描くのは、画面が増えて頭で追えなくなってからで間に合います。
| 項目 | 書く内容 | 例 |
|---|---|---|
| 目的 | 画面で終える行動 | コース条件を決める |
| 入力 | 利用者が選ぶもの | 距離・時間 |
| 出力 | 表示する結果 | 候補コース |
| 例外 | 失敗時の表示 | 候補なし・通信失敗 |
表は左右にスクロールできます。
完了条件を操作で書く。機能名では決まらない
「検索機能を実装する」では、どこまでできれば完了か分かりません。機能名は範囲を示していないので、いつまでも終わりません。
代わりに、利用者の操作で書きます。「場所を入力し、候補を選び、結果が0件の場合も次の行動が表示される」。この形なら、通ったかどうかが自分で判定できます。
操作で書く利点は、そのまま確認の手順になることです。仕様書を読みながら同じ操作をすれば、完成したかどうかが分かります。別に確認項目を作らなくて済みます。
AIに実装を頼むときも、ここが効きます。⚠️ 完了条件を渡さないと、動くけれど意図と違うものが返ってきます。渡し方はAIにコードを書かせる前に決めるべき5つと、その置き場所にまとめました。
⚠️ 「品質が高い」「使いやすい」は完了条件になりません。判定できないからです。判定できない言葉が入っていたら、操作の形に直せるかを考えます。直せないなら、それは完了条件ではなく願いです。
完了条件を書くタイミングは、実装を始める前です。作りながら決めると、できたものに合わせた条件になります。それでは判定の意味がありません。
完了条件が長くなるときは、画面か機能を分ける合図です。1つの条件に「〜して、〜して、〜する」が3つ以上入っていたら、たぶん2つの作業が混ざっています。
操作で書いておくと、あとから検査に変えられることもあります。「0件でも次の行動が出る」は、機械で確かめられる形です。人が毎回見るのをやめられます。
書かなくてよいもの。増やすと読まれなくなる
仕様書が続かない理由は、たいてい書く量が多すぎることです。読む相手が自分しかいないのに、説明の体裁を整えようとして長くなります。
私が書いていないものを挙げると、背景の説明、技術の選定理由、画面のデザイン詳細、将来の構想です。どれも大事ですが、判断の基準としては使いません。
背景や選定理由は、別の場所に残します。仕様書の中に混ぜると、実装のときに読み飛ばす部分が増えます。読み飛ばす部分があると、他の箇所も読まれなくなります。
デザインの詳細も分けています。色や余白は画面を見れば分かりますが、「何が揃えば完成か」は画面を見ても分かりません。仕様書に残すのは後者だけです。
将来の構想は、削った理由と一緒に別の場所へ置きます。仕様書に書くと、いま作るものと区別がつかなくなります。削る判断の残し方はMVPとは？最初のアプリで機能を絞る方法と、外れたときの扱いに書きました。
結果として、私の仕様書は短いです。短いほうが読み返されるので、基準として機能します。長くて読まれない文書は、無いのと変わりません。
とはいえ、書きたくなったら書いてかまいません。問題なのは量ではなく、判断に使う部分が埋もれることです。分けて置けば、長くても困りません。
判断に使うかどうかの見分け方は、「これを読んで何かを決めるか」です。読んで理解するだけのものは、説明であって基準ではありません。
正本を増やさない。同じ内容を二か所に書かない
同じ仕様をチャット、Issue、README、メモへ書くと、一部だけ古くなります。そして、どれが正しいか分からなくなります。
対策は一つで、仕様の正本を決めて、会話や作業記録からは正本へリンクする。写すのではなく、指すようにします。
⚠️ 数字や一覧はとくに複製しないようにしています。「画面は5つ」と書くと、増えたときに必ず古びます。本数ではなく、どこを見れば分かるかを書きます。
私はこの方針を、サイトのリポジトリ全体でも使っています。同じ内容を2箇所に持たない。事業者情報も法務条文も、置き場所は1つだけです。
ClearDropで複数アプリを並行開発するときの分け方はひとりで3つのアプリを作る。仕様を「頭の中」に置かないためにやっていることにまとめています。最初の機能を決める前ならMVPとは？最初のアプリで機能を絞る方法と、外れたときの扱いから始めてください。
正本を決めたら、そこを更新する習慣だけ作れば足ります。決めたことを会話の中で済ませてしまうと、次に作業するときに探すことになります。
リンクで繋ぐ形にしておくと、正本を移動しても直す場所が1つで済みます。内容を写していると、写した先を全部探すことになります。
よくある疑問と、一人で書く仕様書の目的について
個人開発でも仕様書は必要ですか？
数週間後の自分が同じ判断をするために要ります。一人だと誰も指摘しないので、頭の中に置いたままだと食い違ったまま進みます。形式は問いませんが、あとから読める場所に置いてください。
何から書けばいいですか？
目的、対象、利用シナリオの3つからです。ここが書いてあれば、機能を足すか削るかを自分で決められます。画面やデータは、そのあとで埋まります。
完了条件はどう書きますか？
利用者の操作で書いてください。「検索機能を実装する」では範囲が決まりません。「場所を入力し、候補を選び、0件でも次の行動が出る」なら判定できます。そのまま確認の手順にもなります。
仕様が決まっていない部分はどうしますか？
「未定」と書いておいてください。空欄が見えていることのほうが大事です。決まっていないのに埋めると、自分が決めたつもりになります。空欄が10個あって3つが着手を止めているなら、次に決めるのはその3つです。
仕様書が長くなって読まなくなります。
⚠️ 判断に使わないものが混ざっています。背景の説明、技術の選定理由、デザインの詳細、将来の構想。どれも大事ですが、別の場所に置いてください。読み飛ばす部分があると、他の箇所も読まれなくなります。
仕様書はどこに置けばいいですか？
正本を一つ決めて、他からはリンクしてください。チャット、Issue、README、メモに同じ内容を書くと、一部だけ古くなってどれが正しいか分からなくなります。写すのではなく、指すようにします。
仕様書はいつ書けばいいですか？
目的と対象は作り始める前、残りは決まった順で足ります。全部を先に決めようとすると着手が遅れますし、作りながら決めたことを書き残さないと、数週間後に理由が分からなくなります。
仕様が途中で変わったらどうしますか？
正本を書き換えて、変えた理由を残してください。古い内容を消すだけだと、なぜ変わったかが分かりません。前提が戻ったときに、判断をやり直せなくなります。
実装が終わった機能の仕様はどうしますか？
残します。数か月後に触るとき、なぜその形なのかが分かるのは仕様書だけです。実装を読めば何をしているかは分かりますが、なぜそうしたかは書いてありません。
⚠️ この記事は、チームで使う仕様書を扱っていません。個人開発で、読む相手が自分だけという前提で書いています。人数が増えると、必要な項目も書き方も変わります。
また、特定の書式やツールも推奨していません。形式より、判断の基準として読み返されるかのほうが重要だと考えています。
覚えておくと使えるのは、判断に使わないものは書かないという1点です。仕様書が長くて読まれないなら、それは無いのと変わりません。短くして読み返されるほうが、目的を果たします。
書き方より、読み返される形になっているかを先に見てください。
