設計成果物 — 誰が何を見て開発するのか
一言でいうと
設計成果物の読者は開発者で、目的は1つです。聞き返さなくてもコードを書けるようにすることです。質問が再び上がってくるなら、その成果物は失敗です。
なぜ必要なのか
設計書を形式的なものと考えた瞬間に、そのプロジェクトは開発段階で止まります。成果物が不十分だと、開発者は毎回企画担当者に聞かなければならず、企画担当者は1日に20回同じ質問を受け、その答えは文書ではなくメッセンジャーに散らばります。2か月後に新しい開発者が合流したとき、そのメッセンジャーを読む方法はありません。
もっと大きな問題は、同時作業が不可能になることです。画面開発者とバックエンド開発者が同じ画面を分担するには、2人とも同じ仕様を見ている必要がありますが、仕様がなければ、一方がもう一方を待ちます。成果物の本当の用途は記録ではなく、並列化です。
設計成果物は「開発者に送る仕様」である
分析段階が終わると、設計段階に移ります。この段階の成果物の読者は開発者で、目的はたった1つ、開発者が企画担当者に聞き返さなくてもコードを書けるようにすることです。質問が再び上がってくるなら、その成果物は失敗です。
現場で実際に使われるのは、おおよそこの5つです。
| 成果物 | 読者 | ないと起こること |
|---|---|---|
| メニュー構成図 | 全員 | 画面IDの体系が、人によって違ってしまいます |
| 画面定義書 | 画面開発者、マークアップ担当、QA | ボタン1つの動作を、毎回聞くことになります |
| ERD / テーブル定義書 | バックエンド、DBA | カラムの型・長さが、開発者ごとに違って決められます |
| インターフェース仕様書 | 両システムの開発者 | 連携テストの初日を、丸ごと失います |
| プログラム一覧 | PL、QA | 進捗率を数える単位がなく、勘で報告します |
画面定義書: 絵ではなく「動作」が本文
新人が作った画面定義書を見ると、画面キャプチャだけが大きく貼ってあります。開発者が本当に必要とするのは、絵の下にあるべき表です。
- 項目定義: 項目名 / 必須かどうか / 入力形式 / 最大長 / 初期値 / コード参照
- イベント定義: どのボタンを押すと → どんな検証をして → どこへ行くのか
- エラー処理: 検証失敗時の文言、サーバーエラー時の文言
- 権限: この画面を誰が見られて、どのボタンが誰に対して無効なのか
特に権限が抜けた画面定義書は、統合テストで必ず事故を起こします。「管理者にだけ見えるべきボタンが、一般ユーザーに見える」という欠陥は、発見が遅いほど高くつきます。
テーブル定義書: 標準単語が先
公共プロジェクトには「公共機関のデータベース標準化指針」があり、民間の大企業も、ほとんどが社内のデータ標準を持っています。順序は次のとおりです。
표준단어사전 (주문 → ORD, 고객 → CUST, 명칭 → NM, 일자 → DT, 금액 → AMT)
↓
표준도메인 (금액 → NUMBER(15,2), 일자 → CHAR(8), 여부 → CHAR(1) Y/N)
↓
표준용어 (주문금액 → ORD_AMT, 고객명 → CUST_NM)
↓
테이블정의서 (ORD_AMT NUMBER(15,2) NOT NULL DEFAULT 0)
このコードブロックの韓国語は、上から順に、標準単語辞書(注文、顧客、名称、日付、金額)、標準ドメイン(金額、日付、フラグ)、標準用語(注文金額、顧客名)、テーブル定義書を表しています。
この順序を守れば、異なるチームが作ったテーブルでも、CUST_NMはいつも顧客名で、いつも同じ長さです。守らなければ、CUST_NAME、CUSTOMER_NM、CUST_NMが1つのDBに共存し、3年後にデータを移行するとき、その代償を払うことになります。
フラグのカラムはY/Nの1桁で、日付はCHAR(8) YYYYMMDDでという慣行が、今でも多いです。気に入らないかもしれませんが、すでにそう作られたレガシーと連携しなければならないなら、新しいテーブルだけ違う方向に行くほうが、より大きなコストです。標準は「最善」ではなく「合意」です。
インターフェース仕様書: 事故が最も多い文書
システム間の連携は、両方の会社が違い、開発者が違い、テストのスケジュールが違います。だから仕様書に書かれていないことは、100%互いに違う形で実装されます。
必ず書かれていなければならないもの:
- インターフェースID、業務名、送信/受信システム、連携方式(REST/ファイル/キュー/DBリンク)
- 周期(リアルタイム/日次バッチ/時間バッチ)と時刻、そして再処理ルール
- 電文レイアウト: 項目名 / 型 / 長さ / 必須 / サンプル値 / 備考
- 文字セット(UTF-8? EUC-KR?)、日付フォーマット、金額の小数桁数、符号の表現
- 応答コード体系と、各コードに対する受信側の対処(リトライ/中止/担当者への通知)
- 障害時の連絡体制とSLA
文字セットと日付フォーマット、この2つだけが書かれていなくても、連携テストの初日は吹き飛びます。現場の格言があります。「インターフェース仕様書にないものは、必ず違う形で実装されています」。
設計成果物の本当の用途は「同時作業」である
なぜこんなに文書を書くのかと聞かれたら、答えは並列化です。SIプロジェクトは人数が数十人で、期間が決まっています。画面開発者、API開発者、DBA、連携担当者が、互いを待たずに同時に働くには、その間に「合意されたインターフェース」が文書として存在する必要があります。
アジャイルチームが文書を減らせるのは、同じ部屋で毎日会話するからです。SIは、会社が違い、フロアが違い、さらにはネットワークまで分離されています。その条件では、文書は官僚主義ではなく、同期プロトコルです。
成果物レビューで実際に見るべきもの
レビュー会議で誤字脱字を拾うのは、時間の無駄です。見るべきものは、次のとおりです。
- 要件IDが付いているか(追跡可能か)
- 数字があるか(長さ、件数、周期、タイムアウト)
- 例外フローがあるか(正常フローしかない設計書は、半分しかできていません)
- 相手側が署名したか(インターフェース仕様書は、両者の合意文書です)
現場での姿
設計書が不十分なとき、最初に崩れるのは連携テストの初日です。
インターフェース仕様書に、フィールドの長さや必須かどうかが空欄になっていると、両方の開発者が、それぞれ合理的に推測して作ってきます。そして最初の連携試験で、電文が互いに合いません。その1日は、開発ではなく協議で丸ごと消え、その協議の結果は、たいてい仕様書ではなくメッセンジャーに残ります。だから、2か月後に同じ問題がまた起きます。
画面定義書では、別の形で表れます。絵だけが大きく貼ってあり、動作の表がなければ、開発者はボタン1つごとに企画担当者に聞きます。企画担当者が席にいない日は、その画面が止まります。成果物がないと、人がボトルネックになります。
そのため、成果物のレビューで見るべきは、文章の滑らかさではなく、「これを見て、開発者が1人でコードを書けるか」の1点です。