【お仕事ネタ】シバ丸印のこう書いたら楽じゃない？シリーズ第一弾：未来の自分と後工程の人に恨まれないための要件定義書の話--設計書レビューで困るのは「項目」より「レベル感」かもしれない--
要件定義書や基本設計書には、たいてい項目があります。
画面。
機能。
外部連携。
エラー処理。
権限。
非機能要件。
運用。
移行。
TBD。
もちろん、項目がない設計書は困ります。
ただ、実務で本当に厄介なのは、項目があるかどうかだけではありません。
むしろ困るのは、
「書いてはあるけど、この粒度で本当に足りるのか？」
という問題です。
設計書レビューをしていると、こういう場面があります。
レビュー時点では、
まあ、外部連携については書いてあるし、後で詳細化すればよいか。
と通した。
ところが、基本設計や結合テストの段階になってから、
失敗時って予約は完了扱いなんですか？
再送って自動ですか？手動ですか？
外部側に登録済みだった場合、二重登録はどう防ぐんですか？
利用者には何て表示するんですか？
それ、要件定義で決まってないんですか？
と返ってくる。
出ました。
後工程名物、時を超えて刺さるブーメランです。
こうなると、設計書に項目があったかどうかは、もはやあまり慰めになりません。
問題は、項目が存在することではなく、後工程に進めるだけの粒度で書かれていたかどうかです。
この記事では、設計書レビューでよく起きる “レベル感が揃わない問題” について書いてみます。
なお、本文中の例は説明用に作成した架空の旅行予約サイトを題材にしています。
特定の企業、サービス、案件、業務システムを想定したものではありません。
「書いてある」と「使える」は違う
たとえば、架空の旅行予約サイトで、次のような要件定義の記載があったとします。
ホテル予約確定時に、外部ホテル在庫管理システムへ予約情報を連携する。
エラー時はメッセージを表示する。
一見すると、外部連携について書かれているように見えます。
たしかに、連携先らしきものは書いてある。
連携タイミングらしきものも書いてある。
エラー時の話にも触れている。
でも、要件定義レビューの観点では、このままだとかなり不安が残ります。
たとえば、次のようなことが分かりません。
何のために外部ホテル在庫管理システムへ連携するのか
どのデータを連携するのか
連携に失敗した場合、予約は完了扱いなのか、保留扱いなのか、取消扱いなのか
利用者にはどのような状態として見せるのか
ホテル側の在庫は確保済みなのか、未確保なのか
二重予約や在庫不整合をどう防ぐのか
再送は自動なのか、手動なのか
再送してよい条件は何か
補正や取消が必要になった場合、誰が対応するのか
旅行予約サイト側と外部ホテル在庫管理システム側の責任分界点はどこか
結合テストでは何を確認すべきなのか
ここが曖昧なまま進むと、基本設計やテスト設計の段階でだいたい困ります。
「外部連携する」だけでは、ほとんど何も決まっていない
外部連携は、ただ「連携する」と書くだけでは足りません。
なぜなら、外部連携では、正常時よりも異常時の扱いが問題になりやすいからです。
正常に連携できる場合は、まだよいです。
予約情報を送る。
外部システムが受け取る。
予約が成立する。
利用者に完了画面を表示する。
この流れは比較的イメージしやすい。
でも、実際に設計で困るのは、こういうケースです。
外部ホテル在庫管理システムが応答しない
タイムアウトした
在庫確保に失敗した
旅行予約サイト側では予約情報を保存したが、外部連携だけ失敗した
外部側では登録できたが、こちらでは失敗扱いになった
同じ予約情報を再送したら二重登録される可能性がある
利用者が画面を閉じた
決済は成功したが、ホテル在庫の確保に失敗した
管理者がどの画面で復旧すればよいか分からない
こうなると、単なる「エラー時はメッセージを表示する」では足りません。
表示するメッセージも大事です。
ただ、それ以前に決めなければいけないことがあります。
業務上、その予約をどの状態として扱うのか
です。
完了なのか。
保留なのか。
取消なのか。
再送待ちなのか。
手動確認中なのか。
ここが決まらないと、画面設計も、DB設計も、運用設計も、テスト設計も決まりません。
この手の不足は、単に設計書の文章を直せば終わるとは限りません。
予約状態、画面表示、DB項目、管理画面、再送処理、結合テスト、運用手順まで影響することがあります。
だからこそ、要件定義段階で「失敗時に業務としてどう扱うか」だけでも押さえておきたいところです。
要件定義なら、最低限このくらいは見えていてほしい
もちろん、要件定義の段階で詳細設計レベルまで書く必要はありません。
APIの細かいパラメータ生成ロジックや、例外クラスや、SQLや、リトライ間隔の実装方式まで要件定義で書け、という話ではありません。
それはやりすぎです。
もはや要件定義ではなく、未来から来た詳細設計です。
ただし、要件定義で決めておきたいことはあります。
たとえば、先ほどの旅行予約サイトの例なら、最低限このくらいは書かれていてほしいです。
ホテル予約確定時に、予約ID、利用者ID、宿泊施設ID、宿泊日、泊数、部屋タイプ、人数、料金プラン、決済状態を外部ホテル在庫管理システムへ連携する。
外部連携に失敗した場合、旅行予約サイト側では予約情報を「連携保留」状態として保存し、利用者には「予約処理中」と表示する。
連携保留となった予約は、管理者が連携失敗一覧から再送または取消できるようにする。
外部ホテル在庫管理システム側で在庫確保が完了しているかどうかの確認方法、および再送可能条件については、基本設計までに責任分界点を整理する。
これでも、まだ基本設計や詳細設計で詰めるべきことは残っています。
たとえば、
通信方式
同期/非同期
タイムアウト秒数
リトライ回数
エラーコード
レスポンス形式
ログ出力
監視
冪等性キー
再送時の重複防止
外部側登録済みかどうかの確認方法
こういった内容は、基本設計以降で具体化していくことになるでしょう。
ただ、要件定義の段階で先ほどのレベルまで書かれていれば、少なくとも以下の大きな論点は見えます。
何を連携するのか
いつ連携するのか
失敗した場合、業務上どの状態にするのか
利用者にどう見せるのか
管理者がどう復旧するのか
責任分界点として何を整理すべきなのか
このあたりが見えていれば、次工程で設計すべきことが明確になります。
逆に、ここが曖昧なままだと、後工程でかなり高い確率で揉めます。
なぜ「細かすぎる」と思われるレベルまで書く必要があるのか
ここで、「なぜそこまで書く必要があるのか」を少し整理します。
これは、単に「細かく書こう」という話ではありません。
後工程に進めるために、どの論点が決まっていないと危険なのか。
どこまで見えていれば、基本設計や詳細設計で詰められるのか。
逆に、どこが曖昧なままだと、設計・実装・テスト・運用で詰まるのか。
そこを見極めるための粒度です。
「そんなの、お前の現場のマイルールだろ？」と思われるかもしれません。
でも、実はそうとも言い切れません。
工程ごとに成果物の役割を分け、関係者の認識をそろえるという考え方は、IPAのSLCPや共通フレーム系の考え方とも相性がよいです。
また、非機能要求の領域では、IPAの「非機能要求グレード」のように、ユーザ側と開発者側の認識違いを防ぐために、要求項目や要求レベルを整理する資料もあります。
問題は、公的資料や標準を読んでも、
「では、うちの要件定義書の外部連携欄には、具体的にどの粒度で書けばよいのか」
という実務の一行までは、そのまま出てこないことです。
そのギャップを埋めるために、現場では「この工程なら、このレベル感までは書いておきたいよね」という基準を持っておく必要があるのだと思います。
レビュー指摘としては、どう書くか
仮に、要件定義書に次のような記載しかなかったとします。
ホテル予約確定時に、外部ホテル在庫管理システムへ予約情報を連携する。
エラー時はメッセージを表示する。
この場合、レビュー指摘としては、たとえば次のように書きます。
外部ホテル在庫管理システムへの連携失敗時に、旅行予約サイト側で予約をどの状態として扱うのかが未定義です。
予約確定後に外部連携が失敗した場合、予約を「完了」「連携保留」「取消」のいずれとして扱うのかを明記してください。
また、利用者への表示、管理者による再送・取消・補正の要否、外部ホテル在庫管理システムとの責任分界点についても、少なくとも基本設計までに整理できる状態にしてください。
この指摘で見ているのは、単なる文章の不足ではありません。
見ているのは、
そのまま次工程に進めたときに、設計・実装・テスト・運用で困る論点が残っていないか
です。
レビュー指摘は、細かく書けばよいというものではありません。
何でもかんでも指摘すればいいわけでもありません。
レビューが重すぎると、設計者も疲れます。
レビューアも疲れます。
プロジェクトも遅れます。
全員しんどい。つらい。寝たい。
ただし、後工程で大きな手戻りになる論点は、早めに止めたほうがいい。
特に外部連携では、
業務状態
責任分界点
失敗時の扱い
復旧方法
データ不整合
二重登録
テスト観点
このあたりは、後から決めようとすると面倒になりやすいです。
レベル感が揃わないと、レビューは属人化する
設計書レビューが難しい理由のひとつは、レビュー担当者によって求める粒度が変わることです。
ある人は、
要件定義なので、方針が書いてあれば十分です。
と考える。
別の人は、
基本設計で困るから、異常系の業務扱いまでは決めておいてほしいです。
と考える。
さらに別の人は、
詳細な項目定義やエラーコードまでないと不安です。
と考える。
こうなると、レビューを受ける側は混乱します。
前のレビューではOKだったのに、今回はNGと言われた
どこまで書けばよいのか分からない
指摘が人によって違う
レビューアの好みを読むゲームになっている
強いレビューアに当たるかどうかで品質が変わる
これは、かなりよろしくありません。
設計書レビューは、本来「レビュー担当者の好みを当てるゲーム」ではありません。
見たいのは、
この状態で次工程に進めてよいか
です。
そのためには、工程ごとに求める粒度をある程度そろえておく必要があります。
工程ごとに求める粒度は違う
要件定義、基本設計、詳細設計では、求める粒度が違います。
外部連携を例にすると、ざっくりこうです。
要件定義では、詳細設計のような実装レベルまでは求めません。
ただし、業務上の状態や責任分界点がまったく見えていないなら、それは要件定義として不安です。
基本設計では、要件定義で決めた方針をもとに、方式や項目や異常系の設計を詰めます。
詳細設計では、実装できるように処理順序や分岐条件まで落とします。
このように、工程ごとに「ここまでは決めておきたい」というレベル感が違います。
だからこそ、単なる項目一覧ではなく、工程別の粒度基準が必要になります。
必要なのは、項目名ではなくOK/NGの境界線
レビューで本当に必要なのは、項目名の一覧だけではありません。
もちろん、項目一覧も大事です。
ないよりは絶対にあったほうがいいです。
ただ、それだけでは足りません。
必要なのは、
この工程では、最低限どこまで書いてあればOKなのか
どこから先は次工程で詰めればよいのか
逆に、次工程に送ってはいけない未決事項は何か
どの不足は軽微で、どの不足は重大なのか
そのまま進めると、後工程でどんな手戻りが起きるのか
という判断基準です。
たとえば、外部連携の「タイムアウト」が未定義だった場合。
要件定義段階なら、
業務上、どのくらい待てる想定なのか
応答がない場合に予約を保留扱いにできるのか
利用者に何を表示すべきなのか
管理者対応が必要になるのか
といった業務判断が必要になります。
基本設計段階なら、
何秒でタイムアウトとするのか
リトライするのか
リトライ対象のエラーは何か
タイムアウト時にどのステータスに更新するのか
ログや監視はどうするのか
といった設計判断が必要になります。
詳細設計段階なら、
どの例外を捕捉するのか
何回リトライするのか
リトライ間隔はどうするのか
トランザクションをどこで区切るのか
失敗時にどのテーブルをどう更新するのか
まで必要になります。
同じ「タイムアウト未定義」でも、工程によって指摘の意味が変わります。
ここを整理しないと、レビューはただの感覚勝負になります。
利用者向け表示は、ただの文言ではない
外部連携に失敗したとき、利用者に何を表示するかも重要です。
たとえば、旅行予約サイトでホテル予約が完了したと思っていたのに、実際には外部ホテル在庫管理システムへの連携が失敗していたとします。
このとき、利用者に「予約完了」と表示してよいのか。
それとも「予約処理中」と表示するのか。
または「予約を受け付けましたが、確定までお待ちください」と表示するのか。
これは単なる文言の問題ではありません。
利用者が現在の状態を誤解すると、問い合わせ、二重操作、キャンセル誤認、クレームにつながる可能性があります。
利用者向け表示は、単なる文言調整ではありません。
利用者が「予約は確定したのか」「まだ処理中なのか」「自分は次に何をすればよいのか」を誤解しないようにするための、重要な要件です。
このあたりはユーザビリティやアクセシビリティの観点とも関係します。
ただし、この記事では深掘りしすぎると本筋から外れるので、ここでは「外部連携の失敗時には、システム内部の状態だけでなく、利用者にどう見せるかも要件定義段階で方針を持っておきたい」くらいに留めておきます。
TBDは悪ではない。ただし、管理されていないTBDは地雷
要件定義では、すべてをその場で決められるわけではありません。
TBDが残ることもあります。
未確定事項があること自体は、別に悪ではありません。
問題は、TBDが管理されていないことです。
たとえば、
外部ホテル在庫管理システムとの再送条件はTBD。
とだけ書かれていたら、かなり不安です。
なぜなら、
誰が決めるのか
いつまでに決めるのか
決まらない場合に何が止まるのか
基本設計に影響するのか
テスト計画に影響するのか
連携先との調整が必要なのか
が分からないからです。
一方で、次のように書かれていれば、まだ管理可能です。
外部ホテル在庫管理システムとの再送可能条件はTBD。
連携先システム担当者との確認会にて、再送可能なステータス、再送時の重複防止条件、在庫確保済みデータの扱いを確認する。
確認期限は基本設計開始前までとし、未確定の場合は外部連携方式設計を保留する。
これはTBDではありますが、管理されています。
TBDには、少なくとも以下が必要です。
未決事項の内容
担当者
解消期限
影響範囲
解消できない場合の扱い
TBDは悪ではありません。
ただし、放置されたTBDは地雷です。
そして地雷は、だいたい忘れたころに爆発します。
プロジェクトの地雷は、なぜか踏むまで見えません。理不尽。
AIレビューにも「基準」が必要になる
最近は、AIに設計書を読ませてレビューさせることも増えてきました。
これはかなり便利です。
観点の抜け漏れ確認。
表現の曖昧さの抽出。
用語揺れの確認。
未定義事項の洗い出し。
チェックリストとの突合。
うまく使えば、レビューの一次確認にはかなり役立ちます。
ただし、AIに設計書をレビューさせる場合でも、やはり基準が必要です。
単に、
この設計書をレビューしてください。
と投げるだけだと、AIはそれっぽい指摘をたくさん出してくれます。
でも、その中には、
表現をもう少し明確にしましょう
用語を統一しましょう
必要に応じて補足しましょう
エラー処理を検討しましょう
のような、正しいけれど優先度が分かりにくい指摘も混ざります。
そして結局、人間がそれを見ながら、
これは直す。
これは今回は無視でいい。
これは次工程でよい。
これは本当に止めるべき。
と仕分けることになります。
AIが指摘を100個出してくれた結果、人間側に“仕分け地獄”が発生する。
便利なようで、困る。
AIにレビューさせるなら、本来は、
この工程ではどの粒度まで求めるのか
何を重大指摘とするのか
何を軽微指摘とするのか
次工程で詰めればよいものは何か
今止めるべきものは何か
といったレビュー基準を与える必要があります。
AIは便利です。
ただし、AIに何を見てもらうかを決めるのは人間です。
レビュー基準がない状態でAIを使うと、
「それっぽい指摘はたくさん出るけど、どれを直すべきか分からない」
という別の地獄が始まります。
地獄の自動生成。便利なようで、困る。
まとめ
設計書レビューは、誤字脱字や体裁を直すだけの作業ではありません。
もちろん、それも大事です。
ただ、本質はそこではありません。
設計書レビューの本質は、この状態で次工程に進めてよいかを判断することです。
そのためには、「書いてあるか」だけではなく、「その粒度で足りるか」を見る必要があります。
項目はある。
でもレベル感が足りない。
方針はある。
でも責任分界がない。
正常系はある。
でも失敗時の業務状態がない。
エラー表示はある。
でも復旧手段がない。
TBDはある。
でも担当者と期限がない。
こういう不足を見つけて、後工程で燃える前に止める。
それがレビューの価値だと思います。
今回は外部連携を例にしましたが、同じような話は、エラー処理、権限、TBD管理、非機能要件、運用設計などでも起きます。
それぞれの領域で、
悪い記載例
最低限ほしい記載粒度
レビュー指摘例
後工程で起きる困りごと
AIレビューに渡すなら見るべき観点
を整理していくと、設計書レビューはだいぶ楽になるはずです。
まずは無料記事として、こういう「この工程なら、このレベル感までは書いておきたいよね」という話を少しずつ書いてみようと思います。
もし「このテーマも掘り下げてほしい」というものがあれば、コメントなどで教えてもらえると嬉しいです。
たとえば、
エラー処理：共通エラーと個別エラーの境界線が曖昧で燃える
権限・ロール：マトリクスが穴だらけで実装間際に大慌てする
非機能要件：目標値だけ立派で、見積もりや設計に落ちていない
TBD管理：誰がいつ決めるか分からない保留事項が増殖する
AIレビュー：指摘は出るけど、何を直すべきか仕分けるだけで疲れる
このあたりは、どれも後から燃えがちなテーマだと思っています。
反応が多そうなものから、次の記事で掘ってみます。
需要がありそうなら、いずれテンプレートやチェックリスト、レビュー指摘例の形でもう少し使いやすく整理してみるかもしれません。
次回は、外部連携をもう少し掘って、
「外部連携する」と書いてある設計書が、なぜ後から燃えるのか
あたりを書いてみようかなと思っています。
設計書レビュー、難しいですよね。
でも、せめて「何を見ればいいんだっけ？」で毎回迷う時間くらいは減らしたいものです。
迷子のレビューアを減らしたい。
シバ丸印は、だいたいそのくらいの温度感でやっております。
参考資料
本記事は、筆者の実務経験をもとにした整理ですが、以下のような公的・準公的資料の考え方とも関連します。
IPA「SLCP（ソフトウェアライフサイクルプロセス）」
IPA「共通フレーム2013」
IPA「非機能要求グレード」
デジタル庁「ウェブアクセシビリティ導入ガイドブック」
デジタル庁「デジタル社会推進標準ガイドライン」
デジタル庁「地方公共団体情報システム非機能要件の標準」
関連記事
シリーズ第二弾
この記事では「項目があるだけでは足りない」「後工程に進めるだけの粒度が必要」という話を書きました。
その中でも特に後工程で問題になりやすい 外部連携 について、もう少し詳しく掘った記事はこちらです。
【お仕事ネタ】シバ丸印のこう書いたら楽じゃない？シリーズ第二弾：
「外部連携する」と書いてある設計書が、なぜ後から燃えるのか
https://note.com/shibamaru_log/n/n43200bbeda02
あわせて読みたい記事
資格勉強や実務スキルの地図について書いた記事はこちらです。
https://note.com/shibamaru_log/n/n0b6a1bd787c5
妄想記事シリーズはこちらです。
https://note.com/shibamaru_log/n/n8d08f764ead1
