excel
基本設計書のテンプレートを探している段階では、欲しいものが目次の形だと思われがちです。実際に足りていないのは、どこまで書けば設計が終わったと言えるのかという線です。枠だけ手に入れても、その線は引かれません。
先に結論を書きます。基本設計書のテンプレートは、成果物の一覧として選ぶのではなく、誰と何を合意するかの単位として選びます。この見方に切り替えると、埋めるべき様式と、今回は作らなくてよい様式が分かれます。作らない判断ができるようになることが、テンプレートを使う最大の効き目です。
この記事では、テンプレートが整備されていない現場の実態から始めて、基本設計書に含まれる成果物の一覧、ExcelとWordのどちらで持つかの分かれ目、選ぶときに見る4つの点、埋める順番、運用で壊れるところ、そして道具の組み合わせの決め方までを順に扱います。
設計書のテンプレートは、どの会社にも整っているものだと思われています。実態はそうなっていません。受託の開発会社であっても、案件ごとに前の案件のファイルをコピーして名前を変えて使っている、という運用は珍しくありません。
フリーになってから参画先のプロジェクトで経験したのは、意外と設計書のテンプレートは整備されていないということです。 出典: note.com
整備されない理由は、担当者の怠りではありません。設計書の様式は、案件の規模と発注者の検査の仕方に強く引っ張られます。官公庁の案件では納品物の一覧が契約書で指定され、そこに合わせた様式が要ります。自社サービスの開発では検査そのものが無いので、画面の一覧と画面遷移図があれば足りることもあります。この幅を1つの様式で受けようとすると、どの案件でも半分が空欄のファイルになります。空欄が並んだ様式は、次の案件で誰も使わなくなります。
書籍の付録として配られているテンプレートも、同じ壁に当たります。汎用にするために項目が多く、そのまま使うと記入量が案件の実態に合いません。個人が公開している様式のほうが実務に近いことがあるのは、特定の規模と検査の形を前提にして作られているからです。
費用の見方も変えたほうがよい部分です。テンプレートそのものは無償で公開されているものが多く、有償のものでも数百円から数千円の範囲に収まります。基本設計に実際にかかる費用は、そこではありません。画面が30本ある規模で画面仕様書を1本ずつ書き、発注者のレビューを1周回すと、1本あたり1時間から3時間の幅で時間が消えます。人月の単価が80万円前後の相場で計算すると、様式の入手費と設計にかかる工数の差は3桁になります。テンプレートを選ぶ判断は、記入量を決める判断であり、そのまま費用を決める判断でもあります。
基本設計書は1つのファイルではありません。複数の様式の束です。上位に出てくる解説記事が長くなるのは、この束の全部を並べているからです。まずは全体像を押さえます。
業務の側から並ぶものが、業務フロー図と業務要件の一覧です。誰がいつ何をするかを先に固めないと、画面の数も決まりません。
機能の側から並ぶものは数が多くなります。機能一覧、処理機能記述、画面一覧、画面仕様書、画面遷移図、項目ラベル名一覧、エラーメッセージ一覧、帳票一覧、帳票仕様書、ファイル一覧、ファイル仕様書、外部インターフェース一覧、外部インターフェース仕様書、バッチ処理一覧、バッチ処理仕様書、システムメール一覧、システムメール定義書。一覧と仕様書が対になっているところが要点です。一覧は数を合意するための表で、仕様書は中身を合意するための様式です。数の合意が先にあり、中身の合意は後から来ます。
データの側から並ぶものは、DBテーブル一覧、DBテーブル定義書、DBビュー一覧、DBビュー定義書、ER図、コード一覧です。コード一覧は区分値の定義で、後から増えると画面と帳票の両方に影響するため、基本設計の段階で表にしておく価値があります。
全体にかかるものとして、命名規則、セキュリティ仕様、ワークフローの定義、そして非機能要件が並びます。非機能要件は性能、可用性、運用保守、移行、セキュリティといった観点ごとに整理するもので、情報処理推進機構が観点の枠組みを公開しています。自分で観点を考える必要はありません。公開されている枠組みに沿って、今回は要る観点と要らない観点を選ぶ形にします。詳しい資料は情報処理推進機構の公開資料から辿れます。
一覧と仕様書の対を意識しておくと、レビューの回数も読めるようになります。一覧のレビューは数を数える作業なので短時間で終わり、仕様書のレビューは中身を読む作業なので枚数に比例して時間がかかります。先に一覧を確定させるほど、後半の見積りが安定します。
この一覧を見ると、量に圧倒されます。しかし全部を毎回作るわけではありません。帳票が無いシステムに帳票一覧は不要で、バッチが無いなら バッチ処理一覧も不要です。テンプレートの役割は、この取捨選択を会議の冒頭で終わらせることです。一覧を画面に出して、要る様式に印を付ける。この作業が30分で終われば、テンプレートは役目を果たしています。
基本設計書のテンプレートを探すと、Excelのものと Wordのものの両方が出てきます。どちらが優れているかという議論になりがちですが、決め方はもっと単純です。
一覧になるものはExcelで持ちます。画面一覧、機能一覧、DBテーブル一覧、コード一覧、エラーメッセージ一覧。これらは行が増える表なので、並べ替えと絞り込みができる形のほうが扱いやすくなります。行数が数百になったときに、Wordの表では手が出せなくなります。
文章になるものはWordで持ちます。業務要件の説明、セキュリティの方針、非機能要件の考え方。これらは見出しと段落で読ませるもので、表に押し込むと読めない資料になります。
問題が起きるのは、画面仕様書のように図と表と文章が混ざるものです。ここを無理にExcelに寄せると、セルの結合が増えて、あとから項目を追加できないファイルになります。逆にWordに寄せると、項目の抜けを機械で検出できなくなります。実務では、項目の一覧をExcelで持ち、1画面ごとの仕様はWordか、あるいは画面の説明を書ける場所に置く、という分け方が落ち着きます。
もう1つ注意する点があります。Excelのファイルは、同時に開くと後から保存した側が勝ちます。基本設計の時期は、複数の担当者が同じ一覧を同時に触るため、ここで事故が起きます。ファイル名の末尾に日付と名前を足した版が並び、どれが最新か分からなくなる状態は、設計の遅れとして表面化します。共有の仕組みで同時編集ができる形にするか、一覧の担当を1人に決めて他の人は依頼を出す形にするか、どちらかを最初に決めておく必要があります。
テンプレートを比べるときは、見出しの数を数えても判断できません。次の4点を見ます。
1つ目は、粒度が案件に合っているかです。画面仕様書の様式に、入力チェックの条件を1項目ずつ書く欄があるかどうかで、記入量が数倍変わります。発注者が検査で条件の一覧を求める案件なら必要で、社内向けの小さなシステムなら過剰です。
2つ目は、一覧と仕様書が対になっているかです。一覧だけの様式は、数の合意しか取れません。仕様書だけの様式は、抜けが検出できません。両方が揃っていて、一覧の行数と仕様書の枚数が一致することを確認できる形になっているかを見ます。
3つ目は、更新を前提にした作りになっているかです。基本設計書は一度書いて終わりません。詳細設計と製造の途中で仕様が変わり、その変更が設計書に戻ってこないと、次の改修のときに誰も設計書を信じなくなります。改訂履歴の欄が各様式にあるか、あるいは変更を1か所で管理できる形になっているかを見ます。
この3つ目に関連して、様式の中に改訂の理由を書く欄があるかも見ておきます。何を変えたかだけが残っていて、なぜ変えたかが残っていない履歴は、次に読む人の判断材料になりません。1行でも理由が入る欄があるかどうかで、半年後の価値が変わります。
4つ目は、レビューの単位で切れているかです。ここが最も見落とされます。1つのファイルに全様式が入っていると、発注者に見せるときにファイル全体を渡すことになり、まだ固まっていない部分まで議論の対象になります。画面一覧だけを確定させたいのに、DB定義の未記入を指摘される。この状況は進行を止めます。合意を取りたい単位でファイルが分かれている様式のほうが、実務では速く進みます。
手順を決めておくと、書き始めの迷いが消えます。順番は、合意を取りやすいものから取りやすくないものへ、という並びにします。
最初に業務フローと業務要件を確認します。ここは要件定義の成果物を引き継ぐ形になるので、新しく書く量は少なくなります。確認の目的は、画面の数を推定できる状態にすることです。
次に画面一覧を作ります。画面の名前と役目と主な操作だけの表で、この時点で仕様は書きません。画面一覧を先に発注者と合意すると、以降の作業量が確定します。逆に画面仕様書から書き始めると、途中で画面が増えて見積りが崩れます。
画面一覧が固まったら、画面遷移図を作ります。遷移図を書くと、一覧に無い画面が必ず1つか2つ出てきます。確認画面、完了画面、エラー画面。ここで一覧に戻して数を直します。
ここまで終わってから、外側に広がります。帳票一覧、外部インターフェース一覧、バッチ処理一覧、システムメール一覧。それぞれ数を確定させてから、仕様書に入ります。
データの設計は、画面と帳票の項目が出てからのほうが速く進みます。先にER図を引くと、画面に必要な項目が後から足りなくなり、テーブルを組み直すことになります。項目ラベル名一覧を作りながらDBテーブル定義書を埋める形にすると、画面とデータの対応が自然に取れます。
最後に非機能要件と命名規則とセキュリティ仕様を固めます。これらは全体にかかるもので、個別の様式が出揃ってから決めたほうが現実的な内容になります。
テンプレートの効き目を説明するときに、作業が速くなるという言い方がされます。これは半分しか当たっていません。白紙から書いても、書ける人は速く書きます。
本当のメリットは2つです。1つは、抜けが検出できることです。エラーメッセージ一覧の欄があるから、エラー時の文言を誰が決めるのかという話が設計の段階で出ます。この欄が無いと、製造の終盤に開発者が仮の文言を入れ、検査で指摘され、文言の確認だけで2週間の手戻りが発生します。
もう1つは、合意の単位が決まることです。様式が分かれていると、どの単位で発注者の確認を取るかが自動的に決まります。画面一覧で1回、画面仕様書で1回、DB定義で1回。この区切りがあると、確認が終わった部分を後から蒸し返されにくくなります。
効き目が出ない使い方もあります。全部の欄を埋めることを目的にすると、記入のための記入が始まります。内容が薄いまま欄だけが埋まった設計書は、読まれないまま納品され、次の改修で使われません。埋めない欄には、今回は対象外と書いて理由を1行足す。これができている設計書のほうが、後から読む人には役に立ちます。
テンプレートを整えても、運用で壊れます。壊れ方には型があります。
最も多いのは、最新版が分からなくなることです。ファイル名に日付と担当者名が足され、同じ様式が5つ並ぶ。この状態は、ファイルを置く場所とファイル名の規則を決めていないと必ず起きます。日付を名前に入れる運用そのものが原因なので、履歴が自動で残る場所に保存して、名前は固定する形に変えます。
次に多いのは、変更が設計書に戻らないことです。製造の段階で仕様が変わり、その判断はチャットの中で終わる。設計書は古いままになり、次の改修で読んだ人が古い内容を信じて手を入れます。ここを直すには、仕様の変更を決めた場所と設計書が近いところにある必要があります。会話の記録と設計の記録が別の道具に分かれていると、戻す作業が誰の仕事でもなくなります。
3つ目は、レビューの記録が残らないことです。発注者が確認したはずの内容が、検査の段階で違う解釈になる。口頭とオンライン会議だけで確認を進めると、この食い違いが起きます。確認した日付と、確認した相手と、確認した範囲を、設計書の側に残す運用にします。
4つ目は、担当が1人に偏ることです。設計書を書ける人が1人しかいない状態では、その人の手が空くまで進行が止まります。テンプレートを整える本来の目的は、書ける人を増やすことです。1つの様式を2人で分担して書き、相互にレビューする形を最初から組んでおくと、この偏りが起きにくくなります。
様式の中で、記入量と手戻りの量が最も大きく振れるのが画面仕様書です。ここだけは中身に踏み込んで見ておきます。
画面の絵と項目の一覧は、どのテンプレートにも欄があります。抜けやすいのはその先です。1つ目は、項目ごとの入力の条件です。必須か任意か、文字の種類、桁数の上限、日付の範囲。ここが空欄のまま製造に入ると、開発者が推測で決めます。推測で決めた条件は検査で必ず指摘されます。
2つ目は、操作したあとにどうなるかです。登録のボタンを押したあと、同じ画面に戻るのか、一覧に戻るのか、完了の画面に進むのか。画面遷移図に描いてあるつもりでも、成功したときの遷移しか描かれていないことがよくあります。失敗したときにどこへ行くかを1行書いておくと、エラー画面の作り忘れが消えます。
3つ目は、権限による見え方の違いです。同じ画面を、管理者と一般の担当者と社外の関係者が開いたときに、何が見えて何が押せるのか。この違いを画面仕様書に書かず、権限の一覧だけ別の様式に置くと、実装のときに突き合わせる作業が発生します。画面ごとに1行の表を足しておくのが確実です。
4つ目は、データが無いときの表示です。一覧の画面で該当する行が0件だったとき、何を出すか。この欄が無いテンプレートは多く、結果として空白の表が出る画面が納品されます。件数が0のときの文言を決めるのは設計の仕事です。
この4つを画面仕様書の様式に足すと、記入量は増えます。増えた分は、製造と検査で減ります。どちらで時間を使うかという選択であり、設計の段階で使ったほうが安く済みます。
基本設計と詳細設計の線引きが曖昧なままテンプレートを選ぶと、記入量が読めません。ここを先に決めておくと、様式のどこまでを埋めるかが決まります。
実務で落ち着いている切り方は、外から見える振る舞いまでを基本設計、内部の実装の決めごとを詳細設計に置く形です。画面に何が表示され、どの操作で何が起きて、どの条件でエラーになるか。ここまでは発注者と合意する内容なので基本設計に入ります。その処理をどのクラスで受けて、どの単位でメソッドに分けるか。ここは開発者の裁量で決めてよい内容なので詳細設計です。
この線で切ると、発注者が読む範囲と開発者だけが読む範囲が一致します。テンプレートを選ぶときに、実装の書き方を求める欄が並んでいたら、それは詳細設計の様式です。基本設計の段階で埋めようとすると、まだ決まっていない内容を仮で書くことになり、あとで全部書き直します。
境目に乗るものが2つあります。1つはDBテーブル定義書です。テーブルの名前と項目と型と桁数までは基本設計に入りますが、インデックスの設計と物理的な配置は詳細設計に寄ります。もう1つは外部インターフェースの項目定義です。相手のシステムと合わせる内容なので早く固める必要があり、詳細設計まで待てません。基本設計の段階で項目の一覧を作り、通信の方式と再送の扱いだけ先に合意しておく形が現実的です。
境目を決めたら、テンプレートの欄にその線を書き込んでおきます。この欄は詳細設計で埋める、と1行入っているだけで、記入する人の迷いが消えます。
受託の案件では、様式の選択に自由がありません。契約書か仕様書に納品物の一覧が指定されており、そこに書かれた成果物は名前まで合わせて作る必要があります。テンプレートを選ぶ前に、契約書の納品物一覧を確認する。この順番を逆にすると、作った様式が検査で受け付けられません。
検査を通す前提で足す欄は決まっています。改訂履歴の表、承認者の欄、ページ番号と文書の通番、そして用語集です。改訂履歴は各様式の先頭に置き、版と日付と変更内容と担当者を1行ずつ残します。あとから思い出して書けるものではないので、変更した日に書く運用にします。
もう1つ、後から作ると負担が大きいものがあります。要件と機能の対応表です。要件定義書のどの要件が、基本設計書のどの機能で実現されているかを並べた表で、検査の場で必ず聞かれる内容です。これを納品の直前に作ると、要件と機能を突き合わせる作業に数日かかります。機能一覧を作るときに要件の番号を1列足しておけば、対応表はその列を並べ替えるだけで済みます。列を1つ増やすかどうかの判断が、後半の数日を決めます。
官公庁の案件では、様式そのものが指定されていることもあります。この場合は自分でテンプレートを選ぶ余地がなく、指定された様式に内容を合わせる作業になります。市販のテンプレートを探す前に、発注者から様式が出ていないかを確認しておきます。
自社のサービスを作っている場合、検査はありません。納品物の一覧も無く、様式を全部作る理由もありません。それでも省かないほうがよいものがあります。
省いてよいものから挙げます。処理機能記述、ファイル仕様書、ワークフロー定義、そして承認者の欄。これらは検査のために要る様式なので、検査が無ければ作らなくても困りません。画面仕様書も、画面の数が少なく作る人と使う人が同じなら、画面一覧に補足を足す形で足りることがあります。
省かないほうがよいものは4つです。画面一覧、画面遷移図、DBテーブル定義書、コード一覧。この4つは、半年後に改修する人が最初に読むものです。改修する人が自分自身である場合でも、半年前の判断は覚えていません。画面遷移図が無いと、どの画面からどの画面に行けるのかをコードから読み直すことになり、その作業に数時間かかります。
コード一覧を残す理由は別にあります。区分値は運用の途中で増えます。ステータスが4つだったものが7つになり、画面の表示と集計の条件と通知の判定に影響します。一覧が1か所にあれば、増やすときに影響の範囲を数えられます。一覧が無い場合、コードの中を探し回ることになります。
人の入れ替わりがある規模では、もう1つ足します。決定の理由です。なぜこの構造にしたのか、なぜこの方式を選ばなかったのか。設計書の様式には、この欄が無いことが多くあります。表の下に3行の補足を書くだけで、次の人が同じ議論を繰り返さずに済みます。
設計書はExcelとWordで作るのに、進行の管理は別の道具で行う。この分かれ方が、更新が戻ってこない原因になっています。道具を選ぶときの考え方を整理します。
文書そのものは、ExcelとWordのままで構いません。発注者に渡す形式が指定されている案件では、ここを変えられません。変えるべきなのは、その文書がどの作業に紐づいているかを見える場所です。画面仕様書の第3版を書いているのは誰か、レビューは誰が待っているのか。この情報を文書の中に書くと、探せなくなります。
進行を1枚の板で持つと、ここが解決します。画面ごとにカードを作り、そこに設計書のファイルと、決まったことと、確認待ちの相手を集める。ボード型のタスク管理の道具でできることの範囲はできることにまとまっており、カードに説明文と添付と議論を同じ場所で持てるかどうかが分かれ目になります。
文書を書く場所と進行を見る場所を1つにまとめる考え方もあります。文書の作成に強い道具と、進行の管理に強い道具の性格の違いはNotionとの比較で整理しています。開発の案件で使われる道具との違いはBacklogとの比較にまとめました。どちらも、設計書を書く作業に向いているか、進行を見る作業に向いているかで評価が変わります。主要な道具を横に並べた表は比較の一覧にあります。
費用の目安も先に見ておきます。ボード型の道具は少人数なら無料で使えるものがあり、人数が増えたところから1人あたり月額500円（税抜）程度の価格帯から始まります。具体的な区切りは料金で確認できます。設計書の様式を整える工数と比べると、道具の費用は判断の材料として小さい側に来ます。
最後に、テンプレートの選び方を1つの基準に戻します。
基本設計書のテンプレートは、成果物の一覧としてではなく、合意の単位として選びます。画面の数を合意する様式、画面の中身を合意する様式、データの構造を合意する様式。この3つが別のファイルになっていれば、確認の会議を3回に分けられます。1つのファイルに全部が入っていると、会議は1回にまとめるしかなく、その1回が終わらないまま日程が延びます。
合意の単位でファイルを切ると、保存する場所も自然に決まります。合意を取る相手ごとに、渡す範囲が分かれるからです。発注者に渡すもの、社内のレビューで使うもの、開発者だけが見るもの。この3つが混ざったファイルは、どこに保存しても事故が起きます。
そして、切った単位ごとに進行を見る必要が出ます。画面一覧は確認待ち、画面仕様書は執筆中、DB定義は未着手。この状態が1枚で見えていないと、進行のとりまとめをしている人が毎回聞いて回ることになります。様式を分けた瞬間から、分けた数だけ進行の管理が要る。ここまで含めて考えると、テンプレートの選択は文書の話ではなく、進行の設計の話になります。
導入の段階でよく出る疑問はよくある質問にまとめています。
一覧になるものはExcel、文章になるものはWordで持つ形が扱いやすくなります。画面一覧・機能一覧・DBテーブル一覧のように行が増える表はExcel、業務要件やセキュリティの方針のように読ませる資料はWordです。図と表と文章が混ざる画面仕様書は、項目の一覧をExcelで持ち、1画面ごとの説明を別に置く分け方が落ち着きます。
案件によって変わりますが、画面一覧・画面遷移図・機能一覧・DBテーブル定義書の4つは多くの案件で必要になります。帳票やバッチや外部連携が無いシステムでは、対応する一覧と仕様書は作りません。使わない様式には対象外と書いて理由を1行添えておくと、後から読む人が判断できます。
無償で公開されているものが多く、有償のものでも数百円から数千円の範囲に収まります。実際に費用が出るのは記入とレビューの工数のほうで、画面が30本ある規模なら仕様書1本あたり1時間から3時間の幅で時間が消えます。様式を選ぶ判断は記入量を決める判断なので、費用への影響はここに出ます。
仕様の変更を決めた場所と設計書が近いところにある状態を作ります。変更の判断がチャットの中だけで終わると、設計書に戻す作業が誰の仕事でもなくなります。画面ごとにカードを作り、そこに文書と決定と確認待ちの相手を集める形にすると、変更のたびに戻す相手が決まります。